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

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, 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 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, 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 provides an export command that produces DTCG-compatible tokens.json files.

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

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

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

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

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

This outputs a DTCG-compatible 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 file demonstrates the standard format that these tools expect.

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