DESIGN.md Architecture: Core Components of the Google-Labs Design Specification

The DESIGN.md architecture consists of a dual-layer file format that combines YAML front-matter for design tokens with Markdown prose for documentation, all processed by a Node.js CLI providing linting, diffing, and multi-format export capabilities.

DESIGN.md is a self-contained specification format created by Google Labs that describes visual design systems in a single Markdown file. The DESIGN.md architecture deliberately separates machine-readable data from human-readable narrative, enabling both automated tooling and designer-friendly documentation. This specification is enforced by the @google/design.md Node.js CLI, which validates tokens, detects changes between versions, and exports to popular front-end formats like Tailwind CSS.

The Dual-Layer File Structure

The foundation of the DESIGN.md architecture rests on two complementary layers parsed from a single file.

Machine-Readable Token Layer

The YAML front-matter contains canonical token definitions that serve as the single source of truth for the design system. According to the specification in docs/spec.md, this layer supports four primary token types:

• Color: Any valid CSS color string (hex, rgb, oklch, etc.)
• Dimension: Number plus unit (px, em, rem)
• Token Reference: Curly-brace notation like {colors.primary} for aliasing
• Typography: Objects defining fontFamily, fontSize, fontWeight, and related properties

The schema organizes tokens into flat maps per group:

colors:
  primary: "#1A1C1E"
  secondary: "#444746"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
spacing:
  sm: 8px
  md: 16px

Human-Readable Narrative Layer

The Markdown body provides contextual documentation following a canonical section order defined in docs/spec.md lines 92-102. The parser recognizes these sections as ## headings:

1. Overview – Brand narrative and design principles
2. Colors – Palette description and usage guidelines
3. Typography – Type-scale and font family rationale
4. Layout – Grid systems, spacing, and margins
5. Elevation & Depth – Shadows or tonal layer definitions
6. Shapes – Corner radii and geometric properties
7. Components – Atomic definitions for buttons, chips, and UI elements
8. Do's and Don'ts – Style guidelines and usage constraints

While missing sections are allowed, any present sections must follow this strict order. The linter engine raises a section-order warning if headings appear out of sequence.

CLI Architecture and Command Structure

The @google/design.md package provides a Node.js CLI built around a linter engine that enforces the specification. The implementation resides in packages/cli/src/, with command handlers in packages/cli/src/commands/ and the core linting logic in packages/cli/src/linter/.

Core CLI Commands

The CLI exposes four primary commands for design system management:

Command	Purpose	Implementation
lint	Validates a DESIGN.md file and returns JSON findings	packages/cli/src/linter/lint.ts
diff	Compares two DESIGN.md files and reports token-level changes	packages/cli/src/commands/diff.ts
export	Converts tokens to Tailwind, CSS, or DTCG formats	packages/cli/src/commands/export.ts
spec	Outputs the DESIGN.md specification in markdown or JSON	packages/cli/src/commands/spec.ts

The Linter Engine

The linter enforces nine validation rules defined in packages/cli/src/linter/spec-config.ts:

• broken-references: Detects invalid token aliases like {colors.nonexistent}
• missing-primary-color: Ensures the colors map contains a primary key
• contrast-ratio: Validates WCAG contrast requirements
• orphaned-tokens: Identifies unused token definitions
• token-summary: Checks for required token documentation
• missing-sections: Warns when mandatory sections are absent
• missing-typography: Validates typography token completeness
• section-order: Enforces the canonical heading sequence
• unknown-key: Rejects undefined top-level YAML keys

Each rule produces structured findings with severity levels (error, warning, info), accessible programmatically or as JSON output.

Token Schema and Data Types

The formal token schema is defined in docs/spec.md and implemented in the CLI's parser. Tokens are categorized into five primary groups: colors, typography, spacing, rounded, and components.

Color tokens accept any CSS color module level 4/5 string, enabling modern color spaces like OKLCH. Dimension tokens require explicit units to prevent ambiguity between CSS pixels and rems. The reference syntax using curly braces enables token aliasing, allowing semantic names like background: {colors.primary} to resolve to concrete values during export.

Export Capabilities and Programmatic API

Beyond command-line usage, the DESIGN.md architecture supports direct programmatic integration and multi-format export.

Supported Export Formats

The export command in packages/cli/src/commands/export.ts supports three target formats:

• json-tailwind: Generates a Tailwind v3 theme.extend JSON object for direct integration into tailwind.config.js
• css-tailwind: Produces a CSS @theme { … } block compatible with Tailwind v4's CSS-first configuration
• dtcg: Outputs W3C Design Tokens Community Group format (tokens.json) for interoperability with Figma, Style Dictionary, and other design-token tooling

Programmatic Integration

Developers can import the linter directly into build pipelines or custom tools:

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

const report = lint(markdownString);
console.log(report.findings);   // Array of Finding objects with severity and location

This API enables real-time validation in IDEs, pre-commit hooks, or CI/CD workflows without shelling out to the CLI.

Summary

The DESIGN.md architecture provides a machine-actionable yet human-friendly approach to design system documentation:

• Dual-layer format combining YAML front-matter tokens with ordered Markdown sections
• Strict schema supporting colors, typography, spacing, rounded corners, and component definitions with reference aliasing
• Node.js CLI with lint, diff, export, and spec commands implemented in packages/cli/src/commands/
• Nine-rule linter engine located in packages/cli/src/linter/ enforcing validation, contrast ratios, and section ordering
• Multi-format export supporting Tailwind v3/v4 and W3C DTCG standards
• Programmatic API allowing direct integration into TypeScript/JavaScript build tools

Frequently Asked Questions

What are the required sections in a DESIGN.md file?

No sections are strictly required, but any sections present must follow the canonical order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts. The linter will raise a section-order warning if headings appear out of sequence, as enforced by the validation logic in packages/cli/src/linter/spec-config.ts.

How does the DESIGN.md linter detect broken token references?

The linter's broken-references rule scans all token values for curly-brace syntax like {colors.primary} and validates these paths against the defined token hierarchy. If a reference points to a non-existent key, the linter produces an error-level finding indicating the specific line and invalid path.

Can I use DESIGN.md without the CLI tool?

While the file format is human-readable Markdown, realizing the full benefits of the DESIGN.md architecture requires the @google/design.md CLI or programmatic API. The tool handles YAML parsing, reference resolution, WCAG contrast calculations, and format conversion that would be impractical to implement manually.

What export format should I use for a Tailwind CSS project?

Use json-tailwind for Tailwind v3 projects to generate a theme.extend object, or css-tailwind for Tailwind v4's CSS-first configuration approach. Both formats are generated by the export command and handle the conversion of DESIGN.md dimension tokens to the appropriate CSS custom properties or JavaScript theme values.

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