# How to Export Design Tokens to W3C DTCG Format from DESIGN.md

> Export design tokens from DESIGN.md to W3C DTCG format using the CLI or programmatically. Streamline your design system workflows today and ensure W3C compliance.

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

---

**Design tokens defined in a DESIGN.md file can be exported to W3C-compliant DTCG format using the CLI `export` command with `--format dtcg` or programmatically via the `DtcgEmitterHandler` class.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) toolchain provides native support for converting design system definitions into the W3C Design Tokens Community Group (DTCG) standard. This enables interoperability with design tools and development pipelines that consume the [`tokens.json`](https://github.com/google-labs-code/design.md/blob/main/tokens.json) format. The export process maps internal token states—including colors, spacing, rounded corners, and typography—into the standardized 2025.10 DTCG schema.

## Architecture of the DTCG Export Pipeline

The export functionality is implemented across two primary modules in the CLI package. Understanding this architecture helps troubleshoot formatting issues and extend the emitter for custom token types.

### CLI Entry Point in export.ts

The command-line interface routes export requests through [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts). This module parses the `--format dtcg` argument, validates the DESIGN.md input, runs the internal linter to generate a `DesignSystemState`, and instantiates the appropriate emitter handler. When DTCG format is requested, the CLI delegates to `DtcgEmitterHandler` and outputs the resulting JSON with 2-space indentation via `JSON.stringify(result.data, null, 2)`.

### DTCG Emitter Handler Implementation

The core conversion logic resides 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). The `DtcgEmitterHandler` class implements the `DtcgEmitterSpec` interface and exposes an `execute(state)` method that transforms the internal `DesignSystemState` into a DTCG-compliant object structure.

The handler performs the following mappings:

- **Colors** → `color` group via `mapColors()`, converting values to sRGB arrays and hex strings using `colorToValue()`
- **Spacing and Rounded** → `spacing` and `rounded` groups via `mapDimensionGroup()`, formatting values as `{value, unit}` objects using `dimToValue()`
- **Typography** → `typography` group via `mapTypography()`, structuring font properties with `typographyToValue()`
- **Metadata** → Optional `$description` fields added at group or token level

The handler returns an object conforming to the DTCG 2025.10 schema (`https://www.designtokens.org/schemas/2025.10/format.json`) with the structure `{ success: true, data: <tokens> }`.

## Exporting Tokens via CLI

The most common method to export design tokens to W3C DTCG format is the one-line CLI command. Ensure you have the `@google/design.md` package installed or use `npx` to run the export without installation.

```bash

# Export DESIGN.md to DTCG tokens.json

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

```

The CLI reads the markdown file, executes the linting pipeline to resolve token references and aliases, then pipes the formatted JSON to stdout. Redirect the output to a file or pipe it directly into downstream build tools.

## Programmatic Export with DtcgEmitterHandler

For build scripts, CI pipelines, or custom tooling, import the `DtcgEmitterHandler` directly from the linter package. This approach provides fine-grained control over the export process and error handling.

```typescript
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);
}

```

This method invokes the same mapping logic as the CLI, including the conversion of color spaces to sRGB and dimension values to the DTCG dimension object format.

## Expected DTCG Output Structure

The exported [`tokens.json`](https://github.com/google-labs-code/design.md/blob/main/tokens.json) follows the W3C DTCG 2025.10 specification with strict typing via the `$type` property. Below is an excerpt showing color, spacing, and typography groups:

```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" }
      }
    }
  }
}

```

Color tokens include both floating-point sRGB component arrays and hexadecimal representations. Dimension tokens explicitly declare units (px, rem, etc.), while typography tokens aggregate multiple properties under structured `$value` objects.

## Summary

- **Use the CLI** `export --format dtcg` for quick one-off exports of DESIGN.md files to W3C-compliant JSON
- **Leverage `DtcgEmitterHandler`** 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) for programmatic integration into build systems
- **Supported token types** include colors (sRGB/hex), dimensions (spacing/rounded), and typography, all mapped to the DTCG 2025.10 schema
- **Internal helpers** like `colorToValue()`, `dimToValue()`, and `typographyToValue()` handle type-specific conversions automatically
- **Output** is a standard [`tokens.json`](https://github.com/google-labs-code/design.md/blob/main/tokens.json) file compatible with design tools that support the W3C DTCG format

## Frequently Asked Questions

### What is the W3C DTCG format?

The W3C Design Tokens Community Group (DTCG) format is a standardized JSON schema for defining design tokens across tools and platforms. It specifies how to structure color values, dimensions, typography, and other design properties using `$type` and `$value` keys. The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository implements the 2025.10 version of this specification, ensuring exported tokens work with Figma, Style Dictionary, and other DTCG-compatible tools.

### Which token types are supported in the DTCG export?

The current implementation 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) supports colors (mapped to sRGB with hex fallbacks), dimensions (spacing and rounded corners with pixel or rem units), and typography (font families, sizes, weights, and line heights). Each type uses specific converter functions: `colorToValue()` for colors, `dimToValue()` for dimensions, and `typographyToValue()` for font properties.

### Can I customize the DTCG schema version?

The emitter currently targets the fixed 2025.10 schema version as defined 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). The `$schema` URL is hardcoded to `https://www.designtokens.org/schemas/2025.10/format.json` in the handler output. To use a different schema version, you would need to modify the `DtcgEmitterHandler` class or post-process the JSON output to update the schema declaration.

### How are color values converted to DTCG format?

Colors defined in DESIGN.md are converted to the DTCG color object format in the `colorToValue()` function within [`packages/cli/src/linter/dtcg/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/dtcg/handler.ts). The conversion produces an object with `colorSpace` set to "srgb", `components` as an array of three floating-point numbers (0-1 range), and a `hex` string for backward compatibility. This dual representation ensures compatibility with both web workflows (hex) and advanced color management systems (sRGB components).