DESIGN.md: A Machine-Readable Specification for Visual Design Systems

DESIGN.md is a file format that combines YAML front-matter for design tokens with Markdown prose to give coding agents a structured, verifiable view of your visual identity while keeping human-readable documentation intact.

Developed by Google Labs, the google-labs-code/design.md repository provides a complete toolkit for describing visual design systems in a single, persistent file. This specification bridges the gap between design intent and implementation by supplying coding agents with exact token values while preserving the narrative rationale that designers write.

What is DESIGN.md?

DESIGN.md serves as a dual-layer specification that merges machine-readable data with human-friendly documentation. The format consists of:

• YAML front-matter containing authoritative design tokens—colors, typography, spacing, and component definitions—that agents consume directly.
• Markdown prose explaining the rationale behind tokens, ensuring designers' intent remains accessible to human readers.

This architecture gives coding agents a persistent, structured view of a design system while maintaining the documentation quality required for design handoffs. According to the repository's README, the format specifically targets AI coding agents that need unambiguous visual identity instructions【/cache/repos/github.com/google-labs-code/design.md/main/README.md#L3-L9】.

Repository Architecture and Components

The google-labs-code/design.md project ships as a monorepo with three primary distribution mechanisms:

The Specification

The canonical spec resides in docs/spec.md, defining the YAML token schema, required section ordering, and validation rules【/cache/repos/github.com/google-labs-code/design.md/main/docs/spec.md】. This document serves as the source of truth for what constitutes a valid DESIGN.md file.

The CLI Tool

The @google/design.md package provides terminal commands for interacting with DESIGN.md files. Source code for these commands lives in packages/cli/src/commands/, with individual implementations for:

• lint.ts – Validates files against the specification
• diff.ts – Compares two versions of a design system
• export.ts – Converts tokens to external formats like Tailwind or CSS【/cache/repos/github.com/google-labs-code/design.md/main/packages/cli/src/commands/export.ts】

The Linter Library

For programmatic integration, the @google/design.md/linter package exposes validation logic as a reusable TypeScript module. The core runner implementation sits in packages/cli/src/linter/linter/runner.ts【/cache/repos/github.com/google-labs-code/design.md/main/packages/cli/src/linter/linter/runner.ts】. The linter enforces nine built-in rules including WCAG contrast checks, broken reference detection, and mandatory primary color validation.

Exporters and Examples

The repository includes practical examples in examples/*/DESIGN.md (such as examples/totality-festival/DESIGN.md) demonstrating real-world usage patterns【/cache/repos/github.com/google-labs-code/design.md/main/examples/totality-festival/DESIGN.md】.

Working with DESIGN.md Files

The CLI provides four primary commands for managing design systems. Below are practical implementations for common workflows.

Linting for Accessibility and Consistency

Validate your DESIGN.md against the specification and accessibility standards:

npx @google/design.md lint DESIGN.md

The linter produces a JSON report that agents can parse directly:

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

This output format, demonstrated in the README, enables automated CI pipelines to catch contrast violations before they reach production【/cache/repos/github.com/google-labs-code/design.md/main/README.md#L60-L69】.

Comparing Design Versions

Track changes between design system iterations using the diff command:

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

The resulting JSON structure identifies added, removed, and modified tokens:

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

This capability supports design system versioning and regression detection in automated workflows【/cache/repos/github.com/google-labs-code/design.md/main/README.md#L73-L86】.

Exporting to Tailwind and Other Formats

Convert DESIGN.md tokens into framework-specific configuration files:

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

The export command supports multiple output formats including Tailwind v3 JSON themes, CSS custom properties, and DTCG (Design Tokens Community Group) specifications. The resulting Tailwind file can be imported directly into tailwind.config.js as theme.extend.

Programmatic Integration

For Custom tooling, import the linter directly into TypeScript or JavaScript projects:

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

const report = lint(markdownString);
console.log(report.findings);   // array of findings
console.log(report.summary);    // { errors, warnings, info }

This API, documented in the README's "Programmatic API" section, allows build tools and IDEs to integrate DESIGN.md validation natively【/cache/repos/github.com/google-labs-code/design.md/main/README.md#L23-L35】.

Summary

• DESIGN.md combines YAML design tokens with Markdown documentation to create a machine-readable yet human-friendly design system specification.
• The google-labs-code/design.md repository provides a complete toolchain including the specification (docs/spec.md), CLI (@google/design.md), and programmatic linter (@google/design.md/linter).
• Built-in validation includes nine rules covering WCAG contrast ratios, broken references, and schema compliance.
• The CLI supports linting, diffing, and exporting to formats like Tailwind JSON, CSS, and DTCG.
• Real-world examples in the examples/ directory demonstrate production-ready implementations of the format.

Frequently Asked Questions

What makes DESIGN.md different from standard design token JSON files?

Unlike plain JSON token files, DESIGN.md preserves human-readable context through Markdown prose sections that explain design rationale while maintaining structured YAML front-matter for machine consumption. This dual-layer approach ensures coding agents receive unambiguous values while designers retain narrative documentation.

How does the DESIGN.md linter check for accessibility?

The linter runs nine built-in rules including WCAG contrast validation that calculates luminance ratios between text and background colors. It produces machine-readable JSON reports indicating whether color combinations pass AA or AAA standards, allowing automated enforcement of accessibility requirements.

Can I use DESIGN.md without the CLI tool?

Yes, the @google/design.md/linter package exposes the validation logic as a reusable TypeScript/JavaScript module that can be imported into custom build tools, IDEs, or CI pipelines. The CLI is optional for those who prefer programmatic integration.

Where can I find examples of valid DESIGN.md files?

The repository includes production-ready examples in the examples/ directory, including totality-festival/DESIGN.md and paws-and-paths/DESIGN.md. These files demonstrate proper YAML schema structure, section ordering, and documentation patterns that conform to the specification defined in docs/spec.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}