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

The 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 repository treats the 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 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.
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 implements the conversion from design tokens to the Tailwind v3 schema defined in packages/cli/src/linter/tailwind/spec.ts.

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:

// 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 and follows the schema defined in packages/cli/src/linter/tailwind/v4/spec.ts.

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

The resulting theme.css contains valid CSS custom properties:

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

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

• README.md: Documents the CLI syntax and describes each output format in the Export section.
• docs/spec.md: Explains the intent behind the export command and the token-to-format mapping.
• 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: Defines the Tailwind v4 CSS-variables schema.
• packages/cli/src/linter/tailwind/handler.ts: Implements the export logic for Tailwind v3.
• packages/cli/src/linter/tailwind/v4/handler.ts: Implements the export logic for Tailwind v4 CSS.

Summary

• The 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 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 for Tailwind v3 output and packages/cli/src/linter/tailwind/v4/handler.ts for Tailwind v4 CSS variables. These handlers reference schema definitions in adjacent 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 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.

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