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

The 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 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.

# 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 (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, 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 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. 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 to extend the theme.

/** @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:

---
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:

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 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 within the TailwindEmitterHandler class
• Output is wrapped in { "theme": { "extend": ... } } for direct merging into 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 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. 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). 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 file and a tailwind.config.js that demonstrates consuming the emitted JSON output. The example shows how the exported tokens integrate with a real Tailwind v3 build.

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