---
name: design-md
description: Create, edit, validate, export, and apply DESIGN.md files, Google's open format that describes a design system to coding agents (YAML tokens plus Markdown rationale). Use when a repository has or needs a DESIGN.md, when asked to write, fix, lint, or export one, and before generating UI in a project that contains one.
---

# DESIGN.md

A DESIGN.md is a plain-text design system for coding agents. YAML frontmatter holds machine-readable tokens; Markdown sections hold the rationale an agent needs to make decisions the tokens cannot. This skill follows the spec and CLI of `@google/design.md` 0.4.0 (format version "alpha", pre-1.0, so details can change).

## Before generating UI in a project with a DESIGN.md

1. Read DESIGN.md (usually at the repository root) before writing or changing any UI.
2. Use its tokens for colors, type styles, spacing, radii, and component defaults. Do not invent a color, font, size, or radius the file does not define. If something is missing, say so and propose adding it to the file.
3. Treat the prose as constraints: the Overview sets the tone, and Do's and Don'ts are rules. A "never" in the file overrides convenience.
4. Resolve references: `{colors.primary}` means the value of `colors.primary`.

## Writing or editing a DESIGN.md

### Frontmatter

There are nine top-level keys: `version`, `name`, `description`, `omitted`, `colors`, `typography`, `rounded`, `spacing`, `components`. Tools ignore every other key: a near miss such as `colour` triggers `unknown-key`, and an unknown key holding token-like values triggers `token-like-ignored`.

A minimal file that passes the linter with zero warnings:

```md
---
name: Vault
version: alpha
colors:
  primary: "#0F172A"
  secondary: "#475569"
  tertiary: "#2563EB"
  neutral: "#F8FAFC"
  surface: "#FFFFFF"
  on-surface: "#0F172A"
typography:
  headline-lg:
    fontFamily: "Inter"
    fontSize: 36px
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "Inter"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.65
  label-md:
    fontFamily: "Inter"
    fontSize: 12px
    fontWeight: 500
    letterSpacing: "0.06em"
rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  sm: 8px
  md: 16px
  lg: 32px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    padding: 12px
  card:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.lg}"
    padding: 24px
---

## Overview

Vault is a document management tool. The design language is calm and
professional: dark navy on white, with a single blue accent for interactive
elements. No gradients. No decorative borders.
```

Value rules:

- Colors: any CSS color string; hex `#RRGGBB` is the recommended default. Always define `colors.primary`. Weights inside `color-mix()` must be percentages (`40%`, not `0.4`).
- Dimensions: a number followed directly by `px`, `em`, or `rem`. Spacing also accepts unitless numbers, and `lineHeight` accepts a unitless multiplier such as `1.5`.
- Typography tokens take only these seven properties: `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`.
- Components take only these eight sub-tokens: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. There is no shadow or border sub-token. States are sibling keys: `button-primary`, `button-primary-hover`.
- References use `{group.token}` and must point to a defined token. Inside components, `{typography.label-md}` may reference a whole typography token.
- Groups may nest (`colors.brand.primary`, referenced as `{colors.brand.primary}`). Never define a dotted key and a nested group that flatten to the same name; that is an error.
- `omitted` lists token groups left out on purpose: `colors`, `typography`, `spacing`, `rounded`, or `components`, either as plain names or as `{ section, reason }`. It silences the matching missing-section notices. Listing a group that does define tokens is reported as redundant.

### Markdown body

Use `##` headings in this order. Sections may be left out, but the ones present must keep the order, and no heading may repeat:

1. Overview (alias "Brand & Style")
2. Colors
3. Typography
4. Layout (alias "Layout & Spacing")
5. Elevation & Depth (alias "Elevation")
6. Shapes
7. Components
8. Do's and Don'ts

Write intent, not just values: why the primary color exists, when each type style is used, what the product must never look like. Elevation has no tokens, so describe shadows and layering in prose. Correct tokens with empty prose still produce generic UI; the prose is what changes an agent's output.

## Validate

```bash
npx @google/design.md lint DESIGN.md
```

The JSON report lists `findings` (severity, path, message, rule) and a `summary` (errors, warnings, infos). The command exits 1 when there are errors, 0 otherwise, and 2 when the file cannot be read. Fix errors first, then warnings:

| Rule | Severity | Fix |
|---|---|---|
| `broken-ref` | error | Point the reference at a defined token or define it. Unknown component sub-tokens are reported here as warnings. |
| `missing-primary` | warning | Add `colors.primary`. |
| `contrast-ratio` | warning | A component's `textColor` on its `backgroundColor` is below WCAG AA (4.5:1). Darken or lighten one side. |
| `orphaned-tokens` | warning | Reference the color from a component, or remove it. |
| `missing-typography` | warning | Add a typography token, or list `typography` in `omitted`. |
| `section-order` | warning | Reorder the `##` sections. |
| `unknown-key` | warning | Fix the misspelled top-level key. |
| `token-like-ignored` | warning | Move the values under `colors`, `typography`, `spacing`, `rounded`, or `components`. |
| `token-summary` | info | Nothing to fix; check the counts look right. |
| `missing-sections` | info | Add `spacing` or `rounded`, or list them in `omitted`. |
| `omitted-rules` | info or warning | Reported as `declared-omission`, `redundant-omission`, or `unknown-omission`. Remove redundant entries and use valid group names. |

Some findings carry no rule id: unrecognized typography properties (warning), invalid color values (error), and token name collisions (error).

Repeat until there are no errors and, ideally, no warnings. Never silence a warning by deleting tokens or rationale the design needs. Every rule is explained at https://www.md-design.io/guide/cli/RULE-ID (replace RULE-ID with the rule).

## Export

```bash
npx @google/design.md export --format css-tailwind DESIGN.md
```

Formats: `css-tailwind` (Tailwind v4 `@theme`), `css-vars` (`:root` custom properties for colors, spacing, and rounded tokens; add `--prefix ds` to namespace them), `dtcg` (W3C Design Tokens JSON), and `json-tailwind` (Tailwind v3 `theme.extend`; `tailwind` is an alias). A successful export exits 0 even when the file has lint findings, so lint separately in CI.

## Review visually

Paste or drop the file into the viewer at https://www.md-design.io/tool to see it rendered as a brand guideline with every finding listed. It runs in the browser and uploads nothing.

## Point other agents at it

Coding agents do not discover DESIGN.md on their own. Add one line to AGENTS.md, CLAUDE.md, or the editor's rules file:

> Read DESIGN.md before generating or changing UI, and use only its tokens.