Understanding the Relationship Between DESIGN.md Tokens and the W3C Design Tokens Format

DESIGN.md tokens are directly inspired by the W3C Design Tokens Format (DTCG), adopting its typed groups, reference syntax, and export compatibility while adding human-readable markdown documentation.

The google-labs-code/design.md repository defines a design-system specification that couples human-readable markdown prose with machine-readable design tokens expressed as YAML front-matter. Understanding the relationship between DESIGN.md tokens and the W3C Design Tokens Format reveals how this tool bridges documentation and standardized design data.

Core Alignment with W3C Standards

The DESIGN.md specification explicitly states that its token model is inspired by the W3C Design Token Format. This alignment ensures interoperability with existing design token tooling while maintaining a developer-friendly format.

Typed Token Groups

In docs/spec.md, the token schema references the Design Token JSON spec and adopts its concept of typed token groups. Tokens organize hierarchically by type, such as colors, typography, and spacing, mirroring the W3C format's structure.

Reference Syntax

Both formats share identical token referencing capabilities. The specification implements the {path.to.token} placeholder syntax, allowing tokens to reference other tokens for consistency and reuse. This syntax resolves at lint and export time, matching W3C DTCG behavior.

Export Interoperability

DESIGN.md functions as a wrapper around the W3C standard, offering seamless export capabilities that produce DTCG-compatible output.

According to README.md, the export command generates a DTCG-compatible tokens.json file. This enables tools that understand the W3C format to consume DESIGN.md tokens without modification.

Exporting to DTCG Format

Convert any DESIGN.md file to standard JSON tokens using the CLI:

# Convert DESIGN.md → DTCG tokens.json

npx @google/design.md export --format dtcg DESIGN.md > tokens.json

Consuming Exported Tokens

Once exported, use the tokens in JavaScript projects with standard W3C-compatible tooling like Style Dictionary:

import tokens from './tokens.json';

// Example: retrieve a color token
const primary = tokens.colors?.primary?.value ?? '#000000';
console.log('Primary color:', primary);

Token References in Practice

The reference syntax works within DESIGN.md YAML front-matter to create dependent tokens:

---
colors:
  primary: "#1A1C1E"
  on-primary: "#FFFFFF"
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
---

The {colors.primary} syntax resolves during the export process, ensuring that the final tokens.json contains fully resolved values compatible with W3C expectations.

Implementation Details

The relationship between these formats is codified in specific source files:

• README.md: Contains the high-level statement that DESIGN.md tokens are inspired by the W3C format.
• docs/spec.md: Defines the formal token schema and {path.to.token} syntax.
• packages/cli/src/commands/export.ts: Implements the export command that produces DTCG-compatible output.
• examples/totality-festival/design_tokens.json: Demonstrates the sample export format.

Summary

• DESIGN.md tokens follow the W3C Design Tokens Format (DTCG) structure for typed groups and references.
• The export command in packages/cli/src/commands/export.ts generates DTCG-compatible JSON for interoperability.
• Reference syntax {path.to.token} allows token reuse and resolves at export time.
• The specification in docs/spec.md explicitly maps to the W3C Design Token JSON spec.

Frequently Asked Questions

Does DESIGN.md replace the W3C Design Tokens Format?

No. DESIGN.md acts as a wrapper that adds human-readable markdown documentation around W3C-compatible tokens. It extends the format with prose context while maintaining full export compatibility.

Can I use DESIGN.md tokens with existing Style Dictionary workflows?

Yes. By running npx @google/design.md export --format dtcg, you generate a tokens.json file that conforms to W3C standards and works with Style Dictionary, Tailwind, or any DTCG-compatible tool.

What token types does DESIGN.md support?

DESIGN.md supports the same typed groups defined in the W3C specification, including colors, typography, spacing, and other dimension categories. These groups organize tokens hierarchically according to the schema defined in docs/spec.md. This structure ensures that exported tokens maintain their semantic meaning across different design tools.

How do token references resolve in DESIGN.md?

References like {colors.primary} resolve at lint and export time. The export command processes these placeholders, substituting the referenced values to produce a flat, W3C-compatible JSON structure.

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