# .cursorrules - Ship Faster Kit
# Version 1.0.0
#
# Rename this file to .cursorrules
# Place it at the root of your project
# Cursor reads this automatically on every interaction
# ─────────────────────────────────────────────────────────────

## Project Context

This is a SaaS UI project using an AI-assisted design-to-code pipeline.

The token flow is:
Figma Variables → tokens.json → tokens.css → React components

tokens.json contains structured token definitions.
tokens.css contains CSS custom properties generated from tokens.json.
Components reference tokens.css, never raw values.

Cursor is the primary environment where production code is written and finalized.
Claude reads Figma and drafts component structure. Cursor refines and ships.

## Stack

- React 18 + TypeScript
- CSS Modules or Tailwind (confirm before generating)
- No UI libraries (MUI, Chakra, Radix, shadcn) - build from tokens
- Vite for bundling
- GitHub for version control

## Non-Negotiable Rules

1. Tokens only.
   Never hardcode colors, spacing, radii, shadows, or font values.
   Always reference a semantic token via CSS custom property.
   Avoid hardcoding breakpoints where layout tokens exist.
   If a token does not exist, flag it. Do not invent a value.

2. TypeScript always.
   Every component gets a typed Props interface.
   No any. No implicit types.

3. Accessibility first.
   Every interactive element needs:
   - Correct ARIA role or semantic HTML
   - Keyboard navigation support
   - Visible focus state using var(--shadow-focus)
   - Minimum 44x44px touch target on mobile

4. No new dependencies without approval.
   Ask before installing anything.
   Prefer native browser APIs and existing utilities.

5. One component per file.
   No barrel exports of multiple components in one file.
   Index files for folders are acceptable.

6. Realistic content only.
   Never use Lorem ipsum or placeholder@email.com.
   Use product-realistic data in examples.

7. Fix the source, not the output.
   If a generated component has a bug, fix the component.
   Never patch the rendered output directly.

8. Checkpoint often.
   Accept all file changes in Cursor after each working component.
   This is your undo history.

## Component Generation Checklist

Before completing a component, verify:
- [ ] All visual values reference semantic tokens via CSS custom properties
- [ ] TypeScript Props interface is complete
- [ ] Hover, focus, active, and disabled states are handled
- [ ] No hardcoded color, spacing, or size values
- [ ] Accessible markup (roles, labels, keyboard support)
- [ ] Named export (not default)
- [ ] Usage example in a comment at the bottom

## Folder Structure

/src
  /components
    /ui          - atoms: Button, Input, Badge, Card, Avatar
    /patterns    - molecules: FormField, NavBar, SearchBar
    /screens     - organisms: LoginScreen, DashboardScreen
  /tokens
    tokens.json  - token definitions (do not edit manually if Figma-synced)
    tokens.css   - generated CSS custom properties
  /hooks         - custom React hooks
  /utils         - pure utility functions
  /types         - shared TypeScript types

## CSS Custom Property Naming

Token path → CSS variable name:
- semantics.color.text.primary     → --color-text-primary
- semantics.spacing.component.md   → --spacing-component-md
- semantics.radius.card            → --radius-card
- semantics.shadow.card            → --shadow-card
- semantics.shadow.focus           → --shadow-focus
- components.button.height.md      → --button-height-md

## Common Anti-Patterns

style={{ color: '#111827' }}     → use var(--color-text-primary)
padding: '12px 16px'             → use var(--spacing-component-md)
borderRadius: '9999px'           → use var(--radius-button)
Installing shadcn, MUI, Radix    → build from tokens instead
Patching rendered output         → fix the component source
Installing packages without asking → always ask first

## When Stuck

If Cursor is not making progress:
- Say: "Please stop and summarize where you are."
- Restart with a smaller, more specific prompt
- Break the task into one component at a time
- Accept all current changes before starting fresh

## Prompts That Work Well

"Generate [ComponentName] using the component tokens from tokens.json.
Include [size variants and states]. Export as [ComponentName]."

"Refactor [ComponentName] to replace all hardcoded values with semantic tokens
referenced from tokens.css."

# ─────────────────────────────────────────────────────────────
# End of .cursorrules · Ship Faster Kit
