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

> Explore the DESIGN.md architecture's core components: a dual-layer file format blending YAML tokens and Markdown prose, powered by a Node.js CLI for linting, diffing, and export.

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

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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:

```yaml
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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/lint.ts) |
| `diff` | Compares two DESIGN.md files and reports token-level changes | [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts) |
| `export` | Converts tokens to Tailwind, CSS, or DTCG formats | [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts) |
| `spec` | Outputs the DESIGN.md specification in markdown or JSON | [`packages/cli/src/commands/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/spec.ts) |

### The Linter Engine

The linter enforces **nine validation rules** defined in [`packages/cli/src/linter/spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

```typescript
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`](https://github.com/google-labs-code/design.md/blob/main/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.