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

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

# 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.

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 follows the W3C DTCG 2025.10 specification with strict typing via the $type property. Below is an excerpt showing color, spacing, and typography groups:

{
  "$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 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 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 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 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. 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. 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).

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