Skip to content

feat: add design-md export target (DESIGN.md generator) #103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nujovich merged 6 commits into from
Jul 27, 2026
Merged

feat: add design-md export target (DESIGN.md generator) #103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
132b599
feat: add deterministic DESIGN.md token converter
nujovich Jul 20, 2026
9941683
fix: escape pipe characters in DESIGN.md table cells
nujovich Jul 20, 2026
34d8b4b
test: lock DESIGN.md golden output for frankenstein fixture
nujovich Jul 20, 2026
ef7b6fa
feat: register design-md export target and alias
nujovich Jul 20, 2026
b5ad3e1
feat: wire design-md export branch into cmdExport
nujovich Jul 20, 2026
6979598
docs: document the design-md export target
nujovich Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -548,16 +548,16 @@ Add `mint-ds.cache.json` to `.gitignore` if you don't want to commit it.

### Export options

| Flag | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--target <name>` | **Required.** Accepts: `tailwind`, `unocss`, `react`, `vue`, `svelte`, `astro`, `css`, `scss`, `ts`, `css-modules`, `styled`, `emotion`, `vanilla-extract`, `angular`, `angular-legacy`, `solidjs`, `qwik`, `dtcg` (full names like `tailwind-config`, `react-component` also work) |
| `--tokens <file>` | Tokens input path (default: `mint-ds.tokens.json`) |
| `--out <file>` | Override the default output filename |
| `--provider <name>` | LLM backend: `anthropic` (default), `ollama`, or `openrouter` |
| `--api-key <value>` | LLM provider API key (overrides all API key env vars) |
| `--model <name>` | Model name (overrides all model env vars) |
| `--url <url>` | API endpoint URL (overrides all URL env vars) |
| `--stdout` | Print to stdout instead of writing a file |
| Flag | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--target <name>` | **Required.** Accepts: `tailwind`, `unocss`, `react`, `vue`, `svelte`, `astro`, `css`, `scss`, `ts`, `css-modules`, `styled`, `emotion`, `vanilla-extract`, `angular`, `angular-legacy`, `solidjs`, `qwik`, `dtcg`, `design-md` (full names like `tailwind-config`, `react-component` also work) |
| `--tokens <file>` | Tokens input path (default: `mint-ds.tokens.json`) |
| `--out <file>` | Override the default output filename |
| `--provider <name>` | LLM backend: `anthropic` (default), `ollama`, or `openrouter` |
| `--api-key <value>` | LLM provider API key (overrides all API key env vars) |
| `--model <name>` | Model name (overrides all model env vars) |
| `--url <url>` | API endpoint URL (overrides all URL env vars) |
| `--stdout` | Print to stdout instead of writing a file |

### Local development without publishing

Expand All @@ -581,6 +581,7 @@ node bin/mint-ds.mjs audit ./examples/site --provider ollama
| Frameworks | Tailwind Config, Styled Components, Emotion Theme, CSS Modules, Vanilla Extract |
| Components | React + TypeScript, Vue 3 SFC, Svelte, Astro, Angular, Angular (Legacy), SolidJS, Qwik |
| Interop | DTCG (Design Tokens Format Module v1) — for Penpot & Tokens Studio |
| Docs | DESIGN.md — human-readable design system summary for AI-assisted workflows |

## Penpot & DTCG interop

Expand Down
45 changes: 45 additions & 0 deletions bin/__tests__/export-design-md.test.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
import { describe, it, expect } from 'vitest'
import { spawnSync } from 'node:child_process'
import { fileURLToPath } from 'node:url'
import { resolve } from 'node:path'

// The design-md export is fully deterministic (no network, no LLM), so we can
// drive the real CLI end-to-end and assert on stdout.
const CLI = fileURLToPath(new URL('../mint-ds.mjs', import.meta.url))
const REPO_ROOT = fileURLToPath(new URL('../../', import.meta.url))
const TOKENS = resolve(REPO_ROOT, 'examples/frankenstein/mint-ds.tokens.json')

function runExport(args) {
return spawnSync('node', [CLI, 'export', ...args], {
cwd: REPO_ROOT,
encoding: 'utf8',
})
}

describe('mint-ds export --target design-md', () => {
it('prints the generated DESIGN.md to stdout and exits 0', () => {
const result = runExport([
'--target',
'design-md',
'--tokens',
TOKENS,
'--stdout',
])
expect(result.status).toBe(0)
expect(result.stdout).toContain('# frankenstein Design System')
expect(result.stdout).toContain('## Colors')
expect(result.stdout).toContain('### primary')
})

it('resolves the "design" alias too', () => {
const result = runExport([
'--target',
'design',
'--tokens',
TOKENS,
'--stdout',
])
expect(result.status).toBe(0)
expect(result.stdout).toContain('# frankenstein Design System')
})
})
5 changes: 5 additions & 0 deletions bin/mint-ds.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ import { getCssAuditor } from '../lib/css-auditor.mjs'
import { validateFile } from '../lib/dtcg-validator.mjs'
import { diffFiles } from '../lib/token-diff.mjs'
import { convertTokensToDTCG, serializeDTCG } from '../lib/dtcg-exporter.mjs'
import { convertTokensToDesignMd } from '../lib/design-md.mjs'
import { formatLintSummary } from '../lib/audit-summary.mjs'
import { checkCompat } from '../lib/css-compat-data.mjs'
import { lintCss, lintGapDecorationAdoption } from '../lib/css-lint-rules.mjs'
Expand Down Expand Up @@ -173,6 +174,7 @@ ${styles.bold('EXAMPLES')}
npx mint-ds export --target tailwind
npx mint-ds export --target react --out ui/Components.tsx
npx mint-ds export --target css --stdout > variables.css
npx mint-ds export --target design-md > DESIGN.md
npx mint-ds validate tokens.json --spec dtcg
npx mint-ds validate tokens.json --spec dtcg --json
npx mint-ds diff old.tokens.json mint-ds.tokens.json
Expand Down Expand Up @@ -592,6 +594,9 @@ async function cmdExport(argv) {
// Deterministic conversion — no LLM
const dtcg = convertTokensToDTCG(tokens)
code = serializeDTCG(dtcg)
} else if (target === 'design-md') {
// Deterministic conversion — no LLM
code = convertTokensToDesignMd(tokens)
} else {
const cssAuditor = getCssAuditor(flags)
code = await cssAuditor.export(buildExportPrompt(tokens, target))
Expand Down
146 changes: 146 additions & 0 deletions examples/frankenstein/DESIGN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
# frankenstein Design System

## Colors

### primary

| Step | Value |
|---|---|
| 50 | #e3f2fd |
| 100 | #bbdefb |
| 200 | #90caf9 |
| 300 | #64b5f6 |
| 400 | #42a5f5 |
| 500 | #1976d2 |
| 600 | #1565c0 |
| 700 | #0d47a1 |
| 800 | #0a3f8f |
| 900 | #08357d |

### error

| Step | Value |
|---|---|
| 50 | #ffebee |
| 100 | #ffcdd2 |
| 200 | #ef9a9a |
| 300 | #e57373 |
| 400 | #ef5350 |
| 500 | #e53935 |
| 600 | #d32f2f |
| 700 | #c62828 |
| 800 | #b71c1c |
| 900 | #a01818 |

### background

| Step | Value |
|---|---|
| 50 | #fefefe |
| 100 | #fdfdfd |
| 200 | #fafafa |
| 300 | #f7f7f7 |
| 400 | #f6f6f6 |
| 500 | #f5f5f5 |
| 600 | #e8e8e8 |
| 700 | #d4d4d4 |
| 800 | #c0c0c0 |
| 900 | #a8a8a8 |

### text

| Step | Value |
|---|---|
| 50 | #f5f5f5 |
| 100 | #e0e0e0 |
| 200 | #bdbdbd |
| 300 | #9e9e9e |
| 400 | #757575 |
| 500 | #212121 |
| 600 | #1e1e1e |
| 700 | #1a1a1a |
| 800 | #171717 |
| 900 | #141414 |

### border

| Step | Value |
|---|---|
| 50 | #f9f9f9 |
| 100 | #f4f4f4 |
| 200 | #eeeeee |
| 300 | #e7e7e7 |
| 400 | #e2e2e2 |
| 500 | #dddddd |
| 600 | #c7c7c7 |
| 700 | #a8a8a8 |
| 800 | #8a8a8a |
| 900 | #6c6c6c |

### surface

| Step | Value |
|---|---|
| 50 | #ffffff |
| 100 | #ffffff |
| 200 | #ffffff |
| 300 | #ffffff |
| 400 | #ffffff |
| 500 | #ffffff |
| 600 | #e6e6e6 |
| 700 | #cccccc |
| 800 | #b3b3b3 |
| 900 | #999999 |

### muted

| Step | Value |
|---|---|
| 50 | #f2f2f2 |
| 100 | #e0e0e0 |
| 200 | #cccccc |
| 300 | #b3b3b3 |
| 400 | #8c8c8c |
| 500 | #666666 |
| 600 | #5c5c5c |
| 700 | #4d4d4d |
| 800 | #404040 |
| 900 | #333333 |

## Typography

### Font families

| Token | Value |
|---|---|
| body | Helvetica Neue |

### Font weights

| Token | Value |
|---|---|
| bold | 700 |
| extrabold | 800 |

## Spacing

| Token | Value |
|---|---|
| 1 | 4px |
| 2 | 8px |
| 3 | 12px |
| 5 | 20px |
| 6 | 24px |

## Border radius

| Token | Value |
|---|---|
| sm | 4px |
| md | 8px |

## Shadows

| Token | Value |
|---|---|
| sm | 0 2px 4px rgba(0,0,0,0.1) |
Loading
Loading