design-system-capture

design-system-capture

Solves "design amnesia" — the failure mode where every AI design task re-invents visual patterns (radius, shadows, motion, spacing) and interaction patterns (destructive-action handling, optimistic UI, filter persistence) because the agent has no cross-task memory of decisions already made.

Boundary: brand-to-tokens extracts primitives (colors, font families → DTCG tokens). existing-ui-audit inventories what exists. This skill captures usage decisions: "we use 8px radius for elevated surfaces", "all destructive actions require typed confirmation". They are complementary, not redundant.

Why this skill is rich

DESIGN.md and PRODUCT.md serve as the project's design memory. To write useful capture documents and to read/apply them effectively, the agent needs full templates with worked examples showing what a well-structured DESIGN.md and PRODUCT.md look like in practice. A condensed version that says "write down your design decisions" produces documents too vague to be useful. The worked examples teach agents both the vocabulary (elevation, motion strategy, destructive-action policy) and the specificity level that makes these documents actionable across tasks.

When to use

• Starting a new consumer project (initial capture, run once early)
• After 2+ design tasks in the same project (update to capture what was decided)
• When a subsequent design task produces inconsistent results (audit and reconcile)
• Explicitly asked: "capture the design system", "write a DESIGN.md", "document our patterns"

The two documents

DESIGN.md — visual-system decisions

Captures the visual usage decisions (not token primitives) that agents should apply consistently across all UI tasks in this project. Unlike tokens.json (which records what a color value IS), DESIGN.md records how and when to use it.

Format:

# DESIGN.md — [Project name] visual system

> AI-readable project design memory. Update after each design decision.
> Last updated: [date]

## Design philosophy
One sentence: [density/formality/complexity philosophy]

## Owned components
| Component | Status | Story file | Registry item |
|---|---|---|---|
| [Name] | stable \| experimental \| deprecated | [path to *.stories.tsx] | [registry item name, or —] |
Example: "Information-dense dashboard; optimize for power users, not casual exploration."

## Owned components — filled from the tree, never from memory

The § Owned components table is populated by **globbing `*.stories.tsx`** (and, when a
Storybook manifest is reachable, reading it — see
[`storybook-workshop`](../storybook-workshop/SKILL.md) § MCP path). One row per component
the project owns: its name, its status, its story file, and its registry item where the
library publishes one.

**Never write a row from memory.** A remembered component is exactly the row a reader will
trust and a `ui-component-architect` run will then skip re-checking — an inventory that is
wrong in the direction of "we already have this" causes the duplicate it exists to prevent.
A component with no story file gets a row with an empty story cell, not an omission: absent
from the table reads as "does not exist".

`deprecated` rows stay in the table. Deleting one loses the only durable record that the
component should not be reached for again.

## Visual system

### Elevation and radius
- Elevated surfaces (modals, sheets, dropdowns): [X]px radius, [shadow-spec]
- Inline elements (cards, chips): [X]px radius
- Buttons: [X]px radius

### Shadows
- Elevated: [box-shadow value]
- Floating (tooltips, popovers): [box-shadow value]
- None (flat cards): [confirm]

### Motion
- Overlays and modals: [spring / easing spec + duration]
- Micro-interactions (button feedback, toggles): [duration + easing]
- Page transitions: [strategy or "none"]

### Spacing
- Base unit: [X]px
- Card padding: [spec]
- Section gap: [spec]
- Tight grouping: [spec]

### Color usage
- Primary action: [token name]
- Destructive: [token name]
- Surface hierarchy: [primary bg → secondary bg → elevated bg]

## Taste Dials
Three 1–10 dials that tune generation. Absent = unset (design-intelligence
infers from the brief via its Dial Inference Table). One-line rationale each.
- Variance: [1–10] — [why; 1 = perfectly symmetric, 10 = expressive/asymmetric]
- Motion: [1–10] — [why; 1 = static, 10 = cinematic]
- Density: [1–10] — [why; 1 = airy, 10 = packed/data-dense]

## Consistency Locks
Within-project invariants (derived from the confirmed system). A value outside
a declared Lock is off-system; `design_lock.ts` flags it (rebuttable).
- Theme Lock: [single | light+dark via prefers-color-scheme] — no mid-surface inversion
- Colour Lock: [one accent family] — [the accent hue]
- Shape Lock: [one corner-radius scale] — [the radius set, e.g. 6/12/16px]

## Stack and conventions
- CSS approach: [Tailwind / CSS modules / styled-components / etc.]
- Component primitives: [shadcn / Radix / Headless UI / custom]
- Icon system: [Phosphor / Heroicons / Lucide / etc.]