Configuration Options for Exporting in DESIGN.md: Complete CLI Guide

The export command in @google/design.md provides three configuration options: a positional file argument for input path, --format to select the output emitter (json-tailwind, css-tailwind, dtcg, or css-vars), and --prefix to customize CSS variable names.

The export command converts DESIGN.md files into various token formats for design systems. As implemented in google-labs-code/design.md, this CLI tool offers specific configuration options that control input handling, output format selection, and naming conventions. These options map directly to distinct emitter implementations in the source code that transform the parsed design system into production-ready code.

Export Command Configuration Options

The export command (npx @google/design.md export …) accepts a minimal but precise set of configuration flags defined in packages/cli/src/commands/export.ts. Each option controls a specific stage of the transformation pipeline.

Input File Path (Positional Argument)

The file positional argument specifies the path to your DESIGN.md source file. Use - to read from stdin instead of a file. This parameter is processed by the readInput utility in packages/cli/src/utils.ts, which handles both file system access and standard input streams.

Output Format Selection (--format)

The --format flag determines which emitter handles the transformation. Valid values are validated against a closed enum in export.ts:

• json-tailwind: Generates a Tailwind v3 theme.extend JSON object via TailwindEmitterHandler in packages/cli/src/linter/tailwind/handler.ts
• css-tailwind: Produces a Tailwind v4 @theme { … } CSS block using TailwindV4EmitterHandler in packages/cli/src/linter/tailwind/v4/handler.ts
• tailwind: Alias for json-tailwind
• dtcg: Outputs W3C Design Tokens JSON via DtcgEmitterHandler in packages/cli/src/linter/dtcg/handler.ts
• css-vars: Creates CSS custom-property declarations using CssVarsEmitterHandler in packages/cli/src/linter/css-vars/handler.ts

CSS Variable Prefix (--prefix)

The --prefix option applies exclusively to the css-vars format. Supply a string (e.g., my-) to prepend custom property names, resulting in outputs like --my-color-primary. This handler resides in packages/cli/src/linter/css-vars/handler.ts.

The Export Pipeline Architecture

When you execute the export command, it follows a deterministic four-step process:

1. Input Reading: The readInput function from packages/cli/src/utils.ts ingests the DESIGN.md content
2. Linting: The shared lint(content) function parses the file into a DesignSystemState
3. Emitter Dispatch: Based on --format, the CLI instantiates the appropriate emitter class conforming to the EmitterSpec interface
4. Serialization: Format-specific helpers like serializeTailwindV4 or serializeCssVars convert the internal state to the final output string

Practical Usage Examples

CLI Commands

Export to Tailwind v3 JSON:

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

Generate Tailwind v4 CSS @theme block:

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

Create W3C Design Tokens:

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

Export CSS variables with custom prefix:

npx @google/design.md export --format css-vars --prefix my- DESIGN.md > vars.css

Programmatic Integration

Import the linter and emitters directly for Node.js scripts:

import { lint } from '@google/design.md/linter';
import { TailwindEmitterHandler } from '@google/design.md/linter/tailwind/handler';
import { serializeTailwindV4 } from '@google/design.md/linter/tailwind/v4/serialize';

async function exportToTailwindV4(fileContent: string) {
  const report = lint(fileContent);
  const handler = new TailwindV4EmitterHandler();
  const result = handler.execute(report.designSystem);
  if (!result.success) throw new Error(result.error.message);
  return serializeTailwindV4(result.data.theme);
}

Exit Codes and Error Handling

The export command returns deterministic exit codes: 0 indicates successful completion, 1 signals an invalid format selection or emitter error, and 2 indicates the input file could not be read. These semantics are documented in the repository's README.md.

Summary

• The export command accepts three configuration options: the file positional argument, --format, and --prefix
• Five output formats are available through dedicated emitter handlers in packages/cli/src/linter/
• The --prefix option only affects css-vars output, prepending custom strings to CSS variable names
• All emitters implement the EmitterSpec interface, enabling consistent extension points
• Exit codes (0, 1, 2) provide clear success/failure signals for CI/CD integration

Frequently Asked Questions

What is the default output format if I don't specify --format?

The analysis of the source code in packages/cli/src/commands/export.ts indicates that --format is a required parameter without a default value. You must explicitly specify one of the valid enum values: json-tailwind, css-tailwind, tailwind, dtcg, or css-vars.

Can I use the --prefix option with JSON output formats?

No. The --prefix configuration option is exclusively implemented in the CssVarsEmitterHandler class within packages/cli/src/linter/css-vars/handler.ts. It has no effect when used with json-tailwind, css-tailwind, or dtcg formats.

How do I export multiple files at once?

The CLI does not support glob patterns or multiple file arguments in a single invocation. You must run the export command separately for each DESIGN.md file, or pipe content via stdin using - as the file argument for batch processing in shell scripts.

Where are the emitter implementations located?

Each emitter resides in a specific handler file under the linter package: Tailwind v3 JSON uses packages/cli/src/linter/tailwind/handler.ts, Tailwind v4 CSS uses packages/cli/src/linter/tailwind/v4/handler.ts, DTCG tokens use packages/cli/src/linter/dtcg/handler.ts, and CSS variables use packages/cli/src/linter/css-vars/handler.ts.

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