# Changelog ## [12.21.0] — 2026-06-14 **Studio craft pass — the preview is now an intentional specimen, not a scatter of placeholders.** - **Composed preview.** The component wall is rebuilt as a real design-system specimen with deliberate rhythm: a masthead, a centered hero using the site's *own* strongest heading + top CTA verbs, labeled **Color** and **Type** foundations, then Buttons, Inputs, Status, In-context cards, and a metrics strip — each under a clear section eyebrow. The rebuilt-Page tab uses the same crafted components. Copy is honest product language, never lorem. - **Harmonised color derivation.** `deriveTokens` now guarantees a legible surface/text pair (mislabeled near-equal colors no longer slip through), filters greys out of accent selection so a neutral is never promoted to the brand color, deepens a near-invisible accent just enough to read on the surface, and keeps secondary text above a legibility floor. - **Calmer chrome.** Quieter hairlines, consistent 30px rounded controls, pill tab group and segmented light/dark — the editor frame recedes so the extracted system is the focus. All of this lives in the shared studio engine, so the CLI and the website `/studio` get it identically. ## [12.20.0] — 2026-06-14 **Studio gains one-click dark mode.** - **Light / Dark toggle** in the studio — generates a tasteful dark variant from the extracted light tokens: surface drops to a near-black tinted toward the brand hue, text lifts to near-white, and muted / border / card are recomputed so the system stays coherent. The **brand accent is preserved** (lightened only if it would vanish on dark), and type, shape, spacing and motion carry over unchanged. Contrast grading recomputes live, your inspector edits layer on top of either theme, and the chosen theme is encoded in the shareable URL. Pure, shared `deriveDark()` in `src/studio-tokens.js` (new unit tests included), so the CLI and website studios stay in lock-step. ## [12.19.0] — 2026-06-14 **`studio` becomes a living design-system editor — and ships on the website.** Until now `designlang studio` was a read-only viewer: editorial swatches you could copy, static type specimens. This release turns it into a real playground — and brings the exact same experience to the web. - **`designlang studio`** — a local, interactive studio over the latest extraction. An **inspector** (color pickers + the extracted palette, type, shape, spacing, motion) writes a small set of `--p-*` CSS variables; a **tabbed live preview** — a wall of real components (nav, buttons, form, cards, badges, alert, type specimen) and a **rebuilt page** assembled from the extraction's reading order — restyles instantly because everything renders off those variables. Edit a token, watch the whole system move. - **Live WCAG contrast grading** under every color (text-on-surface, accent-on-surface, label-on-accent) updates as you edit — AAA / AA / AA-large / fail, in real time. - **Paper / white / dark backdrops** to judge components on any canvas, an **edit counter**, and smooth token-driven transitions. - **Export** the edited system as DTCG tokens, CSS variables, or a Tailwind theme (zero-dependency client-side downloads), and **share via URL** — edits are encoded as deltas in the location hash, so a tweaked variant is just a link. - **`/studio` on the website** — paste any URL and the same studio opens right in the browser: it extracts the live design language and embeds the editable studio in a framed viewport. Shareable via `?url=`; counts against the same free 2/day demo budget as the extractor. - **Internals** — the token-derivation engine is now a pure, dependency-free module (`src/studio-tokens.js`) shared by the CLI and the website route, so both surfaces stay in lock-step. New unit tests cover derivation, the WCAG contrast math, and the rendered studio document. ## [12.18.0] — 2026-06-12 **`verify` closes the loop — designlang now *proves* its extraction with a fidelity score.** Every release so far *read* a design system and emitted artifacts. None proved the artifacts could rebuild the source. `verify` does exactly that. - **`designlang verify `** — extracts the design, then for each detected component (button + card in v1) rebuilds a clone styled **only** by the extracted tokens (every visual property snapped to its nearest token; colours matched in CIE-Lab ΔE space), renders it, and **pixel-diffs** it against the live component. Emits a **0–100 fidelity score**, a per-token-family attribution of where information was lost, and a `verify.html` triptych (original │ rebuilt-from-tokens │ loss heatmap) per component, plus `verify.json`. `--min ` exits non-zero for CI gating. The score is honest by construction: a component not on the page is `n/a` (excluded, never a silent 100), and a property with no matching token is `unmapped` — counted as loss and surfaced in the attribution, so a weak extractor *lowers* the score rather than hiding behind it. Size mismatches are letterboxed, never stretched. Adds `pixelmatch` + `pngjs` as dependencies. New modules under `src/verify/` (`tokens`, `restyle`, `render`, `diff`, `index`) are isolated and unit-tested. ## [12.17.0] — 2026-06-12 **motionlang adds two more emitters — GSAP and the framework-free Web Animations API.** The motion language already shipped to Framer Motion, Motion One, plain CSS and Tailwind. This release covers the two most-requested remaining targets: GreenSock and the browser-native Web Animations API. - **GSAP preset (`-motion.gsap.js`)** — registers the page's extracted cubic-bezier curves as named `CustomEase`s (so the site's exact feel is reproducible), exposes duration presets in seconds, and ships `gsap.from()` reveal helpers (`fadeIn` / `slideUp` / `scaleIn` / `pop`). When the page uses scroll-/view-timeline, a `revealOnScroll()` ScrollTrigger batch helper is emitted too. `registerEases(gsap)` wires the CustomEases in one call. - **Web Animations API preset (`-motion.waapi.js`)** — zero dependency, runs on the browser-native `Element.animate()`. WAAPI accepts cubic-bezier easing strings verbatim, so the extracted curves are reproduced *exactly* (no spring approximation). Emits `easings`, `durations`, keyframe arrays reconstructed from on-page `@keyframes`, and `fadeIn` / `slideUp` / `scaleIn` helpers that return the live `Animation` and honour `prefers-reduced-motion` automatically. Both surface as live copy/download cards on the motionlang analyzer at designlang.app/motion. ## [12.16.0] — 2026-06-06 **motionlang grows two framework-agnostic emitters + the website PDF download is fixed.** The motion language already shipped to Framer Motion and Motion One. This release covers the two surfaces that needed no framework at all — plain CSS and Tailwind — and fixes the brand-book PDF download on the website. - **Motion CSS (`-motion.css`)** — drop-in stylesheet: `--duration-*` and `--ease-*` custom properties from the live page, reusable `@keyframes` (`fade-in` / `slide-up` / `scale-in` / `pop`, plus any on-page `@keyframes` reconstructed from their real steps), `.mo-*` utility classes wired to the vars, and a `prefers-reduced-motion: reduce` guard so motion degrades to none for users who ask for it. No build step, no framework. - **Tailwind motion preset (`-motion.tailwind.js`)** — a require-able `theme.extend` block mapping the extracted timing onto Tailwind's own scales: `transitionDuration`, `transitionTimingFunction` (incl. a `spring` curve when an overshoot bezier is detected), `keyframes` and `animation` utilities (`animate-slide-up`, …). Merge into `tailwind.config` and use class names instead of magic numbers. Both are exposed through `designlang/api` as the `motion-css` and `motion-tailwind` renderer ids, alongside the existing `framer-motion` and `motion-one` emitters. - **Website: brand-book PDF download fixed.** Downloads sometimes produced a file that wouldn't open. Root cause: the streaming extractor wrote its Blob cache fire-and-forget *after* the response closed, so on serverless the write was killed before completing — leaving `/api/pdf/` with no cached design and returning a 404 JSON body that the browser dutifully saved as `host-brand.pdf`. The cache write is now awaited before the stream closes, and the download button fetches + validates the response is actually a PDF before saving (and surfaces an error instead of writing a broken file). ## [12.15.0] — 2026-05-21 **motionlang — motion becomes a first-class extractable + shippable artefact.** The motion extractor already captured durations, easings and keyframes, but they only landed as a flat `motion-tokens.json` nobody opened. This release turns extracted motion into something you can see, ship and hand to a framework. - **Motion Lab (`-motion.html`)** — a self-contained, dependency-free interactive page. Every extracted easing curve is drawn as a real cubic-Bezier path with a dot riding it at that exact timing function; every duration shown as a pulsing bar timed to its real `ms`; every `@keyframes` block replayed. Open it in any browser. - **Framer Motion presets (`-motion.framer.js`)** — ready-to-import `easings` (cubic-bezier arrays ranked by on-page frequency), `durations` (seconds), `transitions` (`base` / `fast` / `slow` / `spring`) and `variants` (`fade` / `slideUp` / `scaleIn` / `stagger`) — all wired to the extracted timing. Framer Motion is the dominant React animation library, so this is the highest-leverage motion emitter. - **Website Motion Lab** — every `/gallery/[slug]` brand page now renders an interactive Motion Lab section: easing curves drawn in the extracted brand colour, dots riding tracks, play/pause, and a link to the full standalone page. - **Mobile navbar fix** — the hamburger and Install CTA no longer squish together below 640px. Both emitters are exposed through the public `designlang/api` as the `motion-lab` and `framer-motion` renderer ids (plus `agent-prompt`). ## [12.14.0] — 2026-05-17 **Real downloadable PDFs everywhere + a one-shot agent prompt every AI can paste.** Two big shipping themes: every extraction now produces a real print-ready PDF on demand (not just an HTML brand book), and every extraction writes a self-contained agent prompt that drops into any LLM — Claude, GPT, Gemini, Cursor, Windsurf, v0. - **`--pdf` flag in the main `extract` command** — renders the brand-book HTML to a 13-chapter PDF (chapter bookmarks, running footer, embedded fonts, selectable text). Verified ~440KB per brand. ```bash npx designlang stripe.com --pdf --paper letter --landscape ``` - **One-shot agent prompt (`-AGENT.md`)** — a single file you paste into any AI agent. Includes colour roles, type, spacing, radii, motion, voice (tone / pronoun / CTA verbs / real headlines), component anatomy, WCAG score, 7 build rules ("never invent a hex", "snap spacing to scale", etc.), and a manifest of every other artefact designlang produced for context. - **Server-side PDF endpoint** — `GET /api/pdf/` renders the cached extraction's brand book to PDF via the same Browserless / Chromium path the `/api/extract` route uses. Cached for an hour on CDN edge with 24h stale-while-revalidate. - **Website UI** — `/gallery/[slug]` hero CTA is now `Download brand book PDF`; new full-width "Agent prompt" section with a `Copy NN.NKB prompt` button. Post-extraction share row gains `Download brand PDF` and `Copy agent prompt`. - **Pre-rendered static assets** — all 8 featured brand books in `website/public/gallery//` now include the new `.brand.pdf`, `-AGENT.md`, `-reset.css`, `-gradients.css/.json` files so the static gallery has working downloads from minute one. ## [12.13.0] — 2026-05-16 **Six new emitters + a public programmatic API.** Every extraction now writes five additional first-class files, and downstream tools can wire into the engine through a stable surface. - **Tailwind v4 (`-tailwind-v4.css`)** — CSS-first `@theme {}` block with the full HSL colour scales, neutrals, type, spacing, radii, shadows and motion. Parallel to the v3 `tailwind.config.js`, so v4 users get a drop-in file. - **TypeScript token types (`-tokens.d.ts`)** — strict literal unions for `ColorRole`, `ColorHex`, `FontFamilyToken`, `FontWeightToken`, `SpacingToken`, `RadiusToken`, `DurationToken`, `EasingToken` plus a `DesignTokens` roll-up interface. Component props typed against the real extracted brand, not generic `string`. - **Brand-aware CSS reset (`-reset.css`)** — modern reset wired to the extracted background / foreground / links / accent / selection. Honours `prefers-reduced-motion`. - **Gradients (`-gradients.css` + `.json`)** — surfaces every extracted gradient as `:root --grad-N` vars plus `.grad-N` background and `.grad-text-N` background-clip utility classes. - **`--palette ` flag** — compresses noisy 60–200-colour extractions to N perceptually-distinct tokens via weighted LAB-space k-means. Returns cluster medoids — never invents a hex that wasn't on the page. Verified: stripe.com 29 → 8. **Public programmatic API at `designlang/api`.** A frozen surface other packages, scripts and AI agents can import without reaching into internal modules. ```js import { extract, render, renderAll, RENDERERS } from 'designlang/api'; const design = await extract('https://stripe.com', { palette: 8 }); const tailwind = render('tailwind-v4', design); const files = renderAll(design); // { 'stripe-com-tokens.d.ts': '...', ... } ``` `package.json` now exposes: - `designlang` — main entry - `designlang/api` — the new public API (19 renderer ids) - `designlang/mcp` — the existing MCP server entry ## [12.12.0] — 2026-05-15 **Website launch — designlang.app, fully rebuilt.** The marketing/demo site at [designlang.app](https://designlang.app) has been rewritten from the ground up. Highlights: - **Hero with WebGL Grainient background** (red/black, ogl-powered, GPU-paused when offscreen) and a terminal output card showing real CLI execution. - **Live demo showcase** (`See it work.`) — paste any URL into a glass stage, suggestion chips for stripe.com / linear.app / vercel.com / notion.so / figma.com, click-to-copy `npx designlang stripe.com` in the hero. - **Real gallery** — eight pre-rendered brand books for stripe.com, linear.app, vercel.com, notion.so, figma.com, apple.com, arc.net and spotify.com. Each card is the actual extraction the CLI produced; the cover gradient uses the extracted primary + accent tokens. - **Floating glass nav** with a custom logo, segmented pill links, real GitHub star count fetched from the API (server-rendered, 30 min revalidate), and an `npm i designlang` CTA matching the hero gradient. - **Auto-scrolling reddit testimonial marquee** (3 cols, motion/react) with the real comments from the r/ClaudeAI launch thread. - **Polished footer** with brand block, 4 link columns, decorative giant outlined wordmark, version + author + license strip. - **Aggressive SEO** — keyword-dense title and description, ~75-keyword list; JSON-LD graph with `SoftwareApplication`, `Organization`, `WebSite + SearchAction`, `BreadcrumbList`, `FAQPage`, `HowTo`; `aggregateRating` from real GitHub stars; visible FAQ section + ~250-word about block; sitemap includes the 8 gallery brand books; rewritten `llms.txt` for AI-search citability (allows GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, etc.). **Web extractor parity with the CLI.** - `/api/extract`'s file output now includes the brand-book HTML (`.brand.html`) for every run. - `formatBrandBook` is shared between the CLI and the website's `lib/build-files.js`. **Other** - Fixed the README so the logo and "designlang in action" image render on the npm package page (relative paths swapped for raw GitHub URLs). - Removed all decorative status dots from the website per design feedback; status indicators are now typed text chips. ## [12.11.0] — 2026-05-15 **`brand --pdf` ships native PDF brand guides.** ```bash npx designlang brand stripe.com --pdf # → stripe-com.brand.pdf (print-ready, ~3–5s) ``` What you get on top of any "save as PDF": - **Per-chapter page breaks** — every section starts on a fresh page. - **Running footer** — `designlang · · of ` on every page. - **Selectable text + embedded fonts** — never rasterized. - **`--paper a4|letter|tabloid` + `--landscape`** for any output target. - **`--attach-tokens`** embeds the DTCG tokens JSON *inside* the PDF as a proper file attachment — open the PDF in Preview/Acrobat, hit the paperclip, drop the JSON straight into Tailwind. - **`--no-print-background`** strips the brand-colour cover band for a smaller file when you need it. Adds one tiny dep (`pdf-lib`, MIT, ~600KB) used only when `--attach-tokens` is passed; lazy-imported behind a dynamic `import()`. ## [12.10.1] — 2026-05-13 **Tiny ship: \`stats\` now scans multiple URLs at once.** \`designlang stats\` previously took exactly one URL. Now it takes any number, runs them in parallel, and prints each block with a divider: \`\`\`bash npx designlang stats stripe.com vercel.com linear.app \`\`\` In \`--as-json\` mode: - One URL → a bare object (legacy shape, unchanged) - Two-or-more URLs → an array of objects - Per-URL failures don't kill the batch — they surface as \`{ url, error }\` in JSON or a red row in pretty mode, and the process exits non-zero only when at least one site failed. No flag changes, no schema breaks for the existing single-URL callers. ## [12.10.0] — 2026-05-12 **Small ship: \`designlang stats\` + low-confidence warning in grade cards.** Two tight quality-of-life additions on top of the v12.9 extraction pass. ### Added - **\`designlang stats \`** — one-screen summary to stdout. Grade, primary, fonts, spacing base, WCAG, stack, library, tone, material, intent — all in ~15 lines. No files written. Use \`-j\` / \`--as-json\` for machine-readable output (CI, scripting). \`\`\` Grade B · 87/100 Primary #533afd ×899 59% conf Fonts sohne-var Type scale 14 sizes Spacing base 2px · 13 steps Shape 5 radii · 6 shadows Colours 31 tokens WCAG 79% Stack next · unknown Material skeuomorphic Tone neutral Intent landing \`\`\` - **Low-confidence primary warning in \`grade.html\`.** Surfaces the v12.9 \`primary.confidence\` field when it drops under 0.5 — a soft, amber callout above the dimensions grid that tells the reader the brand colour is a near-tie pick rather than a runaway leader. Renders as ordinary inline note, not an error. Stays out of the way when confidence is high (the common case). ### Why \`stats\`? Every other command writes files. There was no one-line "what's this site made of" path for scripting, CI summaries, or a quick sanity check. \`stats\` fills that gap without bloat — it's the read-only, zero-side-effect entry point. 2 new tests (low-confidence note present + absent paths). 398/398 total. ## [12.9.0] — 2026-05-11 **Extraction quality pass — the core MVP, fixed.** Eight features rode on top of the same extractor. This release fixes four real defects in that extractor — visible across grade, battle, remix, pack, theme-swap, brand, and pair without anyone having to re-run the downstream code. ### Fixed - **Cluster representative bug** in \`clusterColors()\`. Before: the first- encountered colour seeded each cluster, so a sparsely-used pale shade could become the canonical hex for a cluster that mostly held a vivid brand colour. The brand-book primary slot was reading lavender for Stripe instead of \`#533afd\`. Fixed: representative is now the most-counted member of the cluster. - **Spacing base detection** missed common production scales. Before: only \`[2, 4, 6, 8]\` were tried as base candidates, so Bootstrap-style base-5 sites and base-7/10/12 sites returned \`base: null\`. Fixed: expanded to \`[2, 4, 5, 6, 7, 8, 10, 12, 16]\` with a small bonus for 4 and 8 to keep results stable for the production-default sites. - **Typography noise**. Before: generic CSS stacks (\`sans-serif\`, \`monospace\`, \`system-ui\`, \`inherit\`), OS UI fonts (\`-apple-system\`), and icon fonts (Material Icons, Font Awesome, Lucide, Tabler, etc.) polluted the \`families\` list, making the brand book mistakenly document an icon font as the brand's body family. Fixed: explicit generic + icon-family filter at the source. ### Added - **\`primary.confidence\`** (0–1) on \`design.colors.primary\`. Computed from the score gap between rank 1 and rank 2 brand candidates — a runaway leader scores 1.0; a near-tie scores 0.3. Downstream consumers (brand book, grade, theme-swap) can surface uncertainty warnings on low-confidence extractions. - **\`asList(v)\`** helper exported from \`src/utils.js\`. Coerces anything-shaped input (array / object / comma-string / scalar) into a clean string array. Consolidates the per-formatter ad-hoc defenses (brand-book, pair, pack all had their own copies). ### Why Verified live on \`stripe.com\`: - Pre-v12.9: primary slot showed a lavender shade, multiple icon-font entries in families, spacing base often \`null\`. - v12.9: primary \`#533afd\` (count 899, confidence 0.59), \`families: ['sohne-var']\`, spacing base detected correctly. No new dependencies, no schema breaks, no public-API changes. 396/396 tests pass (6 new — base-5 + base-6 detectScale, cluster representative correctness, generic-family filter, icon-family filter, asList shape coercion). ## [12.8.0] — 2026-05-10 **Pair — fuse two extracted designs into a single hybrid identity.** \`designlang pair \` extracts both sites in parallel, then mixes their design systems along seven configurable axes (colours, typography, spacing, shape, motion, voice, components). Default split is "visuals from A, voice + type + components from B" — i.e. the most distinctive crossover. Override any axis with \`---from a|b\`. \`\`\`bash npx designlang pair stripe.com linear.app \`\`\` \`\`\` stripe.com × linear.app A Colours · stripe.com B Typography · linear.app A Spacing · stripe.com A Shape · stripe.com A Motion · stripe.com B Voice · linear.app B Components · linear.app ✓ stripe-com-x-linear-app.pair.html ✓ stripe-com-x-linear-app.pair.md ✓ stripe-com-x-linear-app.pair.json \`\`\` ### Added - New CLI command: \`designlang pair \` with \`--colors-from\`, \`--typography-from\`, \`--spacing-from\`, \`--shape-from\`, \`--motion-from\`, \`--voice-from\`, \`--components-from\`, plus \`--brand\` to also emit a full brand-guidelines book of the fused identity. - New module \`src/fuse.js\` — \`fuseDesigns(a, b, opts)\` deep-clones both inputs, picks each axis from the requested source, synthesises a pair-specific meta URL (\`pair://-x-\`), and strips score / cssHealth (those belong to the source extractions, not the fusion). - New formatter \`src/formatters/pair.js\` — editorial pair card with a three-card crossover (A · B · Fused), per-axis source matrix table, and a fused specimen using the *real headline* from whichever site contributed the voice axis. - Plus \`formatPairMarkdown\` for diff-friendly summaries. - 12 new tests covering default split, per-axis overrides, score-stripping, meta synthesis, immutability of source designs, HTML rendering, voice carry-through to the specimen, XSS escaping, and missing-input errors. ### Plugin \`/pair\` is the 8th slash command in the Claude Code plugin (\`/extract\`, \`/grade\`, \`/battle\`, \`/remix\`, \`/pack\`, \`/theme-swap\`, \`/brand\`, \`/pair\`). Plugin manifests bumped to 12.8.0. ### Why \`battle\` answers "which is better"; \`pair\` answers "what would the intersection look like". Same parallel extraction, opposite operation. Pure logic, no LLM, no new dependencies. ## [12.7.1] — 2026-05-09 **Brand book — visual polish pass.** The v12.7.0 brand book had a real-data deficit: the cover used a generic grade-coloured accent strip, every section opened with a philosophical lede ("the felt pace of an interface", "form follows feeling"), and components were a metadata table instead of a real mock. This pass replaces all of that with the extracted values themselves. Changes: - **Cover** now leads with the brand's actual primary as a full-bleed band (auto-detected, falls back through secondary/accent/most-used). Asymmetric layout — band + label + hex above, host name in massive serif below. - **Lede paragraphs replaced with one-line data summaries.** "1 primary · 1 secondary · 1 accent · 27 neutrals · 88 total" instead of "Brand colours carry meaning. Neutrals carry structure." - **Type specimen** now uses real headlines extracted from the site's voice (`design.voice.sampleHeadings`). Falls back to a single neutral pangram only when those are absent. The recycled aphorisms ("quiet authority of restraint", "form follows feeling") are gone. - **Colour chapter** — primary at full-width hero card, secondary + accent at half-width below, neutrals as a flush horizontal strip, full palette grid below. Hex labels render *inside* the swatch in high-contrast text (auto black/white). - **Components chapter** — renders an actual primary + secondary button using the extracted brand colour and radius, plus a card mockup using extracted surface + text colours. Metadata table moved below the visual mock. - **Accessibility chapter** — failing pairs render as actual stacked colour blocks (foreground text on background with ratio inline), not a pure table. Big score number on top. - **Tokens chapter** — code blocks now have a header bar with the language label and target filename. - **"How to use"** trimmed from six rules of thumb to four punchy ones, drops the "rule of thumb" framing. - **Layout** — section padding moved into the wrap (no more gutter around the hero band), TOC now sits on a tinted sub-paper background, chapter headers are thinner with a bottom rule. Same 13 chapters, same public API. No breaking changes. 378/378 tests pass (one assertion updated for the new lowercase "Brand guidelines" cover label). ## [12.7.0] — 2026-05-09 **Brand book — full editorial design-guidelines document for any URL.** \`designlang brand \` produces a self-contained, print-ready HTML "brand guidelines book" that documents every dimension of an extracted design system. Cover, table of contents, 13 chapters: about, logo, colour, typography, spacing, shape, iconography, motion, components, voice, accessibility, tokens, how-to-use. Editorial layout, dark-mode toggle, smooth-scroll TOC, drop-in code blocks per stack. \`\`\`bash npx designlang brand stripe.com \`\`\` \`\`\` Brand book · 54 tokens · 3 fonts · grade B · https://stripe.com ✓ stripe-com.brand.html ✓ stripe-com.brand.md ✓ stripe-com.brand.json \`\`\` ### Why this is different from \`pack\`, \`grade\`, and \`design-language.md\` | Output | Audience | Format | |---|---|---| | \`pack\` (v12.4) | Devs picking up a design system | Directory of files (tokens, components, Storybook, starter) | | \`grade\` (v12.1) | Audit / share | Single audit page with score + verdict | | \`design-language.md\` | LLMs | AI-optimized markdown (data-dense) | | **\`brand\` (v12.7)** | **Designers + handoff** | **Editorial brand-guidelines book — readable, print-ready, hand-off-ready** | ### Added - New CLI command: \`designlang brand [-o] [-n] [--format] [--open]\`. - New formatter \`src/formatters/brand-book.js\` exporting \`formatBrandBook\` (HTML book) and \`formatBrandBookMarkdown\` (terse markdown summary). - 13 chapters with editorial typography (Instrument Serif display + Inter body), generous whitespace, smooth-scroll anchors, dark-mode toggle, print stylesheet with page breaks at chapter boundaries. - Per-colour section: large swatch + HEX/RGB/HSL/usage grid for brand colours, mini-grid for neutrals + full palette. - Per-token section: drop-in code blocks for CSS variables, Tailwind config, with cross-reference to \`pack\` for the full bundle. - Closing "How to use" chapter with six rules of thumb (hierarchy of brand colour, two-family discipline, snap-to-scale spacing, tight radius set, motion as feedback, accessibility as hard constraint). - 7 new tests covering chapter coverage, host/colour/font rendering, XSS escaping, sparse-design fallback, and mixed-shape component anatomy (the bug that broke the first integration — slots / variants arrive as objects, strings, or arrays from the extractor). ### Plugin \`/brand\` is the 7th slash command in the Claude Code plugin (\`/extract\`, \`/grade\`, \`/battle\`, \`/remix\`, \`/pack\`, \`/theme-swap\`, \`/brand\`). \`.claude-plugin/plugin.json\` and \`marketplace.json\` bumped to 12.7.0. ## [12.6.0] — 2026-05-06 **Theme-swap — recolour any extracted design around your brand primary.** \`designlang theme-swap --primary \` takes the existing extraction and rotates the brand palette around a new primary while preserving everything else: type scale, spacing rhythm, neutrals, motion, component anatomy. Closes [#57](https://github.com/Manavarya09/design-extract/issues/57). \`\`\`bash npx designlang theme-swap stripe.com --primary "#ff4800" \`\`\` \`\`\` #533afd → #ff4800 · 91 colours · https://stripe.com Hue shift: 118.5° · neutrals preserved · type/spacing/motion untouched ✓ stripe-com-themeswap-ff4800.themeswap.html ✓ stripe-com-themeswap-ff4800.themeswap.md ✓ stripe-com-themeswap-ff4800.themeswap.json ✓ stripe-com-themeswap-ff4800.themeswap.tokens.json \`\`\` ### Added - New CLI command: \`designlang theme-swap --primary \` with \`--from\`, \`-o\`, \`-n\`, \`--format\`, \`--open\` flags. - New module \`src/recolor.js\` exporting \`recolorDesign(design, opts)\`. Operates in OKLCH so perceptual lightness stays constant — only hue rotates. Auto-detects the source primary; pin it with \`--from\`. Neutrals (chroma < 0.04 in OKLCH) are explicitly preserved so body text, surfaces, and rule lines stay readable. - New formatter \`src/formatters/theme-swap.js\` exporting \`formatThemeSwap\` (HTML side-by-side preview) and \`formatThemeSwapMarkdown\`. - New OKLCH inverse helpers in \`src/utils/color-gamut.js\`: \`srgbToOklab\`, \`srgbToOklch\`, \`hexToOklch\`, \`oklchToHex\` — with chroma fallback for out-of-gamut colours. - The recoloured design is fed through every existing emitter (DTCG, Tailwind, shadcn, Figma vars, CSS vars), so the swap propagates for free. - 10 new tests covering primary-pinning, neutral preservation, hue rotation, error paths, \`--from\` override, HTML/markdown shapes, and XSS escaping. ### Why People keep asking *"what would Stripe look like in our brand colors?"*. \`theme-swap\` answers it in 30 seconds. Bridges \`remix\` (full-vocab restyle) and \`apply\` (token write-through to a project). ## [12.5.0] — 2026-05-06 **Claude Code plugin — five slash commands wrapping the CLI.** designlang is now a first-class Claude Code plugin. Drop it into any session and every CLI verb becomes a slash command: \`\`\`bash /plugin install Manavarya09/design-extract \`\`\` | Command | What it does | |---|---| | \`/extract \` | Full extraction → DTCG, Tailwind, Figma, motion, voice | | \`/grade \` | Shareable HTML Design Report Card (+ \`--badge\`) | | \`/battle \` | Head-to-head graded battle card | | \`/remix --as \` | Restyle in 6 vocabularies | | \`/pack \` | Bundle every output into one design-system directory | ### Added - \`commands/extract.md\`, \`commands/grade.md\`, \`commands/battle.md\`, \`commands/remix.md\`, \`commands/pack.md\` — five slash-command manifests with \`description\` + \`argument-hint\` frontmatter and prompt bodies that wrap the CLI and surface tight summaries. - Refreshed \`.claude-plugin/plugin.json\` (was stale at v1.0.0) — name bumped to \`designlang\`, description rewritten around all v12 surfaces, added \`commands\` directory pointer + expanded keywords. - Refreshed \`.claude-plugin/marketplace.json\` — same updates plus marketplace tags. - New README section "Claude Code plugin" documenting install + the five slash commands. Existing skills-ecosystem section retained for Cursor / Codex / 40+ other agents. No CLI behavior change. The slash commands are pure wrappers — they shell out to \`npx designlang …\` and read the same output files. ## [12.4.0] — 2026-05-05 **Pack — one command, one polished design-system bundle.** \`designlang pack \` runs the full extraction once and writes every emitter output into a single, signed, layered directory. One artifact a designer or dev can clone, drop into a project, or zip up and send to a client. Closes [#59](https://github.com/Manavarya09/design-extract/issues/59). ### Added - New CLI command: \`designlang pack [-o ] [--with-clone] [--open]\` - New module \`src/pack.js\` exporting \`buildPack(design, opts)\` - Layout: \`\`\` -design-system/ ├── README.md — bespoke, "Built from " + grade + at-a-glance stats ├── 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.txt · lovable.txt · cursor.md · claude-artifacts.md │ └── recipes/ — recipe-.md cards (named, no longer indexed) └── extras/ — voice.json + prompt-pack.md rollup \`\`\` - 7 new tests covering directory shape, valid JSON outputs, README content, starter wiring, recipe filenames, and a regression test for the double-stringify bug that broke first integration. ### Why The 17+ loose files designlang already emits are the right pieces, but asking a user to zip them themselves is friction. \`pack\` is the same artifacts as one polished, downloadable, cite-able bundle. ## [12.3.0] — 2026-05-05 **Remix — restyle any site in a different design vocabulary.** A genuinely new product surface: take an extracted page-shape (sections, voice, page-intent, anatomy) and re-render it under one of six opinionated design vocabularies. "What would stripe.com look like if it had been designed brutalist? Or art-deco? Or cyberpunk?" ### Added - **`designlang remix --as `** — re-renders the audited page using the host's *own copy* (headings, ledes, CTA verbs from voice) but styled in another vocabulary. Six built-ins: - `brutalist` — hard edges, mono type, single screaming accent - `swiss` — Helvetica, grids, restraint (post-Bauhaus default) - `art-deco` — gold on ink, geometric ornament, vertical type - `cyberpunk` — neon on midnight, scanlines, mono with glitch energy - `soft-ui` — cushioned shapes, low contrast, Vision-OS-adjacent - `editorial` — broadsheet serifs, generous whitespace, ink on paper - `--all` flag emits one HTML per vocabulary in a single extraction. - `--list` prints the vocabulary registry with blurbs. - New formatter: `src/formatters/remix.js` — maps every section role (hero, feature-grid, pricing-table, stats, testimonial, faq, logo-wall, steps, cta) to vocabulary-styled markup. - New module: `src/vocabularies/` — six self-contained vocab definitions (tokens + font stack + signature CSS) plus `index.js` registry. - Hero-deduplication: real-world section walkers (especially on SPA marketing pages) often emit a hero wrapper + an inner hero with the same h1. Remix now dedupes by heading and excludes claimed headings from the voice pool, so heading-less sections (cta bands, logo walls) don't re-render an already-claimed heading. - 14 new tests (350 total, all passing). Cover registry shape, per-vocab token validity, dedup, XSS escaping, missing-input errors. Why: Grade (v12.1) is the audit, Battle (v12.2) is the comparison, Remix is the *transformation*. Pure visual moat — no competitor (Dembrandt, Superposition, html.to.design, Builder Visual Copilot) ships site-shape-preserving vocabulary swap. ## [12.2.0] — 2026-05-02 **Battle cards + design score badges — distribution + virality on top of Grade.** ### Added - **`designlang battle `** — head-to-head graded battle card. Single shareable HTML pitting two sites against each other, dimension by dimension, with a verdict line and a per-dimension bar table. Both sites are extracted in parallel. Emits `*.battle.html`, `*.battle.md`, and `*.battle.json`. - **`designlang grade --badge`** — also emit `*.grade.svg`, a shields.io-style SVG badge (`design · B · 87`) coloured by letter grade. Drop into any README. - **Live badge endpoint** at `https://designlang.app/badge/.svg` (with rewrites from `/badge/` and `/api/badge/`). Reuses the same blob cache the `/api/extract` route writes to, so the first hit warms the cache and every subsequent hit is served from edge cache in ~50ms. 6h fresh / 24h stale-while-revalidate / 7d max — friendly to the GitHub image proxy. - New formatters: `src/formatters/battle.js`, `src/formatters/badge.js`, with exports `formatBattle`, `formatBattleMarkdown`, `compareScores`, `formatBadge`, `formatScoreBadge`. - 13 new tests (battle markup, score comparison thresholds, SVG escaping, grade-color mapping, missing-score handling). Why this exists: the v12.1 Grade card was the differentiator. Battle is the viral content layer ("Stripe vs Vercel — guess who lost"). The badge is the distribution layer — every README that adopts it is a permanent backlink to a public grade page. ## [12.1.0] — 2026-04-29 **Design Report Card — a shareable audit page, generated from any URL.** ### Added - **`designlang grade `** — produces a standalone, self-contained HTML "Design Report Card" alongside JSON and Markdown variants. Letter grade (A–F) hero, eight scored dimensions with arc gauges, evidence pulled from the audited site itself (palette swatches, type specimen, spacing rhythm), and a strengths / what-to-fix ledger. Editorial layout, paper/ink theme with a dark toggle, print-ready, OG-meta for shareable links. - New formatter: **`src/formatters/grade.js`** with `formatGrade` (HTML) and `formatGradeMarkdown` exports. Reuses the existing `scoreDesignSystem` output — no scoring changes. - Flags: `--format html|md|json|all`, `--open` to launch the report in your browser when it finishes. Why this exists: html.to.design, Locofy, Builder, Polypane all ship extraction or layout cloning. None of them grade the design system itself in a form you can post on Twitter or email to a client. This is that. ## [10.5.0] — 2026-04-22 **The states LLMs always botch.** ### Added - **`src/extractors/form-states.js`** — surfaces forms (input count + style families), modal/dialog/sheet containers, skeleton and spinner loading indicators, empty-state and error-state placeholders, and detects which toast library is on the page (Sonner, react-hot-toast, react-toastify, Radix Toast, Chakra Toast, Notistack). - New output: `*-form-states.json`. Closes the v10.x minor-release series started in v10.1. Everything the v10 spec deferred for v11 is now shipped as minor releases — with no breaking changes along the way. ## [10.4.0] — 2026-04-22 **Identification trio: icon system, background patterns, stack intel.** ### Added - **`src/extractors/icon-system.js`** — fingerprints the icon library (Lucide / Heroicons outline+solid / Phosphor / Tabler / Feather / Remix / Material) from stroke vs fill dominance, stroke width, grid size, and rounded-caps presence. Emits per-icon hints agents can act on. - **`src/extractors/background-patterns.js`** — classifies noise / dot-grid / line-grid / gradient-mesh / svg-pattern / plain from computed `background-image` values. Merged into `*-visual-dna.json`. - **`src/extractors/stack-intel.js`** — extends the existing stack-fingerprint with 12 CMSs (Webflow, Framer, Shopify, Ghost, Sanity, Contentful, Wix, Squarespace, WordPress, Hashnode, Notion, Bubble), 13 analytics platforms, and 7 experimentation platforms. - Bin reads its own version from `package.json` — no more per-release version drift in the CLI. - New outputs: `*-icon-system.json`, `*-stack-intel.json`. ## [10.3.0] — 2026-04-22 **Perf + SEO.** designlang now doubles as a lightweight auditor. ### Added - **`src/extractors/perf.js`** — `captureCoreWebVitals(url)` opens a fresh Playwright context, measures LCP / CLS / INP via PerformanceObserver, categorises every network response into JS / CSS / font / image / document / other, counts third-party requests against a known-host list, and synthesises an interaction so INP reports. Returns grade buckets (good / needs-improvement / poor) per vital. - **`src/extractors/seo.js`** — pure extractor for Open Graph, Twitter cards, canonical, manifest, theme-color, viewport, every favicon, and inline JSON-LD blocks (schema.org structured data). - Crawler now captures `favicons`, `manifest`, and `