Export Formats for DESIGN.md Tokens: CSS, Tailwind v4, and DTCG Output

The design.md CLI supports five export formats—css-tailwind, json-tailwind (alias tailwind), dtcg, and css-vars—that transform DESIGN.md tokens into Tailwind v4 CSS, Tailwind v3 JSON, W3C standard JSON, or plain CSS custom properties.

The google-labs-code/design.md toolchain provides a robust export pipeline for converting design tokens into production-ready code. Through the design-md export command, developers can transform a single DESIGN.md source file into multiple industry-standard formats. This guide examines each supported output format and the underlying implementation in the CLI source code.

Supported DESIGN.md Export Formats

The available formats are declared as a closed enum in packages/cli/src/commands/export.ts:

const FORMATS = ['css-tailwind', 'json-tailwind', 'tailwind', 'dtcg', 'css-vars'] as const;

Each format targets a specific consumer workflow, from modern Tailwind configurations to standardized design token exchanges.

css-tailwind (Tailwind v4 CSS)

The css-tailwind format generates a Tailwind v4 @theme CSS block containing CSS custom properties. This output is designed for the Tailwind v4 configuration system, allowing direct import into CSS-based theme definitions.

json-tailwind / tailwind (Tailwind v3 JSON)

The json-tailwind format emits a JSON object compatible with Tailwind v3’s theme.extend property. The alias tailwind maps to the same emitter handler, providing backward compatibility for existing Tailwind v3 configurations.

dtcg (Design Tokens Community Group)

The dtcg format produces a tokens.json file that follows the W3C Design Tokens Community Group (DTCG) 2025.10 specification. According to the source code in packages/cli/src/linter/dtcg/handler.ts, the emitter maps the internal DesignSystemState to the DTCG JSON schema using a $schema constant pointing to the official specification. This format ensures interoperability with any tool that consumes DTCG-compliant token files.

css-vars (CSS Custom Properties)

The css-vars format outputs a list of CSS custom properties following the pattern --<prefix>-<token>. These properties can be used directly in stylesheets or PostCSS pipelines, with an optional prefix flag to namespace the variables.

CLI Usage Examples

Below are practical invocations for each format. Replace path/to/DESIGN.md with the actual file path or - to read from stdin.

Generate a Tailwind v4 CSS @theme block:

design-md export path/to/DESIGN.md --format css-tailwind > theme.css

Export to Tailwind v3 JSON (using either format name):

design-md export path/to/DESIGN.md --format json-tailwind > tailwind-theme.json

# or using the alias

design-md export path/to/DESIGN.md --format tailwind > tailwind-theme.json

Create a W3C DTCG-compliant tokens file:

design-md export path/to/DESIGN.md --format dtcg > tokens.json

Output CSS custom properties with a custom prefix:

design-md export path/to/DESIGN.md --format css-vars --prefix myapp > design-vars.css

How the Export Pipeline Works

All export commands share a unified four-stage pipeline implemented in packages/cli/src/commands/export.ts:

1. Read input – The readInput utility loads the file or STDIN stream (defined in packages/cli/src/utils.ts).
2. Lint – The lint(content) function parses the Markdown and builds a DesignSystemState object representing the design tokens.
3. Select emitter – The command instantiates the appropriate handler based on the --format flag:
   • TailwindV4EmitterHandler for css-tailwind
   • TailwindEmitterHandler for json-tailwind/tailwind
   • DtcgEmitterHandler for dtcg
   • CssVarsEmitterHandler for css-vars
4. Execute – The handler returns a result object that is serialized using format-specific functions like serializeTailwindV4, JSON.stringify, or serializeCssVars.

Key Implementation Files

The export functionality is distributed across several specialized handlers:

• packages/cli/src/commands/export.ts – Defines the CLI command, the FORMATS enum, argument parsing, and orchestration of the export pipeline.
• packages/cli/src/linter/dtcg/handler.ts – Implements the DTCG emitter, handling the conversion from DesignSystemState to the W3C specification.
• packages/cli/src/linter/tailwind/handler.ts – Contains the Tailwind v3 JSON emitter logic.
• packages/cli/src/linter/tailwind/v4/handler.ts – Implements the Tailwind v4 CSS @theme emitter.
• packages/cli/src/linter/css-vars/handler.ts – Handles the CSS custom properties output generation.
• packages/cli/src/utils.ts – Provides the readInput utility for file and STDIN handling.

Summary

• The design.md CLI supports five export formats defined in the FORMATS constant: css-tailwind, json-tailwind, tailwind, dtcg, and css-vars.
• Tailwind v4 users should use --format css-tailwind to generate @theme CSS blocks.
• Tailwind v3 configurations consume the JSON output from --format json-tailwind or its alias --format tailwind.
• Cross-platform interoperability is achieved through the --format dtcg option, which outputs W3C-standard tokens.json files.
• Plain CSS workflows benefit from --format css-vars, which emits prefixed custom properties for direct stylesheet integration.
• The export pipeline relies on specific handler classes (e.g., DtcgEmitterHandler, TailwindV4EmitterHandler) to transform the internal DesignSystemState into target format outputs.

Frequently Asked Questions

What export formats does DESIGN.md support?

The CLI supports five formats defined in packages/cli/src/commands/export.ts: css-tailwind for Tailwind v4 CSS, json-tailwind (and its alias tailwind) for Tailwind v3 JSON configurations, dtcg for W3C-standard token files, and css-vars for CSS custom properties.

How do I export to Tailwind v4?

Use the css-tailwind format: design-md export DESIGN.md --format css-tailwind > theme.css. This generates an @theme CSS block containing your design tokens as CSS custom properties, which Tailwind v4 can consume directly.

What is the DTCG format used for?

The dtcg format produces a tokens.json file compliant with the W3C Design Tokens Community Group 2025.10 specification. This standardizes token exchange between design tools and development environments, ensuring compatibility with any platform that supports the DTCG specification.

Can I add a custom prefix to CSS variables?

Yes. When using --format css-vars, append the --prefix flag followed by your desired namespace. For example: design-md export DESIGN.md --format css-vars --prefix myapp generates variables like --myapp-color-primary instead of unprefixed tokens.

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