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. 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: "#XXXXXX"
  ink: "#XXXXXX"
  ink-soft: "#XXXXXX"
  rule: "#XXXXXX"
  success: "#XXXXXX"
  warning: "#XXXXXX"
  danger: "#XXXXXX"
typography:
  display-xl:
    fontFamily: <Family>
    fontSize: 64px
    fontWeight: 600
    lineHeight: 1.05
    letterSpacing: -0.02em
  display-lg:
    fontFamily: <Family>
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.08
    letterSpacing: -0.018em
  headline-md:
    fontFamily: <Family>
    fontSize: 32px
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: -0.015em
  headline-sm:
    fontFamily: <Family>
    fontSize: 24px
    fontWeight: 500
    lineHeight: 1.2
    letterSpacing: -0.01em
  body-lg:
    fontFamily: <Family>
    fontSize: 18px
    fontWeight: 400
    lineHeight: 1.55
  body-md:
    fontFamily: <Family>
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  body-sm:
    fontFamily: <Family>
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.55
  label-caps:
    fontFamily: <Mono Family>
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.18em
  code:
    fontFamily: <Mono Family>
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.55
spacing:
  base: 16px
  3xs: 2px
  2xs: 4px
  xs: 8px
  sm: 12px
  md: 16px
  lg: 24px
  xl: 32px
  2xl: 48px
  3xl: 64px
  4xl: 96px
rounded:
  none: 0
  sm: 2px
  md: 4px
  lg: 8px
  full: 9999px
components:
  button-primary:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.surface}"
    rounded: "{rounded.sm}"
    padding: 12px 20px
  button-secondary:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.ink}"
    rounded: "{rounded.sm}"
    padding: 12px 20px
---

<!--
Variation choices:
  surface: <picked>
  accent: <picked>
  type-pairing: <picked>
  radius: <picked>
  spacing: <picked>
-->

# <Brand Name> — Design System

## Overview

<3–5 sentences capturing brand personality, target emotional response, and how the look feels in one paragraph. Reference the visual direction from DESIGN-PLAN.md without restating it verbatim.>

## Colors

<Prose: explain the role of each palette entry — primary as ink/permanence, accent as the only attention-pull, surface as foundation. 3–6 sentences total.>

## Typography

<Prose: explain the type pairing logic, where each level is used, why these families. Mention specific feature settings if any (e.g. "ss01" for Inter alternates, "cv11" for single-story g).>

## Layout

<Spacing scale rationale, grid approach (8pt baseline grid is the default unless the plan said compact/spacious), max widths for content, gutter strategy.>

## Elevation & Depth

<Flat vs. layered. If flat, explain how hierarchy is conveyed (rules, color contrast, scale). If layered, define shadow/border tokens.>

## Shapes

<Radius philosophy. Editorial systems often go zero-radius for an architectural feel; technical systems often hairline (2px); minimal systems lean soft (8px+).>

## Components

<Brief notes on button hierarchy, input states, card structure. Defer detail to design-ui-components — this section is just the rationale.>

## Do's and Don'ts

- Do <use the accent color only for the single most important action per surface>
- Do <maintain WCAG AA contrast: 4.5:1 for body, 3:1 for large text>
- Don't <mix more than 2 type families and 3 weights on a single surface>
- Don't <introduce off-palette colors when an existing token solves the problem>
- <pull every Hard NO from DESIGN-PLAN.md verbatim into this list>

4. Generate tokens.css

Convert the YAML frontmatter into CSS custom properties. Mapping rules:

• colors.<name> → --color-<name>
• typography.<name>.<prop> → --type-<name>-<prop-short> where prop-short = family | size | weight | leading | tracking
• spacing.<name> → --space-<name>
• rounded.<name> → --radius-<name>

Write to ./design/<brand-slug>/tokens.css:

/* Auto-generated from DESIGN.md — do not edit by hand. Re-run /design-system to regenerate. */
:root {
  /* Colors */
  --color-primary: <value>;
  --color-secondary: <value>;
  /* …all colors… */

  /* Typography */
  --type-display-xl-family: <value>;
  --type-display-xl-size: 64px;
  --type-display-xl-weight: 600;
  --type-display-xl-leading: 1.05;
  --type-display-xl-tracking: -0.02em;
  /* …all type levels… */

  /* Spacing */
  --space-base: 16px;
  --space-xs: 8px;
  /* …all spacing… */

  /* Radii */
  --radius-sm: 2px;
  /* …all radii… */
}

/* Convenience utility classes — optional but useful for design-ui-components */
.t-display-xl { font: var(--type-display-xl-weight) var(--type-display-xl-size)/var(--type-display-xl-leading) var(--type-display-xl-family); letter-spacing: var(--type-display-xl-tracking); }
.t-display-lg { font: var(--type-display-lg-weight) var(--type-display-lg-size)/var(--type-display-lg-leading) var(--type-display-lg-family); letter-spacing: var(--type-display-lg-tracking); }
/* …one utility per type level… */

.t-eyebrow {
  font: var(--type-label-caps-weight) var(--type-label-caps-size)/var(--type-label-caps-leading) var(--type-label-caps-family);
  letter-spacing: var(--type-label-caps-tracking);
  text-transform: uppercase;
  color: var(--color-ink-soft);
}

5. Generate showcase.html

A single self-contained HTML page proving every token in context. Structure:

1. Header — brand name in display-xl, tagline in body-lg, eyebrow label "DESIGN SYSTEM v1"
2. Color palette — every color token as a 120×120 swatch with the token name and hex
3. Type scale — every type level rendered with sample text ("The quick brown fox jumps over the lazy dog — 0123456789")
4. Spacing scale — every spacing token as a labeled bar (4px tall, width = the token value)
5. Radii — every radius token as a 64×64 filled square showing the corner shape
6. Component preview — primary button, secondary button, card, badge, hairline divider, eyebrow label

The showcase MUST embed tokens.css via inline <style> so the file is portable.

Keep markup semantic and minimal. Use only the tokens — no magic numbers, no off-palette colors. The showcase is a litmus test: if it looks coherent here, the system holds.

6. Verify and hand off

After writing all three files, do one self-check:

• Did I pick one option from each variation axis and document it?
• Does every color in tokens.css appear in DESIGN.md's YAML?
• Are the Hard NOs from DESIGN-PLAN.md reflected in the Do's/Don'ts?
• Is showcase.html self-contained (no external CSS, no external fonts unless via Google Fonts <link>)?

Then tell the user:

System generated for <brand-slug>:

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

Open showcase.html in a browser to verify. Next: run /design-ui-components <brand-slug> to generate the component library.

Rules

• Brand-agnostic. Never hardcode Shane's brand values. Every value derives from the plan or the variation matrix.
• Self-contained outputs. showcase.html and downstream artifact files should work offline (Google Fonts <link> is the only allowed external).
• Spec-compliant. YAML frontmatter must validate as the Google design.md schema (colors, typography, rounded, spacing, components groups; token references via {path.to.token}).
• Reproducible. The variation choices comment block at the top of DESIGN.md must list the picked option per axis. Re-running with the same plan + same picks should produce equivalent output.
• Anti-pattern compliance. Read the three shared canonical references before generating tokens: ../design-anti-patterns.md (hard floor — wins all conflicts), ../design-principles.md (craft floor — typographic/spatial/color/layout/tension requirements), and ../design-variation-sop.md (direction roster + offer-3 procedure). The Do's and Don'ts section of DESIGN.md should pull in any brand-specific Hard NOs from DESIGN-PLAN.md, but the universals (no purple-cyan gradients, no indigo/violet default, no drop shadows on text, no more than 2 type families, no Inter/Roboto/system primary, no accent-as-partner-to-primary) come from the shared references and don't need to be restated.