---
name: design-md
description: Author, validate, and consume DESIGN.md files — a plain-text spec (YAML front matter + markdown prose) that describes a design system to coding agents. Use when the user asks to create/update a design system, brief an agent on brand style, generate a DESIGN.md, lint/diff/export design tokens, or when a project has a DESIGN.md at its root that should drive UI decisions. Based on google-labs-code/design.md.
user-invocable: true
disable-model-invocation: false
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# DESIGN.md

A format specification from Google Labs for describing a visual identity to coding agents. A `DESIGN.md` file combines machine-readable tokens (YAML front matter) with human-readable rationale (markdown prose). Tokens give exact values; prose tells agents *why* and *how* to apply them.

Full spec: `spec.md` in this skill folder (source: https://github.com/google-labs-code/design.md).

## When to use

- User asks to create, update, or review a `DESIGN.md` file.
- User wants to brief an agent on brand/visual style in a portable, persistent way.
- Project has a `DESIGN.md` at its root — read it before generating UI and treat its tokens as normative.
- User wants to lint, diff, or export design tokens (to Tailwind, DTCG tokens.json).

## CLI (run via npx — no install needed)

```bash
npx @google/design.md lint DESIGN.md
npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format dtcg DESIGN.md > tokens.json
npx @google/design.md spec                  # print the spec (good for prompt injection)
npx @google/design.md spec --rules          # spec + linting rules
```

All commands accept `-` for stdin. `lint` exits 1 on errors; `diff` exits 1 on regressions.

Prefer `sfw npx ...` per the global install rule.

## File shape

```md
---
version: alpha
name: Heritage
description: Architectural minimalism meets journalistic gravitas
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview
...prose...

## Colors
...prose with hex values in bold headings...

## Typography
...prose naming each level's role...
```

## Authoring rules

- **Front matter** is between two `---` fences at the top. Tokens are the source of truth.
- **Colors**: hex only, sRGB, `#` prefix. Define at least `primary`. Common names: `primary`, `secondary`, `tertiary`, `neutral`.
- **Typography**: object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`. Unitless `lineHeight` is a multiplier (recommended).
- **Dimensions**: number + unit (`px`, `em`, `rem`). Spacing values may also be bare numbers.
- **Token references**: `{path.to.token}` — must resolve to a primitive (e.g. `{colors.primary}`). In `components`, composite refs like `{typography.label-md}` are allowed.
- **Components**: map `<name>` to `{ backgroundColor, textColor, typography, rounded, padding, size, height, width }`. Variants (hover, active, pressed) are separate entries with related names: `button-primary-hover`.
- **Sections** (omit as needed, but keep this order):
  1. Overview (aka Brand & Style)
  2. Colors
  3. Typography
  4. Layout (aka Layout & Spacing)
  5. Elevation & Depth
  6. Shapes
  7. Components
  8. Do's and Don'ts
- **Duplicate section headings are errors**; unknown sections/tokens are preserved with warnings.

## Lint rules (what to watch for)

| Rule | Severity |
|---|---|
| `broken-ref` (unresolved `{...}`) | error |
| `missing-primary` | warning |
| `contrast-ratio` (<4.5:1 WCAG AA) | warning |
| `orphaned-tokens` (defined, never referenced) | warning |
| `missing-typography` | warning |
| `section-order` | warning |
| `token-summary`, `missing-sections` | info |

Always run `npx @google/design.md lint` after authoring or editing.

## Consuming a DESIGN.md (when building UI)

1. Read the front matter first — tokens are normative.
2. Read the prose for intent and "why" — it resolves ambiguity the tokens don't cover.
3. Map tokens to the target stack (Tailwind config, CSS vars, Figma variables). Use `export` for mechanical conversions.
4. If a rule isn't explicit, lean on the Overview section's stated personality.

## Workflow shortcuts

- **Create new**: draft front matter → fill prose sections → `lint` → iterate.
- **Brief an agent mid-task**: run `npx @google/design.md spec` and paste into the prompt, alongside the project's `DESIGN.md`.
- **Detect regressions in CI**: `npx @google/design.md diff main-DESIGN.md branch-DESIGN.md` (non-zero exit fails the build).