# How Component Tokens in DESIGN.md Reference Other Tokens: Syntax and Examples

> Discover how component tokens in DESIGN.md reference other tokens using curly-brace syntax and a dot-separated path for clear, organized design system management.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: deep-dive
- Published: 2026-07-04

---

**Component tokens in DESIGN.md reference other tokens using curly-brace syntax `{path.to.token}` containing a dot-separated path resolved relative to the YAML front-matter root.**

DESIGN.md is a design-token specification developed by Google Labs for defining design systems in Markdown files. The specification stores tokens in YAML front-matter and allows component definitions under the `components:` key to reuse existing tokens through explicit references, keeping design systems DRY and maintainable.

## Token Reference Syntax

DESIGN.md uses a specific delimiter pattern to indicate token references. According to the specification in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), a reference is written as a value wrapped in curly braces `{}` containing a dot-separated path to another token in the YAML tree.

The path resolves relative to the root of the front-matter. For example, `{colors.primary-60}` points to the `primary-60` entry inside the `colors` map, while `{typography.label-md}` targets a composite typography object.

## Allowed Reference Targets

The system enforces different rules depending on which token group contains the reference.

### Primitive Value References

For primitive groups—**colors**, **spacing**, and **rounded**—references must point to primitive values such as hex strings or pixel values. These resolve to concrete CSS-ready values during the build process.

### Composite Value References

Inside the `components` section, you may reference **composite values** such as entire typography objects. As documented in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)【/cache/repos/github.com/google-labs-code/design.md/main/docs/spec.md#L86-L87】, this allows components to inherit complex styling definitions with a single reference.

### Recognized Component Properties

Component tokens map property names to token values or references. The specification recognizes the following properties in component definitions【/cache/repos/github.com/google-labs-code/design.md/main/docs/spec.md#L20-L30】:

- `backgroundColor`
- `textColor`
- `typography`
- `rounded`
- `padding`
- `size`
- `height`
- `width`

## Practical Component Definition Example

The `button-primary` component in the specification demonstrates cross-group references. It pulls colors from the `colors` group and corner radius from the `rounded` group:

```yaml
---
name: Example System
colors:
  primary-60: "#4A90E2"
  primary-20: "#D0E8FF"
rounded:
  md: 8px
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor:      "{colors.primary-20}"
    rounded:        "{rounded.md}"
    padding:        12px
---

```

These reference strings resolve at lint/transform time, producing concrete values (`#4A90E2`, `8px`, etc.) that downstream tools emit【/cache/repos/github.com/google-labs-code/design.md/main/docs/spec.md#L107-L114】.

## Variants and Override Patterns

Component variants such as hover or active states follow the same reference rules. A variant like `button-primary-hover` can override specific properties while inheriting others from the base component:

```yaml
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

```

## Resolution Pipeline and CLI Integration

The reference resolution happens during the build phase. The CLI parser defined in [`packages/cli/src/linter/parser/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/parser/spec.ts) validates references against the TypeScript schema, ensuring paths point to existing tokens. The [`packages/cli/src/commands/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/spec.ts) command reads the DESIGN.md file, resolves all token references, and outputs artifacts such as Tailwind configurations.

For example, the CLI transforms the YAML references into a generated Tailwind config:

```ts
// tailwind.config.js – generated from DESIGN.md
module.exports = {
  theme: {
    colors: {
      primary: "#4A90E2",
    },
    borderRadius: {
      md: "8px",
    },
  },
  plugins: [
    function ({ addComponents, theme }) {
      addComponents({
        ".btn-primary": {
          backgroundColor: theme("colors.primary"),
          borderRadius: theme("borderRadius.md"),
        },
      });
    },
  ],
};

```

Real-world implementations can be found in [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md), which demonstrates a complete `components:` block with token references, and [`examples/paws-and-paths/design_tokens.json`](https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/design_tokens.json), which shows the JSON export of resolved tokens for integration with other design-token tools.

## Summary

- **Reference syntax**: Wrap dot-separated paths in curly braces `{colors.primary-60}` to point to any token in the YAML front-matter.
- **Primitive constraints**: Groups like `colors`, `spacing`, and `rounded` must reference primitive values (strings, numbers).
- **Composite support**: Component definitions can reference complex objects like `{typography.label-md}` to inherit multiple properties.
- **Build-time resolution**: The CLI resolves references during linting and transformation, outputting concrete values for Tailwind and other tools.
- **DRY propagation**: Changes to base tokens automatically cascade to all components referencing them, ensuring consistency across the design system.

## Frequently Asked Questions

### What is the exact syntax for referencing a token in DESIGN.md?

Use curly braces containing a dot-separated path relative to the root of the YAML front-matter. For example, `{colors.primary-60}` resolves to the value of the `primary-60` key inside the `colors` map. The specification defines this syntax in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)【/cache/repos/github.com/google-labs-code/design.md/main/docs/spec.md#L86】.

### Can component tokens reference other component tokens?

No. Component tokens should reference primitive groups (colors, spacing, rounded) or composite tokens like typography definitions. While components exist in the same YAML tree, the specification expects component properties to reference base tokens rather than other component definitions to maintain clear dependency hierarchies.

### How are token references validated?

The CLI linter in [`packages/cli/src/linter/parser/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/parser/spec.ts) validates references at parse time against the TypeScript schema. If a reference path does not exist in the token tree, the linter throws an error before any code generation occurs, preventing broken references from reaching production CSS or configuration files.

### When do references get resolved to actual values?

Resolution occurs at lint and transform time. The CLI command in [`packages/cli/src/commands/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/spec.ts) reads the DESIGN.md front-matter, resolves all `{path.to.token}` references to their concrete values (hex codes, pixel values, etc.), and generates downstream artifacts like Tailwind configs or JSON token exports【/cache/repos/github.com/google-labs-code/design.md/main/docs/spec.md#L107-L114】.