Cursor rule

1---
2description: "Design system mechanics: tokens, shadcn/ui, Tailwind v4, composition, theming. Load for UI implementation — aesthetics and anti-slop live in the anti-slop-design skill."
3globs: ["**/*.css", "**/globals.css", "**/tailwind.config.*", "**/components.json", "**/components/ui/**"]
4alwaysApply: false
5---
6 
7# Design System Mechanics
8 
9Token structure, shadcn/ui usage, Tailwind v4 features, and component composition — not aesthetic direction.
10 
11For palettes, font pairings, category tone, layout direction, and the slop checklist, load the **`anti-slop-design`** skill (and its `reference.md` for full pages / responsive matrices). For general coding workflow, use core **Code Discipline**.
12 
13Inspect the project first: `package.json`, `tailwind.config.*`, `globals.css`, `components.json`, existing fonts and icon library. Extend what exists; do not replace the design system unprompted.
14 
15---
16 
17## Token Shape (semantic, not hex soup)
18 
19Prefer **semantic names** mapped to CSS variables so themes and shadcn primitives stay aligned:
20 
21```css
22/* globals.css — Tailwind v4 @theme or :root */
23@theme {
24  --color-background: …;
25  --color-foreground: …;
26  --color-primary: …;
27  --color-muted: …;
28  --color-border: …;
29  --radius-md: 8px;
30  --font-body: …;
31  --font-display: …;
32}
33```
34 
35- Derive real values from the project brand or `anti-slop-design` Category Guide — placeholders above are structural only.
36- Prefer **OKLCH** for new token values (`oklch(0.65 0.15 250)`) — perceptually uniform lightness makes scales and dark-mode variants predictable. Tint neutrals toward the brand hue (chroma 0.005–0.01); never ship pure-gray scales or pure `#000`/`#FFF`.
37- Three token tiers when the system grows: **primitive** (`--blue-600`) → **semantic** (`--color-primary`) → **component** (`--button-bg`). Components consume semantic tokens; only semantic tokens reference primitives. Skip the component tier until a component actually needs an override.
38- Do not default to generic blue/indigo scales or `Inter` / `Roboto` unless the project already uses them.
39- Status colors: `--destructive`, `--success`, etc. — keep consistent with shadcn semantic tokens when present.
40 
41---
42 
43## Typography Mechanics
44 
45- Fluid display sizes with `clamp()`: `font-size: clamp(2rem, 1.2rem + 3.5vw, 4rem)` — no breakpoint jumps on headings.
46- Pair line-height inversely with size: body `1.6–1.8`, headings `1.1–1.2`. A 56px heading at `line-height: 1.6` is broken.
47- Tighten tracking as display size grows (`letter-spacing: -0.01em` to `-0.04em` above ~32px); never negative-track body text.
48- Body measure: `max-width: 65ch` on prose containers, not pixel guesses.
49- Keep ≥1.25 ratio between adjacent type-scale steps; expose the scale as tokens, not ad-hoc `text-[17px]` values.
50- Load fonts with `font-display: swap` and preconnect; subset when the toolchain supports it.
51 
52---
53 
54## Motion Mechanics
55 
56- Animate only `transform` and `opacity`; never `width`/`height`/`top`/`margin` (layout thrash).
57- Tokenize easing and duration: `--ease-out: cubic-bezier(0.22, 1, 0.36, 1)`, durations 150–250ms for micro-interactions, 400–600ms for entrances.
58- Gate all non-essential motion behind `@media (prefers-reduced-motion: no-preference)`.
59- Stagger entrances with `animation-delay` increments (60–100ms); one orchestrated page entrance beats scattered micro-animations.
60 
61---
62 
63## shadcn/ui
64 
65```bash
66npx shadcn@latest init
67npx shadcn@latest add button card input label form dialog
68```
69 
70- Compose from primitives (`Card`, `Button`, `Form`, `Dialog`) — do not fork components unless layout truly requires it.
71- Map theme overrides at **CSS variable** layer (`--primary`, `--radius`, `--background`) before editing component source.
72- Forms: use shadcn `Form` + project validation library (e.g. zod + react-hook-form) when already in the stack.
73 
74---
75 
76## Tailwind v4 Essentials
77 
78- Define tokens in `@theme` in CSS; avoid duplicating palettes in JS config when v4 CSS-first setup is used.
79- Container queries: `container-type: inline-size` on parent, `@container` for child layout.
80- Use semantic utilities (`bg-background`, `text-muted-foreground`) when shadcn tokens exist — not raw `bg-gray-200` / `text-black`.
81 
82---
83 
84## Composition Rules
85 
86- One primary CTA per section; secondary actions visually quieter.
87- Consistent `max-width` and horizontal padding across sections (hero → footer).
88- Extract repeated class strings into components — do not paste 20-class strings everywhere.
89- Never nest cards; separate grouped content with background shifts or whitespace instead.
90- Charts and fixed-height embeds (Chart.js, maps): parent container **must** have explicit height (same discipline as 3D canvases).
91 
92---
93 
94## Dark Mode
95 
96- Prefer `class` strategy with CSS variables when shadcn is present.
97- Pair `--background` / `--foreground` for contrast; test muted text ≥ 4.5:1 on body copy.
98 
99---
100 
101## Responsive & Accessibility
102 
103- Mobile-first breakpoints; 44px minimum touch targets on primary actions.
104- Every input has a label; errors use color + text (and icon when helpful).
105- Visible focus rings — never `outline: none` without an alternative.
106- Full responsive hide/reorder/transform guidance: `anti-slop-design` → `reference.md`.
107 
108---
109 
110## Verification (UI changes)
111 
112| Change | Minimum proof |
113|--------|----------------|
114| Token/theme | Styles apply in browser; no unstyled flash on load |
115| New component | Renders at 375px and desktop; focus/hover work |
116| Form | Label association, error state, keyboard submit |
117| shadcn add | Component imports resolve; theme tokens applied |
118 
119Browser verification required for layout/interaction claims (see status-verification rule).
120 
121---
122 
123## When NOT to Load This File
124 
125- Backend-only or non-UI tasks.
126- Distinctive marketing/landing aesthetic from scratch — start with **`anti-slop-design`** (Step 1: design thinking), then return here for token/shadcn mechanics.
127