DESIGN.md Export Formats: A Complete Guide to JSON and CSS Output Options

The @google/design.md CLI supports three export formats—json-tailwind (Tailwind v3), css-tailwind (Tailwind v4), and dtcg (W3C Design Tokens)—that convert DESIGN.md files into standardized JSON or CSS token definitions for design systems.

The google-labs-code/design.md repository provides a command-line tool for converting DESIGN.md files into machine-readable design tokens. Understanding the available export formats is essential for integrating these tokens into modern CSS frameworks and design system workflows. The CLI validates all format selections against a closed enum in packages/cli/src/commands/export.ts, ensuring type-safe output generation.

Supported Export Formats

The design.md export command accepts three distinct --format values, each targeting specific consumption patterns in web development.

json-tailwind (Tailwind v3)

The json-tailwind format—also accessible via the tailwind alias—generates a JSON object compatible with Tailwind CSS v3's theme.extend configuration. This output can be directly imported into your tailwind.config.js file to define custom colors, fonts, and spacing tokens.

css-tailwind (Tailwind v4)

For projects using Tailwind CSS v4, the css-tailwind format produces a CSS @theme block containing CSS custom properties (--color-*, --font-*, etc.). This aligns with Tailwind v4's native CSS-first configuration approach, emitting a standards-compliant stylesheet that defines design tokens as custom properties.

dtcg (W3C Design Tokens Format)

The dtcg format outputs a JSON file adhering to the W3C Design Tokens Community Group (DTCG) specification. This vendor-neutral standard ensures interoperability between design tools like Figma Tokens Studio and code repositories, supporting bidirectional synchronization of design decisions.

CLI Usage Examples

The export command in packages/cli/src/commands/export.ts implements these formats behind the --format flag. Invalid format selections cause the CLI to exit with code 1 and display a validation error.

Generate a Tailwind v3 configuration file:

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

Create a Tailwind v4 CSS theme block:

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

Export W3C-compliant design tokens:

npx @google/design.md export --format dtcg DESIGN.md > tokens.json

Use the backwards-compatible alias for JSON Tailwind output:

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

Technical Implementation

As implemented in google-labs-code/design.md, the export functionality relies on a strict validation layer within packages/cli/src/commands/export.ts. This file defines the closed enum of supported formats and maps each to specific transformation logic that translates the internal token schema—documented in docs/spec.md—into the target output structure.

The validation logic checks the --format argument at runtime against the allowed values (json-tailwind, tailwind, css-tailwind, dtcg). When validation passes, the CLI invokes the corresponding exporter module to transform the parsed DESIGN.md AST into the desired output structure, handling token normalization and format-specific nesting rules automatically.

Summary

• json-tailwind: Outputs JSON for Tailwind v3 theme.extend configuration; aliased as tailwind for backwards compatibility.
• css-tailwind: Generates CSS custom properties within a Tailwind v4 @theme block for modern CSS-first workflows.
• dtcg: Produces W3C-standardized JSON for cross-platform design token interoperability.
• Validation: packages/cli/src/commands/export.ts enforces format constraints, exiting with code 1 on invalid input.
• Schema: Underlying token definitions are defined in docs/spec.md and transformed by format-specific exporters.

Frequently Asked Questions

What happens if I specify an unsupported export format?

The CLI validates the --format argument against a closed enum in packages/cli/src/commands/export.ts. If you provide an invalid value, the process terminates with exit code 1 and displays an error message indicating the supported options.

Can I use the tailwind alias instead of json-tailwind?

Yes. The --format tailwind flag serves as a backwards-compatible alias for json-tailwind, producing identical JSON output intended for Tailwind v3 configuration files. Both values trigger the same exporter logic.

Which format should I use for Tailwind CSS v4 projects?

Use css-tailwind for Tailwind v4 projects. This format generates a CSS @theme block with custom properties that integrates natively with Tailwind v4's CSS-first architecture, unlike the JSON format intended for v3's JavaScript-based configuration.

Is the DTCG format compatible with Figma Tokens Studio?

Yes. The dtcg format follows the W3C Design Tokens Community Group specification, which is supported by Figma Tokens Studio and other design system management tools for bidirectional synchronization between design files and code repositories.

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