How to Use Token References Like `{colors.primary}` in Component Definitions

In google-labs-code/design.md, you reference design tokens inside component definitions by wrapping the YAML path in curly braces—such as {colors.primary}—and the parser substitutes the corresponding primitive or composite value when the component is consumed.

Design tokens in the google-labs-code/design.md system are declared in the YAML front‑matter of a DESIGN.md file, and you can use token references in component definitions to keep styles synchronized without duplication. This approach lets component properties like backgroundColor and textColor point directly to centralized tokens. When the design system processes the component, each reference is resolved to its actual value according to the rules defined in docs/spec.md.

Declaring Design Tokens in YAML Front‑Matter

Before you can use a token reference, you must define the token in the YAML front‑matter of your DESIGN.md file. Tokens are organized by group—such as colors or rounded—and each group contains key‑value pairs that the parser can resolve later.

---
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
rounded:
  md: 8px
---

In this excerpt, colors.primary resolves to "#1A1C1E" and rounded.md resolves to 8px. These paths form the basis of the reference syntax used inside component definitions.

Referencing Tokens in the Components Section

Inside the components section of DESIGN.md, reference any previously defined token by wrapping its path in curly braces. The syntax is {<object-path>}, where the path follows the YAML hierarchy exactly.

## Components

button-primary:
  backgroundColor: "{colors.primary}"
  textColor: "{colors.secondary}"
  rounded: "{rounded.md}"
  padding: 12px

In the example above, backgroundColor, textColor, and rounded all use token references, while padding is defined as a static value. The parser substitutes {colors.primary} with #1A1C1E, {colors.secondary} with #6C7278, and {rounded.md} with 8px when the component is consumed.

Primitive vs. Composite Token References

The reference must point to a primitive value—such as a color string or dimension—for most token groups. However, in the components section, a reference may also point to a composite value, such as a typography object. The parser resolves these references at consumption time, allowing complex styles to remain centralized.

Real‑World Examples from the Repository

Several example design systems in the repository demonstrate this pattern in production DESIGN.md files. Each project uses the same {<group>.<key>} syntax to keep component styles synchronized with the central token source.

• Totality Festival – In examples/totality-festival/DESIGN.md at line 103, the component sets backgroundColor: "{colors.primary}" to reference the top‑level colors.primary token defined in the file’s front‑matter.

• Paws and Paths – In examples/paws-and-paths/DESIGN.md at line 113, a button component uses the same pattern with backgroundColor: "{colors.primary}" for a different design system.

• Atmospheric Glass – In examples/atmospheric-glass/DESIGN.md at line 101, a component uses textColor: "{colors.primary}" to demonstrate color token usage inside a typography‑related component.

These examples show that the curly‑brace reference pattern stays consistent across projects, regardless of the component type.

Token Reference Rules in the Specification

The authoritative rules for token substitution are documented in docs/spec.md. According to the specification at line 86, the parser evaluates every token reference at build time and replaces it with the actual token value. This guarantees that component definitions stay declarative and automatically reflect any updates to the underlying design tokens.

Key points from the specification include:

• References follow the exact YAML hierarchy (e.g., colors.primary-60, rounded.md).
• Component definitions can freely mix token references with static values.
• Composite references are permitted in the components section, enabling reuse of structured token objects.

Summary

• Define design tokens in the YAML front‑matter of DESIGN.md.
• Use the syntax {<object-path>} to reference a token inside the components section.
• Primitive references resolve to strings or numbers for properties like backgroundColor and rounded.
• The components section also supports composite references, such as typography objects.
• The parser substitutes references at consumption time according to the rules in docs/spec.md.
• Real‑world examples in examples/totality-festival/DESIGN.md, examples/paws-and-paths/DESIGN.md, and examples/atmospheric-glass/DESIGN.md demonstrate the pattern.

Frequently Asked Questions

What is the exact syntax for a token reference?

The syntax is {<object-path>}, where <object-path> is the YAML hierarchy path to the token. For example, {colors.primary} points to the primary key inside the colors group. The parser looks up this path in the front‑matter and replaces the reference with the stored value.

Can token references point to composite values?

Yes, but only within the components section. While most token groups require references to resolve to primitive values like strings or numbers, the components section also allows references to composite values such as typography objects. The parser resolves these when the component is consumed.

Where are design tokens defined?

Design tokens are declared in the YAML front‑matter of a DESIGN.md file. You define groups such as colors and rounded, and then reference specific keys from those groups inside your component definitions using the curly‑brace syntax.

Do component definitions support nested token paths?

Yes. You can reference nested keys by following the YAML hierarchy. For instance, colors.primary-60 or rounded.md are valid paths. As long as the path exists in the front‑matter, the parser can resolve it inside a component property.

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