DESIGN.md Token Types: Color, Dimension, and Typography Specification

DESIGN.md supports three core token types—Color, Dimension, and Typography—defined in YAML front-matter to create type-safe design systems.

The google-labs-code/design.md repository defines a typed token system that standardizes design values across projects. According to the specification in docs/spec.md, these token types enable consistent theming through machine-readable YAML front-matter. Understanding these three fundamental types is essential for building scalable design systems with DESIGN.md.

Core Token Types in DESIGN.md

The DESIGN.md specification organizes design tokens into three distinct categories, each with specific validation rules and syntax requirements as implemented in google-labs-code/design.md.

Color Tokens

Color tokens accept any valid CSS color string, including hex values, named colors, functional notations, and wide-gamut formats like OKLCH. The schema validates these against standard CSS color specifications.

colors:
  primary: "#1A1C1E"
  accent: "oklch(0.7 0.15 240)"

Dimension Tokens

Dimension tokens represent length values requiring numeric values with specific unit suffixes. The specification supports px, em, and rem units only.

spacing:
  base: 16px
  lg: 32px
rounded:
  sm: 4px

Typography Tokens

Typography tokens are composite objects grouping multiple font-related properties. Each property uses appropriate sub-types: fontSize and letterSpacing use Dimension tokens, while fontWeight accepts plain numbers and fontFamily accepts strings.

typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em

Defining Token Types in DESIGN.md Front-Matter

Token definitions reside in the YAML front-matter of DESIGN.md files, as demonstrated in examples/totality-festival/DESIGN.md. The front-matter parser validates entries against the schema defined in docs/spec.md.

---
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
typography:
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: 0.0em
rounded:
  md: 8px
spacing:
  lg: 32px
---

Referencing Tokens with Interpolation Syntax

DESIGN.md implements a token reference syntax using curly braces to reuse defined values across components. This interpolation system allows tokens to reference other tokens within the design system.

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    rounded: "{rounded.md}"
    padding: "{spacing.base}"

Validation and Schema Enforcement

The CLI linter in packages/cli/src/linter/fixtures/DESIGN-test.md validates token syntax against the specification. The schema enforcement ensures that Color tokens contain valid CSS colors, Dimension tokens include supported units, and Typography tokens contain required properties.

Summary

• DESIGN.md supports three core token types: Color, Dimension, and Typography.
• Color tokens accept any valid CSS color string including hex, named, and wide-gamut formats.
• Dimension tokens require numeric values with px, em, or rem unit suffixes.
• Typography tokens are composite objects containing fontFamily, fontSize, fontWeight, lineHeight, and letterSpacing properties.
• Token definitions reside in YAML front-matter and are validated by the CLI linter according to docs/spec.md.

Frequently Asked Questions

What CSS color formats does DESIGN.md support for Color tokens?

DESIGN.md supports the full range of valid CSS color strings, including hexadecimal values (e.g., "#1A1C1E"), named colors, functional notations (rgb, hsl), and modern wide-gamut formats like OKLCH (e.g., "oklch(0.7 0.15 240)"). The specification validates these against standard CSS color specifications as documented in docs/spec.md.

Can I use units other than px, em, or rem for Dimension tokens?

No. The DESIGN.md specification strictly limits Dimension tokens to three unit suffixes: px, em, and rem. Values without units or with unsupported units (such as cm, in, or %) will fail validation by the CLI linter.

How do I reference existing tokens in component definitions?

Use the token reference syntax with curly braces: "{category.token}". For example, "{colors.primary}" references a color token, while "{spacing.base}" references a dimension token. This interpolation system works across all token types and is parsed by the DESIGN.md toolchain.

Where are the token schemas defined in the repository?

The authoritative token schemas are defined in docs/spec.md within the google-labs-code/design.md repository. This file contains the complete specification for Color, Dimension, and Typography token formats, including validation rules and supported value types.

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