designlang 12.8.0 → 12.10.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.10.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.10.0",
   "author": {
     "name": "Manavarya Singh",
     "url": "https://github.com/Manavarya09"

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+## [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 <url>\`** — 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.**

package/bin/design-extract.js

@@ -944,6 +944,104 @@ program
     }
   });
 
+// ── Stats command — fast stdout summary, no files written ──
+program
+  .command('stats <url>')
+  .description('Print a concise one-screen summary to stdout — grade, primary, fonts, spacing, voice. No files written.')
+  .option('-j, --as-json', 'emit machine-readable JSON to stdout instead of pretty text')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+
+    // Quiet path for --as-json: no spinner / chrome noise, just data on stdout.
+    // (`--json` is already a global program flag; `--as-json` avoids the clash.)
+    const wantJson = !!opts.asJson;
+    const spinner = wantJson ? null : ora(`Reading ${url}...`).start();
+    try {
+      const design = await extractDesignLanguage(url);
+      const s = design.score || {};
+      const primary = design.colors?.primary;
+      const families = (design.typography?.families || []).map(f => f?.name || f).filter(Boolean);
+      const summary = {
+        url,
+        title: design.meta?.title,
+        grade: s.grade ?? null,
+        score: s.overall ?? null,
+        primary: primary
+          ? { hex: primary.hex, count: primary.count, confidence: primary.confidence ?? null }
+          : null,
+        families: families.slice(0, 3),
+        fontFamilyCount: families.length,
+        typeScale: (design.typography?.scale || []).length,
+        spacingBase: design.spacing?.base ?? null,
+        spacingScale: (design.spacing?.scale || []).length,
+        radii: (design.borders?.radii || []).length,
+        shadows: (design.shadows?.values || []).length,
+        colors: (design.colors?.all || []).length,
+        wcag: design.accessibility?.score ?? null,
+        material: design.materialLanguage?.label,
+        library: design.componentLibrary?.library,
+        tone: design.voice?.tone,
+        stack: design.stack?.framework,
+        intent: design.pageIntent?.type,
+      };
+
+      if (wantJson) {
+        if (spinner) spinner.stop();
+        process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+        return;
+      }
+
+      spinner.stop();
+      const gradeColor =
+        summary.grade === 'A' ? chalk.green
+        : summary.grade === 'B' ? chalk.cyan
+        : summary.grade === 'C' ? chalk.yellow
+        : summary.grade === 'D' ? chalk.magenta
+        : chalk.red;
+      const confTag = primary && primary.confidence != null
+        ? (primary.confidence < 0.5
+            ? chalk.yellow(`~${Math.round(primary.confidence * 100)}% conf`)
+            : chalk.gray(`${Math.round(primary.confidence * 100)}% conf`))
+        : '';
+      const line = (label, value) =>
+        `  ${chalk.gray(label.padEnd(12))} ${value}`;
+
+      console.log('');
+      console.log(`  ${chalk.bold(url)}`);
+      if (summary.title) console.log(`  ${chalk.gray(summary.title)}`);
+      console.log('');
+      console.log(line('Grade', `${gradeColor.bold(summary.grade || '—')} ${chalk.gray('·')} ${chalk.bold(String(summary.score ?? '—') + '/100')}`));
+      if (primary) {
+        console.log(line('Primary', `${chalk.bold(primary.hex)} ${chalk.gray('×' + primary.count)} ${confTag}`));
+      } else {
+        console.log(line('Primary', chalk.gray('—')));
+      }
+      if (families.length) {
+        const head = families[0];
+        const body = families[1] || head;
+        const extra = families.length > 2 ? chalk.gray(` +${families.length - 2}`) : '';
+        console.log(line('Fonts', `${head}${body && body !== head ? chalk.gray(' / ') + body : ''}${extra}`));
+      } else {
+        console.log(line('Fonts', chalk.gray('—')));
+      }
+      console.log(line('Type scale', `${summary.typeScale} sizes`));
+      console.log(line('Spacing', `${summary.spacingBase ? `base ${summary.spacingBase}px` : 'no base'} · ${summary.spacingScale} steps`));
+      console.log(line('Shape', `${summary.radii} radii · ${summary.shadows} shadows`));
+      console.log(line('Colours', `${summary.colors} tokens`));
+      console.log(line('WCAG', summary.wcag != null ? `${summary.wcag}%` : chalk.gray('—')));
+      console.log(line('Stack', [summary.stack, summary.library].filter(Boolean).join(' · ') || chalk.gray('—')));
+      console.log(line('Material', summary.material || chalk.gray('—')));
+      console.log(line('Tone', summary.tone || chalk.gray('—')));
+      console.log(line('Intent', summary.intent || chalk.gray('—')));
+      console.log('');
+    } catch (err) {
+      if (spinner) spinner.fail('Stats failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
 // ── Grade command — shareable HTML report card ─────────────
 program
   .command('grade <url>')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "12.8.0",
+  "version": "12.10.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/formatters/grade.js

@@ -124,6 +124,16 @@ export function formatGrade(design, opts = {}) {
   const ogTitle = `${host} — Grade ${s.grade}`;
   const ogDesc = `Design system audit by designlang. ${s.overall}/100 across 8 dimensions.`;
 
+  // Surface a low-confidence warning when the primary detection was uncertain
+  // (e.g. monochrome site, near-tie between top brand candidates). The field
+  // arrived in v12.9 — this card now exposes it so readers don't take the
+  // primary at face value when it's a soft pick.
+  const primaryConfidence = design.colors?.primary?.confidence;
+  const lowConfidence = typeof primaryConfidence === 'number' && primaryConfidence < 0.5;
+  const confidenceNote = lowConfidence
+    ? `<p class="confidence-note">Primary detection was low-confidence (${Math.round(primaryConfidence * 100)}%). The brand colour may be a soft pick — review the palette below.</p>`
+    : '';
+
   const dims = DIMENSIONS
     .filter(([k]) => s.scores[k] !== undefined)
     .map(([k, label, blurb]) => {
@@ -225,6 +235,20 @@ ${headHref ? `<link href="${esc(headHref)}" rel="stylesheet">` : ''}
   section > h2 { font-family: var(--display); font-weight: 400; font-size: 32px; margin: 0 0 8px; letter-spacing: -.005em; }
   section > h2 + .lead { color: var(--ink-soft); margin: 0 0 36px; max-width: 60ch; }
 
+  /* Low-confidence primary callout — only rendered when v12.9's
+     primary.confidence drops under 0.5. Soft warning, not an error. */
+  .confidence-note {
+    margin: -16px 0 32px;
+    padding: 12px 16px;
+    background: rgba(212, 145, 0, .08);
+    border-left: 2px solid #d49100;
+    border-radius: 0 4px 4px 0;
+    font-size: 14px;
+    color: var(--ink-soft);
+    max-width: 60ch;
+  }
+  [data-theme="dark"] .confidence-note { background: rgba(212, 145, 0, .14); }
+
   /* — Dimensions grid — */
   .dims { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 32px 48px; }
   @media (max-width: 640px) { .dims { grid-template-columns: 1fr; gap: 28px; } }
@@ -313,6 +337,7 @@ ${headHref ? `<link href="${esc(headHref)}" rel="stylesheet">` : ''}
     <section>
       <h2>Eight dimensions, scored.</h2>
       <p class="lead">Each dimension is graded against calibrated thresholds drawn from production design systems (Stripe, Linear, Vercel, GitHub, Apple). The number is the headline; the prose underneath is what to do next.</p>
+      ${confidenceNote}
       <div class="dims">${dims}</div>
     </section>
 

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)];
+}