# How DESIGN.md Combines Machine-Readable Design Tokens with Human-Readable Rationale

> Discover how DESIGN.md unites machine-readable YAML design tokens and human-readable markdown rationale into one source of truth for designers and tools.

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

---

**DESIGN.md merges structured YAML design tokens in the front-matter with narrative markdown sections to create a single source of truth that both automated tooling and human designers can consume.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository defines a specification that bridges the gap between design systems and engineering implementation. By keeping **machine-readable design tokens** and **human-readable rationale** in one file, DESIGN.md eliminates the drift that occurs when separate documentation and token files are maintained independently.

## The Two-Part Architecture of DESIGN.md

The format intentionally splits content into structured data and narrative prose, parsed separately but versioned together. This architecture ensures that design decisions and their technical implementations never diverge.

### Machine-Readable Tokens in YAML Front-Matter

The **token definitions** live in YAML front-matter delimited by triple dashes (`---`) at the top of the file. According to the specification in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 17-18), this block must start and end with `---` and contains typed sections for `colors`, `typography`, `rounded`, `spacing`, and `components` (lines 41-57).

In [`packages/cli/src/linter/parser/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/parser/handler.ts), the `ParserHandler` scans the markdown AST and extracts any front-matter **yaml** nodes (or fenced `yaml` code blocks). It feeds the raw YAML to `yaml.parse`, and the result becomes a plain JavaScript object that populates the `ParsedDesignSystem` data structure (lines 23-27).

### Human-Readable Rationale in Markdown Sections

Everything after the closing `---` of the front-matter constitutes the **design rationale**. These narrative sections use standard markdown headings like `## Overview`, `## Colors`, and `## Typography` to describe brand personality, visual goals, and usage guidelines.

While parsing, the handler records every level-2 heading (`## …`) and slices the original file into "document sections" (lines 64-100). These sections are stored in `ParsedDesignSystem.documentSections` so that downstream tools can render the prose unchanged for editors and AI agents.

## Parsing the Dual-Format Structure

The `ParserHandler` produces a single `ParsedDesignSystem` object that unifies both representations. This object includes:

- **Token maps** (`colors`, `typography`, etc.) for machine consumption
- **Sections** (the list of heading titles) and **documentSections** (the raw markdown for each heading) for human review
- **SourceMap** data recording where each token originated, including line numbers and whether it came from front-matter or a code block

Because the parser handles both front-matter and fenced `yaml` blocks, designers can choose the most readable format for their workflow while maintaining strict machine readability.

## Token References and Component Definitions

DESIGN.md supports **token references** using the `{path.to.token}` syntax (specified in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), line 86). These references are allowed anywhere a primitive value is expected, including inside component definitions.

This ensures that component styling stays synchronized with the token definitions:

```yaml
---
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.h1}"
    rounded: "{rounded.lg}"
---

## Components

The primary button follows the brand's diamond-ring accent colour.

```

The parser resolves these references at runtime, creating a cohesive system where a single token update propagates automatically through all dependent components.

## Specification and Validation

The official contract for valid [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) files is defined in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md). Key requirements include:

- Tokens must be grouped into typed sections (`colors`, `typography`, etc.)
- The markdown body must contain fixed-order sections (`Overview`, `Colors`, `Typography`, etc.) each introduced by an `##` heading (lines 94-101)
- Token references must follow the `{category.token}` syntax

Tools such as the CLI (`design.md packages/cli`) can validate files against this specification, emit the spec via [`packages/cli/src/commands/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/spec.ts), or lint the file for structural errors.

## Complete Example

A minimal [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file demonstrates how both parts coexist:

```yaml
---
name: Example System
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
---

## Overview

The **Example System** is a sleek, high-contrast UI for scientific dashboards.  
Primary color is used for calls-to-action; secondary for supportive UI elements.

## Colors

- **Primary** – deep ink for headlines.  
- **Secondary** – subtle slate for borders and captions.

## Typography

Headlines use *Public Sans* for authority; body text uses *Inter* for legibility.

```

## Summary

- **DESIGN.md** stores structured design tokens in YAML front-matter and human-readable rationale in markdown sections, creating a single source of truth.
- The **`ParserHandler`** in [`packages/cli/src/linter/parser/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/parser/handler.ts) extracts both parts separately, producing a `ParsedDesignSystem` that contains token maps and document sections.
- **Token references** using `{path.to.token}` syntax allow components to stay synchronized with base token values.
- The format specification in **[`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)** defines the contract for valid files, including required sections and reference syntax.
- CLI tooling supports linting, validation, and spec emission for automated design system maintenance.

## Frequently Asked Questions

### How does the parser extract data from DESIGN.md files?

The `ParserHandler` scans the markdown AST using `unified` and `remark-parse`, identifies `yaml` nodes from the front-matter or fenced code blocks, and parses them into JavaScript objects. It simultaneously extracts level-2 headings and slices the markdown body into sections, storing both the structured tokens and the narrative prose in a `ParsedDesignSystem` object.

### Can I define design tokens outside of the front-matter block?

Yes. While the front-matter is the primary location, the parser also recognizes fenced `yaml` code blocks within the document body as valid token sources. These are extracted alongside the front-matter and merged into the final `ParsedDesignSystem`, though the front-matter remains the recommended location for core tokens.

### What happens if the markdown sections are out of order?

According to [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 94-101), the markdown body must contain fixed-order sections starting with `## Overview`, followed by `## Colors`, `## Typography`, and others. While the parser records all sections, validation tools in the CLI may flag deviations from the specified order to ensure consistency across design system files.

### How do token references work in component definitions?

Token references use the syntax `{category.token}` (for example, `{colors.primary}` or `{typography.h1}`). When the parser encounters these strings in component definitions or other token values, it resolves them at runtime to their actual values. This creates a dependency graph where updating a base token automatically updates all components that reference it.