@webdesignhot/design-md 0.4.0 → 0.5.1

package/README.md

@@ -64,12 +64,9 @@ export <file> --to <tailwind|css-tailwind|json-tailwind|css|dtcg|figma> [--tailw
                        Pass --tailwind-version v3 for the legacy
                        module.exports = { theme: { extend: { ... } } } shape.
     css-tailwind     — v4 @theme {} CSS block (alias of `--to tailwind`,
-                       matches @google/design.md's `--format css-tailwind`
-                       naming from PR #64 so commands transfer between
-                       the two CLIs without re-learning flag conventions).
+                       version-explicit naming for clarity in scripts).
     json-tailwind    — v3 module.exports JSON (alias of
-                       `--to tailwind --tailwind-version v3`, same
-                       Google CLI compat reason as above).
+                       `--to tailwind --tailwind-version v3`).
     css              — :root { --color-bg, --radius-card, … }
     dtcg             — W3C Design Tokens Community Group JSON
     figma            — Figma Variables import format
@@ -79,8 +76,8 @@ extract <url> [-o <path>] [--token-only]
   (Requires a webdesignhot session — opens the browser flow.)
 
 import <url>
-  Alias of `extract`. Naming aligned with Google Labs DESIGN.md tooling
-  so the same verb works whichever CLI you've internalised.
+  Alias of `extract`. Common `import` verb so the muscle memory carries
+  over from other dev tools.
 
 theme <slug> [--dark|--light]
   Compute a dark/light variant of any design.

package/package.json

@@ -1,14 +1,23 @@
 {
   "name": "@webdesignhot/design-md",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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"],
+  "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"
+    "url": "git+https://github.com/WebDesignHot/design-md.git"
   },
   "bin": {
     "design-md": "bin/design-md.mjs"
@@ -23,6 +32,9 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "prepublishOnly": "node -e \"const p=require('./package.json');const e=require('child_process').execSync;let r='0.0.0';try{r=e('npm view '+p.name+' version 2>/dev/null').toString().trim()||'0.0.0'}catch(_){};if(p.version===r){console.error('\\n\\x1b[31m✗ '+p.name+'@'+p.version+' already on npm. Bump version before publishing.\\x1b[0m\\n');process.exit(1)}console.log('→ '+p.name+': '+r+' → '+p.version)\""
+  },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
     "kleur": "^4.1.5",

package/src/commands/add.mjs

@@ -8,8 +8,15 @@ function parseFlags(args) {
   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
+    if (a === '-o' || a === '--out') {
+      const value = args[++i]
+      if (value === undefined || value.startsWith('-')) {
+        console.error(`Usage: design-md add <slug> [-o <path>] [-f]`)
+        console.error(`Error: ${a} requires a <path> value.`)
+        process.exit(2)
+      }
+      flags.out = value
+    } else if (a === '-f' || a === '--force') flags.force = true
     else positional.push(a)
   }
   return { flags, positional }

package/src/commands/diff.mjs

@@ -14,6 +14,19 @@ function parseFlags(args) {
   return { flags, positional }
 }
 
+function flatten(obj, prefix = '') {
+  const out = {}
+  if (!obj || typeof obj !== 'object') return out
+  for (const [k, v] of Object.entries(obj)) {
+    const key = prefix ? `${prefix}.${k}` : k
+    if (v == null) continue
+    if (Array.isArray(v)) out[key] = `[${v.join(', ')}]`
+    else if (typeof v === 'object') Object.assign(out, flatten(v, key))
+    else out[key] = String(v)
+  }
+  return out
+}
+
 function diffMaps(left, right) {
   const result = { added: {}, removed: {}, modified: {} }
   const keys = new Set([...Object.keys(left), ...Object.keys(right)])
@@ -39,10 +52,13 @@ export const diff = {
     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 ?? {})
+    const radii = diffMaps(flatten(A.data.radius ?? {}), flatten(B.data.radius ?? {}))
+    const typography = diffMaps(flatten(A.data.typography ?? {}), flatten(B.data.typography ?? {}))
+    const spacing = diffMaps(flatten(A.data.spacing ?? {}), flatten(B.data.spacing ?? {}))
+    const components = diffMaps(flatten(A.data.components ?? {}), flatten(B.data.components ?? {}))
 
     if (flags.format === 'json') {
-      console.log(JSON.stringify({ colors, radii }, null, 2))
+      console.log(JSON.stringify({ colors, radii, typography, spacing, components }, null, 2))
       return
     }
 
@@ -61,5 +77,8 @@ export const diff = {
 
     printSection('Colors', colors)
     printSection('Radii', radii)
+    printSection('Typography', typography)
+    printSection('Spacing', spacing)
+    printSection('Components', components)
   },
 }

package/src/commands/export.mjs

@@ -1,15 +1,14 @@
 import { resolve } from 'node:path'
 import { readDesignMd } from '../lib/parse.mjs'
 
-// Format aliases align our CLI with @google/design.md's PR #64 naming
-// (`--format css-tailwind` / `--format json-tailwind`) so users can move
-// between the two CLIs without re-learning flag conventions. Both shapes
-// are accepted; the underlying renderer is the same.
+// Format flag accepts `tailwind` (our default v4 CSS) plus the explicit
+// `css-tailwind` / `json-tailwind` aliases so callers can be version-
+// explicit without re-learning conventions. Underlying renderer is the
+// same — only the output shape changes.
 //
-//   `--to tailwind`        → defaults to v4 CSS (was v3 JSON pre-0.2;
-//                             same default we set in 0.2 still applies)
-//   `--to css-tailwind`    → v4 CSS @theme block (Google compat)
-//   `--to json-tailwind`   → v3 JSON theme.extend (Google compat)
+//   `--to tailwind`        → v4 CSS @theme block (default)
+//   `--to css-tailwind`    → v4 CSS @theme block (explicit)
+//   `--to json-tailwind`   → v3 JSON theme.extend
 //   `--to tailwind --tailwind-version v3` → v3 JSON (legacy flag, kept)
 const FORMATS = new Set(['tailwind', 'css-tailwind', 'json-tailwind', 'css', 'dtcg', 'figma'])
 const TAILWIND_VERSIONS = new Set(['v3', 'v4'])
@@ -29,10 +28,12 @@ function parseFlags(args) {
 }
 
 function toCss(data) {
-  const c = data.colors ?? {}
+  const c = flattenColors(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(c)) {
+    if (typeof v === 'string') 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')
@@ -90,11 +91,15 @@ function toTailwind(data, version = 'v4') {
 }
 
 function toDtcg(data) {
-  const c = data.colors ?? {}
+  const c = flattenColors(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' }])),
+    color: Object.fromEntries(
+      Object.entries(c)
+        .filter(([, v]) => typeof v === 'string')
+        .map(([k, v]) => [k, { $value: v, $type: 'color' }]),
+    ),
     radius: Object.fromEntries(
       Object.entries(r).map(([k, v]) => [
         k,
@@ -106,14 +111,16 @@ function toDtcg(data) {
 }
 
 function toFigma(data) {
-  const c = data.colors ?? {}
+  const c = flattenColors(data.colors ?? {})
   const out = {
-    variables: Object.entries(c).map(([k, v]) => ({
-      name: k,
-      type: 'COLOR',
-      value: String(v),
-      description: `${data.name} · ${k}`,
-    })),
+    variables: Object.entries(c)
+      .filter(([, v]) => typeof v === 'string')
+      .map(([k, v]) => ({
+        name: k,
+        type: 'COLOR',
+        value: v,
+        description: `${data.name} · ${k}`,
+      })),
   }
   return JSON.stringify(out, null, 2)
 }

package/src/commands/help.mjs

@@ -21,7 +21,7 @@ ${kleur.dim('COMMANDS')}
                               dtcg             W3C Design Tokens JSON
                               figma            Figma Variables import format
   extract <url>             Extract a draft DESIGN.md from a production URL
-  import <url>              Alias of extract — name aligned with Google Labs
+  import <url>              Alias of extract
   theme <slug> --dark       Compute a dark-mode counterpart of a light design
   preview <slug>            Open the directory detail page in your browser
   submit <file>             Open a PR to add your DESIGN.md to the public catalog

package/src/commands/lint.mjs

@@ -1,10 +1,52 @@
 import { resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
 import kleur from 'kleur'
+import yaml from 'yaml'
 import { readDesignMd } from '../lib/parse.mjs'
 
 const REQUIRED = ['name', 'tagline', 'spec', 'colors', 'typography']
 const SECTIONS_RE = /^##\s+(.+)$/gm
 
+// Pure function: lint raw DESIGN.md content (string).
+// Returns { findings, summary } shaped for programmatic callers
+// (the extract pipeline uses this to surface warnings on drafts).
+export function lintContent(content) {
+  const findings = []
+  let data = {}
+  let body = content
+
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/)
+  if (fmMatch) {
+    try {
+      data = yaml.parse(fmMatch[1]) ?? {}
+      body = fmMatch[2]
+    } catch (err) {
+      findings.push({ level: 'error', code: 'invalid-frontmatter', msg: `YAML parse error: ${err.message}` })
+    }
+  } else {
+    findings.push({ level: 'error', code: 'missing-frontmatter', msg: 'No YAML frontmatter found.' })
+  }
+
+  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) {
+    if (!data.colors.bg) findings.push({ level: 'warn', code: 'missing-color-role', msg: 'colors.bg is recommended.' })
+    if (!data.colors.text) findings.push({ level: 'warn', code: 'missing-color-role', msg: 'colors.text is recommended.' })
+    if (!data.colors.brand && !data.colors.primary) findings.push({ level: 'warn', code: 'missing-primary', msg: 'A primary brand color (colors.brand or colors.primary) 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+.` })
+
+  const summary = {
+    errors: findings.filter((f) => f.level === 'error').length,
+    warnings: findings.filter((f) => f.level === 'warn').length,
+    infos: findings.filter((f) => f.level === 'info').length,
+  }
+  return { findings, summary, sections }
+}
+
 function parseFlags(args) {
   const flags = { format: 'text' }
   const positional = []
@@ -26,22 +68,25 @@ export const lint = {
       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.` })
+    const filePath = resolve(process.cwd(), file)
+    const content = await readFile(filePath, 'utf8')
+    const { findings, summary, sections } = lintContent(content)
+    // Also resolve via readDesignMd for the success-line color/type counts.
+    // readDesignMd → parseDesignMd THROWS on missing/invalid frontmatter —
+    // exactly the malformed inputs lint exists to diagnose. Swallow that here
+    // so findings + summary always print (and --format=json always emits);
+    // the findings already record those problems. Exit code stays driven off
+    // findings below, not this parse.
+    let data = {}
+    try {
+      ;({ data } = await readDesignMd(filePath))
+    } catch {
+      data = {}
     }
-    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)
+      console.log(JSON.stringify({ file, findings, summary, sections }, null, 2))
+      process.exit(summary.errors ? 1 : 0)
     }
 
     if (!findings.length) {
@@ -53,6 +98,6 @@ export const lint = {
       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)
+    if (summary.errors) process.exit(1)
   },
 }

package/src/commands/submit.mjs

@@ -37,9 +37,14 @@ function parseFlags(args) {
   return { flags, positional }
 }
 
-function which(cmd) {
-  const r = spawnSync('which', [cmd], { encoding: 'utf8' })
-  return r.status === 0 ? r.stdout.trim() : null
+// Cross-platform tool detection: probe the tool itself rather than relying on
+// POSIX `which`. Native Windows shells (cmd.exe / PowerShell) have no `which`
+// (they use `where`), so `spawnSync('which', ...)` returns ENOENT and would
+// wrongly report an installed tool as missing. Running `<cmd> --version` and
+// checking exit 0 (with no spawn error) works on macOS, Linux, and Windows.
+function isInstalled(cmd) {
+  const r = spawnSync(cmd, ['--version'], { encoding: 'utf8' })
+  return !r.error && r.status === 0
 }
 
 function run(cmd, args, opts = {}) {
@@ -113,9 +118,8 @@ export const submit = {
 
     console.log(kleur.dim(`→ Submitting ${kleur.bold(data.name)} as slug "${kleur.bold(slug)}"`))
 
-    // 3. Check `gh` CLI
-    const ghPath = which('gh')
-    if (!ghPath) {
+    // 3. Check `gh` CLI (cross-platform; spawn resolves `gh` from PATH later)
+    if (!isInstalled('gh')) {
       console.error()
       console.error(kleur.yellow('⚠ The GitHub CLI (`gh`) is not installed.'))
       console.error()

package/src/commands/theme.mjs

@@ -13,8 +13,21 @@ function parseFlags(args) {
   return { flags, positional }
 }
 
+function flattenColors(c) {
+  // Multi-theme: pick the default theme (or first one) so we invert the
+  // actual token strings rather than copying theme objects verbatim.
+  // Mirrors flattenColors in export.mjs.
+  const values = Object.values(c)
+  if (values.length > 0 && values.every((v) => v && typeof v === 'object')) {
+    return values[0]
+  }
+  return c
+}
+
 function hexToRgb(h) {
-  const m = h.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i)
+  // Expand 3-digit shorthand (e.g. `fff` → `ffffff`) before matching.
+  const expanded = h.replace(/^#?([0-9a-f])([0-9a-f])([0-9a-f])$/i, '#$1$1$2$2$3$3')
+  const m = expanded.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)]
 }
@@ -43,7 +56,7 @@ export const theme = {
 
     const raw = await fetchRawMd(slug)
     const { data } = parseDesignMd(raw)
-    const c = data.colors ?? {}
+    const c = flattenColors(data.colors ?? {})
     const flipped = {}
     for (const [k, v] of Object.entries(c)) {
       if (typeof v === 'string' && v.startsWith('#')) flipped[k] = invertLuma(v)
@@ -52,7 +65,10 @@ export const theme = {
     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}'`)
+    for (const [k, v] of Object.entries(flipped)) {
+      if (typeof v !== 'string') continue
+      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

@@ -26,7 +26,7 @@ const COMMANDS = {
   diff,
   export: exportTokens,
   extract,
-  import: extract, // alias — name aligned with Google Labs PR #40
+  import: extract, // alias — `import` reads natural for "bring this in"
   theme,
   preview,
   submit,