# DESIGN.md YAML Front Matter Schema: Complete Specification for Design Tokens

> Discover the complete DESIGN.md YAML front matter schema specification. Learn about required fields and optional categories like colors, typography, and components for design tokens.

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

---

**The DESIGN.md YAML front matter schema requires a strict structure starting and ending with `---` delimiters, containing required fields like `name` and optional categories including `colors`, `typography`, `rounded`, `spacing`, and `components`.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository defines a machine-readable specification for declaring design systems. Understanding the exact schema for DESIGN.md YAML front matter is essential for properly configuring design tokens that tools can parse and validate.

## Required and Optional Top-Level Fields

The front matter block must reside at the very top of every DESIGN.md file, enclosed between lines containing only three hyphens.

### Core Metadata

Three fields govern the document identity:

- **`name`** (required) – A human-readable string identifying the design system.
- **`version`** (optional) – A string identifier for the spec version, such as `"alpha"`.
- **`description`** (optional) – Free-form text describing the design system's purpose.

### Design Token Categories

Four primary categories store visual design values:

- **`colors`** – Maps token names to **Color** values (hex codes, named colors, or CSS functional notation).
- **`typography`** – Maps token names to **Typography** objects containing `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `letterSpacing`.
- **`rounded`** – Defines corner-radius tokens as **Dimension** values (e.g., `4px`, `0.25rem`).
- **`spacing`** – Defines spatial tokens accepting either **Dimension** strings or bare numbers.

### Component-Specific Tokens

The **`components`** section accepts a nested map where each component name contains its own token definitions. Values may be literal strings or **token references** using the `{path.to.token}` syntax.

## Token Types and Value Formats

According to the specification in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 43-58), each category accepts specific data types:

**Color** values accept any CSS-compatible color string.

**Dimension** values for `rounded` must include units (`px`, `em`, `rem`), while `spacing` dimensions may alternatively be bare numbers.

**Typography** objects require structured fields:

```yaml
typography:
  <token-name>:
    fontFamily: <string>
    fontSize: <dimension>
    fontWeight: <number>
    lineHeight: <number>
    letterSpacing: <dimension>

```

**Token References** in the `components` section use curly-brace notation to inherit values from other sections:

```yaml
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    rounded: "{rounded.md}"

```

## Practical Implementation Examples

### Minimal Valid Configuration

A DESIGN.md file requires only the `name` field and at least one design token category:

```yaml
---
name: Sunset Theme
colors:
  primary: "#FF5722"
  secondary: "navy"
typography:
  body:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: 0em
rounded:
  sm: 4px
spacing:
  base: 16px
  xs: 4px
---

```

### Complete Configuration with Component Tokens

The following example from the repository specification demonstrates all optional fields including `version`, `description`, and component references:

```yaml
---
version: alpha
name: Daylight Prestige
description: A high-contrast, modern UI theme.
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
rounded:
  md: 8px
spacing:
  base: 16px
  sm: 8px
  lg: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.neutral}"
    rounded: "{rounded.md}"
    padding: 12px
---

```

## Schema Validation and Reference Files

The authoritative schema definition resides in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) at lines 43-58, which governs how parsers validate DESIGN.md files.

Real-world implementation examples include:

- [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md) – Demonstrates basic token definitions.
- [`examples/paws-and-paths/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/DESIGN.md) – Shows advanced usage with optional fields and complex component sections.

## Summary

- The DESIGN.md YAML front matter schema mandates `---` delimiters at the document's top with strict indentation rules.
- Only **`name`** is required; **`version`**, **`description`**, and all token categories are optional.
- **`colors`** accepts CSS-compatible values, **`typography`** requires structured objects, and **`rounded`**/`**spacing**` accept dimensions.
- **`components`** supports token inheritance via `{path.to.token}` reference syntax.
- The official specification lives in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), with working examples in the `examples/` directory.

## Frequently Asked Questions

### What is the required structure for DESIGN.md YAML front matter?

The structure must begin and end with a line containing only three hyphens (`---`). Inside this block, only the `name` field is mandatory. All other fields—including `version`, `description`, `colors`, `typography`, `rounded`, `spacing`, and `components`—are optional but must follow the type definitions specified in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) when present.

### How do I reference other tokens in component definitions?

Use curly-brace notation with dot-notation paths: `{section.token-name}`. For example, to reference a primary color in a button component, write `backgroundColor: "{colors.primary}"`. This syntax allows components to inherit values defined in the global token categories.

### What file defines the official schema specification?

The complete schema definition, including validation rules for **Color**, **Dimension**, **Typography**, and token references, is documented in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) at lines 43-58. This file serves as the canonical reference for implementers building parsers for the DESIGN.md format.

### Can spacing values be bare numbers or must they include units?

The `spacing` category accepts either **Dimension** values (strings with units like `px`, `em`, or `rem`) or bare numbers. In contrast, the `rounded` category strictly requires **Dimension** values with units. This distinction is enforced by the validation logic described in the repository specification.