design-md-format

name	design-md-format
description	Create and validate DESIGN.md files that give AI coding agents structured understanding of design systems through machine-readable tokens and human-readable rationale.
triggers	["create a design.md file for our design system","validate this design.md against the spec","export design tokens to tailwind config","lint our design system file","compare two versions of our design system","generate design.md from our brand guidelines","check wcag contrast ratios in design tokens","convert design.md to dtcg format"]

DESIGN.md Format Skill

Skill by ara.so — Design Skills collection.

DESIGN.md is a format specification for describing visual identity to coding agents. It combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose), giving agents persistent, structured understanding of design systems.

Installation

npm install @google/design.md

For direct CLI usage without installation:

npx @google/design.md lint DESIGN.md

Windows note: When using the CLI in package.json scripts on Windows, use the designmd alias instead of design.md to avoid file association issues:

{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md"
  }
}

File Structure

A DESIGN.md file has two layers:

1. YAML front matter — Machine-readable tokens (colors, typography, spacing, etc.)
2. Markdown body — Human-readable rationale organized into specific sections

---
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
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas.

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — interaction driver.

Creating a DESIGN.md File

Complete Token Schema

version: <string>          # optional, current: "alpha"
name: <string>             # required
description: <string>      # optional
colors:
  <token-name>: <Color>    # "#" + hex (sRGB)
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <property>: <value | token reference>

Token Types

Color: Hex format with # prefix

colors:
  primary: "#1A1C1E"
  accent: "#B8422E"
  on-primary: "#FFFFFF"

Typography: Object with font properties

typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.2
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5

Dimension: Number + unit (px, em, rem)

rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px

Token Reference: {path.to.token}

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"

Component Tokens

Valid component properties:

• backgroundColor
• textColor
• typography
• rounded
• padding
• size
• height
• width

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    typography: "{typography.label-caps}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"
  card:
    backgroundColor: "{colors.neutral}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"

Section Order

Markdown sections use ## headings and must appear in this order (all optional):

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

## Overview

Brief description of the design philosophy.

## Colors

Rationale for each color token and when to use it.

- **Primary (#1A1C1E):** Deep ink for headlines
- **Tertiary (#B8422E):** Interaction driver

## Typography

Font selection rationale and hierarchy guidance.

## Components

How to apply component tokens in context.

CLI Commands

Lint

Validate a DESIGN.md file for structural correctness, broken references, and WCAG contrast issues:

# Validate from file
npx @google/design.md lint DESIGN.md

# From stdin
cat DESIGN.md | npx @google/design.md lint -

# Specify output format (only json currently)
npx @google/design.md lint --format json DESIGN.md

Output: JSON with findings array and summary

{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

Exit codes:

• 0: No errors
• 1: Errors found

Diff

Compare two DESIGN.md versions to detect token changes and regressions:

npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md diff --format json old.md new.md

Output: Token-level changes

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

Exit codes:

• 0: No regressions
• 1: Regressions detected (more errors/warnings in "after")

Export

Convert DESIGN.md tokens to other formats:

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

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

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

# From stdin
cat DESIGN.md | npx @google/design.md export --format dtcg - > tokens.json

Tailwind v3 JSON output (json-tailwind):

{
  "colors": {
    "primary": "#1A1C1E",
    "secondary": "#6C7278",
    "tertiary": "#B8422E"
  },
  "fontFamily": {
    "sans": ["Public Sans", "sans-serif"]
  },
  "fontSize": {
    "h1": "3rem",
    "body-md": "1rem"
  },
  "borderRadius": {
    "sm": "4px",
    "md": "8px"
  },
  "spacing": {
    "sm": "8px"
     
  

Tailwind v4 CSS output (css-tailwind):

@theme {
  --color-primary: #1A1C1E;
  --color-secondary: #6C7278;
  --color-tertiary: #B8422E;
  --font-sans: "Public Sans", sans-serif;
  --text-h1: 3rem;
  --text-body-md: 1rem;
  --radius-sm: 4px;
  --radius-md: 8px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
}

Spec

Output the DESIGN.md specification (useful for agent prompts):

# Full spec
npx @google/design.md spec

# Spec + linting rules
npx @google/design.md spec --rules

# Only linting rules
npx @google/design.md spec --rules-only

# JSON format
npx @google/design.md spec --rules-only --format json

Programmatic API

Linting

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

const markdownString = `
---
name: MyDesign
colors:
  primary: "#1A1C1E"
components:
  button:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
---

## Overview
Modern design system.
`;

const report = lint(markdownString);

console.log(report.findings);
// [
//   {
//     severity: 'warning',
//     path: 'components.button',
//     message: 'textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA.'
//   }
// ]

console.log(report.summary);
// { errors: 0, warnings: 1, info: 1 }

console.log(report.designSystem);
// Parsed DesignSystemState object

Parsing and Validation

import { lint, type Finding } from '@google/design.md/linter';

function validateDesignFile(content: string): boolean {
  const report = lint(content);
  
  const hasErrors = report.findings.some((f: Finding) => f.severity === 'error');
  
  if (hasErrors) {
    console.error('Validation failed:');
    report.findings
      .filter((f: Finding) => f.severity === 'error')
      .forEach((f: Finding) => console.error(`  ${f.path}: ${f.message}`));
    return false;
  }
  
  return true;
}

Common Patterns

Creating a Design System from Scratch

---
version: alpha
name: ProductName
description: Modern SaaS design system
colors:
  primary: "#2563eb"
  secondary: "#64748b"
  tertiary: "#0ea5e9"
  neutral: "#f8fafc"
  on-primary: "#ffffff"
  on-tertiary: "#ffffff"
typography:
  h1:
    fontFamily: Inter
    fontSize: 2.5rem
    fontWeight: 700
    lineHeight: 1.2
  h2:
    fontFamily: Inter
    fontSize: 2rem
    fontWeight: 600
    lineHeight: 1.3
  body:
    fontFamily: Inter
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5
  label:
    fontFamily: Inter
    fontSize: 0.875rem
    fontWeight: 500
rounded:
  sm: 4px
  md: 8px
  lg: 12px
  full: 9999px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label}"
    rounded: "{rounded.md}"
    padding: 12px 24px
  button-primary-hover:
    backgroundColor: "#1d4ed8"
  card:
    backgroundColor: "{colors.neutral}"
    rounded: "{rounded.lg}"
    padding: "{spacing.lg}"
  input:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.primary}"
    rounded: "{rounded.sm}"
    padding: "{spacing.sm}"
---

## Overview

Clean, modern SaaS interface prioritizing readability and trust.

## Colors

- **Primary (#2563eb):** Brand blue for primary actions
- **Secondary (#64748b):** Slate for secondary text and borders
- **Tertiary (#0ea5e9):** Sky blue for links and highlights
- **Neutral (#f8fafc):** Near-white background

## Typography

Single font family (Inter) for consistency. Weight and size establish hierarchy.

## Components

All interactive elements use `button-primary` tokens. Cards use `card` tokens.

Integrating with Tailwind

After exporting to Tailwind format:

npx @google/design.md export --format json-tailwind DESIGN.md > design-tokens.json

Tailwind v3 config:

// tailwind.config.js
const designTokens = require('./design-tokens.json');

module.exports = {
  theme: {
    extend: designTokens
  }
};

Tailwind v4 with CSS:

npx @google/design.md export --format css-tailwind DESIGN.md > src/theme.css

/* src/styles.css */
@import "./theme.css";
@import "tailwindcss";

Token References Pattern

Always reference tokens rather than duplicating values:

# ✅ Good - uses references
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
  button-secondary:
    backgroundColor: "{colors.secondary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"

# ❌ Bad - duplicates values
components:
  button-primary:
    backgroundColor: "#2563eb"
    textColor: "#ffffff"
    rounded: 8px
  button-secondary:
    backgroundColor: "#64748b"
    textColor: "#ffffff"
    rounded: 8px

Variant Pattern for Component States

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: 12px 24px
  button-primary-hover:
    backgroundColor: "#1d4ed8"
  button-primary-active:
    backgroundColor: "#1e40af"
  button-primary-disabled:
    backgroundColor: "{colors.secondary}"
    textColor: "#94a3b8"

Linting Rules Reference

Rule	Severity	Description
broken-ref	error	Token reference doesn't resolve (e.g., {colors.missing})
missing-primary	warning	No primary color defined — agents will auto-generate
contrast-ratio	warning	Component backgroundColor/textColor below WCAG AA (4.5:1)
orphaned-tokens	warning	Color token defined but never referenced
token-summary	info	Summary of token counts per section
missing-sections	info	Optional sections absent when other tokens exist
missing-typography	warning	Colors defined but no typography tokens
section-order	warning	Sections appear out of canonical order

Troubleshooting

npm error ENOVERSIONS

Problem: No versions available for @google/design.md

Cause: npm not querying public registry (custom registry in .npmrc, corporate mirror, misconfigured scope)

Solution:

# Check current registry
npm config get registry

# Should be: https://registry.npmjs.org/

# Clear cache and retry
npm cache clean --force
npm install @google/design.md

Broken Token References

Problem: broken-ref error for {colors.accent}

Cause: Token doesn't exist in YAML front matter

Solution:

colors:
  accent: "#0ea5e9"  # Add the missing token

Or update the reference:

components:
  button:
    backgroundColor: "{colors.primary}"  # Use existing token

WCAG Contrast Failures

Problem: contrast-ratio warning for component

Solution: Adjust colors to meet 4.5:1 minimum:

# Before (low contrast)
components:
  button:
    backgroundColor: "#e0e0e0"
    textColor: "#ffffff"

# After (high contrast)
components:
  button:
    backgroundColor: "#1A1C1E"
    textColor: "#ffffff"

Or define explicit on-* colors:

colors:
  primary: "#2563eb"
  on-primary: "#ffffff"  # Guaranteed high contrast
components:
  button:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"

Section Order Warnings

Problem: section-order warning

Cause: Sections out of canonical order

Solution: Reorder markdown sections:

## Overview
...

## Colors
...

## Typography
...

## Components
...

Windows CLI Issues

Problem: CLI not executing in package.json scripts on Windows

Solution: Use designmd alias instead of design.md:

{
  "scripts": {
    "lint": "designmd lint DESIGN.md",
    "export": "designmd export --format tailwind DESIGN.md > tokens.json"
  }
}

Best Practices

1. Always define primary color — Prevents agent auto-generation
2. Use token references — Single source of truth for design changes
3. Include typography early — Prevents agents from using default fonts
4. Write prose rationale — Explains why tokens exist and how to apply them
5. Validate before committing — Run lint in CI/CD pipeline
6. Version your DESIGN.md — Track design evolution with diff
7. Define component variants explicitly — button-primary-hover, not just button-primary
8. Check contrast ratios — Linter catches WCAG issues automatically

Integration Examples

CI/CD Validation

# .github/workflows/design.yml
name: Validate Design System
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npx @google/design.md lint DESIGN.md

Pre-commit Hook

{
  "husky": {
    "hooks": {
      "pre-commit": "npx @google/design.md lint DESIGN.md"
    }
  }
}

Build-time Token Export

{
  "scripts": {
    "prebuild": "designmd export --format tailwind DESIGN.md > src/design-tokens.json",
    "build": "vite build"
  }
}