# How to Convert DESIGN.md Design Tokens to W3C DTCG Format

> Easily convert DESIGN.md design tokens to W3C DTCG format using the CLI or API. Map colors, spacing, and typography to the latest DTCG schema for seamless integration.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-07-01

---

**TLDR:** You can convert DESIGN.md design tokens to W3C DTCG format using the `export --format dtcg` CLI command or the `DtcgEmitterHandler` API, which maps colors, spacing, and typography into the **2025.10** DTCG schema.

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository provides a complete pipeline for transforming markdown-based design systems into standardized token files. Whether you need a one-off export or a custom build integration, the project makes it straightforward to convert DESIGN.md design tokens to W3C DTCG format with full schema compliance.

## CLI Export to W3C DTCG Format

The fastest way to generate a [`tokens.json`](https://github.com/google-labs-code/design.md/blob/main/tokens.json) file is through the CLI. In [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts), the command parses `--format dtcg`, reads the [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) input, runs the linter, and delegates to `DtcgEmitterHandler`. The handler returns `{ success: true, data: <tokens> }`, and the CLI prints the result with two-space indentation via `JSON.stringify(result.data, null, 2)`.

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

```

## Programmatic Conversion to W3C DTCG Format

For custom workflows, instantiate `DtcgEmitterHandler` from `@google/design.md/linter/dtcg` and pass it a `DesignSystemState` object. The handler lives in [`packages/cli/src/linter/dtcg/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/dtcg/handler.ts) and implements the `DtcgEmitterSpec` interface. Type definitions for the output structures, such as `DtcgTokenFile` and `DtcgGroup`, are declared in [`packages/cli/src/linter/dtcg/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/dtcg/spec.ts), while [`packages/cli/src/linter/index.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/index.ts) exposes the handlers for broader use.

### Linting DESIGN.md and Emitting Tokens

Load the markdown, lint it, and call `execute(state)` to receive the DTCG object:

```ts
import { readFileSync } from 'fs';
import { lint } from '@google/design.md/linter';
import { DtcgEmitterHandler } from '@google/design.md/linter/dtcg';

// 1. Load a DESIGN.md file
const markdown = readFileSync('DESIGN.md', 'utf8');

// 2. Run the linter to obtain a DesignSystemState
const report = lint(markdown);

// 3. Convert to DTCG tokens
const handler = new DtcgEmitterHandler();
const result = handler.execute(report.designSystem);

if (result.success) {
  // 4. Write out the tokens.json file
  const json = JSON.stringify(result.data, null, 2);
  console.log(json);
} else {
  console.error('Export failed:', result.error);
}

```

### Internal Mapping Methods

The `execute` method maps the internal `DesignSystemState` through dedicated helpers:
- **`mapColors`** produces the `color` group
- **`mapDimensionGroup`** produces the `spacing` and `rounded` groups
- **`mapTypography`** produces the `typography` group

Value conversion is handled by `colorToValue` (sRGB arrays and hex strings), `dimToValue` (`{ value, unit }` objects), and `typographyToValue` (structured DTCG typography objects). An optional system description is added at the root as `$description`.

## DTCG Output Structure and Schema

The emitted JSON declares the **2025.10** DTCG schema at `https://www.designtokens.org/schemas/2025.10/format.json`. Every group carries a `$type` field, and tokens expose their values under `$value`.

### Colors, Dimensions, and Typography

- **Colors** receive `$type: "color"` with `colorSpace`, `components`, and `hex`.
- **Spacing** and **rounded** tokens receive `$type: "dimension"` with `value` and `unit`.
- **Typography** tokens receive `$type: "typography"` with properties such as `fontFamily` and `fontSize`.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "$description": "Heritage design system",
  "color": {
    "$type": "color",
    "primary": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0.102, 0.110, 0.118],
        "hex": "#1a1c1e"
      }
    },
    "tertiary": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0.724, 0.259, 0.180],
        "hex": "#b8422e"
      }
    }
  },
  "spacing": {
    "$type": "dimension",
    "sm": { "$value": { "value": 8, "unit": "px" } },
    "md": { "$value": { "value": 16, "unit": "px" } }
  },
  "typography": {
    "h1": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Public Sans",
        "fontSize": { "value": 3, "unit": "rem" }
      }
    }
  }
}

```

## Summary

- Run `npx @google/design.md export --format dtcg DESIGN.md` for a one-line CLI conversion to W3C DTCG format.
- The `DtcgEmitterHandler` class in [`packages/cli/src/linter/dtcg/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/dtcg/handler.ts) powers the conversion programmatically.
- Internal helpers such as `colorToValue`, `dimToValue`, and `typographyToValue` map raw values to the **2025.10** DTCG schema.
- Outputs include typed groups for `color`, `spacing`, `rounded`, and `typography` with full `$schema` compliance.

## Frequently Asked Questions

### What DTCG schema version does design.md support?

The emitter targets the **2025.10** DTCG schema. It injects `https://www.designtokens.org/schemas/2025.10/format.json` into the `$schema` field of the generated [`tokens.json`](https://github.com/google-labs-code/design.md/blob/main/tokens.json) file.

### Can I export DESIGN.md tokens to formats other than DTCG?

Yes. The CLI entry point in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts) selects an emitter based on the `--format` argument, so additional handlers can be registered alongside `DtcgEmitterHandler`.

### How are color values represented in the DTCG output?

The `colorToValue` helper converts each color into an sRGB array under `components` and a hexadecimal string under `hex`, wrapped in a `$value` object with `colorSpace: "srgb"`.

### Is the DTCG export available through both the CLI and the API?

Both paths are supported. You can run `export --format dtcg` from the terminal for immediate file generation, or instantiate `DtcgEmitterHandler` directly in TypeScript for custom build pipelines.