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

> Master the export command in DESIGN.md to convert design tokens into production-ready formats like Tailwind CSS W3C Design Tokens and CSS custom properties Streamline your workflow today

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) design system format and real-world development workflows. Located in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/tailwind.config.js):

```bash
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:

```bash
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:

```bash
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:

```typescript
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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) automatically detects stdin mode and handles the stream appropriately.