@webdesignhot/design-md 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webdesignhot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# design-md
+
+> Drop any DESIGN.md into your repo in one command. Browse, install, lint, diff, and export design systems extracted from real production sites.
+
+```bash
+$ npx @webdesignhot/design-md add linear
+✓ Wrote DESIGN.md (8.2 KB · linear)
+
+$ npx @webdesignhot/design-md list
+★ agentkit       AgentKit          dark editorial sans dense
+★ anthropic      Anthropic         light editorial serif
+  arc            Arc               light warm sans
+…
+
+$ npx @webdesignhot/design-md export DESIGN.md --to tailwind > tailwind.theme.js
+```
+
+## Why
+
+A DESIGN.md is a single file that captures a brand's design system as a YAML head + markdown body — engineered to be read by AI coding agents. This CLI is the fastest way to get one into your project.
+
+The catalog at [webdesignhot.com/design.md](https://www.webdesignhot.com/design.md/) ships real-brand design systems extracted from production sites — Linear, Stripe, Vercel, Anthropic, Notion, and dozens more. One command and you have a token-rich style guide your agent can follow.
+
+## Install
+
+```bash
+# one-off
+npx @webdesignhot/design-md <command>
+
+# global
+npm i -g @webdesignhot/design-md
+# the binary is `design-md` regardless of scope:
+design-md add linear
+```
+
+Requires Node 18+.
+
+## Commands
+
+```
+add <slug> [-o, --out <path>] [-f, --force]
+  Write the chosen DESIGN.md to your CWD.
+
+list
+  Print the full catalog (slug · name · tags).
+
+category [name]
+  Without a name, lists every category with a count.
+  With a name, lists every design in that category.
+
+init
+  Interactive picker (default if no command given).
+
+lint <file> [--format=text|json]
+  Validate a DESIGN.md for spec compliance.
+
+diff <a> <b> [--format=text|json]
+  Token-level diff between two DESIGN.md files.
+
+export <file> --to <tailwind|css|dtcg|figma>
+  Convert tokens to one of:
+    tailwind   — theme.extend block for tailwind.config.js
+    css        — :root { --color-bg, --radius-card, … }
+    dtcg       — W3C Design Tokens Community Group JSON
+    figma      — Figma Variables import format
+
+extract <url> [-o <path>] [--token-only]
+  Extract a draft DESIGN.md from any production URL.
+  (Requires a webdesignhot session — opens the browser flow.)
+
+theme <slug> [--dark|--light]
+  Compute a dark/light variant of any design.
+
+preview <slug>
+  Open the directory detail page in your browser.
+
+help
+  Print the full command list.
+```
+
+## License
+
+MIT — © 2026 webdesignhot

package/bin/design-md.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/index.mjs'
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(err?.message ?? err)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@webdesignhot/design-md",
+  "version": "0.1.0",
+  "description": "Drop any DESIGN.md into your repo in one command. Browse, install, lint, diff, and export design systems extracted from real production sites.",
+  "keywords": ["design.md", "design-system", "design-tokens", "ai-agents", "cli", "tailwind", "figma", "dtcg"],
+  "author": "webdesignhot",
+  "license": "MIT",
+  "homepage": "https://www.webdesignhot.com/design.md/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WebDesignHot/design-md"
+  },
+  "bin": {
+    "design-md": "bin/design-md.mjs"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "kleur": "^4.1.5",
+    "yaml": "^2.5.0"
+  }
+}

package/src/commands/add.mjs

@@ -0,0 +1,41 @@
+import { writeFile, access } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import kleur from 'kleur'
+import { fetchRawMd } from '../lib/api.mjs'
+
+function parseFlags(args) {
+  const flags = { out: 'DESIGN.md', force: false }
+  const positional = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '-o' || a === '--out') flags.out = args[++i]
+    else if (a === '-f' || a === '--force') flags.force = true
+    else positional.push(a)
+  }
+  return { flags, positional }
+}
+
+export const add = {
+  usage: 'add <slug> [-o, --out <path>] [-f, --force]',
+  async run(args) {
+    const { flags, positional } = parseFlags(args)
+    const slug = positional[0]
+    if (!slug) {
+      console.error('Usage: design-md add <slug> [-o <path>] [-f]')
+      process.exit(2)
+    }
+    const out = resolve(process.cwd(), flags.out)
+    if (!flags.force) {
+      try {
+        await access(out)
+        console.error(kleur.red(`✗ ${flags.out} already exists. Pass --force to overwrite.`))
+        process.exit(1)
+      } catch {
+        // doesn't exist — proceed
+      }
+    }
+    const md = await fetchRawMd(slug)
+    await writeFile(out, md, 'utf8')
+    console.log(kleur.green(`✓ Wrote ${flags.out}`) + kleur.dim(` (${(md.length / 1024).toFixed(1)} KB · ${slug})`))
+  },
+}

package/src/commands/category.mjs

@@ -0,0 +1,31 @@
+import kleur from 'kleur'
+import { fetchCatalog } from '../lib/api.mjs'
+
+export const category = {
+  usage: 'category [name]',
+  async run(args) {
+    const catalog = await fetchCatalog()
+    const name = args[0]
+    if (!name) {
+      const counts = new Map()
+      for (const e of catalog.entries)
+        for (const c of e.categories ?? []) counts.set(c, (counts.get(c) ?? 0) + 1)
+      const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1])
+      const w = Math.max(...sorted.map(([c]) => c.length), 4)
+      for (const [c, n] of sorted) {
+        console.log(`${kleur.cyan(c.padEnd(w))}  ${kleur.dim(String(n).padStart(3))} designs`)
+      }
+      return
+    }
+    const matches = catalog.entries.filter((e) => (e.categories ?? []).includes(name))
+    if (!matches.length) {
+      console.error(kleur.red(`No designs in category "${name}".`))
+      process.exit(1)
+    }
+    const w = Math.max(...matches.map((e) => e.slug.length), 4)
+    for (const e of matches) {
+      console.log(`${kleur.cyan(e.slug.padEnd(w))}  ${e.name}  ${kleur.dim((e.tags ?? []).join(' '))}`)
+    }
+    console.log(kleur.dim(`\n${matches.length} designs in category "${name}"`))
+  },
+}

package/src/commands/diff.mjs

@@ -0,0 +1,65 @@
+import { resolve } from 'node:path'
+import kleur from 'kleur'
+import { readDesignMd, flattenColors } from '../lib/parse.mjs'
+
+function parseFlags(args) {
+  const flags = { format: 'text' }
+  const positional = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a.startsWith('--format=')) flags.format = a.slice(9)
+    else if (a === '--format') flags.format = args[++i]
+    else positional.push(a)
+  }
+  return { flags, positional }
+}
+
+function diffMaps(left, right) {
+  const result = { added: {}, removed: {}, modified: {} }
+  const keys = new Set([...Object.keys(left), ...Object.keys(right)])
+  for (const k of keys) {
+    const a = left[k]
+    const b = right[k]
+    if (a == null && b != null) result.added[k] = b
+    else if (a != null && b == null) result.removed[k] = a
+    else if (a !== b) result.modified[k] = { from: a, to: b }
+  }
+  return result
+}
+
+export const diff = {
+  usage: 'diff <a> <b> [--format=text|json]',
+  async run(args) {
+    const { flags, positional } = parseFlags(args)
+    const [a, b] = positional
+    if (!a || !b) {
+      console.error('Usage: design-md diff <a> <b>')
+      process.exit(2)
+    }
+    const A = await readDesignMd(resolve(process.cwd(), a))
+    const B = await readDesignMd(resolve(process.cwd(), b))
+    const colors = diffMaps(flattenColors(A.data), flattenColors(B.data))
+    const radii = diffMaps(A.data.radius ?? {}, B.data.radius ?? {})
+
+    if (flags.format === 'json') {
+      console.log(JSON.stringify({ colors, radii }, null, 2))
+      return
+    }
+
+    function printSection(title, d) {
+      console.log(kleur.bold(`\n${title}`))
+      const empty = !Object.keys(d.added).length && !Object.keys(d.removed).length && !Object.keys(d.modified).length
+      if (empty) {
+        console.log(kleur.dim('  no changes'))
+        return
+      }
+      for (const [k, v] of Object.entries(d.added)) console.log(kleur.green(`  + ${k}`) + kleur.dim(` = ${v}`))
+      for (const [k, v] of Object.entries(d.removed)) console.log(kleur.red(`  − ${k}`) + kleur.dim(` (was ${v})`))
+      for (const [k, v] of Object.entries(d.modified))
+        console.log(kleur.yellow(`  ~ ${k}`) + kleur.dim(` ${v.from} → `) + kleur.cyan(v.to))
+    }
+
+    printSection('Colors', colors)
+    printSection('Radii', radii)
+  },
+}

package/src/commands/export.mjs

@@ -0,0 +1,91 @@
+import { resolve } from 'node:path'
+import { readDesignMd } from '../lib/parse.mjs'
+
+const FORMATS = new Set(['tailwind', 'css', 'dtcg', 'figma'])
+
+function parseFlags(args) {
+  const flags = { to: null }
+  const positional = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a.startsWith('--to=')) flags.to = a.slice(5)
+    else if (a === '--to') flags.to = args[++i]
+    else positional.push(a)
+  }
+  return { flags, positional }
+}
+
+function toCss(data) {
+  const c = data.colors ?? {}
+  const r = data.radius ?? {}
+  const lines = [':root {']
+  for (const [k, v] of Object.entries(c)) lines.push(`  --color-${k}: ${v};`)
+  for (const [k, v] of Object.entries(r)) lines.push(`  --radius-${k}: ${typeof v === 'number' ? `${v}px` : v};`)
+  lines.push('}')
+  return lines.join('\n')
+}
+
+function toTailwind(data) {
+  const c = data.colors ?? {}
+  const r = data.radius ?? {}
+  const out = {
+    theme: {
+      extend: {
+        colors: Object.fromEntries(Object.entries(c).map(([k, v]) => [k, String(v)])),
+        borderRadius: Object.fromEntries(
+          Object.entries(r).map(([k, v]) => [k, typeof v === 'number' ? `${v}px` : v]),
+        ),
+      },
+    },
+  }
+  return `module.exports = ${JSON.stringify(out, null, 2)}`
+}
+
+function toDtcg(data) {
+  const c = data.colors ?? {}
+  const r = data.radius ?? {}
+  const out = {
+    $schema: 'https://design-tokens.github.io/community-group/format/',
+    color: Object.fromEntries(Object.entries(c).map(([k, v]) => [k, { $value: String(v), $type: 'color' }])),
+    radius: Object.fromEntries(
+      Object.entries(r).map(([k, v]) => [
+        k,
+        { $value: typeof v === 'number' ? `${v}px` : v, $type: 'dimension' },
+      ]),
+    ),
+  }
+  return JSON.stringify(out, null, 2)
+}
+
+function toFigma(data) {
+  const c = data.colors ?? {}
+  const out = {
+    variables: Object.entries(c).map(([k, v]) => ({
+      name: k,
+      type: 'COLOR',
+      value: String(v),
+      description: `${data.name} · ${k}`,
+    })),
+  }
+  return JSON.stringify(out, null, 2)
+}
+
+const RENDERERS = { tailwind: toTailwind, css: toCss, dtcg: toDtcg, figma: toFigma }
+
+export const exportTokens = {
+  usage: 'export <file> --to <tailwind|css|dtcg|figma>',
+  async run(args) {
+    const { flags, positional } = parseFlags(args)
+    const file = positional[0]
+    if (!file || !flags.to) {
+      console.error('Usage: design-md export <file> --to <tailwind|css|dtcg|figma>')
+      process.exit(2)
+    }
+    if (!FORMATS.has(flags.to)) {
+      console.error(`Unknown format "${flags.to}". Choose: ${[...FORMATS].join(', ')}`)
+      process.exit(2)
+    }
+    const { data } = await readDesignMd(resolve(process.cwd(), file))
+    process.stdout.write(RENDERERS[flags.to](data) + '\n')
+  },
+}

package/src/commands/extract.mjs

@@ -0,0 +1,34 @@
+import kleur from 'kleur'
+import { BASE } from '../lib/api.mjs'
+
+function parseFlags(args) {
+  const flags = { out: null, tokenOnly: false }
+  const positional = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '-o' || a === '--out') flags.out = args[++i]
+    else if (a === '--token-only') flags.tokenOnly = true
+    else positional.push(a)
+  }
+  return { flags, positional }
+}
+
+export const extract = {
+  usage: 'extract <url> [-o <path>] [--token-only]',
+  async run(args) {
+    const { flags, positional } = parseFlags(args)
+    const url = positional[0]
+    if (!url) {
+      console.error('Usage: design-md extract <url>')
+      process.exit(2)
+    }
+    console.log(kleur.dim(`→ Submitting extraction for ${url}…`))
+    console.log(kleur.dim(`  AI extraction is processed by webdesignhot — opening the create flow.`))
+    console.log()
+    const target = `${BASE}/design-md/create?url=${encodeURIComponent(url)}${flags.tokenOnly ? '&tokens=1' : ''}`
+    console.log(`  ${kleur.cyan(target)}`)
+    console.log()
+    console.log(kleur.yellow('Tip: extract requires a webdesignhot session — visit the URL above to authorize.'))
+    console.log(kleur.dim('     The CLI will gain a direct extraction endpoint in v0.2.'))
+  },
+}

package/src/commands/help.mjs

@@ -0,0 +1,35 @@
+import kleur from 'kleur'
+
+const TEXT = `
+${kleur.bold('design-md')} — drop any DESIGN.md into your repo in one command
+
+${kleur.dim('USAGE')}
+  design-md <command> [args]
+
+${kleur.dim('COMMANDS')}
+  add <slug>             Write the design's DESIGN.md to your CWD
+  list                   Print the full catalog (slug · name · tags)
+  category [name]        Browse categories — without a name lists all
+  init                   Interactive picker (default if no command)
+  lint <file>            Validate a DESIGN.md for spec compliance
+  diff <a> <b>           Token-level diff between two DESIGN.md files
+  export <file> --to <f> Convert tokens to tailwind|css|dtcg|figma
+  extract <url>          Extract a draft DESIGN.md from any production URL
+  theme <slug> --dark    Compute a dark-mode counterpart of a light design
+  preview <slug>         Open the directory detail page in your browser
+  help                   This screen
+
+${kleur.dim('EXAMPLES')}
+  $ design-md add linear              ${kleur.dim('# writes DESIGN.md to CWD')}
+  $ design-md list | grep editorial
+  $ design-md export DESIGN.md --to tailwind > tailwind.theme.js
+  $ design-md diff DESIGN.md old.md
+
+${kleur.dim('Spec:')}    https://github.com/google-labs-code/design.md
+${kleur.dim('Catalog:')} https://www.webdesignhot.com/design-md
+`
+
+export const help = {
+  run: async () => process.stdout.write(TEXT),
+  usage: 'help',
+}

package/src/commands/init.mjs

@@ -0,0 +1,63 @@
+import * as p from '@clack/prompts'
+import { writeFile, access } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import kleur from 'kleur'
+import { fetchCatalog, fetchRawMd } from '../lib/api.mjs'
+
+export const init = {
+  usage: 'init',
+  async run() {
+    p.intro(kleur.bold('design-md init'))
+
+    const s = p.spinner()
+    s.start('Loading catalog…')
+    const catalog = await fetchCatalog()
+    s.stop(`${catalog.count} designs available`)
+
+    const slug = await p.select({
+      message: 'Pick a design',
+      maxItems: 12,
+      options: catalog.entries.map((e) => ({
+        value: e.slug,
+        label: `${e.featured ? '★ ' : '  '}${e.name}`,
+        hint: (e.tags ?? []).slice(0, 4).join(' · '),
+      })),
+    })
+    if (p.isCancel(slug)) {
+      p.cancel('Cancelled.')
+      process.exit(0)
+    }
+
+    const out = await p.text({
+      message: 'Write to',
+      placeholder: 'DESIGN.md',
+      defaultValue: 'DESIGN.md',
+    })
+    if (p.isCancel(out)) {
+      p.cancel('Cancelled.')
+      process.exit(0)
+    }
+
+    const target = resolve(process.cwd(), out || 'DESIGN.md')
+    let exists = false
+    try {
+      await access(target)
+      exists = true
+    } catch {}
+    if (exists) {
+      const overwrite = await p.confirm({ message: `${out} exists — overwrite?`, initialValue: false })
+      if (p.isCancel(overwrite) || !overwrite) {
+        p.cancel('Cancelled.')
+        process.exit(0)
+      }
+    }
+
+    const s2 = p.spinner()
+    s2.start(`Fetching ${slug}…`)
+    const md = await fetchRawMd(slug)
+    await writeFile(target, md, 'utf8')
+    s2.stop(`Wrote ${out} (${(md.length / 1024).toFixed(1)} KB)`)
+
+    p.outro(kleur.green(`✓ ${slug} installed.`) + kleur.dim(' Point your AI agent at DESIGN.md and you are done.'))
+  },
+}

package/src/commands/lint.mjs

@@ -0,0 +1,58 @@
+import { resolve } from 'node:path'
+import kleur from 'kleur'
+import { readDesignMd } from '../lib/parse.mjs'
+
+const REQUIRED = ['name', 'tagline', 'spec', 'colors', 'typography']
+const SECTIONS_RE = /^##\s+(.+)$/gm
+
+function parseFlags(args) {
+  const flags = { format: 'text' }
+  const positional = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a.startsWith('--format=')) flags.format = a.slice(9)
+    else if (a === '--format') flags.format = args[++i]
+    else positional.push(a)
+  }
+  return { flags, positional }
+}
+
+export const lint = {
+  usage: 'lint <file> [--format=text|json]',
+  async run(args) {
+    const { flags, positional } = parseFlags(args)
+    const file = positional[0]
+    if (!file) {
+      console.error('Usage: design-md lint <file>')
+      process.exit(2)
+    }
+    const findings = []
+    const { data, body } = await readDesignMd(resolve(process.cwd(), file))
+
+    for (const k of REQUIRED) {
+      if (data[k] == null) findings.push({ level: 'error', code: 'missing-field', field: k, msg: `Required field "${k}" is missing.` })
+    }
+    if (data.colors && !data.colors.bg) findings.push({ level: 'warn', code: 'missing-color-role', msg: 'colors.bg is recommended.' })
+    if (data.colors && !data.colors.text) findings.push({ level: 'warn', code: 'missing-color-role', msg: 'colors.text is recommended.' })
+    if (data.colors && !data.colors.brand) findings.push({ level: 'warn', code: 'missing-color-role', msg: 'colors.brand is recommended.' })
+
+    const sections = [...body.matchAll(SECTIONS_RE)].map((m) => m[1].trim())
+    if (sections.length < 3) findings.push({ level: 'warn', code: 'few-sections', msg: `Only ${sections.length} ## sections — recommend 5+.` })
+
+    if (flags.format === 'json') {
+      console.log(JSON.stringify({ file, findings, sections }, null, 2))
+      process.exit(findings.some((f) => f.level === 'error') ? 1 : 0)
+    }
+
+    if (!findings.length) {
+      console.log(kleur.green('✓ No issues found.'))
+      console.log(kleur.dim(`  ${sections.length} sections · ${Object.keys(data.colors ?? {}).length} colors · ${Object.keys(data.typography ?? {}).length} type roles`))
+      return
+    }
+    for (const f of findings) {
+      const tag = f.level === 'error' ? kleur.red('✗ error') : kleur.yellow('⚠ warn ')
+      console.log(`${tag} ${kleur.dim(f.code)} ${f.msg}`)
+    }
+    if (findings.some((f) => f.level === 'error')) process.exit(1)
+  },
+}

package/src/commands/list.mjs

@@ -0,0 +1,24 @@
+import kleur from 'kleur'
+import { fetchCatalog } from '../lib/api.mjs'
+
+export const list = {
+  usage: 'list',
+  async run() {
+    const catalog = await fetchCatalog()
+    const rows = catalog.entries.map((e) => ({
+      slug: e.slug,
+      name: e.name,
+      tags: (e.tags ?? []).slice(0, 4).join(' '),
+      featured: e.featured ? '★' : ' ',
+    }))
+    const slugW = Math.max(...rows.map((r) => r.slug.length), 4)
+    const nameW = Math.max(...rows.map((r) => r.name.length), 4)
+    for (const r of rows) {
+      const fav = r.featured === '★' ? kleur.yellow('★') : ' '
+      console.log(
+        `${fav} ${kleur.cyan(r.slug.padEnd(slugW))}  ${r.name.padEnd(nameW)}  ${kleur.dim(r.tags)}`,
+      )
+    }
+    console.log(kleur.dim(`\n${catalog.count} designs`))
+  },
+}

package/src/commands/preview.mjs

@@ -0,0 +1,31 @@
+import { execFile } from 'node:child_process'
+import kleur from 'kleur'
+import { BASE } from '../lib/api.mjs'
+
+function opener() {
+  if (process.platform === 'darwin') return ['open', []]
+  if (process.platform === 'win32') return ['cmd', ['/c', 'start', '']]
+  return ['xdg-open', []]
+}
+
+const SAFE_SLUG = /^[a-z0-9][a-z0-9-]{0,80}$/
+
+export const preview = {
+  usage: 'preview <slug>',
+  async run(args) {
+    const slug = args[0]
+    if (!slug || !SAFE_SLUG.test(slug)) {
+      console.error('Usage: design-md preview <slug>  (slug = lowercase, hyphenated)')
+      process.exit(2)
+    }
+    const url = `${BASE}/design-md/${slug}/`
+    console.log(kleur.dim(`→ Opening ${url}`))
+    const [bin, head] = opener()
+    execFile(bin, [...head, url], (err) => {
+      if (err) {
+        console.error(kleur.red('Could not launch browser. Open manually:'))
+        console.log(`  ${url}`)
+      }
+    })
+  },
+}

package/src/commands/theme.mjs

@@ -0,0 +1,59 @@
+import kleur from 'kleur'
+import { fetchRawMd } from '../lib/api.mjs'
+import { parseDesignMd } from '../lib/parse.mjs'
+
+function parseFlags(args) {
+  const flags = { dark: false, light: false }
+  const positional = []
+  for (const a of args) {
+    if (a === '--dark') flags.dark = true
+    else if (a === '--light') flags.light = true
+    else positional.push(a)
+  }
+  return { flags, positional }
+}
+
+function hexToRgb(h) {
+  const m = h.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i)
+  if (!m) return null
+  return [parseInt(m[1], 16), parseInt(m[2], 16), parseInt(m[3], 16)]
+}
+function rgbToHex(r, g, b) {
+  const c = (n) => Math.round(Math.max(0, Math.min(255, n))).toString(16).padStart(2, '0')
+  return `#${c(r)}${c(g)}${c(b)}`
+}
+function invertLuma(hex) {
+  const rgb = hexToRgb(hex)
+  if (!rgb) return hex
+  const [r, g, b] = rgb
+  const inv = (n) => 255 - n
+  return rgbToHex(inv(r), inv(g), inv(b))
+}
+
+export const theme = {
+  usage: 'theme <slug> [--dark|--light]',
+  async run(args) {
+    const { flags, positional } = parseFlags(args)
+    const slug = positional[0]
+    if (!slug) {
+      console.error('Usage: design-md theme <slug> [--dark|--light]')
+      process.exit(2)
+    }
+    if (!flags.dark && !flags.light) flags.dark = true
+
+    const raw = await fetchRawMd(slug)
+    const { data } = parseDesignMd(raw)
+    const c = data.colors ?? {}
+    const flipped = {}
+    for (const [k, v] of Object.entries(c)) {
+      if (typeof v === 'string' && v.startsWith('#')) flipped[k] = invertLuma(v)
+      else flipped[k] = v
+    }
+    console.log(kleur.dim(`# ${data.name} · ${flags.dark ? 'dark' : 'light'} variant (computed)`))
+    console.log()
+    console.log('colors:')
+    for (const [k, v] of Object.entries(flipped)) console.log(`  ${k}: '${v}'`)
+    console.log()
+    console.log(kleur.yellow('Note: this is a naive luminance flip. Refine the result by hand for production.'))
+  },
+}

package/src/index.mjs

@@ -0,0 +1,45 @@
+/**
+ * design-md CLI router.
+ *
+ * Dispatches the first positional arg to a command module under
+ * `./commands/`. Each command exports `run(args)` and a `usage` string.
+ */
+import { add } from './commands/add.mjs'
+import { list } from './commands/list.mjs'
+import { category } from './commands/category.mjs'
+import { init } from './commands/init.mjs'
+import { lint } from './commands/lint.mjs'
+import { diff } from './commands/diff.mjs'
+import { exportTokens } from './commands/export.mjs'
+import { extract } from './commands/extract.mjs'
+import { theme } from './commands/theme.mjs'
+import { preview } from './commands/preview.mjs'
+import { help } from './commands/help.mjs'
+
+const COMMANDS = {
+  add,
+  list,
+  category,
+  init,
+  lint,
+  diff,
+  export: exportTokens,
+  extract,
+  theme,
+  preview,
+  help,
+  '--help': help,
+  '-h': help,
+}
+
+export async function run(argv) {
+  const [cmd, ...rest] = argv
+  if (!cmd) return init.run(rest)
+  const handler = COMMANDS[cmd]
+  if (!handler) {
+    console.error(`Unknown command: ${cmd}`)
+    console.error(`Run \`design-md help\` to see all commands.`)
+    process.exit(2)
+  }
+  return handler.run(rest)
+}

package/src/lib/api.mjs

@@ -0,0 +1,30 @@
+/**
+ * API client — fetches catalog and per-slug raw markdown from
+ * webdesignhot.com. The endpoints are prerendered + immutable so
+ * latency is essentially the CDN's.
+ */
+const DEFAULT_BASE = 'https://www.webdesignhot.com'
+export const BASE = process.env.DESIGN_MD_BASE || DEFAULT_BASE
+
+let _catalog = null
+
+export async function fetchCatalog() {
+  if (_catalog) return _catalog
+  const res = await fetch(`${BASE}/api/design-md/index.json`)
+  if (!res.ok) throw new Error(`Catalog fetch failed: ${res.status}`)
+  _catalog = await res.json()
+  return _catalog
+}
+
+export async function fetchRawMd(slug) {
+  const res = await fetch(`${BASE}/api/design-md/${slug}.md`)
+  if (res.status === 404) throw new Error(`No design with slug "${slug}". Run \`design-md list\` to see available designs.`)
+  if (!res.ok) throw new Error(`Fetch failed: ${res.status}`)
+  return res.text()
+}
+
+export async function fetchExport(slug, format) {
+  const res = await fetch(`${BASE}/api/design-md/${slug}/export/${format}`)
+  if (!res.ok) throw new Error(`Export ${format} failed: ${res.status}`)
+  return res.text()
+}

package/src/lib/parse.mjs

@@ -0,0 +1,29 @@
+/**
+ * Frontmatter parsing helpers. The DESIGN.md/v1 spec puts all tokens
+ * in the YAML head; the markdown body is human prose. We use the
+ * `yaml` package for round-trip-safe parsing.
+ */
+import YAML from 'yaml'
+import { readFile } from 'node:fs/promises'
+
+const FM_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/
+
+export function parseDesignMd(source) {
+  const m = source.match(FM_RE)
+  if (!m) throw new Error('No frontmatter block found (expected leading `---`).')
+  const data = YAML.parse(m[1]) ?? {}
+  const body = m[2] ?? ''
+  return { data, body, raw: source }
+}
+
+export async function readDesignMd(filePath) {
+  const text = await readFile(filePath, 'utf8')
+  return parseDesignMd(text)
+}
+
+export function flattenColors(data) {
+  const out = {}
+  if (!data?.colors) return out
+  for (const [k, v] of Object.entries(data.colors)) out[k] = String(v)
+  return out
+}