# DESIGN.md Design Token Types and Formats: Complete Reference > Discover DESIGN.md design token types like colors, typography, and spacing. Learn about YAML front-matter and CSS-compatible formats including hex and functional colors. - Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md) - Tags: api-reference - Published: 2026-06-30 --- **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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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 `` type for corner radii, expressed as strings with units like `4px` or `0.25rem` (lines 84-85). ### Spacing **Spacing** tokens accept either `` 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`](https://github.com/google-labs-code/design.md/blob/main/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: ```yaml fontFamily: fontSize: fontWeight: lineHeight: letterSpacing: ``` ### 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: ```yaml --- 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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts) converts these YAML definitions into structured JSON following the format seen in [`examples/totality-festival/design_tokens.json`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/design_tokens.json): ```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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and validated by the linter in [`packages/cli/src/linter/spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/design_tokens.json).