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

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 (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 (lines 1450‑1558), each component maps property names to either literal values or token references.

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.

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.

Exporting to Tailwind CSS

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:

/* 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

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, 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.

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