fix: rename tailwind export formats for clarity and backwards compat

README.md

@@ -255,18 +255,25 @@ Exit code `1` if regressions are detected (more errors or warnings in the "after
 
 ### `export`
 
-Export DESIGN.md tokens to other formats (tailwind, tailwind-v3, dtcg). `tailwind` targets the latest Tailwind (v4, CSS `@theme`); use `tailwind-v3` for legacy `tailwind.config.js` output.
+Export DESIGN.md tokens to other formats.
 
 ```bash
-npx @google/design.md export --format tailwind DESIGN.md > theme.css
-npx @google/design.md export --format tailwind-v3 DESIGN.md > tailwind.theme.json
+npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
+npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
 npx @google/design.md export --format dtcg DESIGN.md > tokens.json
 ```
 
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
 | `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |
-| `--format` | `tailwind` \| `tailwind-v3` \| `dtcg` | required | Output format |
+| `--format` | `json-tailwind` \| `css-tailwind` \| `tailwind` \| `dtcg` | required | Output format |
+
+| Format | Output | Description |
+|:-------|:-------|:------------|
+| `json-tailwind` | JSON | Tailwind v3 `theme.extend` config object |
+| `css-tailwind` | CSS | Tailwind v4 `@theme { ... }` block with CSS custom properties |
+| `tailwind` | JSON | Alias for `json-tailwind` |
+| `dtcg` | JSON | W3C Design Tokens Format Module |
 
 ### `spec`
 
@@ -317,8 +324,8 @@ console.log(report.designSystem);   // Parsed DesignSystemState
 
 DESIGN.md tokens are inspired by the [W3C Design Token Format](https://www.designtokens.org/). The `export` command converts tokens to other formats:
 
-- **Tailwind CSS (v4, default)** — `npx @google/design.md export --format tailwind DESIGN.md` — emits a CSS `@theme { ... }` block using Tailwind v4's CSS-variable token namespaces (`--color-*`, `--font-*`, `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--radius-*`, `--spacing-*`). Output is CSS text.
-- **Tailwind v3 config** — `npx @google/design.md export --format tailwind-v3 DESIGN.md` — emits the legacy `tailwind.config.js` `theme.extend` JSON shape for Tailwind v3.
+- **Tailwind v3 config (JSON)** — `npx @google/design.md export --format json-tailwind DESIGN.md` — emits a `theme.extend` JSON object for `tailwind.config.js`. `--format tailwind` is a backwards-compatible alias.
+- **Tailwind v4 theme (CSS)** — `npx @google/design.md export --format css-tailwind DESIGN.md` — emits a CSS `@theme { ... }` block using Tailwind v4's CSS-variable token namespaces (`--color-*`, `--font-*`, `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--radius-*`, `--spacing-*`).
 - **DTCG tokens.json** ([W3C Design Tokens Format Module](https://tr.designtokens.org/format/)) — `npx @google/design.md export --format dtcg DESIGN.md`
 
 ## Status

packages/cli/src/commands/export.ts

@@ -17,13 +17,13 @@ import { lint, TailwindEmitterHandler, TailwindV4EmitterHandler, serializeTailwi
 import { DtcgEmitterHandler } from '../linter/dtcg/handler.js';
 import { readInput } from '../utils.js';
 
-const FORMATS = ['tailwind', 'tailwind-v3', 'dtcg'] as const;
+const FORMATS = ['css-tailwind', 'json-tailwind', 'tailwind', 'dtcg'] as const;
 type ExportFormat = typeof FORMATS[number];
 
 export default defineCommand({
   meta: {
     name: 'export',
-    description: 'Export DESIGN.md tokens to other formats (tailwind, tailwind-v3, dtcg). `tailwind` targets the latest (v4) CSS @theme syntax; use `tailwind-v3` for legacy tailwind.config.js output.',
+    description: 'Export DESIGN.md tokens to other formats. `css-tailwind` emits Tailwind v4 CSS @theme; `json-tailwind` emits Tailwind v3 theme.extend JSON; `tailwind` is an alias for `json-tailwind`; `dtcg` emits W3C Design Tokens.',
   },
   args: {
     file: {
@@ -52,7 +52,7 @@ export default defineCommand({
     const content = await readInput(args.file);
     const report = lint(content);
 
-    if (format === 'tailwind') {
+    if (format === 'css-tailwind') {
       const handler = new TailwindV4EmitterHandler();
       const result = handler.execute(report.designSystem);
 
@@ -63,7 +63,7 @@ export default defineCommand({
       }
 
       console.log(serializeTailwindV4(result.data.theme));
-    } else if (format === 'tailwind-v3') {
+    } else if (format === 'json-tailwind' || format === 'tailwind') {
       const handler = new TailwindEmitterHandler();
       const result = handler.execute(report.designSystem);