How to Reference Tokens Within DESIGN.md: Syntax and Examples

Token references in DESIGN.md use curly-brace syntax {section.tokenName} to pull values from YAML front-matter into your design prose and component definitions.

The google-labs-code/design.md repository provides a specification-driven approach to design documentation that relies on token references to maintain consistency. Learning how to reference tokens within DESIGN.md allows you to establish a single source of truth for design values while ensuring automatic propagation of updates throughout your specification. This system is formally defined in docs/spec.md and implemented across the example repositories.

Token Reference Syntax Basics

DESIGN.md implements curly-brace token references that resolve values defined in the YAML front-matter at parse time. A reference follows the hierarchical path of the token tree using dot notation enclosed in braces:

{section.tokenName}
{section.subSection.tokenName}

The section represents a top-level key in the YAML front-matter—such as colors, typography, or components—while the token path points to a concrete value defined elsewhere in the file. This syntax is formally described in docs/spec.md as Token Reference {path.to.token} and is resolved deterministically by processing agents.

Practical Token Reference Examples

Simple Color References

Reference individual tokens directly within your markdown body to ensure values stay synchronized:

---
colors:
  primary: "#1A1C1E"
---

## Button

The primary button uses the **primary** color: `{colors.primary}`.

When the file is processed, the {colors.primary} placeholder resolves to #1A1C1E.

Component Property References

Components can reference tokens to maintain consistent styling across your design system, as demonstrated in examples/totality-festival/DESIGN.md:

---
colors:
  tertiary: "#B8422E"
rounded:
  sm: 4px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    rounded: "{rounded.sm}"

Here, backgroundColor pulls from colors.tertiary while rounded references rounded.sm, ensuring components inherit updates from the global token definitions.

Nested Object References

Reference entire nested objects to reuse complex typography or spacing definitions:

---
typography:
  heading:
    fontFamily: Public Sans
    fontSize: 3rem
components:
  header:
    typography: "{typography.heading}"

The header component inherits the complete heading typography object via the {typography.heading} reference, preserving all nested properties.

Prose Integration

Embed token references directly within explanatory text to keep documentation synchronized with design values:

--- 
colors:
  accent: "#FF5733"
---

## Call‑to‑Action

Use the accent color `{colors.accent}` for all primary buttons.

This approach ensures that when the accent token value changes in the front-matter, the surrounding prose automatically reflects the current value without manual updates.

Validation and Error Handling

The DESIGN.md toolchain includes a linter that validates token references against the defined YAML front-matter. According to the test fixtures in packages/cli/src/linter/fixtures/DESIGN-test.md, the linter enforces the broken-ref rule, which flags any {...} reference that cannot be resolved. This prevents deployment of documents containing invalid token paths and catches typos or missing definitions early in the development workflow.

Summary

• Curly-brace syntax: Use {section.tokenName} or {section.subSection.tokenName} to reference values from YAML front-matter.
• Hierarchical paths: Follow the dot-notation path of your token tree to access specific values or nested objects.
• Front-matter dependency: Tokens must be defined in the YAML front-matter before they can be referenced in prose or components.
• Automatic validation: The linter checks references against the broken-ref rule to ensure all tokens resolve correctly.
• Real-world examples: Reference implementations appear in examples/totality-festival/DESIGN.md and examples/paws-and-paths/DESIGN.md.

Frequently Asked Questions

Can I reference deeply nested tokens in DESIGN.md?

Yes. The syntax supports arbitrary nesting using dot notation. For example, {typography.heading.fontSize} resolves a token defined as typography: heading: fontSize: 3rem in the YAML front-matter, allowing you to access specific properties within complex token objects.

What happens if a token reference cannot be resolved?

The DESIGN.md linter flags unresolved references using the broken-ref rule. This validation step prevents deployment of documents containing invalid token paths, ensuring design consistency and catching typos or refactoring errors before they reach production.

Can token references be used outside of YAML front-matter?

Absolutely. While tokens are defined in the YAML front-matter, they can be referenced within the markdown body prose, in component definitions under the components section, or anywhere else in the document that accepts text values, making them versatile for both code and documentation.

How does the token reference system ensure design consistency?

By resolving references at parse time, agents guarantee that the same token value appears wherever it is referenced. This deterministic approach, combined with the broken-ref validation rule enforced by the linter, creates a single source of truth that automatically propagates updates throughout your design specification.

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