Supported Color Token Formats in DESIGN.md: Complete Reference

DESIGN.md accepts any valid CSS color string—including hex notation, named colors, rgb(), oklch(), and color-mix() syntax—and converts all values to sRGB for WCAG contrast calculations while preserving the original string for display.

The google-labs-code/design.md specification defines a comprehensive Color token type for design system documentation. Understanding the supported formats for color tokens ensures your design files remain compatible with automated accessibility checks and cross-platform export tools.

Complete List of Supported Color Formats

According to the specification in docs/spec.md (lines 62-68), DESIGN.md recognizes the following CSS color syntaxes:

Hexadecimal Notation

Hex colors are the most universally supported and recommended format. The specification accepts:

• Shorthand: #RGB and #RGBA (4-bit channels)
• Standard: #RRGGBB (8-bit channels)
• With Alpha: #RRGGBBAA (8-bit channels plus transparency)

Named Colors

Standard CSS named colors are valid, including basic keywords like red, blue, and transparent, as well as extended names such as cornflowerblue.

Functional Syntax

Traditional CSS color functions are fully supported:

• rgb() and rgba() — Red, Green, Blue notation with optional alpha
• hsl() and hsla() — Hue, Saturation, Lightness with optional alpha
• hwb() — Hue, Whiteness, Blackness notation

Wide-Gamut Color Functions

For modern displays, the specification supports perceptually uniform color spaces:

• oklch() — Oklab Lightness, Chroma, Hue
• oklab() — Oklab Lightness, a-axis, b-axis
• lch() — CIE Lightness, Chroma, Hue
• lab() — CIE Lab Lightness, a-axis, b-axis

CSS Color Mixing

The color-mix() function enables dynamic interpolation between colors using the syntax color-mix(in srgb, color1 percentage, color2 percentage).

Internal Processing and sRGB Conversion

When DESIGN.md parses color tokens, it converts all input formats to sRGB for WCAG contrast ratio calculations. This ensures accessibility compliance regardless of the input syntax.

The system retains the original color string for display purposes and export operations. This allows designers to preserve their preferred authoring format while maintaining technical accuracy for automated accessibility checks.

Practical Implementation Examples

You can define color tokens in YAML frontmatter using any supported format:

colors:
  primary: "#1A1C1E"                     # Hex (default recommendation)

  secondary: "rgb(108, 114, 120)"        # rgb()

  tertiary: "oklch(62% 0.18 250)"        # Wide‑gamut oklch()

  neutral: "transparent"                 # Named keyword

  accent: "color-mix(in srgb, #ff0000 30%, #0000ff 70%)"  # color‑mix

Reference these tokens in component definitions using the token syntax:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"

Key Files and Resources

Understanding the specification requires referencing these source files:

• docs/spec.md — Contains the formal token schema and the exhaustive list of supported color formats (lines 62-68)
• README.md — Provides a quick overview and basic examples of color token usage
• examples/**/DESIGN.md — Real-world example files demonstrating various color formats in production design systems

Summary

• DESIGN.md accepts any valid CSS color string as a color token value
• Supported formats include hex notation, named colors, rgb()/hsl(), wide-gamut functions (oklch, lab), and color-mix()
• All colors are internally converted to sRGB for WCAG contrast compliance
• The #RRGGBB hex format is the most universally supported and recommended syntax
• Original color strings are preserved for display and export while standardized values handle accessibility calculations

Frequently Asked Questions

Does DESIGN.md support transparent colors?

Yes. You can use the transparent named keyword or specify alpha channels using #RRGGBBAA hex syntax, rgba(), or hsla() functional notation. The alpha component is preserved during sRGB conversion for accurate contrast calculations against varying backgrounds.

Are wide-gamut colors like oklch() converted to sRGB?

Yes. While you can author tokens using oklch(), oklab(), lch(), or lab() syntax, the system converts these to sRGB for WCAG contrast checks. The original wide-gamut string remains in the output for browsers that support display-p3 or other advanced color spaces, but accessibility calculations use the sRGB fallback values.

Can I use CSS variables or custom properties in color tokens?

No. The specification requires literal color values or references to other design tokens using the {colors.token-name} syntax. Raw CSS var() functions are not supported in the current token schema defined in docs/spec.md.

What is the recommended format for maximum compatibility?

Hexadecimal notation (#RRGGBB) is the recommended format. It offers the broadest compatibility across design tools, export pipelines, and legacy systems while remaining human-readable. Use wide-gamut formats like oklch() only when targeting modern displays with specific color space requirements.

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