What Is the DTCG Export Format and How Is It Structured?

The DTCG export format is a JSON representation of DESIGN.md token sets that conforms to the W3C Design Tokens Format Module (2025.10), producing a hierarchical file with typed groups and values for colors, dimensions, and typography.

The DTCG export format is the canonical JSON output generated by the google-labs-code/design.md CLI when converting design tokens from DESIGN.md files. When you execute the export command, the tool parses your in-memory DesignSystemState and emits a structured JSON file that downstream design tools can consume for token interchange.

Core Structure of the DTCG Token File

A DTCG export produces a DtcgTokenFile—a top-level JSON object that acts as a container for all design tokens. According to the TypeScript interfaces defined in packages/cli/src/linter/dtcg/spec.ts, this structure follows a strict hierarchy of groups and tokens.

Root Level Properties

The root of every exported file contains:

• $schema: A required string pointing to the official DTCG JSON schema (https://www.designtokens.org/schemas/2025.10/format.json). The emitter automatically injects this reference during export.
• $description: An optional string extracted from the DESIGN.md front-matter that provides human-readable documentation of the design system.
• Token groups: One or more nested objects (e.g., color, spacing, typography) that contain the actual token definitions.

Token Groups and Types

Each group in the hierarchy implements the DtcgGroup interface defined in packages/cli/src/linter/dtcg/spec.ts. Groups can contain:

• $type: An optional string declaring the semantic type for all tokens in that group (e.g., 'color', 'dimension', 'typography').
• $description: Optional documentation specific to that group.
• Nested tokens or groups: Key-value pairs where the key is the token name and the value is either a DtcgToken or another DtcgGroup.

Token Value Types

Individual tokens use the DtcgToken interface and support various value schemas:

• $type: Optional type override at the token level.
• $value: The actual token value, which can be one of several strongly-typed structures:
  • DtcgColorValue: An object with colorSpace (always 'srgb' for this implementation), components as an array of three normalized 0-1 values (rounded to three decimal places), and an optional lowercase hex string.
  • DtcgDimensionValue: An object containing value (number) and unit (string), such as { "value": 8, "unit": "px" }.
  • DtcgTypographyValue: A composite object containing fontFamily, fontWeight, and optionally fontSize and letterSpacing (both DtcgDimensionValue objects), plus lineHeight (a unit-less multiplier).

CLI Usage and Export Command

To generate a DTCG-compliant JSON file from your DESIGN.md, run the CLI command:

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

This command invokes the DTCG export format emitter, which walks the DesignSystemState and serializes the token hierarchy to stdout. The output file (tokens.json) can then be imported into design tools that support the W3C Design Tokens Format Module.

Implementation Details

The export logic resides in two critical files within the google-labs-code/design.md repository:

1. packages/cli/src/linter/dtcg/spec.ts: Defines the TypeScript interfaces (DtcgTokenFile, DtcgGroup, DtcgToken) and value type definitions that shape the JSON output.
2. packages/cli/src/linter/dtcg/handler.ts: Implements the DtcgEmitterHandler class, which contains the pure-function emitter methods that transform DesignSystemState into the final DTCG-compliant JSON structure.

The handler recursively processes the design system tree, applying the appropriate value converters for colors, dimensions, and typography tokens to ensure the output strictly adheres to the 2025.10 DTCG specification.

Summary

• The DTCG export format produces JSON files conforming to the W3C Design Tokens Format Module (2025.10).
• The root object is a DtcgTokenFile containing $schema, optional $description, and typed token groups.
• Color values use sRGB components with optional hex strings, while dimensions combine numeric values with CSS units.
• The export logic is implemented in packages/cli/src/linter/dtcg/handler.ts and walks DesignSystemState to generate the output.
• Use npx @google/design.md export --format dtcg to generate compliant token files from DESIGN.md sources.

Frequently Asked Questions

What does DTCG stand for?

DTCG stands for Design Tokens Community Group, the W3C community that maintains the Design Tokens Format Module specification. The DTCG export format refers specifically to the JSON schema standardized by this group for interoperable design token exchange.

How do I convert DESIGN.md tokens to DTCG format?

Run the export command with the --format dtcg flag: npx @google/design.md export --format dtcg DESIGN.md. This invokes the emitter in packages/cli/src/linter/dtcg/handler.ts to transform your design system into the standard JSON structure.

What value types are supported in the DTCG export?

The implementation supports DtcgColorValue (sRGB with hex), DtcgDimensionValue (number/unit pairs), and DtcgTypographyValue (composite objects with font properties). These are defined in packages/cli/src/linter/dtcg/spec.ts and cover the most common design token categories.

Where is the DTCG export logic implemented in the codebase?

The mapping logic lives in packages/cli/src/linter/dtcg/handler.ts, which implements the DtcgEmitterHandler class. This file handles the transformation of DesignSystemState into the final JSON structure, while the type definitions reside in the adjacent spec.ts file.

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