design-system-author

Files (12)

• SKILL.md
• README.md · references/presets/
• components.md · references/presets/_template/
• layout-grid.md · references/presets/_template/
• preset.md · references/presets/_template/
• tokens.json · references/presets/_template/
• typography.md · references/presets/_template/
• components.md · references/presets/default/
• layout-grid.md · references/presets/default/
• preset.md · references/presets/default/
• tokens.json · references/presets/default/
• typography.md · references/presets/default/

SKILL.md (first lines)

# Design System Author

## When to use

You are the UI/UX Designer authoring or revising Figma content via MCP. Without a shared Foundation, every screen invents its own spacing scale (16px here, 12px there), text sizes (18pt vs 20pt for the same role), button radii (8px vs 12px), and alignment grid — drift compounds across screens and the Approver sees visual chaos at confirmation time. This skill is the **content-hygiene** complement to [`figma-canvas-layout`](../figma-canvas-layout/SKILL.md) (canvas-hygiene): same pre-handoff lint pattern, different concern.

Consult this skill:

- **In every Figma-writing mode** (`create` / `revise` / `incorporate`) — apply the Foundation tokens, never invent ad-hoc values.
- **In `import` mode** — extract what tokens already exist in the file; flag gaps as `figma-design-system-gap` open-issues.
- **As a pre-handoff lint** — every mode, every dispatch.

## Inputs and outputs

- **Inputs:** SRS §3.4.1 Design References (UI surfaces), SRS `## Design System` or brand-guidance section if present, the Figma file you're writing to via MCP.
- **Outputs:** A `Foundation` Figma page (separate Figma page tab) containing tokens + components; every other page's frames consume from Foundation; an updated `docs/uiux/handoffs/<task-id>.md` enumerating tokens used; a pre-handoff token-compliance lint report appended to the handoff doc.

## The Foundation page

Every Figma file the kit produces has a dedicated **Foundation** Figma page (separate page tab, NOT a section on a screens page). The Foundation page is the single source of truth for tokens + components. Screen pages reference it; screens never define their own colors, type styles, or spacing values.

Foundation is structured as five Figma sections. **Before authoring those sections from scratch**, run the Foundation-source selection step below — most projects inherit from a named preset, while Flow A projects may derive the Foundation from extracted Figma evidence.

### Step 0 — Foundation source selection (run BEFORE any of Sections 1-5)

The kit ships a catalog of named presets at `references/presets/<slug>/`. Each preset is a pre-authored Foundation: tokens, type scale, component minimum set, layout grid. For Design-Flow A, the SRS may instead declare `Design-Guideline: from-figma`, meaning the existing Figma file itself is the Foundation source and the Designer must build or audit against the design-extracted token evidence.

For every Figma-backed dispatch, the UI/UX Designer still captures token evidence from the Figma link regardless of the declared `Design-Guideline:` value. A preset or `none` value decides the Foundation source; it does not waive extraction of the live Figma palette, typography, spacing, radius, elevation, component-pattern, and grid evidence. The handoff must make clear which values are preset/defaulted and which values came from Figma.

#### Procedure

1. **Read the SRS header.** `docs/SRS.md` declares the chosen Foundation source in the `Design-Guideline:` field (set by BA Phase 1.X step 10b at sign-off time). Possible values:
   - A preset slug → e.g., `modern-saas-admin`, `ios-consumer`, `default`.
   - `from-figma` → Design-Flow A extracted enough design-token evidence from the provided Figma file to use it as the Foundation source. Build/audit Foundation from `docs/requirements/design-extracted/<figma-file-id>-*.md` Section 6.
   - `none` → no preset; author Foundation from the SKILL.md defaults (Sections 1–5 below).
   - Missing field → halt with `NEEDS_CONTEXT` and ask the Orchestrator to dispatch BA Mode D to set the field. Do NOT pick a preset unilaterally; the choice is BA + operator territory.

2. **For every Figma URL, load or require token evidence.** Read the latest `docs/requirements/design-extracted/<figma-file-id>-*.md` for each Figma URL in SRS §3.4.1 and inspect `## Section 6 — Design guideline extraction (Flow A)`. If no extraction exists for a Figma-backed project, halt and ask the Orchestrator to dispatch UI/UX Designer in `extract` mode before design handoff/implementation proceeds.
   - This applies even when `Design-Guideline:` is a preset slug or `none`; those choices do not erase the need to inventory what the Figma file actually uses.
   - If the live Figma file version is newer than the extraction evidence, halt with `NEEDS_CONTEXT` and ask whether to re-run extraction.

3. **If `Design-Guideline: from-figma`, use extraction evidence as the Foundation source.**
   - Use formal Figma styles/variables/components first when Section 6 identifies them.
   - When no formal styles exist, use medium/high-confidence repeated values from Section 6 as token candidates.
   - Build Sections 1–5 from the extracted palette, typography, spacing, radius, elevation/effects, component patterns, and layout grid evidence.
   - Preserve numeric values from the extraction. Do not "round" a 6px radius to 8px or convert a 20px spacing value to 24px unless the handoff explicitly records it as a fallback/deviation.
   - If a required token category is absent, fill the missing category from SKILL.md defaults and record the fallback in `## Design System Source` and `## Foundation Changes`.
   - If Section 6 is missing, low-confidence, or contradictory, halt with `NEEDS_CONTEXT`; do not silently switch to a preset.

4. **If a preset slug is declared, load the preset.** Read every file under `.claude/skills/design-system-author/references/presets/<slug>/`:
   - `preset.md` — when-to-use, dos / don'ts (apply throughout your authoring).
   - `tokens.json` — color + spacing + radius + elevation + motion + z-index tokens. **Apply these values verbatim to the Figma Foundation page's Sections 1, 3, 4 — do NOT invent your own values.**
   - `typography.md` — type scale + font stack + rules. **Apply to Section 2.**
   - `components.md` — required component set + variants + states + preset-specific additions. **Apply to Section 5.**
   - `layout-grid.md` — column system + breakpoints + container widths + vertical rhythm rules. **Apply to your page-level layouts and document in `## Foundation Changes` if you need to deviate.**

5. **Honour source-specific rules.** `preset.md` carries Dos / Don'ts for preset sources; Section 6 carries source evidence and gaps for `from-figma`. These ARE Foundation rules — bake them into your component variants + screen authoring. Example: a preset may forbid `text-transform: uppercase`; a `from-figma` extraction may show all cards use 12px radius and 24px internal padding. Both are enforced via the lint at Step 3 below.

6. **Note deviations explicitly.** If the SRS implies a Foundation value that conflicts with the declared Foundation source (e.g., SRS §3.4.1 specifies a custom brand color), document the deviation in the handoff doc's `## Foundation Changes` section. Do NOT silently override the source; the explicit annotation lets FE Dev + QA-Author know which values are preset-stock, Figma-extracted, or project-customized.

#### When to clone a preset

If the project consistently diverges from its declared preset on >3 token values, the cleaner long-term move is to clone the preset to a new slug:

1. `cp -r references/presets/<parent>/ references/presets/<new-slug>/`.
2. Edit the new preset's `preset.md` § Provenance to cite the parent + diff summary.
3. Apply the changes only to the new preset.
4. Re-dispatch BA Mode D to update SRS `Design-Guideline:` to the new slug.
5. Append the new preset to `.claude/skills/registry.md` § Design Guidelines.

Cloning preserves the parent for other projects and lets this project diverge cleanly. Avoid editing the shared preset in place for project-specific reasons.

#### When the preset is `none`

If `Design-Guideline: none`, author Foundation from the SKILL.md defaults below (Sections 1–5). Document in the handoff that no preset applies — FE Dev + QA-Author then derive tokens from your authored Foundation directly, not from any preset path.

#### When the guideline is `from-figma`

If `Design-Guideline: from-figma`, the Flow A design-extracted file is the source of truth. Build or audit the Foundation from its Section 6 token evidence:

- Colors, typography, spacing, radius, elevation/effects, component patterns, and layout grid values come from the extracted Figma evidence.
- The handoff `## Design System Source` section must cite the exact extraction artifact path, Figma version, and confidence level for every token category.
- Missing token categories use SKILL.md defaults only as explicit fallbacks. Each fallback is recorded so FE Dev and QA-Author know which values are extracted vs synthesized.
- If the live Figma file has drifted from the extracted evidence, halt with `NEEDS_CONTEXT` and ask whether to re-run `figma-requirements-extraction` before authoring.

---

### Section 1 — Color tokens

Define named colors as Figma color styles. Two layers:

- **Primitives** — raw color values (e.g., `gray-50`, `gray-100`, ..., `gray-900`; `blue-500`; `red-500`). Don't use primitives directly in screens.
- **Semantic** — purpose-bound aliases referencing primitives (e.g., `text-primary` → `gray-900`; `text-secondary` → `gray-600`; `surface-default` → `white`; `accent-brand` → `blue-500`; `state-error` → `red-500`; `state-success` → `green-500`; `border-default` → `gray-200`). Screens consume semantic tokens only.

Why two layers: changing the brand color updates `accent-brand`'s primitive reference once; every screen that consumes `accent-brand` updates automatically. Direct-primitive consumption defeats this.

### Section 2 — Typography tokens

Define named text styles as Figma text styles. Default scale (modular ratio 1.250, 16px base):

| Name | Size | Weight | Line height | Use |
|---|---|---|---|---|
| `heading-xl` | 48px | 700 | 56px | Page-hero title |
| `heading-lg` | 32px | 700 | 40px | Section title |
| `heading-md` | 24px | 600 | 32px | Card title |
| `heading-sm` | 20px | 600 | 28px | Inline group title |
| `body-lg` | 18px | 400 | 28px | Lead paragraph |
| `body-md` | 16px | 400 | 24px | Default body text |
| `body-sm` | 14px | 400 | 20px | Secondary text, captions |
| `label-md` | 14px | 600 | 20px | Form label, button text |
| `label-sm` | 12px | 600 | 16px | Tag, badge, micro-label |
| `code-md` | 14px | 400 | 20px | Monospace inline code |

Pair with a defined font family (e.g., Inter for body, system monospace for code). Document the family name in Section 2.

### Section 3 — Spacing tokens

Define named spacing values as a 4pt baseline scale (override to 8pt if SRS's design system mandates):

From evolplus/talos, Apache-2.0.

More from evolplus/talos