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

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:

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.
• 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, 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:

• 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, 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:

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

# or using the alias

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

Sample output structure:

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

Exporting W3C Design Tokens

To generate a DT-CG compliant token file:

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

Sample output:

{
  "$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:

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: 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 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.

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 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.

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