design-pass
Target: $ARGUMENTS
Toolkit: ${CLAUDE_SKILL_DIR}/../ui-audit/scripts/ · Checklist: ${CLAUDE_SKILL_DIR}/reference/review-checklist.md
1. Baseline (before touching code)
Make sure the dev server is running (start it in the background if needed; never run a production build), then:
node ${CLAUDE_SKILL_DIR}/../ui-audit/scripts/audit.mjs http://localhost:<port> --pages <path> --widths 375,768,1440 --dark --out /tmp/design-pass/before
2. Audit before patching
- Find every component the target renders, and every other place that renders the same pattern (grep class strings and component names).
- Reuse an existing primitive (button, card, modal, section heading) before writing a new one. If the same markup appears 2+ times, extract it, then restyle once.
- Build exactly what was asked. No new sections, badges, toggles or animations unless asked.
- Use project tokens only. If a value isn't in the scale, use the nearest step, or propose a token (see
design-ref).
3. Apply
Work through the checklist: hierarchy, one primary action per view, the spacing scale, the type scale, empty/loading/error states, and inputs ≥ 16 px on mobile.
4. Verify
node ${CLAUDE_SKILL_DIR}/../ui-audit/scripts/audit.mjs http://localhost:<port> --pages <path> --widths 375,768,1440 --dark --out /tmp/design-pass/after
node ${CLAUDE_SKILL_DIR}/../ui-audit/scripts/diff.mjs /tmp/design-pass/before /tmp/design-pass/after
- Read the after-sheets for every width in light and dark mode. Look at the diff PNGs for unintended changes outside the target.
- Grayscale check: re-run one width with
--inject "document.documentElement.style.filter='grayscale(1)'". - Then the full
ui-auditwidth set once, and typecheck + lint (no build). - If the project keeps a Figma file in sync with code, update the matching frames in the same task.
Exit criteria
- No sideways scroll, no new contrast or axe findings compared with before.
- Diff shows changes only where intended.
- No new component that duplicates an existing one, and no unrequested UI.
- Dark mode checked, or confirmed the project has none.
- Typecheck and lint pass.
- A short summary to the user, plus the 1–2 sheet paths worth looking at.