design-system

Establish the visual foundation every later design task builds on. Run once per project, or to recalibrate. Present a draft for approval before writing any file or touching any style.

Modes: Create (no system yet) | Audit (styles exist but are inconsistent) | Extend (add dark mode, density, motion, a new component family). Infer from the repo; ask if unclear.

Related: design consumes the system | accessibility audits the result | de-slop finds generic defaults | copywrite voice.md for a matching verbal voice.

Step 1: Context

Read product docs and any existing design, convention or voice docs. Detect how styling is done: utility CSS config (Tailwind and similar), CSS custom properties, CSS modules, CSS-in-JS theme, a component library theme, or native/platform styles. Express tokens in the project's existing mechanism. Don't add a parallel system.

Step 2: Audit what exists

Count distinct values per category across stylesheets and 5-10 key components:

grep -rhoE '#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|hsla?\([^)]*\)' <src> | sort | uniq -c | sort -rn | head -40
grep -rhoE 'font-size: *[^;]+|border-radius: *[^;]+|box-shadow: *[^;]+' <src> | sort | uniq -c | sort -rn | head -40

Adapt the patterns to the stack (utility classes, theme objects). Report the number of distinct colours, font sizes, radii, shadows and spacing values, and the clearest inconsistencies (three greys for muted text, two radii on cards). Those are what the system fixes. Note existing contrast failures.

Step 3: Brief

Ask only what the repo can't answer: audience and mood, brand assets that must be kept (logo colours, fonts), platforms, themes needed (light, dark, both), density (data-heavy tool vs marketing site), accessibility target (default WCAG 2.2 AA).

If a look already exists and works, codify it with improvements; don't replace it with something unrecognisable.

Step 4: Draft the system

Load references/foundations.md (tokens, colour, type, spacing, shape, elevation, motion, layout) and references/components.md (states and patterns). For every colour pairing, run the contrast check in foundations.md and put the results in the draft.

Step 5: Present, refine, save

Load references/output.md. Show the full draft with a swatch or sample for each decision and the contrast results. Refine with the user. After approval:

1. Save the reference doc in the project's docs location and add a pointer in its agent or context file.
2. Apply the tokens to the project's mechanism. Only with approval, and in batches.
3. Verify (build, light and dark screenshots if a browser is available, leftover hard-coded values).

Rules

• Specific values, not "a nice blue".
• Name by role, not value. action, not blue-600; roles survive palette changes.
• Contrast is checked, not assumed, in both themes.
• Restraint is a decision, not a rule. Each extra colour, typeface or radius must earn its place by a distinct job.
• Keep the doc under 150 lines. One nobody reads is worse than none.
• Don't change visual design as a side effect of an audit. Report first.