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

> Discover how DESIGN.md tokens build upon the W3C Design Tokens Format, offering typed groups, reference syntax, and markdown documentation for enhanced clarity and compatibility.

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

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/README.md), the `export` command generates a **DTCG-compatible [`tokens.json`](https://github.com/google-labs-code/design.md/blob/main/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:

```bash

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

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

```yaml
---
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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/README.md)**: Contains the high-level statement that DESIGN.md tokens are inspired by the W3C format.
- **[`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)**: Defines the formal token schema and `{path.to.token}` syntax.
- **[`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts)**: Implements the `export` command that produces DTCG-compatible output.
- **[`examples/totality-festival/design_tokens.json`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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.