Design

Design

Enforce correct visual design for websites built with shadcn/ui, Tailwind semantic tokens, and Lucide. Classify the surface first. Do not apply marketing density to a dashboard, or dashboard text-sm to a legal page.

Workflow

1. Ground in the project:
   • Read local tokens (globals.css / :root / .dark / @theme inline).
   • Read components.json (style, baseColor, cssVariables, iconLibrary).
   • Reuse existing primitives (Button, Card, Sidebar, Table, …). Do not invent a parallel visual language.
2. Classify the surface using surfaces.md. Load only the matching surface file(s) plus the foundation files the change needs.
3. Apply foundations:
   • Tokens: tokens.md
   • Type: typography.md
   • Color / dark mode: color.md
   • Spacing, density, radius, z-index: spacing.md
4. Apply surface rules (one density and one primary CTA per view).
5. Clear craft gates: accessibility.md, anti-slop.md.
6. Verify: light + dark, responsive, focus ring, empty/loading/error, 200% zoom when layout is fragile. Prefer a browser check when available.

Hard rules

• Style with semantic tokens (bg-background, text-foreground, bg-primary, text-muted-foreground, border-border, ring-ring). No one-off hex/rgb on product chrome unless the project already does that for a documented brand exception.
• Pair surfaces: bg-primary with text-primary-foreground. Never text-foreground on bg-primary.
• Dark mode overrides the same tokens under .dark. Do not invert the page. Raise card / popover above background. Dark borders: oklch(1 0 0 / 10%).
• One filled primary button per view. Destructive is only for destroy.
• One density per page. Do not mix hero padding with compact table chrome.
• Interactive hit area: 24×24 CSS px minimum (WCAG 2.2 AA); prefer 44×44 for marketing, auth, and primary mobile actions.
• Visible labels on inputs. Placeholder is not a label.
• Icon-only controls need an accessible name. Lucide sizes: 16 / 20 / 24.
• Honor prefers-reduced-motion. Keep the end state; drop travel.

Surface map

Composed examples: examples.md.
Official links: source-map.md.

Decision record (emit with UI work)

## Surface
[marketing | dashboard | auth | …] — [user job]

## Tokens
Reuse local / change --primary|--radius|--font-sans: [why]

## Hierarchy
Type roles used: [display/h1/body/ui/caption]
Density: [generous | comfortable | compact]
Primary CTA: [one verb]

## Gates
- [ ] contrast (text 4.5:1, UI/focus 3:1) light+dark
- [ ] spacing on 4px grid
- [ ] states: empty/loading/error
- [ ] keyboard focus visible, not obscured
- [ ] anti-slop (no default indigo mesh / fake stats / equal card noise)

Out of scope

Email HTML, native mobile apps, and print. If the user asks for those, say so and keep this skill on website UI only.