Design system

Design System

Two modes for governing a project's visual identity:

1. Auto-activate — when editing UI files (components, pages, layouts, styles, DESIGN.md, tailwind.config.*) and a DESIGN.md is present, the skill reads it first and enforces token-only sourcing for colors, typography, spacing, and corner radius. No DESIGN.md? It stays out of the way — a one-line pointer to /award-design, no enforcement, no block on the edit.
2. Subcommands — /design-system <verb> [path] exposes the full DESIGN.md lifecycle, built on the canonical @google/design.md CLI.

Subcommand routing

Parse the first positional token of $ARGUMENTS. If it matches a verb below, load the referenced file and follow its workflow. Otherwise proceed with the token-enforcement workflow at the end of this document.

First token	Mode	Reference
audit (aliases: check, lint)	Lint + fix proposals, human-readable report	references/subcommand-audit.md
diff	Regression check between versions (git-aware)	references/subcommand-diff.md
export	Tokens → Tailwind theme or W3C DTCG tokens.json	references/subcommand-export.md
spec	Emit the canonical spec from the installed CLI	references/subcommand-spec.md
migrate	Port legacy Stitch 9-section DESIGN.md → Google standard	references/subcommand-migrate.md
init	Scaffold a minimal valid DESIGN.md (fallback from /award-design)	references/subcommand-init.md
audit-extensions	Bidirectional drift check — DESIGN.md extension YAML ↔ prose refs ↔ globals.css @theme	references/subcommand-audit-extensions.md
(none, or a UI file path)	Token enforcement — see the default workflow at the end	(this file)

Source of truth

When a DESIGN.md exists at the project root, read it before writing any UI code: every color, font, spacing value, corner radius, and component style comes from this file — the YAML frontmatter tokens (normative values) or the prose explaining when and why to apply them.

No DESIGN.md? Step aside. design-system governs a file; it does not require or create one. It never blocks an edit for lack of a DESIGN.md and never authors a design from scratch — that is /award-design's job (it forces a universe, writes the DESIGN.md up front, then builds the frontend under it). So:

• Building or editing UI with no file → proceed. For a designed build, point to /award-design, which authors the DESIGN.md up front and builds the frontend under it.
• A bare token scaffold is needed now and /award-design is unavailable → /design-system init [archetype] is a minimal fallback, not the primary path.

If a legacy Stitch-format DESIGN.md is detected (9 numbered sections, ## Agent Prompt Guide heading, no YAML frontmatter): suggest /design-system migrate <path> to port it before proceeding.

The standard

DESIGN.md is Google's open format for describing a design system to coding agents. Canonical source: github.com/google-labs-code/design.md. A file has two layers:

1. YAML frontmatter — machine-readable design tokens (colors, typography, rounded, spacing, components). Normative values.
2. Markdown body — eight ## sections explaining rationale. Present sections must appear in order:

#	Section	Aliases	YAML tokens
1	Overview	Brand & Style	—
2	Colors	—	colors:
3	Typography	—	typography:
4	Layout	Layout & Spacing	spacing:
5	Elevation & Depth	Elevation	—
6	Shapes	—	rounded:
7	Components	—	components:
8	Do's and Don'ts	—	—

Full schema, token types, reference syntax, and consumer behavior for unknown content: references/design-md-spec.md. Concrete examples: references/example-claude.md (warm editorial), references/example-stripe.md (minimalist gradient).

Token references and schema (at a glance)

• Colors: hex (sRGB) quoted — primary: "#1A1C1E"
• Dimensions: px / em / rem — 48px, -0.02em, 1.5rem
• Typography: object — fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation
• Token references: {path.to.token} wrapped in braces — "{colors.tertiary}", "{rounded.sm}"
• Component property tokens (the only accepted set): backgroundColor, textColor, typography, rounded, padding, size, height, width
• Variants (hover, active, pressed): separate entries with related keys — button-primary, button-primary-hover

Recommended but non-normative names: primary, secondary, tertiary, neutral, surface, on-surface, error; headline-lg, body-md, label-sm; none, sm, md, lg, xl, full.

Writing principles

DESIGN.md is written for both agents and humans. These principles govern every section:

• Tokens are normative, prose is context. YAML values are what agents render. Prose tells them when and why. Both are required — prose without values is a mood board; values without prose is a spreadsheet.
• Descriptive over technical. Write "whisper-soft shadow" alongside the exact value. Translate CSS into spatial language — rounded-full → "pill-shaped".
• Every value has a role. #5e5d59 alone is meaningless; Olive Gray (#5e5d59): secondary body text — warm medium-dark gray is actionable.
• Name tokens semantically. primary, tertiary, button-primary-hover — not blue-500, shadow-sm.
• Show the personality in Overview. Section 1 sets the tone; every later section should feel written by the same person.
• Exact values are non-negotiable. Every color, dimension, component property is a concrete token.

Rules

• Colors, fonts, spacing, corner radius come only from DESIGN.md YAML tokens
• Map tokens to CSS custom properties in the global stylesheet
• Map tokens to tailwind.config.ts theme.extend — or generate via /design-system export tailwind
• Never use arbitrary Tailwind values (text-[13px], bg-[#abc]) when a token exists
• Never introduce values absent from DESIGN.md — use the closest token and flag to the user
• Extended tokens — values outside the canonical 5 namespaces (motion, shadows, aspectRatios, heights, containers, breakpoints, zIndex, borderWidths, opacity, scrollTriggers) live as top-level YAML namespaces — preserved by the Google CLI per references/design-md-spec.md Extending the spec, validated by convention via /design-system audit-extensions. Components MUST NOT bind to extension namespaces. The lint rejects unknown property names as broken-ref errors — field-tested as 73 errors and 84 warnings cascading from 27 components binding to extension tokens via non-canonical property names like modal.shadow: "{shadows.lifted}". Reference extensions in prose canonically instead (e.g., {motion.duration-reveal-slow}); export to globals.css @theme as 1:1 CSS custom properties (--duration-reveal-slow). See references/extended-tokens.md
• Dark mode: the Google spec has no dedicated mode concept. Use semantic tokens in a single DESIGN.md (e.g., surface, on-surface, inverse-surface, inverse-on-surface) and let the framework's CSS custom properties map each semantic name to the right value per mode. The Google-published atmospheric-glass example follows this pattern — one file, both modes via semantic naming. Avoid dual-file setups (DESIGN.md + DESIGN.dark.md) unless the brand truly diverges between modes
• Shared brand across projects: same DESIGN.md, framework-specific implementation. Distribution patterns — pick one and document in each project's CLAUDE.md:
  • Monorepo — packages/brand/DESIGN.md consumed by all apps; single PR for cross-cutting changes
  • Git submodule — canonical brand repo included as submodule; atomic updates via submodule bump
  • Published package — @org/design-tokens on npm with DESIGN.md + build outputs; versioned, works cross-repo
  • Copy + periodic /design-system diff — copies in each repo; periodic diff against the canonical catches drift; simplest tooling, highest drift risk
• Monorepo: the spec and this skill assume a single root DESIGN.md per project. For monorepos with per-package brand variations, keep each package's DESIGN.md at the package root and adjust the invocation path (/design-system audit packages/web/DESIGN.md). The paths: auto-activation matches the root file by default
• Post-edit invariant — after any DESIGN.md mutation (token update during the enforcement flow, migrate, init, or manual edit via this skill), run /design-system audit <path> and surface findings. A mutation that leaves errors behind is not done
• Duplicate section headings are a spec error — reject the file
• Unknown section headings are preserved (don't error); unknown component properties are accepted with a warning

CLI validator — shared surface

The canonical @google/design.md CLI powers the audit, diff, export, and spec subcommands. Each subcommand wraps one CLI invocation with richer UX (fix proposals, git-awareness, human-readable reports). Raw invocations:

npx @google/design.md lint DESIGN.md                    # validate
npx @google/design.md diff before.md after.md           # regression check (exit 1 on regression)
npx @google/design.md export --format tailwind DESIGN.md
npx @google/design.md spec --rules                      # emit spec + lint rules

Eight linting rules: broken-ref (error), missing-primary, contrast-ratio, orphaned-tokens, token-summary, missing-sections, missing-typography, section-order. Full table with severity, interpretation, and fix strategies: references/cli-reference.md.

Every subcommand verifies CLI availability first (command -v npx + a dry --help probe). When unavailable or offline: fall back to manual validation against references/design-md-spec.md. The skill still enforces the spec without the CLI — it loses only the deterministic check.

Framework behavior

Detect framework from config files (astro.config.*, next.config.*, etc.), then follow project instructions (CLAUDE.md, AGENTS.md, or equivalent) for implementation specifics (component library, font loading, file structure).

Default workflow — token enforcement

When no subcommand is matched — either auto-activated via paths: during a UI edit, or invoked directly to discuss enforcement — follow this workflow.

When there is no DESIGN.md

design-system does not author a design file from scratch. A DESIGN.md is born one of two ways:

1. /award-design authors it (preferred) — it forces a universe and writes the full DESIGN.md up front, then builds the frontend under it. design-system governs the result from there.
2. /design-system init [archetype] — a minimal token scaffold, only when /award-design is unavailable and a bare file is needed now.

Either way, once the file exists, the change flow below applies. Atmosphere scores (Density, Variance, Motion) live in Overview prose, not YAML.

How award-design's universe maps to DESIGN.md:

award-design output	DESIGN.md section	YAML tokens
Archetype + atmosphere (Density/Variance/Motion) + signature moment + photography direction + copy register	1. Overview (prose)	—
Color palette + photography colour guidance	2. Colors	colors:
Typography + kinetic typography intent	3. Typography	typography:
Spacing, grid, scroll choreography, responsive system	4. Layout	spacing: + ext: breakpoints:, containers:, heights:, aspectRatios:, motion:, scrollTriggers:
Shadow language + depth narrative	5. Elevation & Depth	ext: shadows:, borderWidths:, opacity:
Corner radius language	6. Shapes	rounded:
Component specs + variants + micro-interactions + motion philosophy	7. Components	components: (8 property tokens only) + ext: zIndex:
Archetype guardrails + AI-tell rejections + production-hardening rules	8. Do's and Don'ts	—

Extension namespaces (ext: rows above) live as top-level YAML per references/extended-tokens.md. Components bind only to the eight canonical property tokens — extension tokens are referenced in prose, never as components: keys.

Once the file exists (authored or scaffolded), wire it into the project:

1. Audit — run /design-system audit <path> (post-edit invariant). Fix errors before proceeding.
2. Wire into the framework: /design-system export tailwind → merge the result into tailwind.config.ts theme.extend (v3) or globals.css @theme block (v4); set up CSS custom properties in the global stylesheet.
3. Validate the mirror — /design-system audit-extensions <path> confirms every extension token in the YAML has its CSS custom property and every prose reference resolves. Run after every export.

When UI/UX changes are requested

Any visual change — colors, typography, spacing, radius, shadows, component styles, layout, responsive behavior — follows this flow.

1. Check whether the change affects tokens. New value, modified value, or altered visual system → DESIGN.md first. Pure layout bugs, alt text, content reordering → code only.
2. Update DESIGN.md first.
   • Open DESIGN.md, locate the affected YAML tokens and prose sections
   • Update values, semantic names, reference paths
   • Cascade — if the primary color changes, update every components: entry referencing it
   • Sync Do's and Don'ts if the change contradicts an existing guardrail
3. Audit — /design-system audit <path> to verify no broken references or contrast regressions (post-edit invariant).
4. Propagate to code:
   • Re-export Tailwind theme (/design-system export tailwind) or update theme.extend by hand
   • Update CSS custom properties in the global stylesheet
   • Update components using raw values — components referencing tokens by name pick up the new value automatically
5. Shared brand — if the DESIGN.md is shared across projects, propagate to all, then step 4 in each.

Examples of token-affecting changes:

• "Change CTA color" → colors.* + Colors prose + every components: entry referencing the old color
• "Make cards more rounded" → rounded.* + Shapes prose + components.card.rounded
• "Darker theme" → colors.* + Overview + Elevation & Depth prose
• "New badge component" → components.* + Components prose
• "Increase section spacing" → spacing.* + Layout prose

Re-architecting

A fundamental visual change (new archetype, different atmosphere, complete restyle) is a new design, not a token update. Use /award-design to rebuild from a fresh archetype — it writes a fresh DESIGN.md and builds under it. Any existing DESIGN.md is replaced whole, never patched in place.

Gotchas

1. Components binding to extension-namespace tokens triggers broken-ref errors. Components MUST use only the 8 canonical properties (backgroundColor, textColor, typography, rounded, padding, size, height, width). A components: { modal: { shadow: "{shadows.lifted}" } } references an extension namespace and fails lint; the error message does not name the canonical-vs-extension distinction. Fix: reference extension tokens only in prose (e.g., {motion.duration-reveal-slow} inside a Layout paragraph), never as a component property.
2. Duplicate ## section heading breaks spec parsing silently. Two ## Colors sections (from a botched re-architect) cause the parser to read only the first; YAML in the second is dropped without warning. Each of the 8 sections must appear exactly once. Fix: prescan for heading duplicates; fail hard with the duplicated name.
3. export tailwind token name mismatches don't resolve at build time. Semantic token names (surface, on-surface, primary-variant) don't map to Tailwind's expected canon (primary, secondary, neutral); the generated config uses CSS custom properties that never resolve. Fix: align YAML color token names with Tailwind's expected names before export; warn on mismatches.
4. Monorepo paths: glob matches root + per-package DESIGN.md. Auto-activation via paths: matches both ./DESIGN.md and packages/*/DESIGN.md; the skill picks the root by default. Fix: when multiple DESIGN.md files are detected, ask which one to edit. Never silently pick the root.