Design System

Design System

Turn a brief into a validated design system, recorded in DESIGN.md at the project root — the identity file every later design session reads first. This skill also scopes the page set into a PAGES.md skeleton, which the greyboxing skill owns from then on.

Stack-agnostic: express the tokens through the project's own theming mechanism (CSS variables, Tailwind theme, component library — whatever the stack offers).

Prerequisites

When one is missing, tell the user before the step that needs it.

1 — Design read

Read the brief's signals before touching a token: project kind, vibe words, linked references, audience, existing brand assets, and quiet constraints (accessibility-first, regulated, trust-first — these override aesthetic preference).

Declare the read in one line: "Reading this as: <project kind> for <audience>, with a <vibe> language, leaning toward <aesthetic family or design system>."

If the read genuinely diverges, ask one clarifying question — never a questionnaire. A reference image or site the user pins is a pinned aesthetic: record it in DESIGN.md; downstream reviews may not challenge it.

2 — Surfaces

Ask how many surfaces the project has (marketing site, app dashboard, docs…). Each surface gets its own design read line and its own dials; all surfaces share one set of primitives.

3 — Dials

Set three dials per surface, 1–10, inferred from the design read. Every layout and motion decision downstream is gated by these values — greyboxing reads them from DESIGN.md.

4 — Scope the page set

Identify the project type and select the matching page categories:

Load only the selected categories from pages.md and trim pages the project genuinely lacks. Then derive the navigation structure (header links, footer groupings, secondary nav) and tier each page:

• signature — carries conversion or identity (home, listing, product detail, pricing, main dashboard). Gets the full greyboxing loop with prototype variants.
• utility — convention is the right design (legal, auth, 404, settings, confirmations). Direct build — but the full review still applies.

Gate: the user confirms the page list, the tiers, and the navigation structure.

5 — Foundation branch

Pick one per surface:

• Official design system — the brief reads as an established ecosystem (Fluent, Material, Carbon, Polaris, Primer, Atlassian, GOV.UK/USWDS, shadcn/Radix): install and theme the official package. Honesty rule: never recreate a real system's CSS by hand, and one system per surface — never two mixed.
• Replicate a reference site — the user names a site: invoke extract-theme on that URL and adapt its output.
• From scratch — derive tokens from the project's subject, audience, and brand material. The subject's own world — its materials, instruments, vernacular — is where distinctive choices come from.

6 — Tokens

Define every family in one theme source per project (primitives + a semantic layer per surface):

Motion defaults, tuned by the surface's MOTION_INTENSITY:

Easing: natural deceleration — cubic-bezier(0.16, 1, 0.3, 1) for confident arrivals; exits at ~60–70 % of the enter duration; one duration/easing token set globally.

Rotation discipline: DESIGN.md logs the palette family and display face used. Rotate — the previous project's choices are off the table unless the brief pins them.

7 — Grill

Invoke the grilling skill on the decisions so far: design read, dials, foundation choice, palette and type direction. Mandatory — this is the most leveraged, hardest-to-reverse decision set in the pipeline.

8 — Showcase & validation

Invoke the prototype skill (UI branch) to render a token showcase — swatches, type scale, spacing/sizing/radius/elevation scales, motion demos playing their real durations and easings — one per surface where surfaces diverge.

Done when: the grill is done, the user has validated the showcase, and DESIGN.md plus the PAGES.md skeleton are written.

DESIGN.md schema

# DESIGN — <project>

## Brief
Design read (one line per surface) · pinned aesthetic · quiet constraints.

## Dials
| Surface | DESIGN_VARIANCE | MOTION_INTENSITY | VISUAL_DENSITY |

## Primitives
Shared brand DNA: palette, type faces, scales — pointer to the theme source file.

## Surface: <name>
Foundation (official system | replicated | from scratch) · theme (light / dark / auto) ·
semantic token mapping · voice notes for copy.

## Rotation log
Palette family and display face used (this project and known past ones).

PAGES.md skeleton

Created here with the scoping data; greyboxing owns and updates it afterwards:

# PAGES — <project>

## Navigation
Header links · footer groupings · secondary nav.

## Pages
| Page | Surface | Tier | Key sections (from the catalog) | Status |
| ---- | ------- | ---- | ------------------------------- | ------ |
| Home | marketing | signature | hero, social proof, features, … | scoped |

## Site pass
Status: pending