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

> Discover DESIGN.md, a machine-readable format combining YAML tokens and Markdown prose for verifiable visual identity. Keep documentation human-readable and code-ready.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: architecture
- Published: 2026-06-25

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/lint.ts) – Validates files against the specification
- [`diff.ts`](https://github.com/google-labs-code/design.md/blob/main/diff.ts) – Compares two versions of a design system
- [`export.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

```bash
npx @google/design.md lint DESIGN.md

```

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

```json
{
  "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:

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

```

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

```json
{
  "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:

```bash
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`](https://github.com/google-labs-code/design.md/blob/main/tailwind.config.js) as `theme.extend`.

### Programmatic Integration

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

```ts
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`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository provides a complete toolchain including the specification ([`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/totality-festival/DESIGN.md) and [`paws-and-paths/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md).