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

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

The 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 and enforced by the validation engine in 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 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, 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, 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

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

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

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