designlang 12.8.0 → 12.9.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "designlang",
       "source": "./",
       "description": "Eight slash commands wrapping the designlang CLI: /extract (full design language \u2192 DTCG, Tailwind, Figma), /grade (shareable HTML report card + SVG badge), /battle (head-to-head graded comparison), /remix (restyle in 6 vocabularies \u2014 brutalist, swiss, art-deco, cyberpunk, soft-ui, editorial), /pack (one downloadable design-system bundle), /theme-swap (OKLCH-correct recolour around a new brand primary), /brand (full editorial brand-guidelines book \u2014 13 chapters, hand-off-ready), /pair (fuse two designs across configurable axes \u2014 colours from one site, typography from another).",
-      "version": "12.8.0",
+      "version": "12.9.0",
       "author": {
         "name": "Manavarya Singh"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "designlang",
   "description": "Extract any website's design language and ship it. Eight slash commands \u2014 /extract, /grade, /battle, /remix, /pack, /theme-swap, /brand, /pair \u2014 wrap the designlang CLI to pull DTCG tokens, Tailwind/shadcn/Figma vars, motion + voice, generate shareable graded report cards, head-to-head battle pages, six-vocabulary remixes, downloadable design-system bundles, OKLCH-correct theme recolouring, full editorial brand-guidelines books, and design crossovers between two sites.",
-  "version": "12.8.0",
+  "version": "12.9.0",
   "author": {
     "name": "Manavarya Singh",
     "url": "https://github.com/Manavarya09"

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## [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.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "12.8.0",
+  "version": "12.9.0",
   "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": {

package/src/extractors/colors.js

@@ -106,8 +106,29 @@ export function extractColors(computedStyles) {
     return pct < 0.05 && c.members.some(m => m.contexts.has('background'));
   }) || ranked.find(c => c !== primary && c !== secondary) || null;
 
+  // Primary detection confidence — useful signal for downstream consumers
+  // that may want to warn the user when extraction is uncertain (e.g. a
+  // monochrome site where there's no clear brand colour). We compute it
+  // from the score gap between rank 1 and rank 2: a runaway leader is
+  // confident, a near-tie is not.
+  let primaryConfidence = null;
+  if (primary) {
+    const top = brandScore(primary);
+    const next = ranked[1] ? brandScore(ranked[1]) : 0;
+    if (top <= 0) {
+      primaryConfidence = 0;
+    } else if (next <= 0) {
+      primaryConfidence = primary.interactiveBg > 0 ? 1 : 0.6;
+    } else {
+      const gap = (top - next) / top;
+      // Anchor: gap >= 0.5 → 1.0 (runaway). gap 0 → 0.3 (near-tie).
+      primaryConfidence = Math.max(0.3, Math.min(1, 0.3 + gap * 1.4));
+    }
+    primaryConfidence = Math.round(primaryConfidence * 100) / 100;
+  }
+
   return {
-    primary: primary ? { hex: primary.hex, rgb: primary.representative, hsl: rgbToHsl(primary.representative), count: primary.count } : null,
+    primary: primary ? { hex: primary.hex, rgb: primary.representative, hsl: rgbToHsl(primary.representative), count: primary.count, confidence: primaryConfidence } : null,
     secondary: secondary ? { hex: secondary.hex, rgb: secondary.representative, hsl: rgbToHsl(secondary.representative), count: secondary.count } : null,
     accent: accent ? { hex: accent.hex, rgb: accent.representative, hsl: rgbToHsl(accent.representative), count: accent.count } : null,
     neutrals: neutrals.map(c => ({ hex: c.hex, rgb: c.representative, hsl: rgbToHsl(c.representative), count: c.count })),

package/src/extractors/typography.js

@@ -1,14 +1,49 @@
 import { parseCSSValue } from '../utils.js';
 
+// Filter set for fonts that aren't part of the site's brand typography:
+// generic CSS fallbacks, OS UI stacks, icon fonts, and inherited "no
+// declaration" values. These slipped into families[] before and polluted
+// the brand book + grade summary.
+const GENERIC_FAMILIES = new Set([
+  'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy',
+  'system-ui', 'ui-serif', 'ui-sans-serif', 'ui-monospace', 'ui-rounded',
+  'inherit', 'initial', 'unset', 'revert', 'auto', '-apple-system',
+  'blinkmacsystemfont', 'apple-system',
+]);
+const ICON_FAMILY_RE = /^(material[-\s]?icons|font\s?awesome|fa-?solid|fa-?regular|fa-?brands|ionicons|glyphicons|bootstrap-icons|remixicon|feather|tabler-icons|lucide)/i;
+
+function normaliseFamily(raw) {
+  if (!raw) return null;
+  // Strip quotes + take the first stack member (sites declare e.g.
+  // `"Inter", "Helvetica Neue", sans-serif` — only the first is the
+  // *intended* family).
+  const first = String(raw).replace(/["']/g, '').split(',')[0].trim();
+  if (!first) return null;
+  return first;
+}
+
+function isMeaningfulFamily(name) {
+  if (!name) return false;
+  const lower = name.toLowerCase();
+  if (GENERIC_FAMILIES.has(lower)) return false;
+  if (ICON_FAMILY_RE.test(name)) return false;
+  // Single-character or all-symbol names are extraction noise.
+  if (name.length < 2) return false;
+  if (!/[a-z]/i.test(name)) return false;
+  return true;
+}
+
 export function extractTypography(computedStyles) {
   const familyCount = new Map();
   const sizeEntries = [];
   const weightCount = new Map();
 
   for (const el of computedStyles) {
-    // Font families
-    const family = el.fontFamily?.replace(/["']/g, '').split(',')[0]?.trim();
-    if (family) familyCount.set(family, (familyCount.get(family) || 0) + 1);
+    // Font families — normalised first-of-stack, with noise filtered out.
+    const family = normaliseFamily(el.fontFamily);
+    if (family && isMeaningfulFamily(family)) {
+      familyCount.set(family, (familyCount.get(family) || 0) + 1);
+    }
 
     // Font sizes
     const sizeVal = parseCSSValue(el.fontSize);

package/src/utils.js

@@ -188,6 +188,20 @@ export function clusterColors(colors, threshold = 15) {
       clusters.push({ representative: color.parsed, hex: color.hex, members: [color], count: color.count });
     }
   }
+  // The first encountered colour seeded each cluster, but that's order-of-
+  // iteration accident, not signal. Re-pick the representative as the
+  // most-used member of the cluster so downstream consumers (primary
+  // detection, palette display, brand book) get the dominant shade.
+  for (const cluster of clusters) {
+    if (cluster.members.length > 1) {
+      const dominant = cluster.members.reduce(
+        (best, m) => (m.count > best.count ? m : best),
+        cluster.members[0],
+      );
+      cluster.representative = dominant.parsed;
+      cluster.hex = dominant.hex;
+    }
+  }
   return clusters.sort((a, b) => b.count - a.count);
 }
 
@@ -235,13 +249,33 @@ export function nameFromUrl(url) {
 
 export function detectScale(values) {
   if (values.length < 3) return { base: null, scale: values };
-  const candidates = [2, 4, 6, 8];
+  // Expanded candidate set. Real production palettes use 4/8 (Tailwind +
+  // Material), 5 (Bootstrap), 6 (some Apple specs), 7 (rare), 10/12/16
+  // (looser systems). 2 stays as a fallback for icon/component-level
+  // numbers. We give 4 and 8 a small head-start because they win >70%
+  // of the time and were the previous-only choices — keeps results
+  // stable for sites that worked before.
+  const candidates = [2, 4, 5, 6, 7, 8, 10, 12, 16];
+  const bonus = { 4: 0.04, 8: 0.04 };
   let bestBase = null;
   let bestScore = 0;
   for (const base of candidates) {
-    const score = values.filter(v => v > 0 && v % base === 0).length / values.length;
+    const fit = values.filter(v => v > 0 && v % base === 0).length / values.length;
+    const score = fit + (bonus[base] || 0);
     if (score > bestScore) { bestScore = score; bestBase = base; }
   }
   if (bestScore >= 0.6) return { base: bestBase, scale: values };
   return { base: null, scale: values };
 }
+
+// Shared "always-list" coercer for downstream consumers (formatters,
+// pack, brand-book). Different extractors return slot/prop/variant
+// fields as arrays, objects, or comma-separated strings depending on
+// what was detected; this normalises without losing data.
+export function asList(v) {
+  if (v == null) return [];
+  if (Array.isArray(v)) return v.filter(x => x != null);
+  if (typeof v === 'string') return v.split(',').map(s => s.trim()).filter(Boolean);
+  if (typeof v === 'object') return Object.keys(v).filter(k => v[k] !== false && v[k] !== null);
+  return [String(v)];
+}