wedevup template-dashboard-remix-shadcn .cursorrules file for HTML

# Project Guidelines and Standards

## Project Documentation

For detailed project information, refer to:

- Project Overview & Requirements: /docs/project.md
- API Documentation: /docs/api.md
- Development Backlog: /docs/backlog.md
- Feature Specifications: /docs/features/

## Technology Expertise

We are specialists in:

- Remix.js (Modern React Framework)
- TypeScript
- TailwindCSS
- shadcn-ui (Component Library)
- Node.js (20+)
- Vite

## Core Principles

### Architecture

- Follow Remix's nested routing pattern
- Implement loader/action pattern for data handling
- Use Resource Routes for API endpoints
- Keep components atomic and composable
- Implement progressive enhancement where possible
- Use shadcn-ui components as building blocks

### File Structure & Organization

- Follow consistent directory structure:
  ```
  ~/
  ├── components/
  │   ├── ui/          # shadcn-ui components
  │   ├── features/    # feature-specific components
  │   ├── layout/      # layout components
  │   └── auth/        # auth components
  ├── stores/          # Zustand stores
  ├── api/             # API integration
  │   ├── config/      # API configuration
  │   ├── hooks/       # React Query hooks
  │   ├── services/    # API services
  │   └── types/       # API types
  ├── lib/             # Utilities
  ├── styles/          # Global styles
  └── routes/          # Remix routes
  ```
- Follow naming conventions:
  - Files: kebab-case (user-profile.ts)
  - Components: PascalCase (UserProfile.tsx)
  - Hooks: use- prefix (use-auth.ts)
  - Stores: -store suffix (auth-store.ts)
  - Services: -service suffix (user-service.ts)
  - Types: .d.ts extension for definitions
- Keep files under 200 lines
- Maximum nesting depth of 3 levels
- Use meaningful names
- Implement proper TypeScript types

### Testing Strategy

- Directory Structure:

  ```
  ~/tests
  ├── e2e/            # End-to-end tests with Playwright
  │   ├── features/   # Feature-based tests
  │   └── mocks/      # Test mocks if needed
  └── unit/           # Unit tests with Vitest
  ```

- E2E Testing (Playwright):

  - Test critical user flows
  - One test file per feature/route
  - Use page objects for complex flows
  - Mock API responses using Remix resource routes
  - Test files end with .spec.ts
  - Run tests with `npm run test:e2e`

- Test File Naming:

  - E2E Tests: `feature-name.spec.ts`
  - Unit Tests: `component-name.test.ts`

- Best Practices:
  - Write tests before fixing bugs
  - Mock only when necessary
  - Keep tests independent
  - Use meaningful test descriptions
  - Test error states and edge cases
  - Follow AAA pattern (Arrange, Act, Assert)

### Code Style

- Use TypeScript strict mode
- Prefer functional components
- Use named exports over default exports
- Keep components under 350 lines
- Use meaningful variable names (no abbreviations)
- Implement proper TypeScript interfaces/types

### Component Architecture

- Use shadcn-ui components as foundation
- Always compose complex components from simpler ones
- Customize components using theme tokens only
- Follow shadcn-ui's composition pattern strictly
- Maintain accessibility features
- Use Radix primitives for complex interactions
- Create variants using cva (class-variance-authority)
- Document all component variants and props
- Keep component stories updated

### Design System

- Follow shadcn-ui's design system strictly
- Embrace minimalism - less is more
- Use theme variables for colors exclusively
- Implement dark mode support by default
- Maintain consistent spacing using tailwind classes
- Follow 8px grid system
- Use semantic color naming
- Prefer whitespace and typography for hierarchy
- Use subtle animations purposefully
- Follow visual hierarchy principles
- Use negative space effectively
- Design for scalability and reuse

### State Management

- Client State (Zustand):

  - Keep stores small and focused
  - Use middleware when needed (persist, devtools, immer)
  - Follow store slicing pattern
  - Use selectors for state access
  - Avoid storing derived state
  - Implement proper cleanup
  - Use shallow equality checks
  - Document interfaces and actions

- Server State (React Query):
  - Use proper query keys and caching
  - Handle loading and error states
  - Type all responses
  - Use suspense when appropriate
  - Enable devtools in development
  - Implement optimistic updates
  - Handle offline scenarios
  - Use infinite queries for pagination

### Authentication & Security

- Authentication:

  - Use Zustand for auth state
  - Implement JWT-based auth
  - Handle token expiration
  - Secure token storage
  - Implement proper login/logout flow
  - Remember user preferences
  - Clear sensitive data on logout

- Authorization:

  - Use protected routes with role-based access
  - Handle unauthorized access gracefully
  - Implement loading states
  - Type-safe role definitions
  - Example protected route:
    ```tsx
    <ProtectedRoute requiredRole='admin'>
      <AdminDashboard />
    </ProtectedRoute>
    ```

- Security:
  - Implement CSRF protection
  - Use proper authentication headers
  - Sanitize all inputs/outputs
  - Use refresh token rotation
  - Implement proper CORS settings
  - Use environment variables for secrets
  - Never expose sensitive data
  - Implement rate limiting
  - Use HTTPS only

### Navigation & Layout

- Navigation:

  - Use Radix Navigation Menu
  - Separate public/private routes
  - Role-based navigation items
  - Handle mobile navigation
  - Use theme tokens for styling
  - Manage z-index properly

- Layout:
  - Use consistent layout structure:
    ```tsx
    <RootLayout>
      <ProtectedRoute>
        <PageContent />
      </ProtectedRoute>
    </RootLayout>
    ```
  - Implement responsive patterns
  - Maintain consistent spacing
  - Handle nested layouts when needed

### Error Handling

- Use error boundaries strategically
- Handle different error types:
  - Network errors
  - Validation errors
  - Authentication errors
  - Authorization errors
- Show user-friendly messages
- Implement proper retry mechanisms
- Log errors appropriately
- Handle offline scenarios
- Implement form validation

### Performance

- Implement code splitting
- Use proper caching strategies
- Optimize assets and payloads
- Use compression
- Implement request cancellation
- Use proper batch requests
- Monitor performance metrics
- Use proper meta tags for SEO
- Handle loading states gracefully

### Testing & Quality

- Testing Structure:

  ```
  ~/
  ├── tests/
  │   ├── unit/              # Unit tests
  │   ├── integration/       # Integration tests
  │   ├── e2e/              # End-to-end tests
  │   ├── fixtures/         # Test data
  │   ├── mocks/           # Mock implementations
  │   └── utils/           # Test utilities
  ```

- Coverage Requirements:

  - Maintain minimum 85% code coverage
  - 100% coverage for critical paths
  - Track coverage trends in CI
  - Coverage requirements:
    ```
    - Statements: 85%
    - Branches: 85%
    - Functions: 85%
    - Lines: 85%
    ```

- Unit Testing (Vitest + RTL):

  - Test individual components in isolation
  - Mock external dependencies
  - Test component props and events
  - Test hooks independently
  - Test utility functions
  - Test store actions and selectors
  - Follow AAA pattern (Arrange, Act, Assert)
  - Example:
    ```tsx
    describe('Button', () => {
      it('should call onClick when clicked', () => {
        const onClick = vi.fn()
        render(<Button onClick={onClick}>Click me</Button>)
        userEvent.click(screen.getByText('Click me'))
        expect(onClick).toHaveBeenCalled()
      })
    })
    ```

- Integration Testing:

  - Test component interactions
  - Test data flow between components
  - Test store integration
  - Test form submissions
  - Test API integration
  - Use MSW for API mocking
  - Example:

    ```tsx
    describe('LoginForm', () => {
      it('should handle successful login', async () => {
        const user = userEvent.setup()
        render(<LoginForm />)

        await user.type(screen.getByLabelText('Email'), 'test@example.com')
        await user.type(screen.getByLabelText('Password'), 'password')
        await user.click(screen.getByText('Login'))

        expect(await screen.findByText('Welcome')).toBeInTheDocument()
      })
    })
    ```

- E2E Testing (Playwright):

  - Test critical user flows
  - Test across multiple browsers
  - Test responsive design
  - Test accessibility
  - Record test videos
  - Take screenshots on failure
  - Example:
    ```typescript
    test('user can login and access dashboard', async ({ page }) => {
      await page.goto('/')
      await page.fill('[aria-label="Email"]', 'user@example.com')
      await page.fill('[aria-label="Password"]', 'password')
      await page.click('button:has-text("Login")')
      await expect(page).toHaveURL('/dashboard')
    })
    ```

- API Mocking (MSW):

  - Mock API responses
  - Test error scenarios
  - Test loading states
  - Example:
    ```typescript
    const handlers = [
      rest.get('/api/users', (req, res, ctx) => {
        return res(ctx.json([{ id: 1, name: 'John' }]))
      }),
      rest.post('/api/login', (req, res, ctx) => {
        return res(ctx.json({ token: 'fake-token' }))
      })
    ]
    ```

- Testing Best Practices:

  - Write tests before fixing bugs
  - Update tests when modifying features
  - Use meaningful test descriptions
  - Test error scenarios
  - Test edge cases
  - Use proper assertions
  - Clean up after each test
  - Use shared test utilities
  - Document test requirements
  - Follow test-driven development when possible
  - Testing Philosophy:
    - Tests should drive implementation, not the other way around
    - Don't modify tests to make them pass - fix the implementation
    - Only mock what's necessary (external APIs, time-dependent operations)
    - Mocking should not be used to make a failing test pass
    - If a test fails, understand why and fix the underlying issue
    - Tests should reflect real user behavior and requirements
    - Keep tests as close to production behavior as possible
  - Mocking Guidelines:
    - Only mock external dependencies
    - Mock HTTP requests and API calls
    - Mock time-dependent operations
    - Mock complex browser APIs when needed
    - Never mock to hide implementation problems
    - Document why a mock is necessary
    - Keep mocks as simple as possible

- Continuous Integration:

  - Run all tests on PR
  - Block merging on test failure
  - Generate coverage reports
  - Run E2E tests in CI
  - Cache test results
  - Parallelize test execution
  - Monitor test duration

- Testing Quality:

  - No flaky tests
  - Fast execution
  - Independent tests
  - Clear failure messages
  - Easy to maintain
  - Follow testing patterns
  - Use testing utilities
  - Document complex tests

- Accessibility Testing:
  - Test with screen readers
  - Test keyboard navigation
  - Test color contrast
  - Test ARIA attributes
  - Test focus management
  - Use accessibility testing tools