How to Create Component Tokens with Token References in DESIGN.md

Create component tokens with token references in DESIGN.md by using the {path.to.token} syntax within the components YAML map, allowing properties like backgroundColor to reference centralized design tokens such as {colors.tertiary}.

The google-labs-code/design.md specification separates design tokens (YAML front matter) from documentation prose to maintain single-source consistency. Creating component tokens with token references enables you to assign properties like backgroundColor using the {path.to.token} syntax, ensuring that any change to a primitive token automatically propagates to every component that references it.

Understanding Token Reference Syntax

According to docs/spec.md (lines 86-92), DESIGN.md implements a token-reference syntax using curly braces to dereference previously defined tokens. The format follows {path.to.token} where the path represents the hierarchical location of the source token within the YAML structure.

This syntax appears in the Token References section of the README (lines 126-132) and allows any component property to reuse values defined in top-level token groups like colors, rounded, or custom dimensions.

Creating Component Tokens with References

Component tokens live under the components map in DESIGN.md YAML front matter. To create them with token references:

1. Define base tokens in top-level maps (e.g., colors, rounded).
2. Create component entries under the components key.
3. Assign properties using the {path.to.token} syntax.

As specified in docs/spec.md (lines 60-66), the reference must resolve to a primitive value—a raw color, dimension, or number—for most token groups. However, within components, you may also reference other component tokens when composite values are needed.

Example:

colors:
  tertiary: "#0066CC"
  on-tertiary: "#FFFFFF"
  primary: "#FF0000"

rounded:
  sm: 4px

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

Here, backgroundColor references colors.tertiary, textColor references colors.on-tertiary, and rounded references rounded.sm.

Validating Token References

The DESIGN.md CLI validates token references during the linting process. Run npx @google/design.md lint DESIGN.md to verify that all {...} references resolve to existing tokens.

The linter logic resides in packages/cli/src/linter/model/handler.ts, which coordinates validation, while packages/cli/src/linter/model/color-parser.ts handles the specific parsing of token-reference strings. As noted in docs/spec.md (lines 60-66), the linter emits warnings for unknown properties and unresolved references, catching errors before they reach production.

Real-World Examples

For concrete implementations, examine examples/totality-festival/DESIGN.md in the repository. This example demonstrates production usage of component tokens, including background colors that reference centralized theme tokens.

The README (lines 41-48) provides additional examples of the colors map structure, while the specification (lines 45-52) details the component token schema.

Summary

• Component tokens with token references use the {path.to.token} syntax within the components YAML map
• References must resolve to primitive values (colors, dimensions) for most token groups
• The syntax is defined in docs/spec.md and follows the pattern {colors.tertiary} or {rounded.sm}
• Validate references using npx @google/design.md lint DESIGN.md
• Linter implementation resides in packages/cli/src/linter/model/handler.ts and color-parser.ts

Frequently Asked Questions

What is the syntax for creating component tokens with token references?

Use curly braces containing the full token path: {colors.primary}, {rounded.sm}, or {dimension.spacing}. This syntax, defined in docs/spec.md (lines 86-92), allows component properties like backgroundColor to reference centralized design tokens.

Can component tokens reference other component tokens?

Yes. While references must typically resolve to primitive values, docs/spec.md (lines 86-92) specifies that within the components map, you may reference other component tokens when you need composite values, in addition to referencing primitive tokens.

How do I validate that my token references are correct?

Run npx @google/design.md lint DESIGN.md. The linter, implemented in packages/cli/src/linter/model/handler.ts, resolves each {...} reference and verifies targets exist, reporting unresolved references and unknown properties as described in docs/spec.md (lines 60-66).

Where can I find complete examples of component tokens?

The examples/totality-festival/DESIGN.md file provides real-world usage examples. Additionally, the README (lines 44-66) shows a concrete DESIGN.md example with component tokens using token references for properties like backgroundColor.

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