# design.md Exports: Purpose and CLI Implementation for Design Token Conversion

> Learn how to use the design.md file as your single source of truth for design tokens. Discover its CLI export implementation for converting tokens to Tailwind themes, CSS variables, and W3C formats.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: api-reference
- Published: 2026-07-02

---

**The [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) file serves as the single source of truth for design tokens, driving the CLI's `export` command to convert structured front-matter into developer-ready formats like Tailwind v3 themes, Tailwind v4 CSS variables, and W3C Design Tokens.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository treats the [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) file as the central configuration for design systems. This markdown file stores **design tokens**—colors, typography, spacing, and component definitions—in its structured front-matter, which the bundled CLI then reads and validates during the export process. Understanding the purpose of **design.md exports** requires examining how the file's machine-readable data feeds into multiple output formats for developer consumption.

## How design.md Drives the Export Process

### Front-Matter as the Machine-Readable Source

The [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) file splits its content between human-readable rationale in the body and machine-readable **design tokens** in the front-matter. When you run the export command, the CLI extracts only this front-matter section, validates the token definitions, and transforms them into the requested format. This separation of concerns ensures that design documentation remains comprehensive for humans while remaining fully parsable for build tools.

### Supported Export Formats

The export command supports three primary output targets according to the repository specification:

1. **Tailwind v3 JSON** - Generates a theme file compatible with [`tailwind.config.js`](https://github.com/google-labs-code/design.md/blob/main/tailwind.config.js).
2. **Tailwind v4 CSS** - Produces a `@theme` block using CSS custom properties.
3. **W3C DTCG JSON** - Exports tokens in the Design Tokens Community Group format for design tools like Figma.

## Export Command Implementation

### Generating Tailwind v3 JSON Themes

The most common use case involves exporting to Tailwind v3's JSON theme format. The handler logic 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) implements the conversion from design tokens to the Tailwind v3 schema defined in [`packages/cli/src/linter/tailwind/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/spec.ts).

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

```

You can then import the generated file directly into your Tailwind configuration:

```javascript
// tailwind.config.js
module.exports = {
  theme: {
    extend: require('./tailwind.theme.json')
  }
}

```

### Exporting to Tailwind v4 CSS Variables

For projects using Tailwind v4, the CLI generates a CSS file containing a `@theme` block. The export 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) and follows the schema defined in [`packages/cli/src/linter/tailwind/v4/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/v4/spec.ts).

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

```

The resulting [`theme.css`](https://github.com/google-labs-code/design.md/blob/main/theme.css) contains valid CSS custom properties:

```css
@theme {
  --color-primary: #1A1C1E;
  --font-size-h1: 3rem;
  /* …more tokens… */
}

```

### Converting to W3C Design Tokens Format

The CLI also supports the DTCG (Design Tokens Community Group) standard, enabling seamless handoff between development and design tools. This export generates a standardized JSON file that conforms to the official Design Tokens JSON schema.

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

```

## Key Source Files in the Export Pipeline

Understanding the export architecture requires examining several critical files in the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository:

- **[`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md)**: Documents the CLI syntax and describes each output format in the Export section.
- **[`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)**: Explains the intent behind the `export` command and the token-to-format mapping.
- **[`packages/cli/src/linter/tailwind/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/spec.ts)**: Defines the Tailwind v3 JSON schema used by the exporter.
- **[`packages/cli/src/linter/tailwind/v4/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/v4/spec.ts)**: Defines the Tailwind v4 CSS-variables schema.
- **[`packages/cli/src/linter/tailwind/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/tailwind/handler.ts)**: Implements the export logic for Tailwind v3.
- **[`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)**: Implements the export logic for Tailwind v4 CSS.

## Summary

- The [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) file acts as the **single source of truth** for design tokens, storing structured data in its front-matter.
- The **`export`** sub-command reads this file, validates tokens, and converts them to **Tailwind v3**, **Tailwind v4**, or **W3C DTCG** formats.
- Export handlers in `packages/cli/src/linter/tailwind/` implement the actual transformation logic for each specific format.
- The CLI validates token definitions against schemas before output, ensuring type safety and consistency across export targets.

## Frequently Asked Questions

### What data does the export command extract from design.md?

The export command extracts only the **front-matter** from the [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) file, ignoring the markdown body content. This front-matter contains the structured design tokens including colors, typography scales, and spacing values that the CLI validates and converts to the requested output format.

### Can I export design.md to multiple formats simultaneously?

The CLI currently processes one format per command execution. You must run separate export commands for each target format (e.g., once for `json-tailwind` and again for `dtcg`), though you can automate this with shell scripts or package.json scripts to generate all formats in a single build step.

### Where is the export logic implemented in the source code?

The export logic is implemented 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) for Tailwind v3 output and [`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 Tailwind v4 CSS variables. These handlers reference schema definitions in adjacent [`spec.ts`](https://github.com/google-labs-code/design.md/blob/main/spec.ts) files to ensure generated output meets the expected format requirements.

### Does the export command validate the design tokens before conversion?

Yes, the CLI validates all design tokens against their respective schemas before export. According to the [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) documentation, this validation step ensures that malformed tokens or type mismatches are caught early, preventing invalid CSS or JSON from being generated in the output files.