git:20260823.f8dbcee to git:20260823.6c4368b

---

model_tier: inherit

name: design-system-capture

description: "Write and maintain DESIGN.md + PRODUCT.md — captures visual decisions and interaction patterns so design tasks stay consistent across sessions without re-scanning past work."

domain: engineering

personas:

- frontend-engineer

workspaces:

- engineering

packs:

- frontend-design

token_budget_class: rich

scope:

write: []

verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."

execution:

type: manual

---

# 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.

>

> Gated by `tokens.rich_skills` in `.agent-settings.yml` (default `on`).

> If `off`, skip rich context loading and work from brief alone.

## 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:**

```markdown

# 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]

Example: "Information-dense dashboard; optimize for power users, not casual exploration."

## 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; the anti-slop detector 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.]

```

### `PRODUCT.md` — cross-feature interaction patterns

Captures *interaction decisions* that should be consistent across features.

Unlike a feature spec (which describes one feature), PRODUCT.md captures

patterns that apply everywhere.

**Format:**

```markdown

# PRODUCT.md — [Project name] interaction patterns

> AI-readable cross-feature pattern memory. Update when a new pattern is established.

> Last updated: [date]

## Destructive actions

Policy: [typed confirmation ("DELETE") / dialog with verb button / undo toast / etc.]

Example: "All destructive actions require the user to type 'DELETE' or the resource name."

## Mutation feedback

Policy: [optimistic UI + inline undo / loading spinner / success toast / etc.]

Undo window: [N seconds, or "not applicable"]

Example: "Optimistic UI for all mutations; inline undo toast for 5 seconds, then commit."

## Filter and sort persistence

Policy: [URL params / localStorage / session / not persisted]

Restore on load: [yes / no]

## Empty states

Approach: [illustration + CTA / text only / skeleton / etc.]

Example: "Illustration + primary CTA for empty lists; text-only for zero-search-results."

## Error handling

Approach: [inline field errors / toast / error boundary / etc.]

Network errors: [retry + message / fail fast / etc.]

## Navigation and routing

Pattern: [SPA / MPA / hybrid / etc.]

Active state: [how active nav items are marked]

## Mental model

One sentence: [how the product conceptualizes itself to the user]

Example: "Dashboard = control panel for power users, not an exploration space."

```

## Procedure

### Step 1 — Assess what exists

1. Check if `DESIGN.md` and `PRODUCT.md` already exist in the project root.

2. If they exist: read both → skip to Step 3 (Update).

3. If they don't exist: run `existing-ui-audit` (if not already done for this session) to inventory existing components, tokens, and conventions → proceed to Step 2.

### Step 2 — Create (first run)

1. **Extract visual decisions from the audit** (`state.ui_audit`): dominant

radius values, shadow patterns, spacing conventions, motion patterns.

Fill the DESIGN.md template above with the observed values. Mark

un-observed sections as `TBD`.

2. **Extract interaction decisions from the codebase**: scan for delete

confirmation patterns, toast/feedback patterns, filter/URL persistence.

Fill the PRODUCT.md template. Mark un-observed sections as `TBD`.

3. Write `DESIGN.md` and `PRODUCT.md` to the project root.

4. Surface a one-paragraph summary: what was captured, what is still TBD,

and what action the user should take (review and correct the TBDs).

### Step 3 — Update (subsequent runs)

1. Read existing `DESIGN.md` and `PRODUCT.md`.

2. Identify any decisions made in recent tasks that aren't yet captured

(e.g., a modal was built with 12px radius — add that to DESIGN.md).

3. Correct any TBDs that are now resolved.

4. Update the "Last updated" date.

5. Output a diff summary: what changed and why.

## Importing an extracted design system

## How the design skills consume these documents

When `DESIGN.md` or `PRODUCT.md` is present in the project root:

- **`design-intelligence`** and **`fe-design`**: read DESIGN.md at the

start of any design task — use the captured decisions as project

constraints that override corpus suggestions.

- **`ui-component-architect`**: read DESIGN.md for radius/shadow/motion

conventions before proposing any new component.

- **`existing-ui-audit`**: when a full audit is impractical (large project),

read DESIGN.md as a proxy for "what this project's conventions are".

The boundary from `brand-to-tokens`:

- `.tokens.json` carries primitive values (gray-700 = #374151)

- DESIGN.md carries usage decisions (elevated surfaces use 8px radius,

not 4px or 12px)

Both are consumed together; DESIGN.md takes precedence for usage questions.

## Design→dev handoff README (template)

When handing a design to implementation, emit a README a developer can build

from **without the mockup open**. Template only — no vendored values (tokens

come from the consumer's `.tokens.json` / DESIGN.md):

```markdown

# <Feature> — implementation handoff

Fidelity: <hi-fi = pixel-recreate the mockup | lo-fi = apply the codebase's

existing design system, mockup is directional only>

## Screens

- <screen>: components used + each component's states (default/hover/active/

disabled/empty/error/loading)

## Interactions

- <interaction>: trigger → result, duration + easing (name the token, not a ms

literal)

## Tokens

- Color / type / spacing / radius: reference DESIGN.md / .tokens.json — do not

inline hex or px

## Done means

- Implementable from this README alone; every state and interaction named.

```

Fidelity declaration is load-bearing: hi-fi vs lo-fi tells the dev whether to

recreate the mockup pixel-for-pixel or apply the existing system — the single

most common handoff ambiguity.

## Design-system extraction floor

When the goal is to extract this repo's design system as a **reusable package

artifact** (not just DESIGN.md prose), the extraction meets this floor — the

handoff shape emitted alongside `design-system.json`

([import contract](references/design-system-json.md)).

- **Contract contents.** A complete extraction carries: a root guide / manifest;

token CSS (or the stack's equivalent); the typography / colour / spacing /

iconography foundations; component specimens; an asset inventory (logos, icons,

fonts); UI-kit screens; and starting-point templates where appropriate.

- **Specimen granularity.** Many small foundation cards beat one dense dump —

each specimen demonstrates ONE reusable sub-concept (a single button state,

one spacing step, one elevation level), so a consumer lifts concepts

individually rather than parsing a monolith.

- **Developer handoff bundle** (extends § Design→dev handoff README): a

high-fidelity reference, behaviour notes, the assets list, the component

mapping (design name → code component), responsive states, known caveats, and

— when the artifact is a mock — an explicit "prototype, not production code"

warning so a consumer never ships the reference verbatim.

**What to capture FROM** a running project: sources first, SSR fetch second,

rendered snapshot only with consumer tooling; record the git SHA. Rationale:

[snapshot preference order](references/snapshot-preference-order.md).

## Gotcha

- **Over-writing instead of diff-updating** — the most common failure.

Always read existing `DESIGN.md`/`PRODUCT.md` before writing; carry

all existing decisions forward and only add/correct. Losing prior

captured history is worse than capturing nothing.

- **Copying tokens into DESIGN.md** — DESIGN.md is NOT a copy of

`.tokens.json`. It captures *usage decisions* ("8px radius on elevated

surfaces"), not primitive values ("gray-700 = #374151"). The

distinction is what makes DESIGN.md actionable.

- **Capturing feature-specific behavior** — PRODUCT.md is for patterns

that repeat across 2+ features. A delete-confirmation pattern in one

form does NOT belong in PRODUCT.md until it appears in at least two

independent features.

## Do NOT

- Do NOT overwrite DESIGN.md/PRODUCT.md without first reading and diffing

the existing content — accumulated history is the value.

- Do NOT make DESIGN.md a copy of `.tokens.json` — it captures decisions,

not token definitions.

- Do NOT capture feature-specific behavior in PRODUCT.md — only patterns

that repeat across multiple features.

- Do NOT mark a decision as captured without evidence from the actual codebase.

## Output format

On create:

1. Write `DESIGN.md` to the project root with the extracted visual decisions.

2. Write `PRODUCT.md` to the project root with the extracted interaction patterns.

3. Surface a one-paragraph summary of what was captured and what is TBD.

4. List any questions where the existing code is ambiguous.

On update:

1. Update both files with new decisions.

2. Output a short diff: "Added: destructive-action policy. Updated: motion strategy (was TBD, now spring)."