/design-system

name: design-system
description: Generate a brand-agnostic DESIGN.md (Google design.md spec format) plus tokens.css and showcase.html for any branding project. Reads ./design/<brand-slug>/DESIGN-PLAN.md if present, otherwise asks for an inline brief. Use AFTER design-plan and BEFORE design-ui-components. Triggers include "design system for [brand]", "build a DESIGN.md", "generate design tokens", "/design-system".

Skill: design-system

Generates three artifacts that together define a brand's visual system:

1. **`DESIGN.md`** — portable spec following the [Google design.md format](https://github.com/google-labs-code/design.md). YAML frontmatter (machine-readable tokens) + 8 markdown sections (human rationale). 2. **`tokens.css`** — CSS custom properties exported from the YAML, consumed by `design-ui-components` and every platform skill. 3. **`showcase.html`** — single self-contained HTML page that renders every token in context. The visual proof that the system holds together.

When to use

• After `/design-plan` has produced `DESIGN-PLAN.md`
• Before any platform artifact skill (LinkedIn, Twitter, YouTube, etc.) — they all read `DESIGN.md` and `tokens.css`
• When iterating on brand: re-run to regenerate downstream files when the plan changes

Inputs

• **Required:** brand slug (e.g. `shane-personal`)
• **Preferred:** existing `./design/<brand-slug>/DESIGN-PLAN.md` (read with Read tool)
• **Fallback:** if no plan exists, ask the user for a 3-question inline brief (visual direction, voice adjectives, hard NOs)

Outputs

./design/<brand-slug>/
  DESIGN.md          # Google spec format
  tokens.css         # CSS custom properties
  showcase.html      # visual proof

Steps

1. Locate and read the plan

test -f ./design/<brand-slug>/DESIGN-PLAN.md

If present, read it. If absent, ask the user 3 quick questions (visual direction, voice adjectives, hard NOs) and proceed with those answers as the de-facto plan.

2. Derive concrete tokens from the plan

Translate the plan's strategic decisions into specific token values. Use these heuristics by visual direction:

**editorial** → display serif (Fraunces, Playfair Display, Crimson Pro, Newsreader), restrained sans body (Söhne, Public Sans, IBM Plex Sans), mono accents (JetBrains Mono, Berkeley Mono); warm neutral surface (#fbfaf9-ish, not pure white); single ink color near-black; one accent used sparingly; generous letter-spacing on small uppercase labels (0.18em+); hairline rules over heavy borders; small radius (0–4px).

**technical** → mono-dominant or sans-only (IBM Plex, Source Sans 3, JetBrains Mono); cool neutrals or high-contrast; small radius (0–2px); compact density; single signal accent (often a saturated green or amber); grid-paper texture allowed; eyebrow labels mandatory.

**bold** → heavy display sans (Clash Display, Cabinet Grotesk, Satoshi, Söhne Breit, Roobert) at 800–900 against 100–200 body, high-saturation palette, sharp contrast, large radius (8–16px) or zero radius (no middle), unapologetic 4×+ scale jumps.

**minimal** → single humanist sans family (Söhne, Public Sans, IBM Plex Sans), 2–3 weights max, mostly grayscale with one quiet accent, large whitespace, no decorative elements, larger radius (8px+) for softness. Valid only when chosen deliberately against the alternatives — never as the default (see `../../design-variation-sop.md` Rule 1).

> **Never** derive Inter, Roboto, Arial, Open Sans, Lato, Helvetica, or system stack as the primary family — that is the AI-default monoculture (anti-patterns §2). The fuller named-aesthetic roster (Swiss, brutalist, warm minimal, code/terminal, solarpunk, distinctive display, archival, etc.), each defined in concrete type/color/radius/density/layout terms, lives in `../../design-variation-sop.md`. These four directions are the common cases; the roster is the full menu — pick from it deliberately, biased away from recent brands and away from minimal-by-default.

**mixed** → resolve based on the two directions chosen and how they were described.

For each token category, pick one option from the **variation axes** below to avoid output collapse:

• **Surface tone**: warm-cream | cool-paper | true-white | near-black | warm-charcoal
• **Accent role**: single-color | dual-accent | mono-with-signal | no-accent (grayscale only)
• **Type pairing**: serif-display + sans-body | sans-display + sans-body | sans-display + mono-body | mono-only | serif-only
• **Radius scale**: zero (0px) | hairline (2px) | small (4px) | medium (8px) | soft (12–16px)
• **Spacing scale**: 4px-base (compact) | 6px-base (balanced) | 8px-base (spacious)

State which option you picked from each axis at the top of `DESIGN.md` as a comment so the choice is reproducible.

When deriving the actual token *values*, apply `../../design-principles.md`:

• **Typographic extremes** (§1): the type scale uses weight extremes (100/200 vs 800/900, not 400 vs 600) and 3×+ size jumps. Display weights should reach 700–900 or drop to 100–300 — do not cluster every level at 500–600. Pick one distinctive family and use it decisively; max 2 families.
• **Dominant + sharp accent** (§3): one color owns the large surfaces, one saturated accent is used rarely. Reject any palette where you can't name the single dominant and the single accent. Draw the palette from a real reference (IDE theme, material, subject) — never the neutral SaaS center.
• Before committing the system, sketch **three distinct directions** per `../../design-variation-sop.md` Rule 3 and offer them as a one-line menu; generate the best-fit by default, all three only if asked.

3. Write DESIGN.md (Google spec format)

Use this structure exactly. Sections appear in this order. YAML frontmatter is mandatory.

---
version: alpha
name: <Brand Name>
description: <One-line summary of the visual identity>
colors:
  primary: "#XXXXXX"
  secondary: "#XXXXXX"
  accent: "#XXXXXX"
  surface: "#XXXXXX"
  surface-muted: "#XXX