# How Colors Are Specified in DESIGN.md: CSS Design Tokens and Formats

> Learn how colors are specified in DESIGN.md using CSS design tokens in YAML. Discover support for hex, rgb, hsl, oklch, and color-mix functions for flexible styling.

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

---

**Colors in DESIGN.md are declared as design tokens within YAML front-matter under the `colors` key, accepting any valid CSS color string including hex, rgb, hsl, oklch, and color-mix functions.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) specification defines a structured format for design systems where color tokens serve as the foundational palette. These tokens are specified in the document's front-matter block and power consistent theming across exported formats like Tailwind CSS and DTCG. Understanding how colors are specified in DESIGN.md ensures your design tokens validate correctly and render accurately across all target platforms.

## YAML Front-Matter Structure for Color Tokens

Design tokens reside in the YAML front-matter delimited by `---` at the start of the file. The **`colors`** key maps token names to CSS color values, requiring at least a `primary` token while supporting optional semantic tokens like `secondary`, `tertiary`, and `neutral`.

Each token name uses a valid YAML key string (e.g., `brand-accent`, `surface-default`), and every value must be a parseable CSS color literal. The parser validates these entries during the linting process to ensure conformance with the specification.

## Supported CSS Color Formats

The [`color-parser.ts`](https://github.com/google-labs-code/design.md/blob/main/color-parser.ts) module supports comprehensive CSS Color Module Level 4 and 5 syntax. The following formats are valid when specifying colors in DESIGN.md:

### Hexadecimal Values

Standard hex notation in 3, 4, 6, or 8-digit formats:

```yaml
colors:
  primary: "#1A1C1E"
  overlay: "#F7F5F2FF"  # With alpha channel

```

### Named Colors

CSS standard named colors and the `transparent` keyword:

```yaml
colors:
  danger: "red"
  canvas: "cornflowerblue"
  clear: "transparent"

```

### Functional Notation

Space-separated and comma-separated rgb, rgba, hsl, and hwb functions:

```yaml
colors:
  secondary: "rgb(108 114 120)"
  alert: "rgba(255, 0, 0, 0.5)"
  success: "hsl(120deg 100% 50% / 0.8)"
  accent: "hwb(120 0% 0%)"

```

### Wide-Gamut Colors (LAB, LCH, OKLCH)

Perceptually uniform color spaces for professional design systems:

```yaml
colors:
  brand: "lab(50 10 -20)"
  vibrant: "lch(60 30 250)"
  modern: "oklch(0.6 0.1 250)"

```

### Color Mixing

CSS Color Module Level 5 `color-mix()` for derived tokens:

```yaml
colors:
  blended: "color-mix(in srgb, red 20%, blue 80%)"
  subtle: "color-mix(in oklch, var(--primary) 30%, white)"

```

## Parsing and Normalization

The CLI validates color tokens using the **`parseCssColor`** function located in [`packages/cli/src/linter/model/color-parser.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/color-parser.ts). This parser normalizes every valid color to an sRGB representation for internal WCAG contrast calculations while preserving the original notation for export.

If a color string uses unsupported syntax or contains invalid values, the parser returns `null` and the linter reports an error. This ensures that only standards-compliant CSS colors reach the export pipeline for Tailwind, DTCG, or CSS variables.

## Referencing Color Tokens

Colors can be referenced elsewhere in the design system using token interpolation syntax:

```yaml
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.neutral}"

```

The parser resolves `{colors.tokenName}` to the underlying sRGB value at build time, enabling consistent color application across components while maintaining the source of truth in the `colors` block.

## Practical Code Examples

Real-world implementations can be found in example files such as [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md) and [`examples/paws-and-paths/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/DESIGN.md).

### Minimal Color Block

```yaml
---
name: Example System
colors:
  primary: "#1A1C1E"
  secondary: "rgb(108 114 120)"
  tertiary: "hsl(350 70% 50%)"
  neutral: "transparent"
---

```

### Wide-Gamut Implementation

```yaml
colors:
  accent: "oklch(62% 0.18 250)"
  surface: "oklch(95% 0.01 250)"

```

### Mixed Color Derivation

```yaml
colors:
  primary: "#3B82F6"
  primary-light: "color-mix(in oklch, {colors.primary} 70%, white)"

```

## Summary

- Colors are specified in DESIGN.md under the **`colors`** key in YAML front-matter.
- The **`primary`** token is required; `secondary`, `tertiary`, and `neutral` are optional conventions.
- Supported formats include hex, named colors, rgb/hsl/hwb functions, wide-gamut spaces (lab, lch, oklch), and `color-mix()`.
- The **`parseCssColor`** function in [`packages/cli/src/linter/model/color-parser.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/color-parser.ts) validates and normalizes colors to sRGB for WCAG contrast checks.
- Token references use the syntax **`{colors.tokenName}`** to maintain consistency across components.

## Frequently Asked Questions

### What CSS color formats are supported in DESIGN.md?

DESIGN.md supports hex (3, 4, 6, or 8-digit), named colors, functional notation (rgb, rgba, hsl, hwb), wide-gamut color spaces (lab, lch, oklch), and CSS Color Module Level 5 `color-mix()` functions. The parser in [`packages/cli/src/linter/model/color-parser.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/color-parser.ts) handles validation for all these formats according to the specification.

### Is the primary color token required in DESIGN.md?

Yes, the **`primary`** token is mandatory in the `colors` section. While additional tokens like `secondary`, `tertiary`, and `neutral` are conventional and widely used, the specification requires at least one `primary` color for the design system to validate successfully.

### How does the color parser handle invalid color values?

The **`parseCssColor`** function returns `null` for unsupported syntaxes or invalid color strings, causing the linter to report an error. This prevents malformed colors from entering the export pipeline while allowing valid CSS colors to pass through for sRGB normalization and contrast calculations.

### Can I use color-mix() functions in DESIGN.md color tokens?

Yes, `color-mix(in <color-space>, color1 <percentage>, color2 <percentage>)` is fully supported. This allows you to create derived tokens programmatically, such as mixing your primary brand color with white to generate tint variants, while maintaining the original CSS syntax in exported files.