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

> Explore DESIGN.md's three core token types: Color, Dimension, and Typography. Learn how to define them in YAML front-matter for type-safe design systems.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: api-reference
- Published: 2026-06-27

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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.

```yaml
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.

```yaml
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.

```yaml
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`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md). The front-matter parser validates entries against the schema defined in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md).

```yaml
---
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.

```yaml
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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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.