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

> Customize design.md CLI export for CSS custom properties with format selection and optional prefixing. Tailor your workflow for efficient design asset management.

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

---

**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`](https://github.com/google-labs-code/design.md/blob/main/design.md) CLI, maintained in the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

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

```bash
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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.test.ts).

### Handling Invalid Formats

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

```bash
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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/design.md) CLI export process supports customization through the `format` and `prefix` arguments defined in [`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts).