DESIGN.md vs DTCG: Which to Use

Two formats with different goals#

Both DESIGN.md and the W3C DTCG format are ways to represent design tokens. They approach the problem from different angles, and understanding those angles is the fastest way to decide which one belongs in your workflow.

What DESIGN.md is#

DESIGN.md (@google/design.md, Apache 2.0, v0.3.0) is a file format that lives in a code repository alongside README.md. It has two layers:

1. YAML frontmatter: machine-readable tokens (colors, typography, spacing, rounded corners, components).
2. Markdown body: human-readable prose explaining design rationale, organized into canonical sections.

The file is the brief. It is designed to be read by designers, engineers, and AI coding agents from a single source. The @google/design.md CLI can lint it, diff two versions, and export to several target formats.

What DTCG is#

DTCG stands for the W3C Design Tokens Community Group. The group publishes an open specification for a JSON-based token interchange format. As of 2025, the spec reached schema version 2025.10.

Tokens in a DTCG file are JSON objects. Each token has a $value (the actual value) and optionally a $type (the token's semantic type, such as color, dimension, or typography). Groups of tokens can also carry a $type at the group level, which child tokens inherit.

A minimal DTCG snippet looks like this:

{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "color": {
    "$type": "color",
    "primary": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0.102, 0.11, 0.118],
        "hex": "#1a1c1e"
      }
    }
  }
}

DTCG files conventionally use the .tokens or .tokens.json extension. The format is built for tool-to-tool handoff: design tools, token pipelines, and code generators can all consume the same file without a custom parser.

Side-by-side comparison#

When to reach for each#

Reach for DESIGN.md when:

• You want one file that designers, engineers, and AI coding agents can all read without additional tooling.
• You need prose rationale alongside token values (brand voice, accessibility notes, usage guidance).
• You want linting, diffing, and export from a single CLI command.
• You are working with AI agents and want durable design context that travels with the code.

Reach for DTCG when:

• You need to pass tokens between design tools and code generators that already support the format.
• You are building or maintaining a token pipeline that spans multiple tools (design tool export, transformation, platform-specific generation).
• Your team works with tooling built around the W3C spec.

The two formats are not exclusive. Many teams author design decisions in DESIGN.md and export to DTCG for downstream tooling.

The bridge: exporting DESIGN.md to DTCG#

The @google/design.md CLI includes a dtcg export target that emits a valid DTCG JSON file from a DESIGN.md source:

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

The exported file uses $schema: https://www.designtokens.org/schemas/2025.10/format.json, groups tokens by type (with a $type at the group level), and emits $value objects for each token. Color values are expressed as sRGB component arrays alongside a hex convenience field.

This means DESIGN.md can serve as the source of truth for human and agent use while still feeding DTCG-based pipelines. You do not have to choose one or the other.

A note on token references#

Both formats support referencing one token from another, though the syntax differs.

DESIGN.md uses curly-brace YAML references:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"

DTCG uses a similar curly-brace string syntax inside $value:

{
  "button-primary": {
    "background": {
      "$value": "{color.tertiary}"
    }
  }
}

The DESIGN.md CLI resolves references at lint time and reports broken references as errors, which makes reference integrity machine-checkable during development.

Summary#

DESIGN.md and DTCG are complementary rather than competing. DESIGN.md is a repo-native, human+AI-readable format with a prose layer. DTCG is a JSON interchange standard for tool pipelines. If your goal is a living brief that fits in a repository, DESIGN.md is the right choice. If your goal is feeding a token pipeline that spans design tools and code generators, DTCG is the right choice. If you need both, the CLI bridge handles the conversion.

Try it in the tool

Read the DESIGN.md guide