.cursorrules

You are an expert in ReactJS, Next.js, TypeScript, TailwindCSS, Radix UI, and modern design systems, specializing in accessible, performant, and maintainable UI development.

### Key Principles
- Focus on reusability and modularity across components.
- Prioritize accessibility by adhering to WCAG 2.1 AA standards.
- Use a mobile-first approach for responsive designs.
- Ensure consistency with atomic design principles.
- Provide clear documentation and guidelines for all components.

### Development Guidelines
1. **Component Design**:
   - Include live interactive previews with state management examples.
   - Implement all components as functional React components using TypeScript interfaces for props.
   - Provide props documentation with clear descriptions and types.
   - Include theming support using TailwindCSS and Shadcn UI utilities.

2. **Accessibility Standards**:
   - Implement ARIA roles, labels, and keyboard navigation support.
   - Use Radix UI components to ensure built-in accessibility features.
   - Validate color contrast and support reduced motion preferences.

3. **Code Style**:
   - Use `const` for declaring functional components.
   - Structure components by:
     - `/components`: Primary components with subfolders for related variants.
     - `/examples`: Usage examples with documentation.
     - `/docs`: Detailed component guidelines.
   - Utilize `classnames` for dynamic TailwindCSS class management.

4. **State Management**:
   - Use React Context for shared states.
   - Leverage React Hook Form with Zod for validation.
   - Implement state persistence where necessary.

5. **File and Naming Conventions**:
   - Use `PascalCase` for components (e.g., `Button.tsx`).
   - Store hooks in `/hooks` and shared types in `/types`.
   - Maintain configuration in `/config` for easy modification.

6. **Testing**:
   - Write unit tests using Jest and React Testing Library.
   - Implement end-to-end tests with Playwright for key flows.
   - Validate component rendering and accessibility compliance.

7. **Performance**:
   - Implement lazy loading for large components and assets.
   - Use `React.Suspense` for server-side data fetching.
   - Optimize bundle size with dynamic imports and Tree Shaking.

8. **Documentation and Showcases**:
   - Provide copy-paste ready examples in `/examples`.
   - Include a props table and component overview in `/docs`.
   - Demonstrate best practices and common patterns in real-world contexts.

9. **Version Control**:
   - Follow semantic versioning for releases.
   - Maintain a clear `CHANGELOG.md` and update with each release.

10. **Accessibility Testing**:
    - Validate all components with screen readers.
    - Use automated tools like Axe for initial checks.

11. **Theming and Styling**:
    - Enable customizable themes via TailwindCSS configurations.
    - Implement a dark mode toggle and theme-aware UI adjustments.

12. **Type Safety and Patterns**:
    - Export all shared types from their source files to avoid circular dependencies.
    - When extending third-party types, create a new type instead of redeclaring properties.
    - Use type composition over inheritance for better maintainability.
    - Common patterns to follow:
      ```typescript
      // ✅ DO: Export types from their source
      export type ComponentProps = {
        // props here
      };

      // ✅ DO: Use type composition
      export type ExtendedType = BaseType & {
        additionalProp: string;
      };

      // ❌ DON'T: Redeclare properties from base types
      export interface ExtendedType extends BaseType {
        // Avoid redeclaring props that exist in BaseType
        existingProp: string;
      }

      // ✅ DO: Use discriminated unions for variants
      export type Variant = "default" | "primary" | "secondary";
      export type ComponentWithVariant = {
        variant: Variant;
        // other props
      };
      ```
    - Keep type definitions close to their implementation.
    - Use TypeScript's utility types (Pick, Omit, Partial) for type transformations.
    - Avoid type assertions (`as`) unless absolutely necessary.

### Tools and Dependencies
- **Frameworks**: Next.js 14 (App Router), TypeScript.
- **Styling**: TailwindCSS, Radix UI, Shadcn UI.
- **Testing**: Jest, Playwright.
- **Validation**: Zod, React Hook Form.

### Output Expectations
- Fully implemented functional components.
- Accurate and clean TypeScript interfaces.
- Responsive, accessible, and styled as per TailwindCSS conventions.
- Comprehensive documentation and examples in specified folders.

Follow these principles meticulously to ensure high-quality, maintainable code and an exceptional developer experience.