@webdesignhot/design-md 0.2.0 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 > 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
+$ npx @webdesignhot/design-md add stripe
 ✓ Wrote DESIGN.md (8.2 KB · linear)
 
 $ npx @webdesignhot/design-md list
@@ -31,7 +31,7 @@ npx @webdesignhot/design-md <command>
 # global
 npm i -g @webdesignhot/design-md
 # the binary is `design-md` regardless of scope:
-design-md add linear
+design-md add stripe
 ```
 
 Requires Node 18+.
@@ -58,14 +58,21 @@ lint <file> [--format=text|json]
 diff <a> <b> [--format=text|json]
   Token-level diff between two DESIGN.md files.
 
-export <file> --to <tailwind|css|dtcg|figma> [--tailwind-version <v3|v4>]
+export <file> --to <tailwind|css-tailwind|json-tailwind|css|dtcg|figma> [--tailwind-version <v3|v4>]
   Convert tokens to one of:
-    tailwind   — @theme {} CSS block (Tailwind v4 default).
-                 Pass --tailwind-version v3 for the legacy
-                 module.exports = { theme: { extend: { ... } } } shape.
-    css        — :root { --color-bg, --radius-card, … }
-    dtcg       — W3C Design Tokens Community Group JSON
-    figma      — Figma Variables import format
+    tailwind         — @theme {} CSS block (Tailwind v4 default).
+                       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).
+    json-tailwind    — v3 module.exports JSON (alias of
+                       `--to tailwind --tailwind-version v3`, same
+                       Google CLI compat reason as above).
+    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.
@@ -78,6 +85,13 @@ import <url>
 theme <slug> [--dark|--light]
   Compute a dark/light variant of any design.
 
+submit <file> [--dry-run]
+  Submit your DESIGN.md as a PR to the public catalog at
+  github.com/WebDesignHot/design-md. Auto-forks via the `gh` CLI,
+  syncs the fork with upstream main, branches, commits, pushes,
+  and opens a PR with templated body. Requires `gh` installed and
+  authed (https://cli.github.com).
+
 preview <slug>
   Open the directory detail page in your browser.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdesignhot/design-md",
-  "version": "0.2.0",
+  "version": "0.4.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",

package/src/commands/export.mjs

@@ -1,7 +1,17 @@
 import { resolve } from 'node:path'
 import { readDesignMd } from '../lib/parse.mjs'
 
-const FORMATS = new Set(['tailwind', 'css', 'dtcg', 'figma'])
+// 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.
+//
+//   `--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 --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'])
 
 function parseFlags(args) {
@@ -111,12 +121,12 @@ function toFigma(data) {
 const RENDERERS = { tailwind: toTailwind, css: toCss, dtcg: toDtcg, figma: toFigma }
 
 export const exportTokens = {
-  usage: 'export <file> --to <tailwind|css|dtcg|figma> [--tailwind-version v3|v4]',
+  usage: 'export <file> --to <tailwind|css-tailwind|json-tailwind|css|dtcg|figma> [--tailwind-version v3|v4]',
   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>')
+      console.error('Usage: design-md export <file> --to <tailwind|css-tailwind|json-tailwind|css|dtcg|figma>')
       process.exit(2)
     }
     if (!FORMATS.has(flags.to)) {
@@ -128,9 +138,17 @@ export const exportTokens = {
       process.exit(2)
     }
     const { data } = await readDesignMd(resolve(process.cwd(), file))
-    const out = flags.to === 'tailwind'
-      ? toTailwind(data, flags.tailwindVersion)
-      : RENDERERS[flags.to](data)
+
+    let out
+    if (flags.to === 'tailwind') {
+      out = toTailwind(data, flags.tailwindVersion)
+    } else if (flags.to === 'css-tailwind') {
+      out = toTailwindV4(data)
+    } else if (flags.to === 'json-tailwind') {
+      out = toTailwindV3(data)
+    } else {
+      out = RENDERERS[flags.to](data)
+    }
     process.stdout.write(out + '\n')
   },
 }

package/src/commands/help.mjs

@@ -13,21 +13,28 @@ ${kleur.dim('COMMANDS')}
   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
-                            tailwind defaults to v4 (--tailwind-version v3 for legacy)
+  export <file> --to <f>    Convert tokens — formats:
+                              tailwind         v4 CSS @theme (default; --tailwind-version v3 for legacy)
+                              css-tailwind     v4 CSS @theme (Google CLI alias)
+                              json-tailwind    v3 JSON theme.extend (Google CLI alias)
+                              css              :root { --color-* / --radius-* }
+                              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
   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
   help                      This screen
 
 ${kleur.dim('EXAMPLES')}
-  $ design-md add linear              ${kleur.dim('# writes DESIGN.md to CWD')}
+  $ design-md add stripe              ${kleur.dim('# writes DESIGN.md to CWD')}
   $ design-md list | grep editorial
   $ design-md export DESIGN.md --to tailwind > theme.css
   $ design-md export DESIGN.md --to tailwind --tailwind-version v3 > tailwind.config.js
   $ design-md import https://stripe.com
   $ design-md diff DESIGN.md old.md
+  $ design-md submit ./DESIGN.md      ${kleur.dim('# auto-fork + open PR via `gh` CLI')}
 
 ${kleur.dim('Spec:')}    https://www.webdesignhot.com/design.md/spec ${kleur.dim('(webdesignhot/0.1)')}
 ${kleur.dim('Catalog:')} https://www.webdesignhot.com/design.md/

package/src/commands/submit.mjs

@@ -0,0 +1,240 @@
+/**
+ * Submit a DESIGN.md to the public catalog at github.com/WebDesignHot/design-md.
+ *
+ * Flow:
+ *   1. Validate file (lint).
+ *   2. Resolve slug from frontmatter (or prompt).
+ *   3. Verify `gh` CLI is installed and authed.
+ *   4. Fork WebDesignHot/design-md to user's account (idempotent).
+ *   5. Clone fork to a temp dir.
+ *   6. Copy file to design-md/<slug>.md.
+ *   7. Branch + commit + push.
+ *   8. Open a PR against WebDesignHot/design-md:main with a templated body.
+ *   9. Print the PR URL.
+ *
+ * Aborts gracefully if `gh` is missing or unauthed; falls back to printing
+ * the manual-PR instructions (file path + raw upload guide).
+ */
+import { resolve, join, basename } from 'node:path'
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { execSync, spawnSync } from 'node:child_process'
+import kleur from 'kleur'
+import * as p from '@clack/prompts'
+import { readDesignMd } from '../lib/parse.mjs'
+
+const UPSTREAM = 'WebDesignHot/design-md'
+const UPSTREAM_BRANCH = 'main'
+
+function parseFlags(args) {
+  const flags = { dryRun: false }
+  const positional = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--dry-run') flags.dryRun = true
+    else positional.push(a)
+  }
+  return { flags, positional }
+}
+
+function which(cmd) {
+  const r = spawnSync('which', [cmd], { encoding: 'utf8' })
+  return r.status === 0 ? r.stdout.trim() : null
+}
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts })
+  if (r.status !== 0) {
+    throw new Error(`${cmd} ${args.join(' ')} failed:\n${r.stderr || r.stdout || '(no output)'}`)
+  }
+  return r.stdout?.trim() ?? ''
+}
+
+function deriveSlug(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/--+/g, '-')
+}
+
+async function exists(p) {
+  try {
+    await stat(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export const submit = {
+  usage: 'submit <file> [--dry-run]',
+  async run(args) {
+    const { flags, positional } = parseFlags(args)
+    const file = positional[0]
+    if (!file) {
+      console.error('Usage: design-md submit <file>')
+      console.error('  Submits your DESIGN.md as a PR to github.com/WebDesignHot/design-md.')
+      process.exit(2)
+    }
+
+    const filePath = resolve(process.cwd(), file)
+    if (!(await exists(filePath))) {
+      console.error(kleur.red(`✗ File not found: ${filePath}`))
+      process.exit(1)
+    }
+
+    // 1. Lint inline (cheap re-check)
+    const { data } = await readDesignMd(filePath)
+    const errors = []
+    if (!data.name) errors.push('frontmatter.name is required')
+    if (!data.spec) errors.push('frontmatter.spec is required (e.g. webdesignhot/0.1)')
+    if (!data.source_url) errors.push('frontmatter.source_url is required')
+    if (!data.colors?.bg || !data.colors?.text || !data.colors?.brand) {
+      errors.push('frontmatter.colors must include bg, text, and brand')
+    }
+    if (errors.length) {
+      console.error(kleur.red('✗ File has issues that must be fixed before submitting:'))
+      for (const e of errors) console.error(`  · ${e}`)
+      console.error(kleur.dim('  Run `design-md lint <file>` for full diagnostics.'))
+      process.exit(1)
+    }
+
+    // 2. Resolve slug
+    let slug = data.slug
+    if (!slug) {
+      const fromFile = basename(filePath, '.md')
+      slug = fromFile === 'DESIGN' ? deriveSlug(data.name) : fromFile
+    }
+    if (!slug || !/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+      console.error(kleur.red(`✗ Invalid slug "${slug}" — must be kebab-case lowercase.`))
+      process.exit(1)
+    }
+
+    console.log(kleur.dim(`→ Submitting ${kleur.bold(data.name)} as slug "${kleur.bold(slug)}"`))
+
+    // 3. Check `gh` CLI
+    const ghPath = which('gh')
+    if (!ghPath) {
+      console.error()
+      console.error(kleur.yellow('⚠ The GitHub CLI (`gh`) is not installed.'))
+      console.error()
+      console.error('  This command auto-forks + opens a PR for you. Install with:')
+      console.error(kleur.cyan('    brew install gh        # macOS'))
+      console.error(kleur.cyan('    winget install GitHub.cli   # Windows'))
+      console.error(kleur.cyan('    https://cli.github.com — other platforms'))
+      console.error()
+      console.error('  Or submit manually:')
+      console.error(`    1. Fork ${kleur.cyan(`https://github.com/${UPSTREAM}`)}`)
+      console.error(`    2. Add your file at ${kleur.cyan(`design-md/${slug}.md`)}`)
+      console.error('    3. Open a PR against `main`.')
+      process.exit(1)
+    }
+
+    // Verify gh is authed
+    try {
+      run('gh', ['auth', 'status'], { stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch {
+      console.error(kleur.yellow('⚠ `gh` is installed but not authenticated.'))
+      console.error(`  Run: ${kleur.cyan('gh auth login')}`)
+      process.exit(1)
+    }
+
+    if (flags.dryRun) {
+      console.log(kleur.green(`✓ Dry-run passed. Would submit ${data.name} as ${slug}.`))
+      console.log(kleur.dim(`  File: ${filePath}`))
+      console.log(kleur.dim(`  Target: ${UPSTREAM}/design-md/${slug}.md`))
+      return
+    }
+
+    // 4. Fork (idempotent — gh handles already-forked case)
+    const ghUser = run('gh', ['api', 'user', '-q', '.login'])
+    console.log(kleur.dim(`→ Forking ${UPSTREAM} to ${ghUser}/design-md (no-op if already forked)`))
+    try {
+      run('gh', ['repo', 'fork', UPSTREAM, '--clone=false'], { stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch {
+      // gh fork prints "already exists" to stderr but exits 0 sometimes; treat as ok
+    }
+
+    // 5. Clone fork to a temp dir
+    const work = join(tmpdir(), `design-md-submit-${slug}-${Date.now()}`)
+    await mkdir(work, { recursive: true })
+    console.log(kleur.dim(`→ Cloning fork to ${work}`))
+    run('gh', ['repo', 'clone', `${ghUser}/design-md`, work, '--', '--depth=1'])
+
+    // Sync fork with upstream's main (in case fork is stale)
+    try {
+      run('git', ['-C', work, 'remote', 'add', 'upstream', `https://github.com/${UPSTREAM}.git`])
+      run('git', ['-C', work, 'fetch', '--depth=1', 'upstream', UPSTREAM_BRANCH])
+      run('git', ['-C', work, 'reset', '--hard', `upstream/${UPSTREAM_BRANCH}`])
+    } catch (err) {
+      console.error(kleur.yellow(`⚠ Could not sync fork with upstream: ${err.message}`))
+      console.error(kleur.dim('  Continuing with current fork state.'))
+    }
+
+    // 6. Copy file
+    const targetPath = join(work, 'design-md', `${slug}.md`)
+    if (await exists(targetPath)) {
+      const overwrite = await p.confirm({
+        message: `design-md/${slug}.md already exists in the catalog. Open a PR to update it?`,
+        initialValue: false,
+      })
+      if (p.isCancel(overwrite) || !overwrite) {
+        console.log(kleur.yellow('Aborted.'))
+        process.exit(0)
+      }
+    }
+    const fileContent = await readFile(filePath, 'utf8')
+    await writeFile(targetPath, fileContent)
+
+    // 7. Branch + commit + push
+    const branch = `submit/${slug}-${Date.now().toString(36).slice(-4)}`
+    console.log(kleur.dim(`→ Branch: ${branch}`))
+    run('git', ['-C', work, 'checkout', '-b', branch])
+    run('git', ['-C', work, 'add', `design-md/${slug}.md`])
+    const commitMsg = `submit: ${data.name} (${slug})\n\nFrom: ${data.source_url ?? 'unspecified'}`
+    run('git', ['-C', work, '-c', 'commit.gpgsign=false', 'commit', '-m', commitMsg])
+    console.log(kleur.dim(`→ Pushing to ${ghUser}/design-md:${branch}`))
+    run('git', ['-C', work, 'push', '-u', 'origin', branch])
+
+    // 8. Open PR
+    const prTitle = `submit: ${data.name}`
+    const prBody = `## New entry: ${data.name}
+
+**Slug**: \`${slug}\`
+**Source URL**: ${data.source_url ?? '(not provided)'}
+**Categories**: ${(data.categories ?? []).join(', ') || '(none)'}
+**Tags**: ${(data.tags ?? []).join(', ') || '(none)'}
+
+${data.tagline ? `> ${data.tagline}\n` : ''}
+${data.description ?? ''}
+
+---
+
+Submitted via \`design-md submit\`.
+
+### Reviewer checklist
+- [ ] \`design-md lint\` passes
+- [ ] All 15 sections present in body
+- [ ] Tokens reflect actual production site
+- [ ] Lineage block names real influences with URLs
+- [ ] Categories + tags use existing taxonomy
+`
+    console.log(kleur.dim('→ Opening PR'))
+    const prUrl = run('gh', [
+      'pr', 'create',
+      '--repo', UPSTREAM,
+      '--base', UPSTREAM_BRANCH,
+      '--head', `${ghUser}:${branch}`,
+      '--title', prTitle,
+      '--body', prBody,
+    ])
+
+    // 9. Done
+    console.log()
+    console.log(kleur.green('✓ Submitted.'))
+    console.log(`  ${kleur.cyan(prUrl)}`)
+    console.log()
+    console.log(kleur.dim('Your design will appear on webdesignhot.com once we review and merge.'))
+  },
+}

package/src/index.mjs

@@ -14,6 +14,7 @@ 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 { submit } from './commands/submit.mjs'
 import { help } from './commands/help.mjs'
 
 const COMMANDS = {
@@ -28,6 +29,7 @@ const COMMANDS = {
   import: extract, // alias — name aligned with Google Labs PR #40
   theme,
   preview,
+  submit,
   help,
   '--help': help,
   '-h': help,