.cursorrules

You are an expert in TypeScript, React, NextJS, HTML, CSS, and website development.

Code Style and Structure

- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns; avoid classes.
- Prefer iteration and modularisation over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Structure files: exported component, subcomponents, helpers, static content, types.
- Follow NextJS's official documentation for setting up and configuring your projects: https://nextjs.org/docs
- Always use Nextjs App Router, and never the Pages Router.

Naming Conventions

- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Use camcelCase for files (e.g., components/auth-wizard/authWizard.tsx).
- Favor named exports for components.
- When naming components, aim to describe what the component is/does, not how it looks or what content is in it. E.G. not "How It Works Block" but instead "Card Carousel".

TypeScript Usage

- Use TypeScript for all code; prefer interfaces over types.
- Use functional components with TypeScript interfaces.
- Use strict mode in TypeScript for better type safety.

Syntax and Formatting

- Use the "function" keyword for pure functions.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative JSX.
- Use Prettier for consistent code formatting.
- Prefer using nullish coalescing operator ( ?? ) instead of a logical or ( || ), as it is a safer operator.
- Favor single quotes over double quotes for strings.

UI and Styling

- Implement responsive design with Flexbox for screen size adjustments.
- Use CSS Modules or Tailwind CSS for component styling.
- Ensure high accessibility (a11y) standards using ARIA roles and native accessibility props.
- Leverage framer motion for performant animations and transitions.

Performance Optimization

- Minimise the use of useState and useEffect; prefer context and reducers for state management.
- Implement code splitting and lazy loading for non-critical components with React's Suspense and dynamic imports.
- Profile and monitor performance using JavaScript and React's built-in tools and debugging features.
- Avoid unnecessary re-renders by memoising components and using useMemo and useCallback hooks appropriately.

Navigation

- Use Nextjs for routing and navigation; follow its best practices.

State Management

- Use React Context.
- For complex state management, consider using Zustand.

Error Handling and Validation

- Use Zod for runtime validation and error handling.
- Implement proper error logging using Sentry or a similar service.
- Prioritise error handling and edge cases:
  - Handle errors at the beginning of functions.
  - Use early returns for error conditions to avoid deeply nested if statements.
  - Avoid unnecessary else statements; use if-return pattern instead.
  - Implement global error boundaries to catch and handle unexpected errors.

Testing

- Write unit and integration tests using Vitest and React Testing Library.
- Consider snapshot testing for components to ensure UI consistency.
- Put unit tests in a **tests** directory, next to the file being tested.

Key Conventions

1. Prioritise Core Web Vitals (Load Time, Jank, and Responsiveness).
2. Follow React and NextJS's best practices for website development.
3. Use pnpm for package management.
4. If you are unsure about something, ask the user for clarification. If you think something can be improved, make sure to suggest the changes.
5. If you are not sure about the answer, or the question could be rephrased to get a better results, say so instead of guessing.

Current File Structure

# Paste below the result of this command, no matter how long "tree -L 4 -a -I 'node_modules|.git|__pycache__|.DS_Store|.pytest_cache|.vscode|.turbo|.next|.idea'"

000-cursor-rules.mdc

# Cursor Rules Format
## Core Structure

```mdc
---
description: ACTION when TRIGGER to OUTCOME
globs: *.mdc
---

# Rule Title

## Context
- When to apply this rule
- Prerequisites or conditions

## Requirements
- Concise, actionable items
- Each requirement must be testable

## Examples
<example>
Good concise example with explanation
</example>

<example type="invalid">
Invalid concise example with explanation
</example>
```

## File Organization

### Location
- Path: `.cursor/rules/`
- Extension: `.mdc`

### Naming Convention
PREFIX-name.mdc where PREFIX is:
- 0XX: Core standards
- 1XX: Tool configs
- 3XX: Testing standards
- 1XXX: Language rules
- 2XXX: Framework rules
- 8XX: Workflows
- 9XX: Templates
- _name.mdc: Private rules

### Glob Pattern Examples
Common glob patterns for different rule types:
- Core standards: .cursor/rules/*.mdc
- Language rules: src/**/*.{js,ts}
- Testing standards: **/*.test.{js,ts}
- React components: src/components/**/*.tsx
- Documentation: docs/**/*.md
- Configuration files: *.config.{js,json}
- Build artifacts: dist/**/*
- Multiple extensions: src/**/*.{js,jsx,ts,tsx}
- Multiple files: dist/**/*, docs/**/*.md

## Required Fields

### Frontmatter
- description: ACTION TRIGGER OUTCOME format
- globs: `glob pattern for files and folders`

### Body
- <version>X.Y.Z</version>
- context: Usage conditions
- requirements: Actionable items
- examples: Both valid and invalid

## Formatting Guidelines

- Use Concise Markdown primarily
- XML tags limited to:
  - <example>
  - <danger>
  - <required>
  - <rules>
  - <rule>
  - <critical>
  - <version>
- Always indent content within XML or nested XML tags by 2 spaces
- Keep rules as short as possbile
- Use Mermaid syntax if it will be shorter or clearer than describing a complex rule
- Use Emojis where appropriate to convey meaning that will improve rule understanding by the AI Agent
- Keep examples as short as possible to clearly convey the positive or negative example

## AI Optimization Tips

1. Use precise, deterministic ACTION TRIGGER OUTCOME format in descriptions
2. Provide concise positive and negative example of rule application in practice
3. Optimize for AI context window efficiency
4. Remove any non-essential or redundant information
5. Use standard glob patterns without quotes (e.g., *.js, src/**/*.ts)

## AI Context Efficiency

1. Keep frontmatter description under 120 characters (or less) while maintaining clear intent for rule selection by AI AGent
2. Limit examples to essential patterns only
3. Use hierarchical structure for quick parsing
4. Remove redundant information across sections
5. Maintain high information density with minimal tokens
6. Focus on machine-actionable instructions over human explanations

<critical>
  - NEVER include verbose explanations or redundant context that increases AI token overhead
  - Keep file as short and to the point as possible BUT NEVER at the expense of sacrificing rule impact and usefulness for the AI Agent.
  - the front matter can ONLY have the fields description and globs.
</critical>