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

> Learn how to use token references in component definitions with Design.md. This guide shows you how to use curly-brace syntax to sync components with your design system.

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

---

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

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

```yaml
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:

```yaml
  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:

```yaml
  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:

```yaml
  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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/DESIGN.md) and [`examples/atmospheric-glass/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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.