design-system
Gives implementers a working checklist so every screen uses primitives and tokens instead of one-off styles.
looks for
- raw hex colours, px spacing or font sizes in a component
- a new UI library or icon set being added
- a component duplicated across two screens
- a screen that only works in light mode
outputs
- → screens built from shared primitives
- → new tokens with light and dark values where needed
- → a clean run of {{TOKEN_CHECK}}
SKILL.md
Design system
The spec lives in {{DESIGN_SYSTEM}}. This is the working checklist.
One package
Use {{UI_LIBRARY}} and only it. Do not add another UI kit, icon set, CSS
framework or template. A missing component is a primitive you add to
{{PRIMITIVES_DIR}}, not a dependency.
Every page starts the same way
<PageShell>
<PageHeader title="…" actions={<PrimaryButton/>} />
<FilterBar>…</FilterBar>
<DataTableCard>…</DataTableCard>
</PageShell>
Reach for a primitive, not a box
| Need | Primitive |
|---|---|
| Titled block | SectionCard |
| Rows of data | DataTableCard (numbers right-aligned) |
| Search / filters | FilterBar |
| Actions on selected rows | BatchBar |
| Form | FormGrid (labels above, helper text for constraints) |
| Headline number | KpiCard |
| Status | StatusIndicator / Badge |
| Must act now | BannerAlert |
| Explanation | InfoTip |
| No data / loading / crash | EmptyState / Skeleton / ErrorFallback |
A component used by two screens moves to {{PRIMITIVES_DIR}} with a one-line doc comment.
Never type a style value
- Type: a variant from the scale, never a font-size number. Weights: 400/500/600/700 only.
- Colour: a palette or token key, never hex. New colour = new token with light and dark values.
- Spacing: scale units (e.g. 0.5, 1, 1.5, 2, 3, 4, 6), never raw px.
- Radius and shadow: set by the theme per component, not in screens.
Four states on every data surface
Error (banner + retry; old data stays) → loading (skeleton in place, no centred spinner) → empty (one action) → data.
Copy
Short labels, sentence case, verb + object buttons, errors say what to do next, no "please", no exclamation marks.
Both modes, keyboard, contrast
Check dark mode before finishing. Icon buttons have labels; dialogs return
focus; status never relies on colour alone; never outline: none.
Verify
{{TOKEN_CHECK}} # zero new findings in your files
{{VERIFY_COMMAND}}
Then screenshot the screen in light and dark. "Should look fine" is not proof.
Customize for your project
{{DESIGN_SYSTEM}}, {{UI_LIBRARY}}, {{PRIMITIVES_DIR}}, {{TOKEN_CHECK}}
(a script that greps for hex, px and font-size literals), {{VERIFY_COMMAND}}.
Rename the primitives to yours.
pairs with
- skilltrueorfalse
ui-hig
Checks a screen against platform guidelines and the Laws of UX and names the specific rule each problem breaks.
- a new screen or flow being designed
- small or crowded tap targets
- too many choices on one screen
Claude · Codex · ChatGPT - skilltrueorfalse
accessibility
Checks and fixes semantics, keyboard, focus, contrast, labels and motion against WCAG 2.2 AA.
- div or span used as a button
- custom controls (switch, tabs, menu, dialog, combobox)
- icon-only buttons
Claude · Codex · ChatGPT - skilltrueorfalse
motion
Sets the rules for presets, wrappers, reduced motion and performance so animation is consistent and 60 fps.
- library animation calls scattered through pages
- animating width, height, top, left or box-shadow
- no prefers-reduced-motion handling
Claude · Codex · ChatGPT - agenttrueorfalse
ui-review
Reviews only the changed lines of a UI diff and reports blocking vs. should-fix findings with quoted code and fixes.
- a diff under pages, components or theme
- hex colours, px values or font sizes added in a change
- a new data surface without loading/empty/error states
Claude · Codex · ChatGPT - personatrueorfalse
ui-ux-designer
Reviews layout, colour, density and component boundaries and outputs a precise design brief; does not write production code.
- a redesign request
- generic "AI slop" UI (random gradients, glows, wasted whitespace)
- inconsistent spacing or rogue colours
Claude · Codex · ChatGPT