aidenlx/zotlit / .claude/skills/design-review
design-review
VerifiedReviews a docs-site UI change against apps/docs/DESIGN.md — runs the design lint rule, renders the touched surfaces, and routes judgement calls to the better-* skills with DESIGN.md's values as the reference. Use before landing any change under apps/docs/src that touches markup or classes.
Design review
The docs site has one design spec, apps/docs/DESIGN.md. This skill checks a change against it in three tiers, each catching what the tier above cannot:
- The kit (
apps/docs/src/components/ui/*) carries every size, so a call site names a variant and nothing else. - The lint check, the oxlint rule
zotlit-design/workbench-chrome(packages/config/oxlint-plugin-design.ts), catches mechanical drift in Workbench chrome (src/lib/workbench/*.tsx, set inapps/docs/oxlint.config.ts): a raw popover, a size or spacing at a call site, a physical direction class, an arbitrary text size, uppercase chrome. The other surfaces carry their rules in tiers 1 and 3. - The spec's prose carries judgement calls: grouping, hierarchy, which surface speaks which voice. Those go to the
better-*skills with DESIGN.md's values in hand.
A correction lands in the narrowest tier that can hold it for good. A size that repeats at two call sites becomes a kit variant and a line in DESIGN.md, and the check learns to reject the call-site spelling. A one-off class is the outcome to avoid.
Steps
-
Resolve the scope the way
interface-reviewdoes: the branch ahead of the merge base plus the working tree, or the target the user names. Keep files underapps/docs/src. -
Read the spec for the surface. DESIGN.md is organised per surface (
### Template Workbench,### Landing,### Learn, docs chrome); the Workbench's own guide isapps/docs/WORKBENCH-DESIGN.md. Read the section for every surface the change renders in, and "The label voice" whenever the change adds a label. -
Run the check on the changed files, with paths relative to
apps/docs. The lint config is type-aware, so in a new worktree runpnpm exec turbo run typecheck --filter=@zotlit/docsonce first: it generates the@/paraglidemodules the files import.pnpm --filter @zotlit/docs exec oxlint <changed files under src/>Each
zotlit-design/workbench-chromeerror namesfile:lineand the rule. Fix the cause in the kit or the spec; extend the rule when a new rule earned its place in DESIGN.md. Other diagnostics are this review's only when the change introduced them (git blamethe line). When no changed file is a non-test.tsxfile directly undersrc/lib/workbench/, report the check as covering none of the touched surfaces and carry on. -
Render the touched surfaces. Start the dev server and capture each touched surface at 1440 px and 640 px with agent-browser (conventions:
docs/agents/agent-browser.md; exportNO_PROXY='localhost,127.0.0.1'). Measure rather than eyeball: read control heights and font sizes from the DOM and compare them with the spec's numbers.agent-browser eval "JSON.stringify([...document.querySelectorAll('button')].map(b=>[b.textContent.trim().slice(0,24), Math.round(b.getBoundingClientRect().height), getComputedStyle(b).fontSize]))"A native
<select>with focus stalls screenshot capture; blur it, or capture before opening it.The Default profile locks the Match tab. To review Match, write a profile with its own id —
node .claude/skills/design-review/review-profile.mjs .scratch/review-profile.md— and load it through Open profile → Open profile from file. -
Route the judgement calls. Hand the rendered surfaces to
better-layout,better-typography, andbetter-uiwith the spec's values as the density system, so the reviewer applies 32 px / 12 px / 4-8-12-16 rather than its generic defaults.better-interfaceconsolidates the verdict. -
Report in the
better-*table format, one row per root cause with every location. Add aTiercolumn:kit,check, orspec, naming where the fix belongs. End withBlockwhile anyHIGHor anyworkbench-chromeerror remains,Approveotherwise. State every viewport and state you did not render asNot verified.
Extending the system
When a review finds a rule worth keeping:
- Put the value in the kit variant first (
button.tsx,input.tsx,native-select.tsx). - Write the decision into the matching DESIGN.md section as the target state, in one or two sentences.
- Teach
workbench-chromeinpackages/config/oxlint-plugin-design.tsto reject the call-site spelling of the same value, with a case inoxlint-plugin-design.test.ts. - Leave call sites naming only variants, layout classes (
flex-1,ms-auto,mt-2), and state classes (aria-pressed:*,data-pressed:*).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |