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

> Learn to create component tokens with token references in DESIGN.md using {path.to.token} syntax for properties like backgroundColor. Streamline your design system with centralized token management.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

```yaml
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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/handler.ts), which coordinates validation, while [`packages/cli/src/linter/model/color-parser.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/color-parser.ts) handles the specific parsing of token-reference strings. As noted in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/handler.ts) and [`color-parser.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 60-66).

### Where can I find complete examples of component tokens?

The [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/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`.