# Design CLI Export Output Formats: JSON, CSS, and W3C Tokens Explained

> Explore design CLI export options: JSON, CSS, and W3C tokens. Streamline your design system with Tailwind CSS and W3C Design Tokens.

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

---

**The `design` CLI supports four export formats: `css-tailwind` for Tailwind v4 CSS, `json-tailwind` (aliased as `tailwind`) for Tailwind v3 JSON configuration, and `dtcg` for W3C Design Tokens.**

The `design` command-line tool from the **google-labs-code/design.md** repository converts DESIGN.md token files into portable code artifacts. Developers can export design tokens into multiple **output formats** including JSON configurations and CSS rules, enabling seamless integration with Tailwind CSS and standardized design token workflows.

## Available Export Formats in the Design CLI

The CLI recognizes four distinct format identifiers defined as a constant array in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts):

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

```

### JSON-Based Formats

Two formats emit structured data as pretty-printed JSON using `JSON.stringify(..., null, 2)`:

- **`json-tailwind`** (and its alias **`tailwind`**): Generates a Tailwind v3 `theme.extend` object suitable for extending [`tailwind.config.js`](https://github.com/google-labs-code/design.md/blob/main/tailwind.config.js).
- **`dtcg`**: Produces W3C Design Tokens (DT-CG) compliant JSON with standardized schema descriptors.

### CSS Output Format

- **`css-tailwind`**: Emits Tailwind v4 CSS `@theme` rules as plain text, allowing direct integration into modern CSS-first Tailwind configurations.

## Internal Architecture and Handler Dispatch

Format validation and handler dispatch operate through a pipeline defined in the source code. In [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts), the CLI validates the user-provided `--format` argument against the closed `FORMATS` enum.

Upon validation, the command selects the appropriate emitter handler as re-exported from [`packages/cli/src/linter/index.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/index.ts):

- **`TailwindEmitterHandler`**: Processes `json-tailwind` and `tailwind` requests, returning a `result` object whose `data` field contains the JSON representation.
- **`DtcgEmitterHandler`**: Handles `dtcg` format requests, outputting W3C-standardized token JSON.
- **Tailwind v4 Handler**: Implemented in [`packages/cli/src/linter/tailwind/v4/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/v4/handler.ts), this handler manages `css-tailwind` conversion to CSS rules.

Both JSON-based handlers (`TailwindEmitterHandler` and `DtcgEmitterHandler`) stringify output using `JSON.stringify(..., null, 2)` before printing to stdout.

## Command Examples and Output Samples

### Exporting to Tailwind JSON

To export a DESIGN.md file as a Tailwind v3 configuration extension:

```bash
design export path/to/DESIGN.md --format json-tailwind

# or using the alias

design export path/to/DESIGN.md --format tailwind

```

Sample output structure:

```json
{
  "theme": {
    "extend": {
      "colors": {
        "primary": "#ff5722",
        "secondary": "#03a9f4"
      },
      "spacing": {
        "gutter": "1rem"
      }
    }
  }
}

```

### Exporting W3C Design Tokens

To generate a DT-CG compliant token file:

```bash
design export path/to/DESIGN.md --format dtcg

```

Sample output:

```json
{
  "$schema": "https://design-tokens.github.io/schema/2.0/schema.json",
  "tokens": {
    "color": {
      "primary": { "value": "#ff5722" },
      "secondary": { "value": "#03a9f4" }
    }
  }
}

```

### Exporting Tailwind v4 CSS

To generate Tailwind v4 `@theme` CSS rules:

```bash
design export path/to/DESIGN.md --format css-tailwind

```

This outputs plain CSS containing `@theme` blocks defining the design tokens for Tailwind v4's CSS-first configuration approach.

## Summary

- The **design CLI export** command supports four output formats defined in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts): `css-tailwind`, `json-tailwind`, `tailwind`, and `dtcg`.
- **JSON formats** (`json-tailwind`, `tailwind`, `dtcg`) are pretty-printed with 2-space indentation via `JSON.stringify(..., null, 2)`.
- **Handler dispatch** in [`packages/cli/src/linter/index.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/index.ts) routes to `TailwindEmitterHandler` or `DtcgEmitterHandler` for JSON outputs, while `css-tailwind` utilizes the specialized v4 handler.
- The **CSS output** generates Tailwind v4 `@theme` rules as implemented in [`packages/cli/src/linter/tailwind/v4/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/v4/handler.ts).

## Frequently Asked Questions

### What output formats does the design CLI export command support?

The CLI supports four formats: `css-tailwind` for Tailwind v4 CSS `@theme` rules, `json-tailwind` (and alias `tailwind`) for Tailwind v3 JSON configuration objects, and `dtcg` for W3C Design Tokens Community Group compliant JSON.

### What is the difference between json-tailwind and tailwind formats?

They are functionally identical aliases. Both values trigger the `TailwindEmitterHandler` and produce the same Tailwind v3 `theme.extend` JSON structure. The `tailwind` alias provides a shorter command-line option.

### How does the CLI convert DESIGN.md to W3C Design Tokens?

When you specify `--format dtcg`, the CLI invokes the `DtcgEmitterHandler` to transform the lint report into a JSON file compliant with the W3C Design Tokens specification, automatically including the correct `$schema` reference URL.

### Where is the export format validation logic located?

Format validation occurs in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts) where the `FORMATS` constant array defines the allowed values. The CLI checks user input against this closed set before dispatching to the appropriate handler in [`packages/cli/src/linter/index.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/index.ts).