design-system

name	design-system
description	Govern an existing DESIGN.md — Google's open standard for design tokens (YAML frontmatter + eight prose sections). Auto-activates during UI edits to enforce token-only sourcing for colors, typography, spacing, and corner radius when a DESIGN.md is present; steps aside when none exists — it never forces or authors one (`/award-design` authors it up front, then builds under it). Exposes seven CLI-backed subcommands — audit (lint + fix), diff (regression check), export (Tailwind / DTCG), spec (canonical spec), migrate (port legacy Stitch), init (minimal scaffold fallback), audit-extensions (drift check vs globals.css @theme). Token-affecting UI changes update DESIGN.md first, audit, then propagate to code.
when_to_use	When the user asks to change colors, typography, spacing, corner radius, shadows, component styles, layout, or any visual aspect of the UI. When creating new components or pages. When editing existing UI files. When the user changes the theme or references visual tokens in an existing DESIGN.md. Full redesigns / new visual direction → /award-design. When linting, diffing, exporting, porting, or initializing a DESIGN.md file. When DESIGN.md uses extension namespaces (motion, shadows, etc.) — run `audit-extensions` to validate them against the globals.css `@theme` mirror. Keywords — audit, check, lint, diff, export, spec, migrate, init, audit-extensions, DESIGN.md, tokens, extended tokens. For empty directories, run `/scaffold` first (then `/award-design` for a DESIGN.md) before invoking this skill.
argument-hint	[audit|diff|export|spec|migrate|init|audit-extensions] [flags] [path]
paths	["src/components/**","src/app/**","src/pages/**","src/layouts/**","src/styles/**","src/features/*/components/**","DESIGN.md","tailwind.config.*"]
license	MIT
allowed-tools	Read Write Edit Grep Glob Bash(npx *) Bash(command *) Bash(bash *) Bash(git *) Bash(mktemp *) Bash(wc *) Bash(tr *)
metadata	{"author":"coroboros","sources":["github.com/google-labs-code/design.md","www.designtokens.org"]}

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.