What Is the Export Command in DESIGN.md? A Complete Guide to Token Conversion

The export command converts DESIGN.md design tokens into production-ready formats including Tailwind CSS configurations, W3C Design Tokens, and CSS custom properties.

The export command serves as the primary bridge between the google-labs-code/design.md design system format and real-world development workflows. Located in packages/cli/src/commands/export.ts, this CLI utility transforms human-readable markdown tokens into machine-consumable code that integrates directly with modern CSS frameworks and build pipelines.

How the Export Command Works

The export pipeline follows a strict validation and transformation sequence defined using the citty framework's defineCommand function.

CLI Definition and Arguments

The command accepts three key arguments parsed from the command line:

• file – Path to the DESIGN.md source file, or - to read from stdin
• format – Target output format (must match the closed FORMATS enum)
• prefix – Optional CSS custom property prefix (used exclusively with css-vars format)

In packages/cli/src/commands/export.ts, the command structure is defined between lines 15-27, establishing the interface that validates user input before processing begins.

Input Validation and Error Handling

Before transformation occurs, the command enforces strict validation rules:

1. Format validation – The --format value is checked against the FORMATS enum. Invalid selections trigger a JSON error message and exit code 1.
2. File reading – The readInput utility from utils.ts handles both file system and stdin inputs. If reading fails, the process exits with code 2 and outputs a structured error message.
3. Linting – Raw markdown passes through the lint(content) function to produce a validated designSystem object, ensuring tokens conform to the DESIGN.md specification before export.

Format-Specific Emitters

Based on the selected format, the command instantiates specialized emitter handlers to perform the actual conversion:

• css-tailwind – Uses TailwindV4EmitterHandler calling serializeTailwindV4 to generate Tailwind v4 CSS @theme { … } blocks
• json-tailwind or tailwind – Uses TailwindEmitterHandler with JSON.stringify for Tailwind v3 theme.extend JSON objects
• dtcg – Uses DtcgEmitterHandler to produce W3C Design Token format JSON
• css-vars – Uses CssVarsEmitterHandler calling serializeCssVars to generate CSS custom property declarations

If any emitter reports a failure, the command outputs a JSON error and exits with code 1. Successful exports always exit with code 0, even when the source contains lint findings (which are handled separately via the lint command).

Supported Export Formats

The export command supports five distinct output formats targeting different consumption patterns:

Tailwind v4 CSS (css-tailwind) Generates modern @theme CSS blocks compatible with Tailwind CSS v4's configuration system.

Tailwind v3 JSON (json-tailwind, tailwind) Produces JSON objects suitable for tailwind.config.js theme extension.

W3C Design Tokens (dtcg) Exports to the standardized Design Tokens Community Group (DTCG) format for cross-platform token sharing.

CSS Variables (css-vars) Creates plain CSS custom property declarations with optional namespacing via the --prefix flag.

Practical Usage Examples

Export to Tailwind v3 Configuration

Convert DESIGN.md tokens into a JSON file ready for tailwind.config.js:

npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json

Export to Tailwind v4 CSS Theme

Generate the modern CSS-based theme format:

npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

Export with Prefixed CSS Variables

Add a namespace prefix to prevent CSS collisions:

npx @google/design.md export \
  --format css-vars \
  --prefix myapp- \
  DESIGN.md > design-vars.css

This produces properties like --myapp-color-primary instead of --color-primary.

Programmatic Integration

Embed the export functionality directly in Node.js build scripts:

import { lint } from '@google/design.md/linter';
import { TailwindEmitterHandler } from '@google/design.md/cli';

const markdown = await Deno.readTextFile('DESIGN.md');
const report = lint(markdown);

const handler = new TailwindEmitterHandler();
const result = handler.execute(report.designSystem);

if (result.success) {
  console.log(JSON.stringify(result.data, null, 2));
} else {
  console.error('Export failed:', result.error);
}

Exit Codes and Error Semantics

The export command follows strict exit code conventions for CI/CD integration:

• Exit 0 – Successful export, regardless of lint findings severity
• Exit 1 – Format validation errors or emitter execution failures
• Exit 2 – Input file reading errors (file not found or permission denied)

This separation allows build pipelines to distinguish between token conversion failures (exit 1) and missing source files (exit 2), while treating lint warnings as non-blocking (exit 0).

Summary

• The export command in packages/cli/src/commands/export.ts transforms DESIGN.md tokens into five production formats using specialized emitter handlers
• Supported formats include css-tailwind, json-tailwind, tailwind, dtcg, and css-vars, each targeting specific framework requirements
• The command validates inputs against a closed enum, lints content before processing, and returns structured JSON errors on failure
• Exit codes 0, 1, and 2 distinguish between success, conversion errors, and input reading failures respectively
• Optional --prefix flags enable CSS namespacing, while stdin support (-) allows unix-style piping in build pipelines

Frequently Asked Questions

What file formats can the DESIGN.md export command generate?

The command generates five distinct formats: Tailwind v4 CSS (css-tailwind), Tailwind v3 JSON (json-tailwind or tailwind), W3C Design Tokens (dtcg), and CSS custom properties (css-vars). Each format uses a dedicated emitter handler in packages/cli/src/linter/handler/ to ensure specification-compliant output.

Why does the export command exit with code 0 even when linting finds issues?

The export command separates concerns between token conversion and quality assurance. Lint findings indicate potential design system inconsistencies but do not prevent successful token transformation. Users should run the dedicated lint command separately to enforce quality gates, while relying on export purely for format conversion.

How do I use the export command in a CI/CD pipeline?

Pipe the output directly to your build artifacts and check exit codes: npx @google/design.md export --format css-tailwind DESIGN.md > theme.css. An exit code of 0 indicates successful conversion, 1 indicates format or emitter errors, and 2 indicates the source file could not be read. This allows pipelines to fail fast on configuration errors while accepting successful exports.

Can I read DESIGN.md from stdin instead of a file?

Yes. Pass - as the file argument to read from stdin: cat DESIGN.md | npx @google/design.md export --format json-tailwind - > tokens.json. The readInput utility in packages/cli/src/utils.ts automatically detects stdin mode and handles the stream appropriately.

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