| name | design-md |
| description | Establish a design-system baseline for a frontend project using Google's DESIGN.md format (a single file with YAML design tokens plus markdown rationale that gives coding agents a persistent, structured understanding of the visual identity). Use when starting or restyling a frontend project, when the user mentions DESIGN.md, design tokens, design system, brand-to-UI, or wants colors/typography/spacing/radius locked down before UI work. Author and lint a DESIGN.md, then export tokens to Tailwind or W3C DTCG so frontend-design and gsap skills build against concrete values instead of guessing. |
DESIGN.md — design-system baseline for frontend projects
Google's DESIGN.md is a format specification for describing a visual identity to coding agents. A single DESIGN.md file gives the agent a persistent, structured understanding of a design system: machine-readable tokens (exact values) plus human-readable prose (why those values exist and how to apply them). Put one at the project root before any UI is built, and every later skill (frontend-design, gsap, etc.) works against the same concrete source of truth instead of inventing its own palette.
Source: github.com/google-labs-code/design.md · npm: @google/design.md (current: v0.3.0, alpha).
The two-layer format
A DESIGN.md file has exactly two layers:
- YAML front matter — machine-readable design tokens, delimited by
--- fences at the top of the file. These tokens are the normative values.
- Markdown body — human-readable design rationale organized into
## sections. The prose provides context for how to apply the tokens.
---
name: Heritage
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
body-md:
fontFamily: Public Sans
fontSize: 1rem
label-caps:
fontFamily: Space Grotesk
fontSize: 0.75rem
rounded:
sm: 4px
md: 8px
spacing:
sm: 8px
md: 16px
components:
button-primary:
backgroundColor: "{colors.tertiary}"
textColor: "{colors.on-tertiary}"
rounded: "{rounded.sm}"
padding: 12px
button-primary-hover:
backgroundColor: "{colors.tertiary-container}"
---
## Overview
Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.
## Colors
The palette is rooted in high-contrast neutrals and a single accent color.
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
An agent that reads this file produces a UI with deep ink headlines in Public Sans, a warm limestone background, and Boston Clay call-to-action buttons.
Token schema
version: <string>
name: <string>
description: <string>
colors:
<token-name>: <Color>
typography:
<token-name>: <Typography>
rounded:
<scale-level>: <Dimension>
spacing:
<scale-level>: <Dimension | number>
components:
<component-name>:
<token-name>: <string | token reference>
Token types
| Type | Format | Example |
|---|
| Color | Any CSS color (hex, rgb(), oklch(), named, etc.) | "#1A1C1E", "oklch(62% 0.18 250)" |
| Dimension | number + unit (px, em, rem) | 48px, -0.02em |
| Token Reference | {path.to.token} | {colors.primary} |
| Typography | object with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation | see example above |
Section order
Sections use ## headings. They can be omitted, but those present must appear in this order:
| # | Section | Aliases |
|---|
| 1 | Overview | Brand & Style |
| 2 | Colors | |
| 3 | Typography | |
| 4 | Layout | Layout & Spacing |
| 5 | Elevation & Depth | Elevation |
| 6 | Shapes | |
| 7 | Components | |
| 8 | Do's and Don'ts | |
Component tokens
Components map a name to a group of sub-token properties. Variants (hover, active, pressed) are expressed as separate component entries with a related key name (e.g. button-primary → button-primary-hover).
Valid component properties: backgroundColor, textColor, typography, rounded, padding, size, height, width.
Consumer behavior for unknown content
| Scenario | Behavior |
|---|
| Unknown section heading | Preserve; do not error |
| Unknown color token name | Accept if value is valid |
| Unknown typography token name | Accept as valid typography |
| Unknown component property | Accept with warning |
| Duplicate section heading | Error; reject the file |
Workflow
- Author a
DESIGN.md at the project root. Front matter first (normative tokens), then ## sections in canonical order.
- Lint it to catch broken token refs, WCAG contrast failures, orphaned tokens, section-order issues.
- Export tokens to the format the frontend stack expects (Tailwind v3/v4, or W3C DTCG).
- Hand off to UI-building skills (frontend-design, gsap) — they now have exact colors, fonts, spacing, radii to execute against.
CLI — @google/design.md
Windows-critical: the original bin name is design.md, whose .md suffix collides with the Windows Markdown file association and silently misbehaves (no output, or the file opens in an editor). Always invoke the dot-free designmd alias via npx -p. This is verified working on this machine.
Run any command (resolves from the public npm registry, no global install needed):
npx -p "@google/design.md" designmd lint DESIGN.md
npx -p "@google/design.md" designmd diff DESIGN.md DESIGN-v2.md
npx -p "@google/design.md" designmd export --format css-tailwind DESIGN.md > theme.css
All commands accept a file path or - for stdin. Output is JSON for lint/diff, code for export.
lint — validate structure
npx -p "@google/design.md" designmd lint DESIGN.md
npx -p "@google/design.md" designmd lint --format json DESIGN.md
cat DESIGN.md | npx -p "@google/design.md" designmd lint -
Exit code 1 if errors are found, 0 otherwise.
diff — detect token-level regressions between two versions
npx -p "@google/design.md" designmd diff DESIGN.md DESIGN-v2.md
Exit code 1 if the "after" file has more errors/warnings than the "before" file (i.e. a regression).
export — emit tokens for the frontend stack
npx -p "@google/design.md" designmd export --format json-tailwind DESIGN.md > tailwind.theme.json
npx -p "@google/design.md" designmd export --format css-tailwind DESIGN.md > theme.css
npx -p "@google/design.md" designmd export --format dtcg DESIGN.md > tokens.json
--format | Output | Use case |
|---|
json-tailwind (alias tailwind) | JSON | Tailwind v3 theme.extend object for tailwind.config.js |
css-tailwind | CSS | Tailwind v4 @theme { ... } block (CSS custom properties --color-*, --font-*, --text-*, --radius-*, --spacing-*) |
dtcg | JSON | W3C Design Tokens Format Module — interoperable with other design-token tooling |
Exit 0 on success, 1 on invalid --format/emitter error, 2 if input file unreadable.
spec — output the format spec
Status: broken in v0.3.0. The published npm package omits dist/spec.md, so designmd spec fails with "Failed to load spec.md." Do not rely on it. The condensed spec embedded in this skill is the current workaround; for the authoritative full spec see docs/spec.md in the source repository.
Linting rules (9)
The linter runs these rules; each produces findings at a fixed severity.
| Rule | Severity | What it checks |
|---|
broken-ref | error | Token references ({colors.primary}) that don't resolve to any defined token |
missing-primary | warning | Colors defined but no primary color — agents will auto-generate one |
contrast-ratio | warning | Component backgroundColor/textColor pairs below WCAG AA minimum (4.5:1) |
orphaned-tokens | warning | Color tokens defined but never referenced by any component |
token-summary | info | Summary of how many tokens are defined in each section |
missing-sections | info | Optional sections (spacing, rounded) absent when other tokens exist |
missing-typography | warning | Colors defined but no typography tokens — agents will use default fonts |
section-order | warning | Sections appear out of canonical order |
unknown-key | warning | A top-level YAML key that looks like a typo of a known schema key (e.g. colours: → colors:); custom extension keys stay silent |
How this skill fits with the rest of the toolbox
- frontend-design executes the look — give it the DESIGN.md (or the exported Tailwind theme) so its bold aesthetic choices land on the project's real tokens instead of generic defaults.
- gsap-* skills execute motion — feed them the DESIGN.md's
rounded, spacing, and component tokens so easing/durations/stagers match the system's rhythm.
- performance-optimization benefits from
export producing a single sourced token set (fewer ad-hoc values, smaller runtime CSS).
- Treat DESIGN.md as the upstream artifact: tokens flow
DESIGN.md → export → tailwind theme / css vars → frontend-design + gsap implementation.
Status & limits
The DESIGN.md format is at version alpha. The spec, token schema, and CLI are under active development — expect changes. This project is not in Google's OSS Vulnerability Rewards Program.
