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

Design tokens live in the YAML front-matter at the top of a 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 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 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 (lines 41-58) and demonstrated in the 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 (lines 13-15).

Step 3: Use the Correct Value Format

Each token type requires a specific format as defined in 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.

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.

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.

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.

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:

npx @google/design.md lint

The linter validates against the formal schema in 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 file showing properly structured front-matter tokens:

---
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 files.
• Top-level keys (colors, typography, rounded, spacing, components) organize tokens by category as defined in 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 specification.

What format should I use for color tokens?

Color tokens accept any valid CSS color string. According to 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 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, checks for required tokens like primary colors, and ensures all values match their expected types (colors, dimensions, or typography objects).

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