design-md-format

Q: How do I install design-md-format?

Run npx skills add https://github.com/reason-machines/design-skills --skill design-md-format in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/design-md-format/ (personal) or .claude/skills/design-md-format/ (project).

by reason-machines

Create and validate DESIGN.md files that give AI coding agents structured understanding of design systems through machine-readable tokens and human-readable rationale.

Installs: 178
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/design-skills --skill design-md-format

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads design-md-format automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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:

YAML front matter — Machine-readable tokens (colors, typography, spacing, etc.)
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):

Overview (or "Brand & Style")
Colors
Typography
Layout (or "Layout & Spacing")
Elevation & Depth (or "Elevation")
Shapes
Components
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

Always define primary color — Prevents agent auto-generation
Use token references — Single source of truth for design changes
Include typography early — Prevents agents from using default fonts
Write prose rationale — Explains why tokens exist and how to apply them
Validate before committing — Run lint in CI/CD pipeline
Version your DESIGN.md — Track design evolution with diff
Define component variants explicitly — button-primary-hover, not just button-primary
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"
  }
}

FAQ

What does the design-md-format skill do?

Create and validate DESIGN.md files that give AI coding agents structured understanding of design systems through machine-readable tokens and human-readable rationale.

How do I install design-md-format?

Run npx skills add https://github.com/reason-machines/design-skills --skill design-md-format in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/design-md-format/ (personal) or .claude/skills/design-md-format/ (project).

Which AI agents can use design-md-format?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is design-md-format safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains design-md-format?

It is published by reason-machines in reason-machines/design-skills. It has 178 recorded installs.

Popular other skills

View category →

hyperframes-cli

heygen-com/hyperframes

The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

1.3M installs

triage

mattpocock/skills

Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

1M installs

ask-matt

mattpocock/skills

Ask which skill or flow fits your situation. A router over the skills in this repo.

778.4K installs

to-questionnaire

mattpocock/skills

Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

508.9K installs

wait-what

mattpocock/skills

Stop. That last message did not land: re-pitch it.

459.7K installs

loop-me

mattpocock/skills

Grill me about specs for the workflows I want to build, within this workspace.

447.9K installs

design-md-format

Install

Install

Describe the task

Review the result

SKILL.md

DESIGN.md Format Skill

Installation

File Structure

Creating a DESIGN.md File

Complete Token Schema

Token Types

Component Tokens

Section Order

CLI Commands

Lint

Diff

Export

Spec

Programmatic API

Linting

Parsing and Validation

Common Patterns

Creating a Design System from Scratch

Integrating with Tailwind

Token References Pattern

Variant Pattern for Component States

Linting Rules Reference

Troubleshooting

npm error ENOVERSIONS

Broken Token References

WCAG Contrast Failures

Section Order Warnings

Windows CLI Issues

Best Practices

Integration Examples

CI/CD Validation

Pre-commit Hook

Build-time Token Export

FAQ

More from reason-machines/design-skills

Popular other skills

`npm error ENOVERSIONS`