mcpskills.net — Curated AI Skills, MCPs & Agents

mcpskills.net

DESIGN.md is a self-contained, plain-text representation of a design system from Google Labs. It combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose), giving AI coding agents a persistent, structured understanding of a visual identity.

How It Works

A DESIGN.md file has two layers:

YAML front matter — Machine-readable design tokens delimited by --- fences at the top of the file. These are the normative values.
Markdown body — Human-readable design rationale organized into ## sections. This prose provides context for how to apply the tokens.

Token Schema

---
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
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.1em
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

Token Types

| Type | Format | Example | |------|--------|---------| | Color | Any CSS color (hex, rgb(), oklch(), named) | "#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 | — |

Component Tokens

Components map a name to a group of sub-token properties for consistent component styling:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

Valid component properties: backgroundColor, textColor, typography, rounded, padding, size, height, width.

Variants (hover, active, pressed) are expressed as separate component entries with a related key name.

Section Structure

Every DESIGN.md follows this canonical order. Sections can be omitted, but those present must appear in this sequence:

Overview (alias: "Brand & Style") — Holistic description of the product's look and feel
Colors — Color palettes and their semantic roles
Typography — Font families, scales, and usage
Layout (alias: "Layout & Spacing") — Grid system, spacing scale, containment principles
Elevation & Depth (alias: "Elevation") — Shadow, layering, and visual hierarchy
Shapes — Corner radius and form language
Components — Per-component styling guidance
Do's and Don'ts — Guardrails and common pitfalls

CLI Tool

npm install @google/design.md

Lint — Validate a DESIGN.md file

npx @google/design.md lint DESIGN.md

Exit code 1 if errors are found, 0 otherwise. Outputs structured JSON with findings (broken refs, missing tokens, contrast ratios, etc.).

Diff — Compare two DESIGN.md files

npx @google/design.md diff DESIGN.md DESIGN-v2.md

Reports token-level changes (added, removed, modified) and detects regressions.

Export — Convert tokens to other formats

# Tailwind v3 config (JSON)
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json

# Tailwind v4 theme (CSS)
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

# W3C Design Tokens Format Module
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

Spec — Output the format specification

npx @google/design.md spec               # Full spec in markdown
npx @google/design.md spec --rules       # Spec + linting rules
npx @google/design.md spec --rules-only --format json  # Rules as JSON (for agent prompts)

Linting Rules

| Rule | Severity | What it checks | |------|----------|----------------| | broken-ref | error | Token references that don't resolve to any defined token | | missing-primary | warning | Colors defined but no primary color exists | | contrast-ratio | warning | Component color pairs below WCAG AA (4.5:1) | | orphaned-tokens | warning | Color tokens defined but never referenced by any component | | missing-typography | warning | Colors defined but no typography tokens | | section-order | warning | Sections out of canonical order | | unknown-key | warning | Top-level key looks like a typo of a known key | | missing-sections | info | Optional sections absent when other tokens exist | | token-summary | info | Summary of how many tokens are defined per section |

Programmatic API

import { lint } from '@google/design.md/linter'

const report = lint(markdownString)
console.log(report.findings)       // Finding[]
console.log(report.summary)        // { errors, warnings, info }
console.log(report.designSystem)   // Parsed DesignSystemState

Integration with AI Agents

Generate — Create a DESIGN.md in Google Stitch or write one manually
Lint — npx @google/design.md lint DESIGN.md to validate
Export — Convert to tailwind config, CSS variables, or DTCG tokens
Consume — Drop into Claude Code, Cursor, or any agent that reads context files

Design Token Interoperability

DESIGN.md tokens are inspired by the W3C Design Token Format. Export supports:

Tailwind v3 — theme.extend JSON object
Tailwind v4 — CSS @theme block with --color-*, --font-*, --text-*, --radius-*, --spacing-* namespaces
DTCG — W3C Design Tokens Format Module JSON

Status

The DESIGN.md format is at version alpha. The spec, token schema, and CLI are under active development.

Google DESIGN.md