Understanding json-tailwind and css-tailwind Export Formats in DESIGN.md

The json-tailwind format generates a JSON object for Tailwind v3's theme.extend configuration, while css-tailwind produces a CSS @theme block with custom properties for Tailwind v4.

The google-labs-code/design.md repository provides a CLI tool for managing design tokens across different platforms. When exporting to Tailwind CSS, understanding the distinction between the json-tailwind and css-tailwind export formats ensures you generate compatible configuration code for your specific Tailwind version.

What is json-tailwind?

The json-tailwind format targets Tailwind CSS v3 and generates a plain JavaScript object that integrates directly into the theme.extend section of a tailwind.config.js file.

Output Structure

This format outputs a JSON object containing mappings for colors, fontFamily, fontSize, borderRadius, spacing, and other theme properties. The structure follows Tailwind v3's configuration schema, allowing direct merging into existing configurations.

{
  "theme": {
    "extend": {
      "colors": {
        "primary": "#1A1C1E",
        "secondary": "#6C7278"
      },
      "fontFamily": {
        "body": ["Public Sans"]
      },
      "fontSize": {
        "body-md": ["16px", { "lineHeight": "1.6" }]
      },
      "borderRadius": {
        "sm": "4px"
      },
      "spacing": {
        "base": "16px"
      }
    }
  }
}

Implementation Details

In packages/cli/src/commands/export.ts (lines 20-27), the CLI registers the json-tailwind format and maps it to the JSON emitter. The TailwindEmitterHandler class in packages/cli/src/linter/tailwind/handler.ts processes the internal design-system model and structures it specifically for Tailwind v3 consumption.

What is css-tailwind?

The css-tailwind format targets Tailwind CSS v4 and generates a CSS @theme block that exposes design tokens as CSS custom properties.

CSS Custom Properties Format

Unlike the JSON approach, this format outputs a CSS block using the @theme directive. Token names are validated as CSS identifiers and converted to custom property syntax (--color-..., --font-..., etc.). String values like font families are escaped as CSS string literals to ensure proper parsing.

@theme {
  --color-primary: #1A1C1E;
  --color-secondary: #6C7278;
  --font-family-body: "Public Sans";
  --font-size-body-md: 16px;
  --line-height-body-md: 1.6;
  --border-radius-sm: 4px;
  --spacing-base: 16px;
}

Implementation Details

The v4 emitter is implemented in packages/cli/src/linter/tailwind/v4/handler.ts (lines 20-25, 29-33, 57-74). This handler, TailwindV4EmitterHandler, adds extra validation to ensure token names are valid CSS identifiers and handles CSS-specific escaping requirements that Tailwind v4 expects.

Key Differences Between json-tailwind and css-tailwind

While both formats derive from the same internal design-system model, they serve different architectural patterns:

• Tailwind Version: json-tailwind supports v3 via JavaScript configuration, while css-tailwind supports v4 via CSS-based configuration.
• Output Type: JSON object versus CSS @theme block.
• Token Representation: JSON uses nested objects; CSS uses flat custom properties with -- prefixes.
• Font Handling: JSON format embeds font families as arrays; CSS format escapes them as string literals.
• Integration: JSON requires copying into tailwind.config.js; CSS can be imported directly into v4's CSS-first configuration.

How to Export Design Tokens

Use the DESIGN.md CLI to export your design tokens in either format.

For Tailwind v3 projects:

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

For Tailwind v4 projects:

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

In packages/cli/src/commands/export.ts (lines 55-66), the export command maps these format flags to their respective handlers, ensuring the correct emitter processes the design tokens.

Summary

• json-tailwind generates a JSON object for Tailwind v3's theme.extend configuration.
• css-tailwind produces a CSS @theme block with custom properties for Tailwind v4.
• Both formats share the same internal model but use different emitters: TailwindEmitterHandler for v3 and TailwindV4EmitterHandler for v4.
• The v4 emitter includes additional CSS identifier validation and string escaping.

Frequently Asked Questions

Which Tailwind version does json-tailwind support?

The json-tailwind format specifically targets Tailwind CSS v3. It generates a JSON structure designed to merge into the theme.extend object of a tailwind.config.js file, which is the standard configuration method for v3 projects.

Can I use css-tailwind with Tailwind v3?

No, the css-tailwind format is designed exclusively for Tailwind CSS v4. The CSS @theme block and custom property syntax follow v4's CSS-first configuration architecture, which is not compatible with v3's JavaScript-based configuration system.

Where are the export handlers defined in the source code?

The export handlers are defined in the DESIGN.md CLI source. The JSON emitter for v3 is located at packages/cli/src/linter/tailwind/handler.ts, while the CSS emitter for v4 is at packages/cli/src/linter/tailwind/v4/handler.ts. Both are registered in packages/cli/src/commands/export.ts at lines 20-27 and 55-66.

How are font families handled differently between the two formats?

In json-tailwind, font families are exported as JavaScript arrays (e.g., ["Public Sans"]) suitable for the fontFamily theme key. In css-tailwind, the same font families are escaped as CSS string literals (e.g., "Public Sans") and assigned to --font-family-* custom properties, as implemented in the v4 handler (lines 57-74).

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