# How to Export DESIGN.md Tokens to Tailwind v3 JSON Format

> Export DESIGN.md tokens to Tailwind v3 JSON format easily. Learn how to leverage the design.md CLI to generate a JSON object ready for your Tailwind CSS configuration.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-07-01

---

**The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) CLI exports DESIGN.md tokens to Tailwind v3 JSON format using the `json-tailwind` (or `tailwind`) format option, generating a JSON object wrapped in `{ "theme": { "extend": ... } }` that can be required directly into your Tailwind config's theme.extend section.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository provides a command-line tool that parses DESIGN.md files and validates design tokens. You can export these tokens to Tailwind v3 JSON format to extend your Tailwind theme without manual transcription.

## Running the Export Command

Use the CLI's `export` command with the `json-tailwind` format (alias: `tailwind`) to generate the JSON file.

```bash

# From the repository root

pnpm run cli export path/to/DESIGN.md json-tailwind > tailwind.tokens.json

```

Replace `pnpm run cli` with your actual entry point defined in [`package.json`](https://github.com/google-labs-code/design.md/blob/main/package.json) (e.g., `node ./packages/cli/src/index.js`). The tool reads from a file path or `-` for stdin via the `readInput` utility in [`src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/src/utils.ts), then prints the formatted JSON to stdout.

## How the Export Pipeline Works

The export process follows a three-stage pipeline implemented in the CLI source code.

### Reading and Parsing Input

First, the command invokes `readInput` from [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) to load the DESIGN.md content. Next, the `lint(content)` function (defined in the linter module) builds a `DesignSystemState` object that holds all token groups—including **colors**, **typography**, **rounded**, and **spacing**—parsed from the YAML frontmatter.

### Converting to Tailwind v3 JSON

When the format argument is `json-tailwind` or `tailwind`, the CLI instantiates a `TailwindEmitterHandler` 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). This handler's `execute(state)` method maps each token group to the corresponding Tailwind configuration key:

- **colors** → `colors`
- **typography.fontFamily** → `fontFamily`
- **typography.fontSize** → `fontSize`
- **rounded** → `borderRadius`
- **spacing** → `spacing`

The handler wraps the mapped tokens in `{ "theme": { "extend": ... } }` and returns the result as pretty-printed JSON via `JSON.stringify(result.data, null, 2)`. Because `TailwindEmitterHandler` is a pure function with no side effects, you can safely redirect the output to a file.

## Integrating the Output with Tailwind Config

Require the generated JSON file in your [`tailwind.config.js`](https://github.com/google-labs-code/design.md/blob/main/tailwind.config.js) to extend the theme.

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: "class",
  theme: {
    extend: require("./tailwind.tokens.json").theme.extend,
  },
};

```

After running your build command (e.g., `npm run dev`), Tailwind generates utility classes from your DESIGN.md tokens:

- `text-primary` maps to your primary color token
- `font-body` applies the body font family and size
- `rounded-sm` uses your rounded token
- `mt-unit` applies your spacing unit

## Complete Workflow Example

Start with a DESIGN.md file containing your design system tokens:

```yaml
---
name: Example System
colors:
  primary: "#ff6f61"
  secondary: "#4a90e2"
typography:
  body:
    fontFamily: Inter
    fontSize: 16px
    lineHeight: 24px
    fontWeight: 400
rounded:
  sm: 4px
spacing:
  unit: 8px
---

```

Export the tokens:

```bash
node packages/cli/src/index.js export ./examples/totality-festival/DESIGN.md tailwind > tailwind.tokens.json

```

Then import into your Tailwind configuration as shown above. If the format argument is invalid, the CLI exits with code 1 and prints an error object to stderr (see [`export.ts`](https://github.com/google-labs-code/design.md/blob/main/export.ts) lines 44-48).

## Summary

- Use the **`json-tailwind`** or **`tailwind`** format with the CLI `export` command to generate Tailwind v3 compatible JSON
- The export logic resides 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)** within the `TailwindEmitterHandler` class
- Output is wrapped in **`{ "theme": { "extend": ... } }`** for direct merging into [`tailwind.config.js`](https://github.com/google-labs-code/design.md/blob/main/tailwind.config.js)
- Token groups map automatically: colors, typography (fontFamily/fontSize), rounded (borderRadius), and spacing
- The CLI reads input via **`readInput`** in [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) and parses tokens through the **`lint`** function

## Frequently Asked Questions

### What Tailwind version does the json-tailwind format target?

The `json-tailwind` format specifically targets **Tailwind v3** configuration structure. It generates a JSON object that conforms to the `theme.extend` API introduced in Tailwind v3, allowing you to merge DESIGN.md tokens without modifying the base theme.

### Can I export to other formats besides Tailwind?

Yes. The CLI supports multiple output formats selectable via the format argument in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts). While `json-tailwind` (alias `tailwind`) produces Tailwind v3 JSON, other formats may be available depending on the emitter handlers implemented in the repository.

### How do I handle export errors?

The CLI writes errors to **stderr** as JSON objects and exits with code 1. For example, if you provide an invalid format argument, the process will terminate and log an error object (see lines 44-48 in [`export.ts`](https://github.com/google-labs-code/design.md/blob/main/export.ts)). Always check the exit code when scripting the export command in CI/CD pipelines.

### Where can I find a working example in the repository?

Examine **`examples/totality-festival/`** in the repository root. This directory contains a sample [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file and a [`tailwind.config.js`](https://github.com/google-labs-code/design.md/blob/main/tailwind.config.js) that demonstrates consuming the emitted JSON output. The example shows how the exported tokens integrate with a real Tailwind v3 build.