| name | design-check |
| description | Visual and UX review pass for any change that touched UI — frontend components, HTML, CSS, templates, dashboards, CLI output formatting, or anything a human looks at. Use whenever a diff includes UI files, when the user asks for a design review, or as part of /ship. If the diff touched nothing user-visible, state that and exit immediately. |
Design Check
Step 0: Applicability
Inspect the diff. If nothing user-visible changed (no frontend files, templates, styles, CLI output, emails, rendered docs), say "No UI surface touched — design check not applicable" and stop. Do not invent work.
Step 1: Render it
You cannot review design from source code alone.
- Web UI → run the dev server and screenshot the changed views (Playwright/puppeteer if headless). Capture at least one narrow viewport (~380px) and one desktop width.
- CLI output → run the command and capture actual terminal output, including a case with long values and a case with empty results.
- Generated documents/emails → render to the final format and look at it.
Step 2: Review against this checklist
Consistency
- Matches the existing design system / component library of the repo. New one-off styles need justification.
- Spacing, type scale, and colour come from existing tokens or variables, not hardcoded values.
States
- Loading, empty, error, and overflow states all exist and look intentional.
- Long text: does it truncate, wrap, or break the layout?
- Interactive elements have hover/focus/disabled states.
Accessibility
- Sufficient colour contrast; information not conveyed by colour alone.
- Focus order and keyboard operability for anything interactive.
- Images/icons that convey meaning have accessible labels.
Taste
- Avoid AI-default clichés: gratuitous purple gradients, Inter-by-default, emoji-as-decoration, cards inside cards.
- Alignment is deliberate. Nothing is "almost" aligned.
- Density appropriate to the audience (data tools can be dense; marketing pages breathe).
Step 3: Fix or flag
Fix mechanical issues directly (a missing empty state, hardcoded colour, broken responsive layout). Flag judgement calls for the user with a screenshot and a one-line recommendation each — don't redesign unilaterally.
Step 4: Verdict
- PASS — with screenshots as evidence.
- PASS WITH NOTES — list flagged judgement calls.
- FAIL — list blocking issues; loop back after fixes.
Gotchas
- The most common failure is skipping rendering and reviewing the JSX/CSS as text. Render first, always.
- Check the diff's effect on neighbours: a width change in a shared component breaks pages you didn't touch.
- Dark mode: if the repo supports it, screenshot both modes.
- If a
frontend-design skill is installed, defer to it for aesthetic standards and use this skill for the process/checklist.
