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

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, 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【/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:

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

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 validates references against the TypeScript schema, ensuring paths point to existing tokens. The 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:

// 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, which demonstrates a complete components: block with token references, and 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【/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 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 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】.

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