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

> Discover the key differences between json-tailwind and css-tailwind export formats in DESIGN.md. Learn how each format configures Tailwind v3 and v4 for your projects.

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

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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.

```json
{
  "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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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.

```css
@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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

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

```

For Tailwind v4 projects:

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

```

In [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/handler.ts), while the CSS emitter for v4 is at [`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). Both are registered in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/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).