designlang 10.0.0 → 10.2.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [10.2.0] — 2026-04-22
+
+**Dark mode pairing + responsive screenshots.** Joins the light & dark extractor passes into semantic pairs, and adds full-page captures at 4 breakpoints × (light, dark).
+
+### Added
+
+- **`src/extractors/dark-mode-pair.js`** — pure function that maps light ↔ dark pairs for primary/secondary/accent/background/text roles and every CSS variable that actually differs between themes. Emits a drop-in Tailwind `darkMode: 'class'` config plus an audit (tokens missing from either pass).
+- **`src/extractors/responsive-screenshots.js`** — full-page PNGs at mobile / tablet / desktop / wide × (light, dark). Writes to `screenshots/responsive/<breakpoint>-<scheme>.png` with an index.
+- New flag `--responsive-shots`. Auto-on with `--full`.
+- New outputs: `*-dark-mode.json`, `*-responsive.json`.
+
+### Changed
+
+- CLI version test now reads from `package.json` instead of a hardcoded string — no per-release test churn going forward.
+
+## [10.1.0] — 2026-04-22
+
+**Component screenshots.** The existing `--screenshots` flag now emits cluster-aware, retina (2×), multi-variant PNGs instead of five hardcoded selectors and a full-page image.
+
+### Added
+
+- **`src/extractors/component-screenshots.js`** — queries the live DOM with the same candidate selector the crawler uses, groups matches by `kind + variantHint + sizeHint`, and captures up to three representatives per group. Falls back to the v9 hardcoded list when no clusters produced anything (auth / docs pages).
+- Retina capture via a dedicated Playwright context at `deviceScaleFactor: 2`.
+- **`*-screenshots.json`** — index file mapping every cropped PNG to its cluster name, variant, bounds, and fallback flag.
+- Markdown formatter gains a **Component Screenshots** section listing the first 20 crops.
+
+### Behaviour
+
+- No new CLI flags. `--screenshots` and `--full` continue to opt into capture.
+- Backward compatible — when no clusters match, the v9 hardcoded selector set still fires.
+
+### Tests
+
+297 → **299** passing.
+
 ## [10.0.0] — 2026-04-22
 
 **The Intent Release.** v9 captured *how* a site looks; v10 captures *what it is* — the semantic layer LLM agents need to rebuild a site faithfully, not just restyle a generic scaffold. Six new extractors, a multi-page crawl orchestrator, an optional smart-classifier LLM fallback, and a ready-to-paste prompt pack. 297/297 tests passing.

package/README.md

@@ -7,6 +7,7 @@
   <a href="https://github.com/Manavarya09/design-extract/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Manavarya09/design-extract?color=0A0908&labelColor=F3F1EA" alt="license"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/designlang?color=0A0908&labelColor=F3F1EA" alt="node version"></a>
   <a href="https://designlang.manavaryasingh.com/"><img src="https://img.shields.io/badge/website-live-FF4800?labelColor=F3F1EA" alt="website"></a>
+[![SafeSkill 77/100](https://img.shields.io/badge/SafeSkill-77%2F100_Passes%20with%20Notes-yellow)](https://safeskill.dev/scan/manavarya09-design-extract)
 </p>
 
 ---

package/bin/design-extract.js

@@ -9,6 +9,9 @@ import { extractDesignLanguage } from '../src/index.js';
 import { refineWithSmart } from '../src/classifiers/smart.js';
 import { crawlCanonicalPages } from '../src/multipage.js';
 import { extractLogo } from '../src/extractors/logo.js';
+import { captureComponentScreenshotsV10 } from '../src/extractors/component-screenshots.js';
+import { pairDarkMode } from '../src/extractors/dark-mode-pair.js';
+import { captureResponsiveScreenshots } from '../src/extractors/responsive-screenshots.js';
 import { buildPromptPack } from '../src/formatters/prompt-pack.js';
 import { formatMarkdown } from '../src/formatters/markdown.js';
 import { formatTokens } from '../src/formatters/tokens.js';
@@ -52,7 +55,7 @@ const program = new Command();
 program
   .name('designlang')
   .description('Extract the complete design language from any website')
-  .version('10.0.0');
+  .version('10.2.0');
 
 // ── Main command: extract ──────────────────────────────────────
 program
@@ -84,6 +87,7 @@ program
   .option('--smart', 'use optional LLM fallback when heuristic classifiers have low confidence (needs OPENAI_API_KEY or ANTHROPIC_API_KEY)')
   .option('--pages <n>', 'crawl N canonical pages (pricing/docs/blog/about/product) in addition to the homepage', parseInt)
   .option('--no-prompts', 'skip writing the prompt-pack directory')
+  .option('--responsive-shots', 'capture full-page PNGs at 4 breakpoints × (light,dark)')
   .option('--json', 'output raw JSON to stdout (for CI/CD)')
   .option('--json-pretty', 'output formatted JSON to stdout')
   .option('--no-history', 'skip saving to history')
@@ -220,6 +224,32 @@ program
         } catch (e) { design.logo = { found: false, error: e.message }; }
       }
 
+      // v10.1: cluster-aware retina component screenshots.
+      if (merged.full || merged.screenshots) {
+        spinner.text = 'Capturing component screenshots (retina)...';
+        try {
+          design.componentScreenshots = await captureComponentScreenshotsV10(url, outDir, {
+            width: merged.width,
+            height: parseInt(merged.height) || 800,
+            channel: merged.systemChrome ? 'chrome' : undefined,
+          });
+        } catch (e) { design.componentScreenshots = { error: e.message }; }
+      }
+
+      // v10.2: dark-mode pairing (pure, based on already-extracted data).
+      design.darkModePaired = pairDarkMode(design);
+
+      // v10.2: responsive screenshots at 4 breakpoints × (light, dark).
+      if (merged.full || merged.responsiveShots) {
+        spinner.text = 'Capturing responsive screenshots...';
+        try {
+          design.responsiveShots = await captureResponsiveScreenshots(url, outDir, {
+            includeDark: merged.dark || merged.full,
+            channel: merged.systemChrome ? 'chrome' : undefined,
+          });
+        } catch (e) { design.responsiveShots = { error: e.message }; }
+      }
+
       // v10: multi-page canonical crawl (pricing/docs/blog/about/product).
       const pagesArg = merged.pages != null ? merged.pages : (merged.full ? 5 : 0);
       if (pagesArg > 0) {
@@ -306,6 +336,15 @@ program
       if (design.multiPage) {
         files.push({ name: `${prefix}-multipage.json`, content: JSON.stringify(design.multiPage, null, 2), label: 'Multi-Page Crawl' });
       }
+      if (design.componentScreenshots && (design.componentScreenshots.components || []).length) {
+        files.push({ name: `${prefix}-screenshots.json`, content: JSON.stringify(design.componentScreenshots, null, 2), label: 'Component Screenshots index' });
+      }
+      if (design.darkModePaired && design.darkModePaired.available) {
+        files.push({ name: `${prefix}-dark-mode.json`, content: JSON.stringify(design.darkModePaired, null, 2), label: 'Dark Mode Pairing' });
+      }
+      if (design.responsiveShots && Array.isArray(design.responsiveShots.shots) && design.responsiveShots.shots.length) {
+        files.push({ name: `${prefix}-responsive.json`, content: JSON.stringify(design.responsiveShots, null, 2), label: 'Responsive Screenshots index' });
+      }
       if (merged.prompts !== false) {
         const pack = buildPromptPack(design);
         const promptsDir = join(outDir, `${prefix}-prompts`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "10.0.0",
+  "version": "10.2.0",
   "description": "Extract the complete design language from any website — colors, typography, spacing, shadows, motion, component anatomy, brand voice, page intent, section roles, material language, component library, imagery style, and logo. Outputs AI-optimized markdown, W3C design tokens, motion tokens, typed component stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
   "type": "module",
   "bin": {

package/src/extractors/component-screenshots.js

@@ -0,0 +1,161 @@
+// v10.1 — Component Screenshots
+//
+// Given a Playwright Page, crop PNG screenshots for each detected component
+// cluster. We re-query the DOM using the same candidate selector the crawler
+// uses, group matches by `kind + variantHint + sizeHint`, and capture up to
+// three representatives per group at 2× retina. Writes into a `screenshots/`
+// subdirectory under the output root and returns an index the bin emits as
+// `*-screenshots.json`.
+
+import { chromium } from 'playwright';
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+
+const CANDIDATE_SELECTOR = 'button, a[role="button"], .btn, [class*="button"], input[type="text"], input[type="email"], input[type="search"], textarea, [class*="card"]';
+
+const FALLBACK_GROUPS = [
+  { slug: 'button', selector: 'button:not(:empty), a[role="button"], [class*="btn"]:not(:empty)' },
+  { slug: 'card', selector: '[class*="card"]:not(:empty)' },
+  { slug: 'input', selector: 'input[type="text"], input[type="email"], input[type="search"], textarea' },
+  { slug: 'nav', selector: 'nav, [role="navigation"]' },
+  { slug: 'hero', selector: '[class*="hero"], section:first-of-type' },
+];
+
+function slugify(s) {
+  return (s || 'component')
+    .toString()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '') || 'component';
+}
+
+async function collectClusteredHandles(page) {
+  // In-page classification mirrors what the crawler does for candidates but
+  // returns enough to screenshot (unique index so we can re-find handles).
+  const groups = await page.evaluate((sel) => {
+    const out = {};
+    let ix = 0;
+    for (const el of document.querySelectorAll(sel)) {
+      const r = el.getBoundingClientRect();
+      if (r.width < 20 || r.height < 10) continue;
+      if (r.width > window.innerWidth || r.height > window.innerHeight * 2) continue;
+      const cs = getComputedStyle(el);
+      if (cs.visibility === 'hidden' || cs.display === 'none' || parseFloat(cs.opacity) < 0.1) continue;
+
+      const tag = el.tagName.toLowerCase();
+      const cls = typeof el.className === 'string' ? el.className.toLowerCase() : '';
+      let kind = 'other';
+      if (tag === 'button' || el.getAttribute('role') === 'button' || /\bbtn\b|button/.test(cls)) kind = 'button';
+      else if (tag === 'input' || tag === 'textarea') kind = 'input';
+      else if (/card/.test(cls)) kind = 'card';
+      else if (tag === 'a') kind = 'link';
+
+      const variant = ((cls.match(/\b(primary|secondary|tertiary|ghost|outline|solid|destructive|danger|success|warning|subtle)\b/) || [])[1]) || 'default';
+      const size = ((cls.match(/\b(xs|sm|md|lg|xl|small|medium|large)\b/) || [])[1]) || '';
+
+      const key = [kind, variant, size].filter(Boolean).join('--');
+      if (!out[key]) out[key] = [];
+      el.setAttribute('data-dl-shot', String(ix));
+      out[key].push({ ix, w: Math.round(r.width), h: Math.round(r.height), kind, variant, size });
+      ix++;
+    }
+    return out;
+  }, CANDIDATE_SELECTOR);
+  return groups;
+}
+
+async function captureGroup(page, key, entries, screenshotDir, maxPerGroup = 3) {
+  const out = [];
+  const slug = slugify(key);
+  let variant = 0;
+  for (const info of entries.slice(0, maxPerGroup)) {
+    const handle = await page.$(`[data-dl-shot="${info.ix}"]`);
+    if (!handle) continue;
+    const file = `${slug}-${variant}.png`;
+    const path = join(screenshotDir, file);
+    try {
+      await handle.screenshot({ path, omitBackground: false });
+    } catch { continue; }
+    out.push({
+      cluster: key,
+      variant,
+      path: `screenshots/${file}`,
+      bounds: { w: info.w, h: info.h },
+      kind: info.kind,
+      variantHint: info.variant,
+      sizeHint: info.size,
+      retina: true,
+    });
+    variant++;
+  }
+  return out;
+}
+
+async function captureFallbacks(page, screenshotDir) {
+  const out = [];
+  for (const g of FALLBACK_GROUPS) {
+    try {
+      const handles = await page.$$(g.selector);
+      for (const h of handles.slice(0, 2)) {
+        const box = await h.boundingBox();
+        if (!box || box.width < 20 || box.height < 10) continue;
+        const path = join(screenshotDir, `${g.slug}-${out.filter(x => x.cluster === g.slug).length}.png`);
+        await h.screenshot({ path });
+        out.push({
+          cluster: g.slug,
+          variant: out.filter(x => x.cluster === g.slug).length,
+          path: `screenshots/${path.split('screenshots/')[1]}`,
+          bounds: { w: Math.round(box.width), h: Math.round(box.height) },
+          retina: true,
+          fallback: true,
+        });
+      }
+    } catch { /* skip */ }
+  }
+  return out;
+}
+
+// Public entry. Launches a fresh Playwright context at deviceScaleFactor: 2
+// so captures are crisp on retina displays without a second full run.
+export async function captureComponentScreenshotsV10(url, outDir, { width = 1280, height = 800, channel } = {}) {
+  const screenshotDir = join(outDir, 'screenshots');
+  mkdirSync(screenshotDir, { recursive: true });
+
+  const browser = await chromium.launch({ headless: true, ...(channel && { channel }) });
+  try {
+    const context = await browser.newContext({
+      viewport: { width, height },
+      deviceScaleFactor: 2,
+      colorScheme: 'light',
+    });
+    const page = await context.newPage();
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => {});
+    await page.waitForLoadState('networkidle').catch(() => {});
+    await page.evaluate(() => document.fonts.ready).catch(() => {});
+
+    const groups = await collectClusteredHandles(page);
+    let components = [];
+    for (const [key, entries] of Object.entries(groups)) {
+      if (!entries.length) continue;
+      const rows = await captureGroup(page, key, entries, screenshotDir);
+      components.push(...rows);
+    }
+
+    // If clustering produced nothing (auth / docs pages often do), fall back
+    // to the v9 hardcoded selector list so users still get something.
+    if (!components.length) {
+      components = await captureFallbacks(page, screenshotDir);
+    }
+
+    let fullPage = null;
+    try {
+      const p = join(screenshotDir, 'full-page.png');
+      await page.screenshot({ path: p, fullPage: true });
+      fullPage = { path: 'screenshots/full-page.png', retina: true };
+    } catch { /* non-fatal */ }
+
+    return { components, fullPage, count: components.length };
+  } finally {
+    await browser.close();
+  }
+}

package/src/extractors/dark-mode-pair.js

@@ -0,0 +1,96 @@
+// v10.2 — Dark Mode Pairing
+//
+// When the user passes --dark the crawler runs a second pass under
+// `color-scheme: dark` and the main extractor emits `design.darkMode` with
+// parallel colors + CSS variable maps. This module joins the two halves into
+// *semantic pairs* — same role in light mode ↔ same role in dark mode — so
+// downstream consumers (prompt pack, Tailwind darkMode config, agents) can
+// author a single `[data-theme="dark"]` override block without guessing.
+//
+// Pure function. No Page handle, no side effects — takes the finished design
+// object and returns a plain JSON structure.
+
+function hexOf(c) {
+  if (!c) return null;
+  if (typeof c === 'string') return c.toLowerCase();
+  return (c.hex || '').toLowerCase();
+}
+
+function pairRoleColors(light = {}, dark = {}) {
+  const pairs = {};
+  for (const role of ['primary', 'secondary', 'accent']) {
+    const l = hexOf(light[role]);
+    const d = hexOf(dark[role]);
+    if (l || d) pairs[role] = { light: l, dark: d };
+  }
+  const bgPair = {
+    light: (light.backgrounds?.[0]?.hex || null),
+    dark: (dark.backgrounds?.[0]?.hex || null),
+  };
+  if (bgPair.light || bgPair.dark) pairs.background = bgPair;
+  const textPair = {
+    light: (light.text?.[0]?.hex || null),
+    dark: (dark.text?.[0]?.hex || null),
+  };
+  if (textPair.light || textPair.dark) pairs.text = textPair;
+  return pairs;
+}
+
+function pairVariables(lightVars = {}, darkVars = {}) {
+  // Walk the union of keys; emit light/dark only when values differ.
+  const keys = new Set([...Object.keys(lightVars || {}), ...Object.keys(darkVars || {})]);
+  const out = {};
+  for (const k of keys) {
+    const l = lightVars[k];
+    const d = darkVars[k];
+    if (l == null && d == null) continue;
+    if (typeof l === 'string' && typeof d === 'string' && l === d) continue;
+    out[k] = { light: l ?? null, dark: d ?? null };
+  }
+  return out;
+}
+
+export function pairDarkMode(design = {}) {
+  if (!design.darkMode) {
+    return { available: false, reason: 'no --dark pass captured' };
+  }
+  const lightColors = design.colors || {};
+  const darkColors = design.darkMode.colors || {};
+  const roles = pairRoleColors(lightColors, darkColors);
+  const variables = pairVariables(design.variables || {}, design.darkMode.variables || {});
+  const pairedVarCount = Object.keys(variables).length;
+
+  // Light colors that don't appear in dark (and vice versa) signal tokens the
+  // site forgot to theme — useful for an audit.
+  const lightSet = new Set((lightColors.all || []).map(c => (c.hex || '').toLowerCase()).filter(Boolean));
+  const darkSet = new Set((darkColors.all || []).map(c => (c.hex || '').toLowerCase()).filter(Boolean));
+  const missingInDark = [...lightSet].filter(x => !darkSet.has(x)).slice(0, 20);
+  const missingInLight = [...darkSet].filter(x => !lightSet.has(x)).slice(0, 20);
+
+  // Tailwind-ready config snippet.
+  const tailwind = {
+    darkMode: 'class',
+    theme: {
+      extend: {
+        colors: Object.fromEntries(
+          Object.entries(roles)
+            .filter(([, v]) => v.light && v.dark)
+            .map(([role, v]) => [role, { DEFAULT: v.light, dark: v.dark }]),
+        ),
+      },
+    },
+  };
+
+  return {
+    available: true,
+    roles,
+    variables,
+    pairedVarCount,
+    audit: {
+      missingInDark,
+      missingInLight,
+      coverage: pairedVarCount > 0 ? 'paired' : 'light-only-vars',
+    },
+    tailwind,
+  };
+}

package/src/extractors/responsive-screenshots.js

@@ -0,0 +1,55 @@
+// v10.2 — Responsive Screenshots
+//
+// Full-page PNGs at each breakpoint × (light, dark). Lives alongside the
+// component screenshots dir so output stays organised. Writes to
+// `screenshots/responsive/<breakpoint>-<scheme>.png` and returns an index.
+
+import { chromium } from 'playwright';
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+
+const BREAKPOINTS = [
+  { slug: 'mobile', width: 375, height: 812 },
+  { slug: 'tablet', width: 768, height: 1024 },
+  { slug: 'desktop', width: 1280, height: 800 },
+  { slug: 'wide', width: 1920, height: 1080 },
+];
+
+async function captureAt(url, dir, bp, scheme, channel) {
+  const browser = await chromium.launch({ headless: true, ...(channel && { channel }) });
+  try {
+    const ctx = await browser.newContext({
+      viewport: { width: bp.width, height: bp.height },
+      deviceScaleFactor: bp.slug === 'mobile' ? 2 : 1,
+      colorScheme: scheme,
+    });
+    const page = await ctx.newPage();
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => {});
+    await page.waitForLoadState('networkidle').catch(() => {});
+    await page.evaluate(() => document.fonts.ready).catch(() => {});
+    const file = `${bp.slug}-${scheme}.png`;
+    const path = join(dir, file);
+    await page.screenshot({ path, fullPage: true });
+    return { breakpoint: bp.slug, scheme, width: bp.width, path: `screenshots/responsive/${file}` };
+  } finally {
+    await browser.close();
+  }
+}
+
+export async function captureResponsiveScreenshots(url, outDir, { includeDark = true, channel } = {}) {
+  const dir = join(outDir, 'screenshots', 'responsive');
+  mkdirSync(dir, { recursive: true });
+  const out = [];
+  const schemes = includeDark ? ['light', 'dark'] : ['light'];
+  for (const bp of BREAKPOINTS) {
+    for (const scheme of schemes) {
+      try {
+        const row = await captureAt(url, dir, bp, scheme, channel);
+        out.push(row);
+      } catch (e) {
+        out.push({ breakpoint: bp.slug, scheme, error: e.message });
+      }
+    }
+  }
+  return { count: out.filter(r => !r.error).length, shots: out };
+}

package/src/formatters/markdown.js

@@ -802,6 +802,24 @@ export function formatMarkdown(design) {
     }
   }
 
+  // ── v10.1: Component Screenshots ──
+  if (design.componentScreenshots && Array.isArray(design.componentScreenshots.components) && design.componentScreenshots.components.length) {
+    lines.push('## Component Screenshots');
+    lines.push('');
+    lines.push(`${design.componentScreenshots.components.length} retina crops written to \`screenshots/\`. Index: \`*-screenshots.json\`.`);
+    lines.push('');
+    lines.push('| Cluster | Variant | Size (px) | File |');
+    lines.push('|---------|---------|-----------|------|');
+    for (const c of design.componentScreenshots.components.slice(0, 20)) {
+      lines.push(`| ${c.cluster} | ${c.variant} | ${c.bounds?.w || '?'} × ${c.bounds?.h || '?'} | \`${c.path}\` |`);
+    }
+    if (design.componentScreenshots.fullPage) {
+      lines.push('');
+      lines.push(`Full-page: \`${design.componentScreenshots.fullPage.path}\``);
+    }
+    lines.push('');
+  }
+
   // ── Quick Start ──
   lines.push('## Quick Start');
   lines.push('');

package/src/index.js

@@ -202,6 +202,9 @@ export { extractComponentLibrary } from './extractors/component-library.js';
 export { extractMaterialLanguage } from './extractors/material-language.js';
 export { extractImageryStyle } from './extractors/imagery-style.js';
 export { extractLogo } from './extractors/logo.js';
+export { captureComponentScreenshotsV10 } from './extractors/component-screenshots.js';
+export { pairDarkMode } from './extractors/dark-mode-pair.js';
+export { captureResponsiveScreenshots } from './extractors/responsive-screenshots.js';
 export { refineWithSmart } from './classifiers/smart.js';
 export { crawlCanonicalPages, computeCrossPageConsistency, discoverCanonicalPages } from './multipage.js';
 export { buildPromptPack, formatV0Prompt, formatLovablePrompt, formatCursorPrompt, formatClaudeArtifactPrompt } from './formatters/prompt-pack.js';