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

> Explore the DTCG export format a W3C compliant JSON structure for DESIGN.md token sets. Understand its hierarchical organization of colors dimensions and typography.

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

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

```bash
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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository:

1. **[`packages/cli/src/linter/dtcg/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/spec.ts) file.