# How to Export DESIGN.md Tokens to Tailwind v4 CSS Format

> Easily export DESIGN.md tokens to Tailwind v4 CSS format using the CLI. Convert design system categories to CSS variables for seamless integration.

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

---

**Use the [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) CLI with the `--format css-tailwind` flag to convert DESIGN.md tokens into a Tailwind v4-compatible `@theme` CSS block that maps design system categories to CSS variables.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository provides a deterministic CLI pipeline for exporting design tokens. When you export DESIGN.md tokens to Tailwind v4 CSS format, the tool validates token names against CSS identifier rules and serializes the design system into a pure CSS `@theme` block suitable for modern Tailwind configurations.

## Installation and Prerequisites

The CLI requires Node.js ≥ 20 or Bun. Install the package globally or in your project to access the [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) binary.

```bash
npm install -g @google/design.md

```

## CLI Export Workflow

### Basic Command Structure

The `design.md export` command located in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts) reads a DESIGN.md file and emits the token set in your chosen format. For Tailwind v4, specify `css-tailwind` as the format target.

```bash
design.md export path/to/DESIGN.md --format css-tailwind > tailwind-theme.css

```

This command writes the `@theme` CSS block to stdout, which you can redirect to a file for integration into your stylesheets.

### Input Options

Use `-` as the file path to read from standard input, enabling piping from other processes.

```bash
cat DESIGN.md | design.md export - --format css-tailwind

```

### Token Validation and Exit Codes

The CLI validates every token name against the CSS identifier regex `/^[a-zA-Z0-9][a-zA-Z0-9-]*$/`. If validation fails, the command exits with a non-zero status, making it safe for CI pipelines and pre-commit hooks.

## Integrating with Tailwind v4

Tailwind v4 consumes `@theme` blocks directly. Import the generated CSS file into your Tailwind configuration to register the design tokens as CSS variables accessible within the framework.

```javascript
// tailwind.config.js
const fs = require('fs');
const path = require('path');

module.exports = {
  plugins: [
    function ({ addBase }) {
      const css = fs.readFileSync(path.resolve(__dirname, 'tailwind-theme.css'), 'utf8');
      addBase(css);
    },
  ],
};

```

## Programmatic Node.js API

For custom build pipelines, invoke the emitter and serializer directly without spawning child processes. This approach uses the pure functions exposed by the `@google/design.md` package.

```typescript
import { readFile } from 'fs/promises';
import { lint } from '@google/design.md/linter';
import { TailwindV4EmitterHandler } from '@google/design.md/linter/tailwind/v4/handler';
import { serializeToCss } from '@google/design.md/linter/tailwind/v4/serialize';

const designMd = await readFile('./DESIGN.md', 'utf8');
const report = lint(designMd);

const emitter = new TailwindV4EmitterHandler();
const result = emitter.execute(report.designSystem);

if (!result.success) {
  throw new Error(result.error.message);
}

const css = serializeToCss(result.data.theme);
console.log(css);

```

## Technical Implementation Details

### Parsing and Linting Stage

In [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts), the `readInput` function loads the source file and the `lint` function constructs a `DesignSystemState` object representing the parsed design system with all token categories extracted.

### Tailwind v4 Emitter Handler

The `TailwindV4EmitterHandler` class 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) validates token names and maps design system categories—**colors**, **typography**, **border-radius**, and **spacing**—into a plain `TailwindV4ThemeData` object. This handler is pure (no side effects) and deterministic, producing the same output for identical inputs.

### CSS Serialization

The `serializeToCss` function in [`packages/cli/src/linter/tailwind/v4/serialize.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/v4/serialize.ts) walks the ordered `CATEGORIES` list and writes each entry as a CSS variable inside an `@theme` block. The emitter outputs a string that the CLI prints to stdout in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts).

## Summary

- Install the `@google/design.md` CLI and run `design.md export --format css-tailwind` to generate a Tailwind v4 `@theme` CSS block.
- Token names are validated against `/^[a-zA-Z0-9][a-zA-Z0-9-]*$/` to ensure CSS identifier compatibility.
- The pipeline uses `TailwindV4EmitterHandler` and `serializeToCss` from the `packages/cli/src/linter/tailwind/v4/` directory to produce deterministic output safe for CI environments.
- Integrate the generated CSS into your Tailwind v4 configuration using the `addBase` plugin function or by importing the CSS file directly into your stylesheet.

## Frequently Asked Questions

### What is the correct format flag for exporting to Tailwind v4?

Use `--format css-tailwind`. This flag triggers the `TailwindV4EmitterHandler` which validates tokens and outputs the `@theme` CSS block required by Tailwind v4.

### How does the CLI validate token names before export?

The emitter validates every token name against the regex `/^[a-zA-Z0-9][a-zA-Z0-9-]*$/` to ensure compliance with CSS identifier rules. Invalid names cause the export to fail with a non-zero exit code.

### Can I export tokens from standard input instead of a file?

Yes. Pass `-` as the file path to read from stdin: `design.md export - --format css-tailwind`. This is useful for piping content in CI/CD pipelines.

### Where are the core Tailwind v4 emitter functions located?

The main logic resides 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) for the emitter handler and [`packages/cli/src/linter/tailwind/v4/serialize.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/v4/serialize.ts) for the CSS serialization. The CLI entry point is [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts).