CLAUDE.md

1# CLAUDE.md — Website Design Stack
2 
3This repository is a **ready-to-use environment that makes Claude Code good at website
4design**. When you (Claude) do any UI, web page, landing page, component, or visual-polish
5work in a project that uses this stack, follow the workflow below. It combines a *knowledge*
6layer (what to build), a *taste* layer (making it distinctive), and a *feedback* layer
7(actually seeing the rendered result and fixing it).
8 
9## The design loop (follow in order)
10 
111. **PLAN with data — `ui-ux-pro-max`.** Before writing markup, get a concrete design
12   system. Run the generator, then pull specifics per surface:
13```bash
14   python3 <skill>/scripts/search.py "<product> <industry> <keywords>" --design-system -p "Project"
15   python3 <skill>/scripts/search.py "<query>" --domain style|color|typography|ux|landing|web-vitals
16```
17   Use it for: product-type patterns, color tokens, font pairings, UX anti-patterns,
18   landing structure, and Core Web Vitals budgets. Treat its output as the source of truth
19   for tokens (color, type, spacing).
20 
212. **COMMIT to an aesthetic — `frontend-design`.** Do not sample the safe center of the
22   training distribution. Answer four questions first — *purpose, tone, constraints,
23   differentiation* — pick ONE tone and execute it precisely. Avoid the three AI-slop
24   defaults (cream + serif + terracotta; near-black + acid accent; hairline broadsheet)
25   unless the brief explicitly asks. Spend boldness in **one** signature element; keep the
26   rest quiet.
27 
283. **BUILD.** Implement with the chosen tokens. Match the surrounding code's conventions.
29   For component-driven stacks, use the **shadcn** MCP to search/add components instead of
30   hand-rolling primitives.
31 
324. **SEE IT — Playwright / Chrome DevTools MCP.** You are not done when the code compiles.
33   Open the page in a real browser, screenshot it, read the console, exercise interactive
34   states (hover, focus, open menus, submit forms), and resize the viewport. Fix what you
35   see — z-index, animation timing, layout shift, overflow. This feedback loop is the whole
36   point of the stack; a change you have not looked at is not finished.
37 
385. **REVIEW — `/design-review` (the `design-review` subagent).** Before you call a UI change
39   complete, run the design-review subagent. It drives Playwright across mobile→ultrawide
40   viewports, checks WCAG 2.1 AA (contrast, focus order, keyboard traps), responsive
41   integrity, and interaction states, and returns ranked findings. Fix Blocker/High
42   findings before finishing.
43 
44## Quality floor (never ship below this)
45 
46- **Responsive:** no horizontal scroll at 375 / 768 / 1024 / 1440 px; content reflows, not shrinks.
47- **Accessible:** visible `:focus-visible` on every interactive element; WCAG AA contrast
48  (4.5:1 text, 3:1 large text / UI); semantic landmarks; labelled controls; `prefers-reduced-motion` respected.
49- **Performant:** stable layout (no CLS from unsized media/fonts), lazy-load below-fold
50  images, `font-display: swap`, avoid render-blocking. Check against the `web-vitals` domain.
51- **Intentional copy:** active voice, sentence case, name things by what users recognize.
52 
53## What's wired in this repo
54 
55| Layer | Tool | Where |
56|-------|------|-------|
57| Knowledge | `ui-ux-pro-max` skill | installed via `scripts/setup.sh` (plugin) |
58| Taste | `frontend-design` skill | installed via `scripts/setup.sh` (plugin) |
59| Component gen | `shadcn` MCP | `.mcp.json` |
60| Visual feedback | `@playwright/mcp` + `chrome-devtools-mcp` | `.mcp.json` |
61| Automated review | `design-review` subagent + `/design-review` command | `.claude/agents`, `.claude/commands` |
62| Standalone audit | `scripts/design-audit.mjs` (multi-viewport screenshots) | `scripts/`, CI in `.github/workflows` |
63 
64See `docs/STACK.md` for why each tool is here, `docs/SETUP.md` to install, and
65`docs/WORKFLOW.md` for a worked end-to-end example.
66 
67## Notes
68 
69- `<skill>` above resolves to the installed skill path (e.g. `.claude/skills/ui-ux-pro-max`
70  or the plugin location). The skill's own `SKILL.md` tells you the exact command form.
71- Optional: 21st.dev **Magic** MCP (`@21st-dev/magic`) generates React components from a
72  prompt but needs an API key — see `docs/SETUP.md`. It is intentionally left out of the
73  default `.mcp.json` so the stack works with zero secrets.
74