# How to Use DESIGN.md Tokens in Components: The Complete Reference

> Learn to use DESIGN.md tokens in components with the {path.to.token} syntax. Export to CSS Tailwind or JSON after CLI validation. Get the complete reference now.

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

---

**Reference any token inside a component definition using the `{path.to.token}` syntax within the `components` block of your DESIGN.md front‑matter, then validate with the CLI linter and export to CSS, Tailwind, or JSON.**

The DESIGN.md specification (google-labs-code/design.md) separates design systems into machine‑readable **tokens** and human‑readable prose. When building UI components, you can reference these tokens directly inside the YAML front‑matter to maintain a single source of truth for colors, typography, spacing, and rounded corners.

## Understanding the Token Reference Syntax

According to the specification in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 86‑92), DESIGN.md uses a specific token‑reference syntax to inject values into component definitions.

### The Curly‑Brace Syntax

Enclose the absolute path to any token in curly braces: `{colors.primary}`, `{rounded.sm}`, or `{typography.label-md}`. The path starts from the root of the token tree.

### Primitive vs. Composite References

Outside the `components` block, references must resolve to primitive values. Inside `components`, you may also reference composite types such as full typography objects.

## Defining Components in DESIGN.md

Component definitions live under the `components` block of the token schema. As documented in [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md) (lines 1450‑1558), each component maps property names to either literal values or token references.

```yaml
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

```

In this example:

- `backgroundColor` pulls the actual hex value from `colors.tertiary`
- `textColor` resolves to `colors.on-tertiary`
- `rounded` re‑uses the `sm` radius defined in the `rounded` token group
- `padding` is a literal dimension, illustrating that components can mix token references and hard‑coded values

### Creating Component Variants

Variants such as hover and active states are expressed as separate entries sharing a base name. This composition pattern keeps related states organized while allowing specific token overrides.

## Validating Token References

Broken references cause the build to fail. The CLI linter enforces token resolution before export.

### Running the Linter

Execute `npx @google/design.md lint` to verify that every `{...}` reference resolves to a defined token. The validation logic is implemented 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).

```bash
npx @google/design.md lint design.md

```

## Exporting Components to Production Code

Once validated, export the component definitions to your target platform using the command defined in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts).

### Exporting to Tailwind CSS

```bash
npx @google/design.md export --format css-tailwind design.md > tailwind-theme.css

```

The generated CSS contains variables that map component tokens to concrete values:

```css
/* Generated from design.md */
--color-primary: #0d47a1;
--radius-sm: 4px;
--component-card-bg: var(--color-primary);
--component-card-text: #ffffff;
--component-card-rounded: var(--radius-sm);

```

### Consuming Tokens in React

```tsx
import './tailwind-theme.css';

export const Card = ({children}: {children: React.ReactNode}) => (
  <div className="bg-component-card-bg text-component-card-text rounded-component-card-rounded p-4">
    {children}
  </div>
);

```

The class names are derived from the exported Tailwind variables, guaranteeing that the component’s visual style stays in sync with the DESIGN.md token definitions.

## Summary

- Use `{path.to.token}` syntax inside the `components` block to reference primitive or composite tokens
- Define component variants as separate entries with shared base names (e.g., `button-primary` and `button-primary-hover`)
- Run `npx @google/design.md lint` to validate references against the schema
- Export via `npx @google/design.md export` to generate CSS, Tailwind, or DTCG JSON
- Mix literal values and token references freely within component properties

## Frequently Asked Questions

### What file paths can I reference in component tokens?

You must use absolute paths from the root of the YAML token tree. For example, `{colors.primary}` references the `primary` key under the top‑level `colors` block, while `{rounded.sm}` references the `sm` key under the `rounded` group.

### Can I use composite tokens like typography objects inside components?

Yes. While most token groups require primitive values, the `components` block explicitly allows references to composite types such as `{typography.label-md}` which resolve to full typography objects rather than single values.

### How do I validate that my component token references are correct?

Run the CLI linter with `npx @google/design.md lint <file>`. The linter, implemented 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), checks that every reference resolves to a defined token and reports broken references as errors.

### What export formats support component tokens?

The CLI supports multiple formats including CSS, Tailwind CSS, and DTCG JSON. Use `npx @google/design.md export --format <format>` to generate platform‑specific code from your DESIGN.md component definitions.