Skip to content

aidenlx/zotlit / .claude/skills/design-review

design-review

Verified

Reviews 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.

FileKindSize
SKILL.mdskill md4.7 KB
review-profile.mjsscript646 B
---
name: design-review
description: Reviews 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:

1. **The kit** (`apps/docs/src/components/ui/*`) carries every size, so a call site names a variant and nothing else.
2. **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 in `apps/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.
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

1. **Resolve the scope** the way `interface-review` does: the branch ahead of the merge base plus the working tree, or the target the user names. Keep files under `apps/docs/src`.

2. **Read the spec for the surface.** DESIGN.md is organised per surface (`### Template Workbench`, `### Landing`, `### Learn`, docs chrome); the Workbench's own guide is `apps/docs/WORKBENCH-DESIGN.md`. Read the section for every surface the change renders in, and "The label voice" whenever the change adds a label.

3. **Run the check** on the changed files, with paths relative to `apps/docs`. The lint config is type-aware, so in a new worktree run `pnpm exec turbo run typecheck --filter=@zotlit/docs` once first: it generates the `@/paraglide` modules the files import.

   ```bash
   pnpm --filter @zotlit/docs exec oxlint <changed files under src/>
   ```

   Each `zotlit-design/workbench-chrome` error names `file:line` and 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 blame` the line). When no changed file is a non-test `.tsx` file directly under `src/lib/workbench/`, report the check as covering none of the touched surfaces and carry on.

4. **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`; export `NO_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.

   ```bash
   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**.

5. **Route the judgement calls.** Hand the rendered surfaces to `better-layout`, `better-typography`, and `better-ui` with 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-interface` consolidates the verdict.

6. **Report** in the `better-*` table format, one row per root cause with every location. Add a `Tier` column: `kit`, `check`, or `spec`, naming where the fix belongs. End with `Block` while any `HIGH` or any `workbench-chrome` error remains, `Approve` otherwise. State every viewport and state you did not render as `Not 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-chrome` in `packages/config/oxlint-plugin-design.ts` to reject the call-site spelling of the same value, with a case in `oxlint-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:*`).
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall