# DESIGN.md Token Types and Validation: Colors, Typography, and Component Schema

> Explore DESIGN.md token types including colors, typography, and components, and discover how validation functions ensure design consistency across your projects. Learn more now.

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

---

**DESIGN.md defines five typed token groups—colors, typography, rounded, spacing, and components—each validated by specific functions like `isValidColor`, `isStandardDimension`, and `isTokenReference` in the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) linter.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) specification uses a typed token model embedded in YAML front-matter to define design systems programmatically. Understanding what token types DESIGN.md supports and how they are validated ensures your design files pass linting and export correctly to formats like Tailwind CSS v4. This guide covers the complete token schema and validation logic implemented in the source code.

## Supported Token Types

The DESIGN.md specification organizes tokens into five distinct groups, each with specific value types defined in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and enforced by the validation engine in [`packages/cli/src/linter/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/spec.ts).

### Colors

The **colors** group accepts any valid CSS color string. The validation function `isValidColor` delegates to `parseCssColor` to ensure the string conforms to CSS color grammar, supporting hex values, named colors, functional notations (rgb, hsl), and wide-gamut formats.

### Typography

The **typography** group requires a `Typography` object containing specific sub-fields: `fontFamily` (string), `fontSize` (Dimension), `fontWeight` (number), `lineHeight` (Dimension), `letterSpacing` (Dimension), `fontFeature` (optional), and `fontVariation` (optional). Dimension validation uses `isStandardDimension` for spec-compliant units (px, rem) or `isParseableDimension` for any known CSS unit.

### Rounded

The **rounded** group defines corner radii using `Dimension` values. These follow the same validation rules as typography dimensions, accepting strings like `4px` or `0.25rem` that `isStandardDimension` recognizes.

### Spacing

The **spacing** group accepts either `Dimension` strings or raw `number` values. String values are parsed by `parseDimensionParts`, while numeric values pass through directly without unit conversion.

### Components

The **components** group contains `Component` maps of sub-tokens. Each sub-token value can be a literal (string, number, boolean) or a **token reference** (e.g., `{colors.primary}`). References are validated by `isTokenReference` to ensure they match the required curly-brace syntax.

## Validation Logic and Implementation

The linter in [`packages/cli/src/linter/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/spec.ts) provides granular validation functions that enforce type safety before tokens enter the build pipeline.

### Color Parsing with `parseCssColor`

`isValidColor(raw)` returns `true` only when `parseCssColor(raw)` successfully parses the string. This guarantees that color tokens conform to the CSS Color Module Level 4 specification, rejecting malformed hex codes or invalid color names immediately.

### Dimension Standards and Units

Dimensions support two validation modes:

- **`isStandardDimension(raw)`**: Restricts units to those defined in [`spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/spec-config.ts), currently `"px"` and `"rem"`.
- **`isParseableDimension(raw)`**: Accepts any unit in the internal `CSS_UNITS` set, providing flexibility for legacy CSS units while maintaining parsing safety.

### Token Reference Syntax

Token references must match the regex pattern `^\{[a-zA-Z0-9._-]+\}$`. The `isTokenReference` function validates that the string is wrapped in curly braces and contains only alphanumeric characters, dots, underscores, and hyphens. This prevents path traversal and ensures resolvable token paths.

### Tailwind Export Name Validation

When exporting to Tailwind v4 via [`packages/cli/src/linter/tailwind/v4/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/v4/handler.ts), token names undergo additional validation against the CSS identifier pattern `/^[a-zA-Z0-9][a-zA-Z0-9-]*$/`. Invalid names trigger an `INVALID_TOKEN_NAME` error, preventing the generation of invalid CSS custom properties.

## Practical Implementation Examples

### Valid DESIGN.md Front-Matter

```yaml
---
name: Example Design
colors:
  primary: "#1A1C1E"
  secondary: "hsl(200, 30%, 50%)"
typography:
  body:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  sm: 4px
spacing:
  base: 8px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    rounded: "{rounded.sm}"
    padding: "12px"
---

```

In this example, `isValidColor` validates the hex and HSL strings, `isStandardDimension` checks the `16px` and `4px` values, and `isTokenReference` verifies the `{colors.primary}` and `{rounded.sm}` syntax.

### Programmatic Validation

```typescript
import { isValidColor, isStandardDimension, isTokenReference } from './linter/model/spec.js';

const colorOk = isValidColor('#ff8800');          // true
const dimOk   = isStandardDimension('12px');     // true
const refOk   = isTokenReference('{colors.primary}'); // true

```

If any validation returns `false`, the linter rejects the token with a descriptive error message, preventing invalid design tokens from reaching the output stage.

## Summary

- DESIGN.md supports five token groups: **colors**, **typography**, **rounded**, **spacing**, and **components**.
- Color validation relies on `isValidColor` and `parseCssColor` to enforce CSS color grammar compliance.
- Dimensions are validated against standard units (px, rem) or parseable CSS units using `isStandardDimension` and `isParseableDimension`.
- Token references must match the regex `^\{[a-zA-Z0-9._-]+\}$` and are checked by `isTokenReference`.
- Tailwind v4 exports require token names to match `/^[a-zA-Z0-9][a-zA-Z0-9-]*$/`, returning `INVALID_TOKEN_NAME` errors for non-compliant identifiers.

## Frequently Asked Questions

### What CSS color formats does DESIGN.md support?

DESIGN.md supports any valid CSS color string recognized by the `parseCssColor` function, including hex codes (#1A1C1E), named colors, rgb/rgba, hsl/hsla, and wide-gamut color functions. The `isValidColor` validator in [`packages/cli/src/linter/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/spec.ts) ensures all color values conform to the CSS Color Module specification before acceptance.

### Can I use arbitrary CSS units like `em` or `vw` in spacing tokens?

Yes, but with caveats. While `isParseableDimension` accepts any unit in the internal `CSS_UNITS` set (including `em`, `vw`, `%`), the stricter `isStandardDimension` used for typography and rounded tokens only permits `px` and `rem`. The `spacing` group accepts both `Dimension` strings and raw numbers, parsing units via `parseDimensionParts` according to the design system configuration.

### How does DESIGN.md validate token references like `{colors.primary}`?

Token references are validated by the `isTokenReference` function against the regex `^\{[a-zA-Z0-9._-]+\}$`. This ensures the reference is wrapped in curly braces and contains only valid path characters (alphanumeric, dots, underscores, hyphens). Invalid references fail linting before token resolution occurs.

### Why does my token name trigger an INVALID_TOKEN_NAME error during Tailwind export?

The Tailwind v4 emitter in [`packages/cli/src/linter/tailwind/v4/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/v4/handler.ts) requires token names to match the CSS identifier pattern `/^[a-zA-Z0-9][a-zA-Z0-9-]*$/`. Names starting with numbers, containing spaces, or using special characters other than hyphens will trigger the `INVALID_TOKEN_NAME` error. Rename your tokens to start with a letter and use only alphanumeric characters and hyphens.