Supported Token Categories in DESIGN.md: The Complete Guide

DESIGN.md supports five normative token categories—colors, typography, rounded, spacing, and components—defined in the YAML front-matter and validated by the built-in linter.

DESIGN.md provides a structured format for defining design systems as code within the google-labs-code/design.md repository. The specification organizes design tokens into distinct categories that downstream tools consume, validate, and export to various formats like Tailwind CSS or DTCG. Understanding these supported token categories is essential for creating valid design system files that pass linting and integrate correctly with the CLI tooling.

The Five Supported Token Categories

According to the official specification in docs/spec.md, DESIGN.md recognizes exactly five token categories that appear as top-level keys in the YAML front-matter. These categories are normative and enforced by the linter.

Colors

The colors category defines named color values using any valid CSS color string. These tokens serve as the foundation for theming across your design system.

colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"

Typography

The typography category captures font-related properties including fontFamily, fontSize, fontWeight, and lineHeight. This enables systematic control over text styling throughout the interface.

typography:
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6

Rounded

The rounded category establishes a scale of corner-radius tokens, mapping abstract levels to specific dimension values. This typically defines border radius values for UI components.

rounded:
  sm: 4px
  md: 8px

Spacing

The spacing category defines layout spacing tokens—either dimensions or unit-less numbers—for gutters, margins, and component padding.

spacing:
  base: 16px
  sm: 8px
  lg: 32px

Components

The components category contains component-specific token maps that reference the other four categories or define literal values directly. This is where high-level UI components assemble their design tokens.

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

Defining Token Categories in DESIGN.md

A complete DESIGN.md file includes all five categories within the YAML front-matter, along with metadata fields like version, name, and description. Note that these metadata keys are not token categories.

---
version: alpha
name: Sample Design System
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
typography:
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
rounded:
  sm: 4px
  md: 8px
spacing:
  base: 16px
  sm: 8px
  lg: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.md}"
    padding: 12px
---

Referencing Tokens Across Categories

Components can reference tokens from other categories using the interpolation syntax {category.token}. This creates dependency chains that export tools resolve when generating platform-specific code.

components:
  card:
    borderColor: "{colors.secondary}"
    borderRadius: "{rounded.lg}"
    margin: "{spacing.lg}"

Validation and Tooling

The linter implementation in packages/cli/src/linter/ enforces these five categories strictly. Any keys outside colors, typography, rounded, spacing, and components—aside from the metadata fields version, name, or description—will trigger validation errors.

The export logic in packages/cli/src/commands/export.ts processes these categories to generate output for various formats including Tailwind CSS and DTCG. Production examples demonstrating all five categories appear in examples/totality-festival/DESIGN.md.

Summary

• DESIGN.md supports exactly five token categories: colors, typography, rounded, spacing, and components.
• These categories appear as top-level keys in the YAML front-matter of DESIGN.md files.
• Metadata keys like version, name, and description are not considered token categories.
• The linter validates category names against the specification in docs/spec.md.
• Export tools consume these categories to generate platform-specific design tokens.

Frequently Asked Questions

What are the five supported token categories in DESIGN.md?

The five supported token categories are colors, typography, rounded, spacing, and components. These categories represent the normative schema defined in the DESIGN.md specification and are strictly enforced by the linter.

Can I use custom token categories beyond the five supported ones?

No. The linter in packages/cli/src/linter/ validates that only the five official categories appear as token groups. Additional keys beyond version, name, and description metadata will cause validation errors.

How do I reference a color token in a component definition?

Use the interpolation syntax {colors.token-name}. For example, {colors.primary} references the primary color defined in the colors category within a component's backgroundColor or textColor property.

Where does the DESIGN.md specification define these categories?

The complete token schema and category definitions are documented in docs/spec.md. The linter implementation and export logic in packages/cli/src/ enforce these definitions, while real-world examples are available in examples/totality-festival/DESIGN.md.

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