How to Customize the Export Process in the design.md CLI

The design.md CLI provides built-in options to customize the export process through format selection and optional prefixing for CSS custom properties.

The design.md CLI, maintained in the google-labs-code/design.md repository, includes a flexible export command that transforms design system files into various token formats. You can customize the export process by selecting output formats and applying custom prefixes to generated CSS variables. The core command logic resides in packages/cli/src/commands/export.ts, which validates arguments and dispatches to specialized emitter handlers based on your configuration.

Command-Line Arguments for Export Customization

The export command defined in packages/cli/src/commands/export.ts accepts three key arguments that control how design tokens are processed and output.

Positional File Argument

The file argument specifies the path to your DESIGN.md source file. You can also pass - to read from stdin, enabling integration with piping workflows and automated build pipelines.

Format Selection

The format argument determines the output type. The CLI validates this against a closed FORMATS enum containing these supported values:

• css-tailwind
• json-tailwind
• tailwind
• dtcg
• css-vars

If you provide an unrecognized format, the CLI prints a JSON error and sets process.exitCode = 1, allowing CI/CD systems to detect invalid configurations immediately.

CSS Variable Prefixing

When exporting to css-vars format, the optional prefix argument prepends a custom string to every generated CSS variable name. This is particularly useful for namespacing design tokens in large projects or when integrating multiple design systems.

How the Export Pipeline Processes Customizations

When you run the export command, the CLI validates the format and dispatches to the appropriate emitter handler. For CSS custom property exports specifically, the pipeline involves three distinct stages:

1. Handler Initialization: The CssVarsEmitterHandler (located in packages/cli/src/linter/css-vars/handler.ts) processes the design tokens and returns raw declarations.
2. Serialization: The CLI calls serializeCssVars from packages/cli/src/linter/css-vars/serialize.ts, passing the optional prefix argument when provided.
3. Output Generation: The serializer constructs a CSS block within a :root selector, applying the prefix to each variable name. For example, a prefix of ds generates variables like --ds-color-primary and --ds-spacing-unit.

Practical Export Examples

Exporting to Tailwind JSON

Generate a Tailwind-compatible JSON configuration by specifying the json-tailwind format:

design-md export ./examples/totality-festival/DESIGN.md --format json-tailwind > tailwind-theme.json

This invokes the TailwindEmitterHandler and outputs a formatted JSON object suitable for Tailwind CSS configuration files.

Creating Prefixed CSS Variables

Add a namespace prefix to your CSS custom properties using the --prefix flag:

design-md export ./examples/totality-festival/DESIGN.md \
  --format css-vars \
  --prefix ds > design-vars.css

The resulting CSS file contains variables such as --ds-color-primary, as verified in the test suite at packages/cli/src/commands/export.test.ts.

Handling Invalid Formats

Attempting to use an unsupported format triggers the validation error handling:

design-md export ./examples/totality-festival/DESIGN.md --format unknown

This outputs a JSON error message and exits with code 1, preventing invalid configurations from proceeding downstream.

Extending the Export Architecture

You can further customize the export process by extending the CLI's emitter system. Adding a new format requires updating the FORMATS constant array in packages/cli/src/commands/export.ts and implementing a corresponding emitter handler. Follow the patterns established by existing handlers like TailwindEmitterHandler, DtcgEmitterHandler, or CssVarsEmitterHandler to ensure seamless integration with the validation and serialization pipeline.

Summary

• The design.md CLI export process supports customization through the format and prefix arguments defined in packages/cli/src/commands/export.ts.
• Choose from five supported formats including css-vars, json-tailwind, and dtcg to match your target platform's requirements.
• Apply custom prefixes to CSS variables using --prefix when exporting to css-vars format, which modifies the output via serializeCssVars in packages/cli/src/linter/css-vars/serialize.ts.
• Invalid formats trigger immediate validation errors with exit code 1, enabling robust error detection in automated workflows.
• The modular handler architecture allows extending the system with new export formats by following existing patterns in the linter directory.

Frequently Asked Questions

Can I export to multiple formats simultaneously?

No, the export command processes one format at a time. To generate multiple outputs, run the command separately for each format. Each execution reads the source DESIGN.md independently and applies format-specific serialization logic through its respective emitter handler.

What happens if I provide an invalid format string?

The CLI validates the format argument against the FORMATS enum in packages/cli/src/commands/export.ts. If the format is unrecognized, it prints a JSON error message to stderr and sets process.exitCode = 1. This ensures your build pipeline can detect configuration errors immediately without producing invalid output files.

Is the prefix option available for all export formats?

No, the --prefix argument only applies when using css-vars format. When exporting to JSON-based formats like json-tailwind or dtcg, the prefix argument is ignored because these formats use structured object keys rather than prefixed CSS custom properties. The serializeCssVars function specifically handles the prefix logic for CSS variable generation.

Can I read from stdin instead of a file?

Yes, pass - as the file argument to read from stdin. This enables piping workflows where you can process DESIGN.md content from other tools or preprocessors before exporting to your desired format. The stdin handling is implemented in the positional argument parsing at lines 30-34 of packages/cli/src/commands/export.ts.

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