How DESIGN.md Combines Design Tokens and Rationale: A Single-File Design System

DESIGN.md stores design systems in a single Markdown file that splits machine-readable tokens in YAML front-matter from human-readable rationale in the Markdown body, enabling agents to access both exact values and contextual intent.

The google-labs-code/design.md repository introduces a novel approach to design system documentation that keeps code and context in one place. By unifying design tokens and explanatory prose in a single file, DESIGN.md ensures that automated agents always have access to the "why" behind the "what."

The Dual-Layer Architecture

DESIGN.md files are divided into two distinct layers that serve different purposes but remain tightly coupled.

YAML Front-Matter for Design Tokens

The first layer consists of a machine-readable YAML block delimited by --- at the top of the file. This front-matter contains the authoritative values for colors, typography, spacing, rounded corners, and component-specific tokens. The schema follows the W3C Design Tokens format and is defined in the project specification.

According to the source code, this block includes keys such as colors, typography, rounded, spacing, and components. For example, colors.primary might be set to "#1A1C1E" to define the primary brand color.

Markdown Body for Design Rationale

The second layer is the free-form Markdown body that follows the front-matter. Organized under ## headings (such as Overview, Colors, and Typography), this section explains why each token exists, the brand personality, visual goals, and application guidelines. The body does not affect token values but provides the contextual "story" that agents use to make design decisions.

As implemented in google-labs-code/design.md, the prose remains human-readable while containing optional token references (e.g., {colors.primary}) that link back to the YAML definitions.

Token Resolution and Coupling

When a DESIGN.md file is processed, the parser first extracts the YAML block and builds a token graph. It then walks the Markdown sections, resolving any token references inside the body against this graph. This guarantees that the prose always refers to a valid token.

This tight coupling ensures that design rationale stays in sync with the tokens that drive the UI. An agent can read the tokens to obtain exact values while simultaneously reading the prose to understand intent—for example, learning that the primary color is "deep ink for headlines, giving a sense of permanence."

Implementation Examples

Minimal DESIGN.md Structure

The following example demonstrates how both layers coexist in a single file:

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
rounded:
  sm: 4px
spacing:
  sm: 8px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas. The UI evokes a premium matte finish.

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.  
- **Secondary (#6C7278):** Sophisticated slate for borders and captions.

## Typography

Headlines use **Public Sans** Semi‑Bold; body text uses **Public Sans** Regular at 1 rem.

The front-matter (lines 1-13) defines the tokens; the sections that follow (lines 15-…) provide the rationale.

Programmatic Access with TypeScript

To access tokens programmatically, use the linter provided by the package:

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

const markdown = fs.readFileSync('DESIGN.md', 'utf‑8');
const report = lint(markdown);

// Tokens are available under report.designSystem.tokens
console.log(report.designSystem.tokens.colors.primary); // "#1A1C1E"

The lint function validates that the prose references only defined tokens and that the token values conform to the spec, as detailed in README.md lines 61-66.

Key Files and Validation

Several files in the repository define and validate how DESIGN.md combines tokens and rationale:

• README.md – Provides a high-level overview of the format and end-to-end examples of token and prose combination, particularly around lines 5-8 and 33-38.
• docs/spec.md – Contains the authoritative specification describing the YAML schema, token reference rules, and required markdown section order (lines 8-10).
• examples/totality-festival/DESIGN.md – A real-world sample demonstrating how projects write both tokens and rationale together.
• packages/cli/src/linter/ – The CLI implementation that parses front-matter, resolves token references, and validates prose against the spec.
• packages/cli/src/linter/fixtures/ – Fixture files used by the test suite to ensure the token-rationale coupling behaves correctly.

Summary

• DESIGN.md uses YAML front-matter for machine-readable design tokens and Markdown body for human-readable rationale.
• The parser builds a token graph from the YAML and validates references in the prose, ensuring tight coupling between values and intent.
• Token references like {colors.primary} in the body resolve against the front-matter definitions, preventing stale documentation.
• The @google/design.md/linter package provides programmatic access to tokens via the lint() function, which returns a structured report including report.designSystem.tokens.
• Key specification files in docs/spec.md and examples in examples/totality-festival/DESIGN.md demonstrate the format's practical application.

Frequently Asked Questions

What is the primary benefit of combining tokens and rationale in one file?

Keeping both layers in a single file ensures that design rationale never diverges from the actual token values. When an agent reads a DESIGN.md file, it can access exact CSS values from the YAML while simultaneously understanding the brand intent from the Markdown, enabling context-aware design decisions without switching between files.

How does DESIGN.md validate that prose references match defined tokens?

The linter in packages/cli/src/linter/ extracts the YAML front-matter to build a token graph, then walks the Markdown body to resolve references like {colors.primary}. If a reference does not exist in the token graph, the linter reports an error, guaranteeing that all prose references point to valid, defined tokens.

Is DESIGN.md compatible with the W3C Design Tokens format?

Yes. The YAML schema in the front-matter follows the W3C Design Tokens format, supporting standard categories such as colors, typography, spacing, and rounded. This ensures interoperability with existing design token workflows and tools that recognize the W3C specification.

Can I use DESIGN.md without the linter or CLI tools?

While the file is valid Markdown and human-readable on its own, realizing the full benefit of the token-rationale coupling requires parsing the YAML front-matter and resolving token references. The @google/design.md/linter package provides this functionality, but the file structure remains readable by any standard Markdown parser for manual reference.

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