git:20260626.d9fb956 to git:20260705.5a5efb9

---

name: do-design-system

allowed-tools: Read, Write, Edit, Grep, Glob, Bash

---

# Design System Skill

## Repo Context Probe

If `.claude/skill-context/do-design-system.md` exists, read it and honor its declarations; otherwise use the generic defaults described below.

The moodboard scrape, `.pen` JSON editing, motif tables, and gap-audit log are all generic — they need only a browser surface and a JSON-editable `.pen`. The context file declares the repo-specific machinery for Steps 5–7: the **deterministic generator** that emits downstream artifacts (`brand.css`, `source.css`, `design-system.md`) from the `.pen` source, any **PreToolUse hooks** that guard those generated artifacts, and the reference implementation. When the file is absent (the common case in a foreign repo), there is no generator — sync `brand.css` from the `.pen` variables by hand (Step 6) and skip the hook-specific guidance.

## Scope

This skill edits ONLY:

- `docs/designs/design-system.pen` (reserved filename — the system source)

- `docs/designs/charter.md` (when scaffolding)

- `docs/designs/gap-audit.md` (append-only)

- `docs/designs/inspiration/**` (adds images + per-pass README)

- `docs/designs/README.md` and `docs/designs/product/README.md` (indexes)

- Downstream CSS: brand tokens + Tailwind `@theme` bridge

The skill MUST NOT touch:

- Any `.pen` file other than `design-system.pen` (product/ wireframes,

flows, mockups have different schemas and will be corrupted)

- Application code, templates, or component implementations

- Renames or deletions of existing tokens/components

## When to load sub-files

## Inputs

1. **Moodboard URL** (Cosmos / Pinterest / Are.na / plain image folder).

2. **`docs/designs/charter.md`** — principles, voice, a11y targets, token

tiers, component taxonomy, font licensing. If missing, offer to

scaffold from `charter-template.md`. MUST exist before moodboard

edits can land.

3. **`docs/designs/design-system.pen`** — source of truth, plain JSON.

4. **Downstream CSS** — `brand.css` (tokens) + `source.css` (Tailwind

bridge, if present).

5. **`docs/designs/gap-audit.md`** — append-only changelog.

## Pipeline

## Step 0 — Audit file organization

## Step 3 — Critique the existing system

For each absent/partial motif, write one paragraph:

> **Problem.** What's missing and why the moodboard says it matters.

> **Evidence.** Specific image references (e.g. #04, #06).

> **Fix.** One concrete edit.

> **Principle.** Which charter principle this supports.

If an edit doesn't align with any charter principle, either:

- Drop it (the moodboard is pulling the system off-brand), or

- Propose a charter amendment FIRST, in a separate commit, before

landing the edit.

Avoid these critique failure modes:

- **Narrating what's already there.** Only call out gaps.

- **Demanding renames.** Rename = breaking change for downstream

templates. Defer to a separate pass.

- **Adding five cards.** If the system has N near-duplicate variants,

flag for consolidation but don't ship the consolidation in this pass.

## Step 4 — Propose minimal additive edits

Present as a table. Target 3–7 edits — enough to shift the system,

few enough to land cleanly in one commit.

```markdown

| # | Edit | Tier | Why | Principle |

|---|---|---|---|---|

| 1 | Add --font-serif = Lora | semantic | Editorial voice for research titles | Editorial over marketing |

| 2 | Retune --status-operational #4CAF50 → #5C7A3E | semantic | Kill Material green | Honest, not clever |

| 3 | New component Annotation/Crosshair | component | Pairs with existing Annotation/Mark | Dense information before whitespace |

```

**Invariants:**

- **Additive only.** New tokens, new components, retuned values. No

renames, no deletions.

- **Reuse existing orphan tokens before inventing new ones.** If the

moodboard calls for gold and `--warm` exists but is unused, use

`--warm`. Don't add `--gold`.

- **Tier-aware naming.** New tokens land in the charter's declared tier

(primitive / semantic / component). Semantic by default.

- **Component taxonomy match.** New components use `Category/Variant`

from charter's taxonomy list. If no category fits, propose adding

one to the charter FIRST, in a separate edit.

- **Font licensing.** Any new font requires a listed license in the

charter's fonts table. Add the row before adding the token.

- **Accessibility.** Retuned colors verified against charter's contrast

targets. Don't land a token that fails the stated WCAG target.

- **State rationale in one line.** If you can't say why in one line,

the edit is not tight enough.

Get explicit approval before applying. The user may swap typefaces,

cut edits, retune hexes, or contest the principle citation. Do not

proceed on assumed approval.

## Step 5 — Apply edits to `design-system.pen`

## Step 6 — Sync downstream CSS

Downstream artifacts — `brand.css` (`:root` tokens), `source.css` (Tailwind `@theme` bridge), and

any `design-system.md` — must mirror the `.pen` source 1:1.

- **Context file declares a generator** → run it exactly as specified. Such a generator is

typically deterministic (running twice produces byte-identical output) and emits every artifact

from the `.pen`. In that case do NOT hand-edit the generated files — the repo may register a

PreToolUse hook that blocks direct Write/Edit against them and a commit-time hook that blocks on

drift. Follow the context file's invocation and lint step.

- **No context file (generic case)** → there is no generator. Hand-edit `brand.css` so its token

names and values match the `.pen` variables exactly (and `source.css` if the project uses

Tailwind). Token-name divergence between the `.pen` and the CSS is silent, so mirror them

carefully.

For each new component, decide whether to ship a CSS class now or defer

until a template needs it. Speculative classes rot; defer is usually

right.

## Step 7 — Produce the gap-audit diff (before commit)

Record what this pass changed in `gap-audit.md` as a dated section, BEFORE `git commit`.

- **Context file declares a generator with an audit mode** → run its audit step (which diffs the

regenerated artifacts against `HEAD`) before committing, and follow its ordering constraints

(the diff must be produced while `HEAD` still holds the prior pass's generated state). Paste its

output into `gap-audit.md`.

- **No context file (generic case)** → hand-write the dated section: list the variable edits, new

components, and downstream CSS updates this pass made.

Append the audit/change summary to `<pen-dir>/gap-audit.md` under:

```markdown

## YYYY-MM-DD — <theme slug>

**Moodboard:** `inspiration/YYYY-MM-DD-<theme>/` (source: <URL>)

<paste the output of `--audit` here>

### Still open

- Card consolidation (deferred — 5 near-duplicate variants)

- Serif body scale (deferred until first research page ships)

```

Update the running component count in the doc header.

**Never add `product/` files to this audit.** It is design-system

scope only.

## Step 8 — Commit

Stage only your own files:

```bash

git add docs/designs/design-system.pen \

docs/designs/charter.md \

docs/designs/gap-audit.md \

docs/designs/inspiration/ \

<css-root>/brand.css <css-root>/source.css

git status --short # verify nothing unexpected is staged

git commit -m "design: <theme> pass — <one-line summary>

<body: variable changes, new components, downstream CSS updates,

gap-audit additions. Reference moodboard pass folder.>

"

```

## Reference implementation