designlang 12.4.0 → 12.7.1

package/commands/extract.md

@@ -0,0 +1,41 @@
+---
+description: Extract the complete design language from a URL — DTCG tokens, Tailwind, Figma vars, motion, voice, components.
+argument-hint: <url> [extra flags…]
+---
+
+Run **designlang** against the user-provided URL and surface the result.
+
+```bash
+npx designlang $ARGUMENTS
+```
+
+If no `$ARGUMENTS` were supplied, ask the user which URL to extract.
+
+Default output goes to `./design-extract-output/`. Once it finishes, read the generated `*-design-language.md` (the AI-optimized markdown) and present a tight summary to the user:
+
+- Primary palette (hex codes)
+- Type families + scale
+- Spacing base + scale
+- WCAG accessibility score
+- Component patterns detected
+- Notable signals (motion feel, material language, brand voice tone)
+
+Then offer follow-ups:
+
+- `/grade <url>` — shareable HTML Design Report Card + SVG badge
+- `/battle <urlA> <urlB>` — head-to-head graded comparison
+- `/remix <url> --as <vocab>` — restyle in another vocabulary
+- `/pack <url>` — bundle every output into one design-system directory
+
+Useful flags the user may pass via `$ARGUMENTS`:
+
+| Flag | Effect |
+|---|---|
+| `--full` | screenshots + responsive + interactions + deep-interact |
+| `--depth <n>` | crawl N additional canonical pages |
+| `--dark` | also extract dark mode |
+| `--platforms ios,android,flutter,wordpress` | multi-platform emitters |
+| `--smart` | LLM fallback for low-confidence classifiers (needs `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`) |
+| `--cookie-file ./session.json` | authenticated extraction |
+
+Full reference: https://github.com/Manavarya09/design-extract#full-cli-reference

package/commands/grade.md

@@ -0,0 +1,29 @@
+---
+description: Generate a shareable HTML "Design Report Card" — letter grade, 8 dimensions, evidence (palette, type, rhythm), strengths + fixes, plus an SVG badge.
+argument-hint: <url> [--badge] [--open]
+---
+
+Audit the design system at the user-provided URL. Emits a self-contained HTML report card plus JSON + Markdown variants. Pass `--badge` to also emit a shields.io-style SVG you can drop into any README.
+
+```bash
+npx designlang grade $ARGUMENTS
+```
+
+If no `$ARGUMENTS` were supplied, ask the user which URL to grade.
+
+After the run completes:
+
+1. Read the generated `*.grade.md` file from `./design-extract-output/`
+2. Surface the headline grade (A–F · score · 8 dimensions)
+3. Highlight the top 3 strengths and top 3 issues from the report
+4. Offer to open the HTML in the browser (the `--open` flag does this automatically)
+
+If the user wants the live shareable badge URL instead of generating files locally, they can use:
+
+```markdown
+![Design Score](https://designlang.app/badge/<host>.svg)
+```
+
+This endpoint is blob-cached 24h with edge caching for ~50ms repeat hits.
+
+Compare two sites with `/battle <A> <B>`, restyle with `/remix`, bundle everything with `/pack`.

package/commands/pack.md

@@ -0,0 +1,37 @@
+---
+description: Bundle every designlang output (DTCG tokens, Tailwind, shadcn, Figma vars, motion, anatomy, Storybook, prompts) into one polished design-system directory ready to zip and ship.
+argument-hint: <url> [--with-clone] [--open]
+---
+
+Run the full extraction once and write every emitter output into a single, signed, layered directory.
+
+```bash
+npx designlang pack $ARGUMENTS
+```
+
+If no URL is provided, ask the user. Default output is `./<host>-design-system/`.
+
+Layout produced:
+
+```
+<host>-design-system/
+├── README.md           bespoke "Built from <host>" + grade + at-a-glance
+├── LICENSE.txt         provenance + usage guidance
+├── tokens/             DTCG + Tailwind + CSS vars + Figma vars + motion + theme.js
+├── components/         typed React stubs (anatomy.tsx)
+├── storybook/          runnable Storybook project
+├── starter/            minimal HTML starter wired to tokens/variables.css
+├── prompts/            v0 / Lovable / Cursor / Claude Artifacts + named recipes/*.md
+└── extras/             voice.json + prompt-pack.md rollup
+```
+
+After the run:
+
+1. Surface the headline (`X files, Y KB · ./<dir>`)
+2. Read the auto-generated `README.md` and tell the user what's inside
+3. Suggest next steps:
+   - `cd <dir> && zip -r ../<dir>.zip .` to package for sharing
+   - `cd <dir>/storybook && npm install && npm run storybook` to run the design system locally
+   - Copy `tokens/tailwind.config.js` straight into a project
+
+Use `--with-clone` to swap the minimal HTML starter for the full Next.js clone (slower; only when the user wants a runnable app).

package/commands/remix.md

@@ -0,0 +1,29 @@
+---
+description: Restyle a site in another design vocabulary — brutalist, swiss, art-deco, cyberpunk, soft-ui, or editorial. Preserves page shape, swaps the visual vocabulary.
+argument-hint: <url> --as <brutalist|swiss|art-deco|cyberpunk|soft-ui|editorial> | --all
+---
+
+Restyle the page shape of an extracted site under a different visual vocabulary.
+
+```bash
+npx designlang remix $ARGUMENTS
+```
+
+If `$ARGUMENTS` is empty, ask the user for a URL and offer the six vocabularies. If only a URL is given, default to `--all` so they see every variant side by side.
+
+The six vocabularies:
+
+| `--as <id>` | Vibe |
+|---|---|
+| `brutalist` | Raw, blocky, monospace, no shadows |
+| `swiss` | Clean grid, sans, minimal palette |
+| `art-deco` | Geometric, gold accents, serif display |
+| `cyberpunk` | Neon, dark, glowing CTAs |
+| `soft-ui` | Pastel, soft shadows, generous radii |
+| `editorial` | Newspaper feel, serif, narrow columns |
+
+Use `--all` to emit all six in one pass — six standalone HTML files plus a comparison index.
+
+After the run, read the comparison index (`*-remix-index.html` or `*-remix.<vocab>.html`) and tell the user which file to open. Offer to launch `--open` automatically.
+
+Pair with `/battle` for cross-vocab fights ("Stripe-as-cyberpunk vs Vercel-as-art-deco"), or `/pack` to bundle a remixed system as a downloadable design directory.

package/commands/theme-swap.md

@@ -0,0 +1,42 @@
+---
+description: Recolour an extracted site's design around a new brand primary. OKLCH hue rotation preserves perceptual lightness — neutrals, type, spacing, and motion stay untouched. Side-by-side HTML preview + recoloured tokens (DTCG, Tailwind, shadcn, Figma).
+argument-hint: <url> --primary <hex>  [--from <hex>] [--open]
+---
+
+Take any extracted site and swap its brand primary to the user-provided hex. The whole palette rotates around that hue while neutrals and structural tokens stay put.
+
+```bash
+npx designlang theme-swap $ARGUMENTS
+```
+
+If `$ARGUMENTS` doesn't contain both a URL and `--primary <hex>`, ask the user for the missing piece.
+
+After the run completes, all output goes to `./design-extract-output/`:
+
+- `*.themeswap.html` — editorial side-by-side preview (open this)
+- `*.themeswap.md` — markdown diff table
+- `*.themeswap.json` — structured before→after deltas
+- `*.themeswap.tokens.json` — recoloured DTCG token set you can drop into a project
+
+After the command finishes:
+
+1. Read `*.themeswap.md` to summarise the swap (`from → to`, hue shift, count of changed colours).
+2. Show the user the verdict line ("X colours changed, neutrals preserved, type/spacing/motion untouched").
+3. Offer to open the HTML preview (`--open` does this automatically).
+4. Suggest the recoloured token files as drop-ins for an existing Tailwind / shadcn project.
+
+## Useful flags
+
+| Flag | Effect |
+|---|---|
+| `--primary <hex>` | **required.** Target brand colour (e.g. `"#ff4800"`). |
+| `--from <hex>` | Override the auto-detected source primary when the extractor misclassifies (e.g. a neutral got promoted by usage count). |
+| `--format html\|md\|json\|tokens\|all` | Pick the output(s). Default `all`. |
+| `--out <dir>` | Output directory. Default `./design-extract-output`. |
+| `--open` | Open the HTML preview in your default browser. |
+
+## Pairs nicely with
+
+- `/grade <url>` — grade the recoloured site by feeding the same target through `/extract` then `/grade`.
+- `/pack <url>` — bundle the recoloured tokens as a downloadable design-system folder.
+- `/remix <url> --as <vocab>` — full vocabulary swap (brutalist, art-deco, cyberpunk…) instead of just brand colour.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "designlang",
-  "version": "12.4.0",
-  "description": "Extract the complete design language from any website and ship it — clone to a working Next.js starter, guard tokens with a CI drift bot, or browse everything in a local studio. Outputs W3C DTCG tokens, motion tokens, typed anatomy stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
+  "version": "12.7.1",
+  "description": "Extract the complete design language from any website and ship it \u2014 clone to a working Next.js starter, guard tokens with a CI drift bot, or browse everything in a local studio. Outputs W3C DTCG tokens, motion tokens, typed anatomy stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
   "type": "module",
   "bin": {
     "designlang": "./bin/design-extract.js"
@@ -48,4 +48,4 @@
   ],
   "author": "masyv",
   "license": "MIT"
-}
+}

package/src/ci.js

@@ -32,9 +32,43 @@ export async function runCi(url, opts) {
   out.push(`## designlang · design regression guard`);
   out.push(`\n**URL:** \`${url}\`  \n**Run:** ${new Date().toISOString()}\n`);
 
-  // 1. Extract
+  // 1. Extract — guard the throw site so CI artifacts never come back empty.
+  // Playwright can crash on flaky networks, ad-walled URLs, or self-signed
+  // proxies; when that happens we still want a report file + a summary.json
+  // so downstream jobs (artifact uploads, status comments, dashboards) have
+  // something to point at. We preserve the original error via `cause` so the
+  // stack survives — losing the trace was a real problem with #76's draft.
   const { extractDesignLanguage } = await import('./index.js');
-  const design = await extractDesignLanguage(url);
+  let design;
+  try {
+    design = await extractDesignLanguage(url);
+  } catch (err) {
+    const stack = err?.stack || String(err);
+    out.push(section('Extraction', [
+      `_failed — ${err.message}_`,
+      '',
+      '```',
+      stack,
+      '```',
+    ].join('\n')));
+    const md = out.join('\n');
+    const mdPath = join(outDir, 'ci-report.md');
+    writeFileSync(mdPath, md, 'utf-8');
+    const summary = {
+      url,
+      score: null,
+      grade: null,
+      driftVerdict: 'unknown',
+      extractionFailed: true,
+      error: err.message,
+      timestamp: new Date().toISOString(),
+    };
+    writeFileSync(join(outDir, 'ci-summary.json'), JSON.stringify(summary, null, 2), 'utf-8');
+    if (process.env.GITHUB_STEP_SUMMARY) {
+      try { writeFileSync(process.env.GITHUB_STEP_SUMMARY, md, { flag: 'a' }); } catch {}
+    }
+    return { mdPath, md, summary, shouldFail: true, cause: err };
+  }
 
   // 2. Score block
   if (design.score) {