# DESIGN.md Tokens and W3C Design Tokens Format: A Complete Compatibility Guide

> Explore the relationship between DESIGN.md tokens and W3C Design Tokens Format. Learn how DESIGN.md exports compatible JSON for seamless tooling interoperability.

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

---

**DESIGN.md tokens are directly inspired by the W3C Design Token Format (DTCG) and can be exported as fully compatible DTCG JSON files, allowing seamless interoperability between markdown-based design specifications and standard design token tooling.**

DESIGN.md is a specification that combines human-readable markdown documentation with machine-readable design tokens expressed as YAML front-matter. The relationship between **DESIGN.md tokens and W3C Design Tokens Format** is defined by direct inspiration and compatibility, with the specification explicitly modeling its token structure after the W3C standard to ensure seamless interoperability with existing design tools.

## How DESIGN.md Implements the W3C Design Tokens Format

The relationship between DESIGN.md and the W3C standard is explicitly defined in the specification files and represents a direct implementation of DTCG concepts.

### Token Schema and Typed Groups

In [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), the token schema explicitly references the **Design Token JSON spec** and adopts its concepts of **typed token groups**. These groups organize tokens by category, such as:

- `colors` – for color values and palettes
- `typography` – for font families, sizes, and weights  
- `spacing` – for dimension and layout values

The [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md) confirms this relationship, stating that *"DESIGN.md tokens are inspired by the W3C Design Token Format"*. This structural alignment ensures that any tool capable of parsing W3C Design Tokens can understand the fundamental organization of DESIGN.md token data.

### Reference Syntax Compatibility

Both formats share the same **reference syntax** for token reuse. DESIGN.md implements the **`{path.to.token}` placeholder syntax** defined in the W3C specification, allowing tokens to reference other tokens for consistency and single-source-of-truth maintenance.

For example, the reference `{colors.primary}` used in DESIGN.md front-matter resolves at lint and export time, mirroring the exact behavior specified in the W3C DTCG standard. This is formalized in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), which defines the resolution rules for these cross-references.

## Exporting to DTCG-Compatible JSON

DESIGN.md functions as a **wrapper around the W3C Design Tokens Format** that adds an optional markdown body for design rationale while keeping the token definition identical to the W3C standard. The CLI implementation in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts) provides an `export` command that produces **DTCG-compatible [`tokens.json`](https://github.com/google-labs-code/design.md/blob/main/tokens.json) files**.

To convert a DESIGN.md file to the W3C format:

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

```

This export capability enables seamless consumption by tools that understand the W3C format, such as Style Dictionary, Tokens Studio, or custom build pipelines. The [`examples/totality-festival/design_tokens.json`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/design_tokens.json) file in the repository demonstrates the resulting DTCG-compatible output structure.

## Practical Usage Examples

### Referencing Tokens in DESIGN.md Front-Matter

Within a DESIGN.md file, you can use W3C-style references to create relationships between tokens:

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

```

The `{colors.primary}` and `{colors.on-primary}` references resolve during the export process, producing fully dereferenced values in the output JSON.

### Consuming Exported Tokens in JavaScript

Once exported, the DTCG-compatible JSON can be imported directly into applications:

```javascript
import tokens from './tokens.json';

// Access nested color values safely
const primaryColor = tokens.colors?.primary?.value ?? '#000000';
console.log('Primary color:', primaryColor);

```

This interoperability pattern allows design systems to maintain human-readable documentation in markdown while providing machine-readable assets to development teams.

## Summary

- **DESIGN.md tokens and W3C Design Tokens Format** share a direct lineage, with the former explicitly inspired by the latter according to [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md) and [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md).
- **Typed token groups** (colors, typography, spacing) align with DTCG organizational standards.
- **The `{path.to.token}` reference syntax** enables token reuse and matches W3C resolution behavior.
- **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 tool interoperability.
- **References resolve at lint/export time**, ensuring consistency across both human and machine-readable outputs.

## Frequently Asked Questions

### Are DESIGN.md tokens identical to W3C Design Tokens?

DESIGN.md tokens are not identical but are **directly inspired by** and compatible with the W3C Design Token Format. They implement the same core concepts—typed groups, reference syntax, and value structures—while wrapping them in YAML front-matter within markdown files. The export function produces JSON that conforms strictly to the DTCG specification.

### How do I export DESIGN.md to the W3C format?

Use the CLI export command implemented in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts):

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

```

This outputs a DTCG-compatible [`tokens.json`](https://github.com/google-labs-code/design.md/blob/main/tokens.json) file that any W3C-compliant tool can consume.

### Can I use W3C reference syntax in DESIGN.md?

Yes. DESIGN.md supports the **`{group.token}` reference syntax** as defined in the W3C Design Token Format. You can reference tokens within your YAML front-matter using this syntax, and these references will resolve during the linting or export process, producing concrete values in the final output.

### What tools can consume exported DESIGN.md tokens?

Any tool that supports the **W3C Design Tokens Format** can consume the exported JSON, including Style Dictionary, Tokens Studio for Figma, Amazon Style Dictionary, and custom build pipelines. The [`examples/totality-festival/design_tokens.json`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/design_tokens.json) file demonstrates the standard format that these tools expect.