design-md-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",
    "md": "16px"
  }
}

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"
  }
}