# How to Add Design Tokens in DESIGN.md: A Complete Guide

> Learn how to add design tokens in DESIGN.md. This guide explains organizing tokens like colors and typography in YAML front-matter for your Design.md files.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-06-30

---

**Design tokens live in the YAML front-matter at the top of a [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file, organized under specific top-level keys like `colors`, `typography`, and `components`, with each token type requiring a specific value format.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) project defines a specification for documenting design systems in markdown. According to the source code, design tokens are declared in the YAML front-matter block that precedes the markdown content, enabling both human readability and machine consumption by agents and linting tools.

## Understanding the DESIGN.md Token Structure

The [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) specification enforces a strict schema for organizing tokens. The allowed top-level keys include `colors`, `typography`, `rounded`, `spacing`, and `components`, as defined in the token schema located in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 41-58) and demonstrated in the [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md) front-matter example (lines 10-33).

### Top-Level Token Groups

Structure your tokens under these specific categories:

- **colors** – Defines color values for your design system
- **typography** – Defines font families, sizes, weights, and line heights
- **rounded** – Defines border radius values
- **spacing** – Defines margin and padding scales
- **components** – Defines component-specific properties that reference other tokens

## How to Add Design Tokens Step by Step

### Step 1: Open or Create the DESIGN.md File

Locate the opening `---` delimiter that marks the beginning of the YAML front-matter. If you're creating a new file, start with three dashes followed by your token definitions, ending with another three dashes before your markdown content.

### Step 2: Insert Tokens Under the Appropriate Group

Add your token under the relevant top-level key. For example, add new colors under the `colors` key, not as root-level properties. The linter (`npx @google/design.md lint`) will validate that your tokens follow the expected hierarchy and flag missing required tokens—such as a missing `primary` color, which generates a warning according to the [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md) (lines 13-15).

### Step 3: Use the Correct Value Format

Each token type requires a specific format as defined in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md):

- **Color** – Any valid CSS color string such as `"#RRGGBB"`, `rgb()`, or `oklch()` (lines 62-68)
- **Dimension** – A number with a unit such as `px`, `em`, or `rem` (lines 84-85)
- **Typography** – An object containing properties like `fontFamily`, `fontSize`, and `fontWeight` (lines 74-82)
- **Component** – A key-value pair where the value may be a literal or a token reference using the `{path.to.token}` syntax (lines 27-30)

## Value Format Reference

### Color Tokens

Colors support any CSS color format. The specification explicitly allows hex codes, RGB functions, and modern color spaces like OKLCH.

```yaml
colors:
  primary: "#0A0A0A"
  secondary: "#5A5A5A"
  accent: "#FF5722"
  success: "rgb(40, 167, 69)"

```

### Dimension Tokens

Dimensions require explicit units. Valid units include `px`, `em`, and `rem`.

```yaml
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  xl: 2rem

rounded:
  sm: 4px
  md: 8px

```

### Typography Tokens

Typography definitions must be objects containing font properties. The schema requires specific keys for font metrics.

```yaml
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.2
    letterSpacing: -0.02em
  body:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5

```

### Component Tokens

Component tokens can reference other tokens using curly brace notation. This creates a dependency chain that tooling can resolve.

```yaml
components:
  button-primary:
    backgroundColor: "{colors.accent}"
    textColor: "{colors.surface}"
    rounded: "{rounded.sm}"
    padding: 12px
  alert-success:
    backgroundColor: "{colors.success}"
    textColor: "#FFFFFF"
    rounded: "{rounded.md}"
    padding: 16px

```

## Validating Your Design Tokens

After adding or modifying tokens, run the official linter to ensure syntax compliance:

```bash
npx @google/design.md lint

```

The linter validates against the formal schema in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and checks for required tokens. It will flag syntax errors, invalid value types, and missing required fields like the mandatory `primary` color.

## Complete Example

Here is a full [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file showing properly structured front-matter tokens:

```yaml
---
name: My Project
description: Example design system
colors:
  primary: "#0A0A0A"
  secondary: "#5A5A5A"
  accent: "#FF5722"
  surface: "#FFFFFF"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.2
    letterSpacing: -0.02em
  body:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  sm: 4px
  md: 8px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.accent}"
    textColor: "{colors.surface}"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview

This design system uses the tokens defined above...

```

## Summary

- **Design tokens** reside in YAML front-matter between `---` delimiters at the top of [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) files.
- **Top-level keys** (`colors`, `typography`, `rounded`, `spacing`, `components`) organize tokens by category as defined in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 41-58).
- **Value formats** vary by type: CSS color strings for colors, dimension units for spacing, and objects for typography.
- **Token references** use the `{path.to.token}` syntax to link component properties to global tokens.
- **Validation** is performed via `npx @google/design.md lint`, which checks against the schema and flags missing required tokens.

## Frequently Asked Questions

### Where do design tokens go in a DESIGN.md file?

Design tokens belong in the YAML front-matter block at the very top of the file, enclosed between triple-dash delimiters (`---`). This block appears before any markdown content and uses the specific top-level keys defined in the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) specification.

### What format should I use for color tokens?

Color tokens accept any valid CSS color string. According to [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 62-68), you can use hexadecimal codes (`#RRGGBB`), RGB functions (`rgb()`), or modern color spaces like OKLCH. The linter validates that these are parseable CSS color values.

### How do I reference one token inside another?

Use curly brace notation to reference tokens within component definitions or other token values. The syntax is `{path.to.token}`, such as `{colors.accent}` or `{rounded.sm}`. As shown in the [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md) example (lines 27-30), this allows components to inherit values from your global design tokens.

### How do I validate my DESIGN.md tokens?

Run the command `npx @google/design.md lint` in your terminal. This linter validates your file against the formal schema in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), checks for required tokens like `primary` colors, and ensures all values match their expected types (colors, dimensions, or typography objects).