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

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 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 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:

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

Named Colors

CSS standard named colors and the transparent keyword:

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

Functional Notation

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

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:

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:

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. 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:

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 and examples/paws-and-paths/DESIGN.md.

Minimal Color Block

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

Wide-Gamut Implementation

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

Mixed Color Derivation

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

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