DESIGN.md Design Token Types and Formats: Complete Reference

DESIGN.md supports five primary design token types—colors, typography, rounded, spacing, and components—embedded in YAML front-matter with CSS-compatible formats including hex, functional colors, dimensions, and token references.

The google-labs-code/design.md repository defines a typed design token system that lives directly in Markdown files. According to the specification in docs/spec.md, these design token types and formats align with standard CSS values while supporting modern wide-gamut color spaces and flexible dimension units.

Supported Design Token Types

The DESIGN.md schema organizes tokens into five distinct groups, each with specific value constraints and use cases as defined in the specification.

Colors

The colors token group accepts any valid CSS color string. According to docs/spec.md (lines 62-69), these values are normalized to sRGB internally for contrast checking, but the original notation is preserved for export.

Typography

Typography tokens require an object containing fontFamily, fontSize, fontWeight, lineHeight, and letterSpacing (lines 74-82 in docs/spec.md). The specification notes that fontWeight may be expressed as either a bare number or quoted string, while lineHeight accepts either a dimension (e.g., 24px) or a unit-less multiplier (e.g., 1.6).

Rounded

Rounded tokens use the <Dimension> type for corner radii, expressed as strings with units like 4px or 0.25rem (lines 84-85).

Spacing

Spacing tokens accept either <Dimension> values (e.g., 8px, 0.5rem) or plain numbers for unit-less ratios, providing flexibility for both absolute and relative spacing definitions (lines 52-55).

Components

Components tokens describe component-specific properties such as backgroundColor and textColor. Values may be literal strings or references to other tokens within the YAML tree (lines 56-58).

Token Value Formats and Syntax

Each token type enforces specific formatting rules that maintain compatibility with CSS standards while enabling modern design workflows.

Color Formats

DESIGN.md accepts comprehensive CSS color syntax as specified in docs/spec.md:

• Hexadecimal: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
• Named colors: red, cornflowerblue, transparent
• Functional notation: rgb(), rgba(), hsl(), hsla(), hwb()
• Wide-gamut: oklch(), oklab(), lch(), lab()
• Color mixing: color-mix(in srgb, …)

Dimension Values

Dimensions are strings suffixed with CSS units (px, em, rem). Examples include 16px and 0.125rem. These apply to rounded corners, spacing, and typography properties like fontSize and letterSpacing.

Typography Objects

Typography tokens require a structured YAML map:

fontFamily: <string>
fontSize: <Dimension>
fontWeight: <number>
lineHeight: <Dimension|number>
letterSpacing: <Dimension>

Token References

Values wrapped in curly braces create references to other tokens in the same YAML tree, such as {colors.primary-60} or {typography.label-md}. Within the components section, these references can target composite tokens, enabling centralized design system maintenance.

Practical Implementation

Complete YAML Front-Matter Example

The following example from the specification demonstrates all supported token types and formats:

---
name: Example Design System
colors:
  primary: "#1A1C1E"
  secondary: "rgb(108,114,120)"
  accent: "oklch(0.6 0.2 250)"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
rounded:
  sm: 4px
spacing:
  base: 16px
  xs: 4px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.secondary}"
    typography: "{typography.h1}"
    rounded: "{rounded.sm}"
    padding: 12px
---

JSON Export Structure

The CLI command implemented in packages/cli/src/commands/export.ts converts these YAML definitions into structured JSON following the format seen in examples/totality-festival/design_tokens.json:

{
  "colors": {
    "primary": {
      "$type": "color",
      "$value": {
        "colorSpace": "srgb",
        "components": [0.1, 0.12, 0.14],
        "hex": "#1A1C1E"
      }
    }
  },
  "typography": {
    "h1": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Public Sans",
        "fontSize": { "value": 48, "unit": "px" },
        "fontWeight": 600,
        "lineHeight": { "value": 1.1, "unit": "" },
        "letterSpacing": { "value": -0.02, "unit": "em" }
      }
    }
  },
  "rounded": {
    "sm": {
      "$type": "dimension",
      "$value": { "value": 0.25, "unit": "rem" }
    }
  }
}

The linter in packages/cli/src/linter/spec-config.ts validates these definitions against the schema, ensuring type safety across the build pipeline.

Summary

• DESIGN.md embeds five token types in YAML front-matter: colors, typography, rounded, spacing, and components.
• Color tokens support hex, named, functional, wide-gamut (oklch, oklab), and color-mix syntax, normalized to sRGB for contrast checking.
• Typography tokens require structured objects with fontFamily, fontSize, fontWeight, lineHeight, and letterSpacing properties.
• Dimension values (rounded and spacing) use CSS units (px, em, rem) or unit-less numbers for ratios.
• Token references using curly brace syntax ({colors.primary}) enable composition and inheritance across the design system.
• The CLI export tool converts these YAML definitions to JSON, TypeScript, or Tailwind configurations while preserving type annotations.

Frequently Asked Questions

What file format does DESIGN.md use for design tokens?

DESIGN.md embeds design tokens in YAML front-matter within Markdown files. The schema is defined in docs/spec.md and validated by the linter in packages/cli/src/linter/spec-config.ts.

Can I use modern CSS color spaces like OKLCH in DESIGN.md?

Yes. The specification explicitly supports wide-gamut color spaces including oklch(), oklab(), lch(), and lab(), alongside traditional hex, RGB, and HSL values. These are normalized to sRGB internally for contrast calculations but preserve the original notation in exports.

How do I reference one token from another in DESIGN.md?

Wrap the token path in curly braces to create a reference. For example, use {colors.primary-60} to reference a color, or {typography.label-md} to reference a composite typography token. This works within the components section and enables centralized updates across your design system.

What units are supported for spacing and rounded tokens?

Spacing accepts either dimension strings with units (px, em, rem) or unit-less numbers for ratios. Rounded tokens specifically require dimension values with units. The CLI export preserves these units in the generated JSON output as shown in examples/totality-festival/design_tokens.json.

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