How to Use Token References in Component Definitions in Design.md

Token references in component definitions use curly-brace syntax {path.to.token} to pull values from the YAML front-matter, ensuring components stay synchronized with the central design system.

Design.md (from google-labs-code/design.md) is a specification that separates machine-readable design tokens from human-readable documentation. By referencing tokens within component definitions, you create a single source of truth that propagates changes automatically when tokens are updated.

Syntax Rules for Token References

According to the specification in docs/spec.md, token references must follow strict formatting rules to be recognized by the linter.

Curly-Brace Wrapping and Path Structure

A valid token reference must be wrapped in curly braces and contain the full path to a primitive token value. As documented in the Token References paragraph of the specification (lines 86-87 in docs/spec.md), the syntax follows the pattern {category.token-name}.

For example:

• {colors.primary} resolves to a color value
• {rounded.lg} resolves to a border radius value
• {spacing.gutter} resolves to a spacing value

Composite Token Support

Within the components: section, you may reference both primitive tokens and composite tokens. While primitive tokens resolve to single values (like 12px or #1a1a1a), composite tokens—such as typography definitions—resolve to entire objects containing multiple properties.

components:
  button-primary:
    typography: "{typography.label-md}"  # Resolves to full typography object

Validation and Error Handling

The linter implementation in packages/cli/src/linter/spec-config.ts validates every token reference at build time. If a referenced token does not exist in the YAML front-matter, the linter emits a broken-ref error, preventing broken styles from reaching production.

Practical Examples in Component Definitions

The following examples from examples/totality-festival/DESIGN.md (lines 101-108) demonstrate real-world usage patterns.

Referencing Color and Spacing Tokens

Assign semantic color roles and spacing values to component properties:

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.lg}"
    padding: 12px

Mixing Literal Values with Token References

You can combine hardcoded values with token references for one-off adjustments:

  card-glass-level-2:
    backgroundColor: "rgba(52, 52, 58, 0.2)"
    rounded: "{rounded.xl}"
    padding: "{spacing.gutter}"

Referencing Composite Typography Tokens

Typography tokens encapsulate multiple properties (font family, size, weight, line height) under a single reference:

  input-field:
    backgroundColor: "{colors.surface-container-lowest}"
    textColor: "{colors.on-surface}"
    typography: "{typography.body-md}"
    rounded: "{rounded.lg}"
    padding: 12px

Consistent Token Application Across Components

Maintain visual consistency by reusing the same tokens across different component types:

  badge-celestial:
    backgroundColor: "{colors.tertiary-container}"
    textColor: "{colors.on-tertiary-container}"
    typography: "{typography.label-md}"
    rounded: "{rounded.full}"
    padding: 4px

Token Resolution at Build Time

When you run npx @google/design.md lint, the CLI processes the DESIGN.md file and resolves each {...} expression to its concrete value defined in the YAML front-matter. This resolution happens before any downstream compilation, ensuring that components receive finalized values rather than reference strings.

The resolution process:

1. Parses the YAML front-matter to build a token registry
2. Scans all component definitions for curly-brace patterns
3. Validates paths against the registry (emitting broken-ref errors for invalid paths)
4. Substitutes references with actual values

This build-time resolution guarantees that examples/paws-and-paths/DESIGN.md and examples/atmospheric-glass/DESIGN.md maintain strict consistency with their respective token systems.

Summary

• Token references use curly-brace syntax ({path.to.token}) to link component properties to design tokens defined in YAML front-matter.
• Both primitive and composite tokens are supported within component definitions, enabling references to simple values like colors or complex objects like typography.
• The linter validates references at build time via packages/cli/src/linter/spec-config.ts, reporting broken-ref errors for undefined tokens.
• Build-time resolution occurs when running npx @google/design.md lint, replacing references with concrete values before downstream processing.

Frequently Asked Questions

Can I use token references outside of the components section?

Token references are primarily intended for use within the components: section of your DESIGN.md file. While the specification focuses on component definitions, the curly-brace syntax may be supported in other contexts depending on your specific linter configuration, but the canonical usage is for component property assignment.

What happens if I reference a token that doesn't exist?

The linter will emit a broken-ref error during validation. This error prevents the build from completing successfully, ensuring that you cannot accidentally ship components with missing or undefined style values. You must either define the missing token in the YAML front-matter or remove the invalid reference.

Are composite typography tokens treated differently than primitive tokens?

Yes, composite tokens like {typography.label-md} resolve to entire objects containing multiple CSS properties (font-family, font-size, line-height), whereas primitive tokens like {colors.primary} resolve to single scalar values. Both are valid within component definitions, but composite tokens are only permitted in properties that expect object values, such as the typography property.

How do I validate token references before building?

Run the command npx @google/design.md lint in your project directory. This command processes your DESIGN.md file, validates all token references against the YAML front-matter, and reports any broken-ref errors or path mismatches before they affect your compiled output.

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