dembrandt 0.11.0 → 0.12.1

package/README.md

@@ -6,7 +6,7 @@
 
 Extract a website's design system into design tokens in a few seconds: logo, colors, typography, borders, and more. One command.
 
-![Dembrandt — Any website to design tokens](https://raw.githubusercontent.com/dembrandt/dembrandt/main/docs/images/banner.png)
+![Dembrandt: Any website to design tokens](https://raw.githubusercontent.com/dembrandt/dembrandt/main/docs/images/banner.png)
 
 ## Install
 
@@ -77,7 +77,7 @@ Default: formatted terminal display only. Use `--save-output` to persist results
 
 ### Multi-Page Extraction
 
-Analyze multiple pages to get a more complete picture of a site's design system. Results are merged into a single unified output with cross-page confidence boosting — tokens appearing on multiple pages get higher confidence scores.
+Analyze multiple pages to get a more complete picture of a site's design system. Results are merged into a single unified output with cross-page confidence boosting: tokens appearing on multiple pages get higher confidence scores.
 
 ```bash
 # Analyze homepage + 4 auto-discovered pages (default: 5 total)
@@ -133,7 +133,7 @@ The DTCG format is an industry-standard JSON schema that can be consumed by desi
 
 ### DESIGN.md
 
-Use `--design-md` to generate a [DESIGN.md](https://stitch.withgoogle.com/docs/design-md) file — a plain-text design system document readable by AI agents.
+Use `--design-md` to generate a [DESIGN.md](https://stitch.withgoogle.com/docs/design-md) file, a plain-text design system document readable by AI agents.
 
 ```bash
 dembrandt example.com --design-md
@@ -142,7 +142,7 @@ dembrandt example.com --design-md
 
 ### Brand Guide PDF
 
-Use `--brand-guide` to generate a printable PDF summarizing the extracted design system — colors, typography, components, and logo on a single document.
+Use `--brand-guide` to generate a printable PDF summarizing the extracted design system: colors, typography, components, and logo on a single document.
 
 ```bash
 dembrandt example.com --brand-guide
@@ -176,10 +176,63 @@ Opens http://localhost:5173 with API on port 3002.
 - Spacing, shadows, border radius visualization
 - Button and link component previews
 - Dark/light theme toggle
-- Section nav links on extraction pages — jump directly to Colors, Typography, Shadows, etc. via a sticky sidebar
+- Section nav links on extraction pages, jump directly to Colors, Typography, Shadows, etc. via a sticky sidebar
 
 Extractions are performed via CLI (`dembrandt <url> --save-output`) and automatically appear in the UI.
 
+## Recipes
+
+**Quick brand scan**
+```bash
+dembrandt stripe.com
+```
+
+**Compare two sites**
+```bash
+dembrandt stripe.com --save-output
+dembrandt braintree.com --save-output
+# Compare output/stripe.com and output/braintree.com side by side
+```
+
+**Multi-page audit** — get a fuller picture across the whole site
+```bash
+dembrandt stripe.com --pages 10 --sitemap --save-output
+```
+
+**Spot-check a value** — verify a specific token fast
+```bash
+dembrandt stripe.com --json-only | grep -i "border-radius"
+```
+
+**Export for Tailwind** — get spacing and color values into your config
+```bash
+dembrandt stripe.com --dtcg --save-output
+# Use the .tokens.json with Style Dictionary to generate tailwind.config.js
+```
+
+**Export for Tokens Studio / Figma**
+```bash
+dembrandt stripe.com --dtcg --save-output
+# Import the .tokens.json directly into Tokens Studio
+```
+
+**Generate DESIGN.md for your AI agent**
+```bash
+dembrandt stripe.com --design-md
+# Point your agent at the output DESIGN.md
+```
+
+**Regression baseline** — snapshot now, catch drift later
+```bash
+dembrandt myapp.com --save-output --dtcg
+# Store output as baseline, re-run after deploys and diff
+```
+
+**CI / headless environments**
+```bash
+dembrandt myapp.com --no-sandbox --save-output
+```
+
 ## Use Cases
 
 - Design system documentation
@@ -204,9 +257,9 @@ Uses Playwright to render the page, reads computed styles from the DOM, analyzes
 
 ### Color Confidence
 
-- High — Logo, primary interactive elements
-- Medium — Secondary interactive elements, icons, navigation
-- Low — Generic UI components (filtered from display)
+- High: Logo, primary interactive elements
+- Medium: Secondary interactive elements, icons, navigation
+- Low: Generic UI components (filtered from display)
 - Only shows high and medium confidence colors in terminal. Full palette in JSON.
 
 ## Limitations
@@ -228,12 +281,10 @@ Dembrandt does not host, redistribute, or claim rights to any third-party brand
 
 ## Contributing
 
-Bugs, weird sites, pull requests — all welcome.
+Bugs, weird sites, pull requests. All welcome.
 
 Open an [Issue](https://github.com/dembrandt/dembrandt/issues) or PR.
 
 @thevangelist
 
----
-
-MIT — do whatever you want with it.
+MIT. Do whatever you want with it.

package/index.js

@@ -11,23 +11,27 @@ import { program } from "commander";
 import chalk from "chalk";
 import ora from "ora";
 import { chromium, firefox } from "playwright-core";
-import { extractBranding } from "./lib/extractors.js";
-import { displayResults } from "./lib/display.js";
-import { toW3CFormat } from "./lib/w3c-exporter.js";
-import { generatePDF } from "./lib/pdf.js";
-import { generateDesignMd } from "./lib/design-md.js";
+import { extractBranding } from "./lib/extractors/index.js";
+import { displayResults } from "./lib/formatters/terminal.js";
+import { toW3CFormat } from "./lib/formatters/w3c.js";
+import { generatePDF } from "./lib/formatters/pdf.js";
+import { generateDesignMd } from "./lib/formatters/markdown.js";
 import { parseSitemap } from "./lib/discovery.js";
 import { mergeResults } from "./lib/merger.js";
-import { writeFileSync, mkdirSync } from "fs";
-import { join } from "path";
+import { writeFileSync, mkdirSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
 import { checkRobotsTxt } from "./lib/robots.js";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const { version } = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8"));
+
 program
   .name("dembrandt")
   .description("Extract design tokens from any website")
-  .version("0.11.0")
+  .version(version)
   .argument("<url>")
-  .option("--browser <type>", "Browser to use (chromium|firefox)", "chromium")
+  .option("--browser <type>", "Browser to use (chromium|firefox); set BROWSER_CDP_ENDPOINT env var to connect to an existing Chromium instance via CDP", "chromium")
   .option("--json-only", "Output raw JSON")
   .option("--save-output", "Save JSON file to output folder")
   .option("--dtcg", "Export in W3C Design Tokens (DTCG) format")
@@ -39,6 +43,7 @@ program
   .option("--no-sandbox", "Disable browser sandbox (needed for Docker/CI)")
   .option("--raw-colors", "Include pre-filter raw colors in JSON output")
   .option("--screenshot <path>", "Save a screenshot of the page")
+  .option("--wcag", "Analyze WCAG contrast ratios between palette colors")
   .option("--pages <n>", "Analyze up to N total pages including start URL (default: 5)", (v) => {
     const n = parseInt(v, 10);
     if (isNaN(n) || n < 1) throw new Error(`--pages must be a positive integer, got: ${v}`);
@@ -93,10 +98,18 @@ program
         if (opts.noSandbox && opts.browser === 'chromium') {
           launchArgs.push("--no-sandbox", "--disable-setuid-sandbox");
         }
-        browser = await browserType.launch({
-          headless: !useHeaded,
-          args: launchArgs,
-        });
+        if (process.env.BROWSER_CDP_ENDPOINT) {
+          if (opts.browser !== 'chromium') {
+            throw new Error("BROWSER_CDP_ENDPOINT is only supported with --browser chromium.");
+          }
+          spinner.text = "Connecting over CDP...";
+          browser = await browserType.connectOverCDP(process.env.BROWSER_CDP_ENDPOINT);
+        } else {
+          browser = await browserType.launch({
+            headless: !useHeaded,
+            args: launchArgs,
+          });
+        }
 
         try {
           const isMultiPage = opts.pages || opts.sitemap;
@@ -108,6 +121,7 @@ program
             slow: opts.slow,
             screenshotPath: opts.screenshot,
             discoverLinks: isMultiPage && !opts.sitemap ? maxPages : null,
+            wcag: opts.wcag,
           });
 
           // Multi-page crawl
@@ -170,7 +184,7 @@ program
           await browser.close();
           browser = null;
 
-          if (useHeaded) throw err;
+          if (useHeaded || process.env.BROWSER_CDP_ENDPOINT) throw err;
 
           if (
             err.message.includes("Timeout") ||

package/lib/colors.js

@@ -228,6 +228,52 @@ export function hexToRgb(hex) {
   return null;
 }
 
+/**
+ * Compute WCAG 2.1 relative luminance for a hex color.
+ * @param {string} hex
+ * @returns {number|null}
+ */
+export function relativeLuminance(hex) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return null;
+  return 0.2126 * srgbToLinear(rgb.r) + 0.7152 * srgbToLinear(rgb.g) + 0.0722 * srgbToLinear(rgb.b);
+}
+
+/**
+ * Compute WCAG contrast ratios for all pairs in a color palette.
+ * @param {Array<{color: string, normalized: string, confidence: string}>} palette
+ * @returns {Array<{fg: string, bg: string, ratio: number, aa: boolean, aaLarge: boolean, aaa: boolean}>}
+ */
+export function computeWcag(palette) {
+  const colors = palette
+    .filter(c => c.normalized && c.normalized.startsWith('#'))
+    .slice(0, 10);
+
+  const pairs = [];
+  for (let i = 0; i < colors.length; i++) {
+    for (let j = i + 1; j < colors.length; j++) {
+      const l1 = relativeLuminance(colors[i].normalized);
+      const l2 = relativeLuminance(colors[j].normalized);
+      if (l1 === null || l2 === null) continue;
+      const lighter = Math.max(l1, l2);
+      const darker = Math.min(l1, l2);
+      const ratio = (lighter + 0.05) / (darker + 0.05);
+      const fg = l1 >= l2 ? colors[i].normalized : colors[j].normalized;
+      const bg = l1 >= l2 ? colors[j].normalized : colors[i].normalized;
+      pairs.push({
+        fg,
+        bg,
+        ratio: Math.round(ratio * 100) / 100,
+        aa: ratio >= 4.5,
+        aaLarge: ratio >= 3,
+        aaa: ratio >= 7,
+      });
+    }
+  }
+
+  return pairs.sort((a, b) => b.ratio - a.ratio);
+}
+
 /**
  * Convert any supported color format to all formats
  * @param {string} colorString - Color in hex, rgb(), or rgba() format

package/lib/extractors/breakpoints.js

@@ -0,0 +1,251 @@
+export async function extractBreakpoints(page) {
+  return await page.evaluate(() => {
+    const breakpoints = new Set();
+
+    for (const sheet of document.styleSheets) {
+      try {
+        for (const rule of sheet.cssRules || []) {
+          if (rule.media) {
+            const match = rule.media.mediaText.match(/(\d+)px/g);
+            if (match) match.forEach((m) => breakpoints.add(parseInt(m)));
+          }
+        }
+      } catch (e) {}
+    }
+
+    return Array.from(breakpoints)
+      .sort((a, b) => a - b)
+      .map((px) => ({ px: px + "px" }));
+  });
+}
+
+export async function detectIconSystem(page) {
+  return await page.evaluate(() => {
+    const systems = [];
+
+    if (document.querySelector('[class*="fa-"]')) {
+      systems.push({ name: "Font Awesome", type: "icon-font" });
+    }
+    if (document.querySelector('[class*="material-icons"]')) {
+      systems.push({ name: "Material Icons", type: "icon-font" });
+    }
+    if (document.querySelector('svg[class*="heroicon"]') || document.querySelector('svg[data-slot="icon"]')) {
+      systems.push({ name: "Heroicons", type: "svg" });
+    }
+    if (document.querySelector('svg[class*="hugeicons"]') || document.querySelector('[class*="hugeicons-"]')) {
+      systems.push({ name: "Hugeicons", type: "svg" });
+    }
+    if (document.querySelector('ion-icon') || document.querySelector('[class*="ionicons"]')) {
+      systems.push({ name: "Ionicons", type: "svg" });
+    }
+    if (document.querySelector('svg[data-feather]') || document.querySelector('i[data-feather]') || document.querySelector('[class*="feather-"]')) {
+      systems.push({ name: "Feather Icons", type: "svg" });
+    }
+    if (document.querySelector('svg[class*="icon"]')) {
+      systems.push({ name: "SVG Icons", type: "svg" });
+    }
+
+    return systems;
+  });
+}
+
+export async function detectFrameworks(page) {
+  return await page.evaluate(() => {
+    const frameworks = [];
+    const html = document.documentElement.outerHTML;
+    const body = document.body;
+
+    function countMatches(selector) {
+      try {
+        return document.querySelectorAll(selector).length;
+      } catch {
+        return 0;
+      }
+    }
+
+    function hasResource(pattern) {
+      const links = Array.from(document.querySelectorAll('link[href], script[src]'));
+      return links.some(el => pattern.test(el.href || el.src));
+    }
+
+    // Tailwind CSS
+    const tailwindEvidence = [];
+    if (/\b\w+-\[[^\]]+\]/.test(html)) tailwindEvidence.push('arbitrary values (e.g., top-[117px])');
+    if (/(sm|md|lg|xl|2xl|dark|hover|focus|group-hover|peer-):[a-z]/.test(html)) tailwindEvidence.push('responsive/state modifiers');
+    if (hasResource(/tailwindcss|tailwind\.css|cdn\.tailwindcss/)) tailwindEvidence.push('stylesheet');
+    if (tailwindEvidence.length >= 2) {
+      frameworks.push({ name: 'Tailwind CSS', confidence: 'high', evidence: tailwindEvidence.join(', ') });
+    }
+
+    // Bootstrap
+    const bootstrapEvidence = [];
+    const hasContainer = countMatches('.container, .container-fluid') > 0;
+    const hasRow = countMatches('.row') > 0;
+    const hasCol = countMatches('[class*="col-"]') > 0;
+    if (hasContainer && hasRow && hasCol) bootstrapEvidence.push('grid system (container + row + col)');
+    if (/\bbtn-primary\b|\bbtn-secondary\b|\bbtn-success\b/.test(html)) bootstrapEvidence.push('button variants');
+    if (hasResource(/bootstrap\.min\.css|bootstrap\.css|getbootstrap\.com/)) bootstrapEvidence.push('stylesheet');
+    if (bootstrapEvidence.length >= 2) {
+      frameworks.push({ name: 'Bootstrap', confidence: 'high', evidence: bootstrapEvidence.join(', ') });
+    }
+
+    // Material UI (MUI)
+    const muiCount = countMatches('[class*="MuiBox-"], [class*="MuiButton-"], [class*="Mui"]');
+    if (muiCount > 3) frameworks.push({ name: 'Material UI (MUI)', confidence: 'high', evidence: `${muiCount} MUI components` });
+
+    // Chakra UI
+    const chakraCount = countMatches('[class*="chakra-"]');
+    if (chakraCount > 3) frameworks.push({ name: 'Chakra UI', confidence: 'high', evidence: `${chakraCount} Chakra components` });
+
+    // Ant Design
+    const antCount = countMatches('[class^="ant-"], [class*=" ant-"]');
+    if (antCount > 3) frameworks.push({ name: 'Ant Design', confidence: 'high', evidence: `${antCount} Ant components` });
+
+    // Vuetify
+    const vuetifySpecific = countMatches('[class*="v-btn"], [class*="v-card"], [class*="v-app"], [class*="v-toolbar"], [class*="v-navigation"], [class*="v-list"], [class*="v-sheet"]');
+    const hasVuetifyTheme = body.classList.contains('theme--light') || body.classList.contains('theme--dark');
+    const hasVuetifyApp = countMatches('[class*="v-application"]') > 0;
+    if ((vuetifySpecific > 8 && hasVuetifyApp) || (hasVuetifyTheme && vuetifySpecific > 5)) {
+      frameworks.push({ name: 'Vuetify', confidence: 'high', evidence: `${vuetifySpecific} Vuetify components` });
+    }
+
+    // Shopify Polaris
+    const polarisCount = countMatches('[class*="Polaris-"]');
+    if (polarisCount > 2) frameworks.push({ name: 'Shopify Polaris', confidence: 'high', evidence: `${polarisCount} Polaris components` });
+
+    // Radix UI
+    const radixCount = document.querySelectorAll('[data-radix-], [data-state]').length;
+    if (radixCount > 5) frameworks.push({ name: 'Radix UI', confidence: 'high', evidence: `${radixCount} Radix primitives` });
+
+    // DaisyUI
+    if (tailwindEvidence.length >= 2) {
+      const daisySpecific = countMatches('.btn-primary.btn, .badge, .drawer, .swap, .mockup-code');
+      const hasDaisyTheme = body.hasAttribute('data-theme');
+      if (daisySpecific > 3 || hasDaisyTheme) {
+        frameworks.push({ name: 'DaisyUI', confidence: 'high', evidence: `Tailwind + ${daisySpecific} DaisyUI components` });
+      }
+    }
+
+    // Foundation
+    const foundationEvidence = [];
+    if (countMatches('.grid-x, .grid-y, .cell') > 0 || countMatches('.button.primary, .button.secondary') > 0) foundationEvidence.push('grid/button system');
+    if (hasResource(/foundation\.min\.css|foundation\.css|zurb\.com\/foundation/)) foundationEvidence.push('stylesheet');
+    if (foundationEvidence.length >= 1 || countMatches('[data-foundation]') > 0) {
+      frameworks.push({ name: 'Foundation', confidence: 'high', evidence: foundationEvidence.join(', ') || 'data attributes' });
+    }
+
+    // Bulma
+    const bulmaEvidence = [];
+    if (countMatches('.columns, .column') > 0 && countMatches('.column') > 2) bulmaEvidence.push('columns system');
+    if (/\bbutton is-primary\b|\bbutton is-link\b/.test(html)) bulmaEvidence.push('button modifiers');
+    if (hasResource(/bulma\.min\.css|bulma\.css/)) bulmaEvidence.push('stylesheet');
+    if (bulmaEvidence.length >= 2) frameworks.push({ name: 'Bulma', confidence: 'high', evidence: bulmaEvidence.join(', ') });
+
+    // Semantic UI
+    const semanticCount = countMatches('.ui.button, .ui.menu, .ui.card, .ui.grid');
+    if (semanticCount > 3 || hasResource(/semantic\.min\.css|semantic-ui/)) {
+      frameworks.push({ name: 'Semantic UI', confidence: 'high', evidence: `${semanticCount} .ui components` });
+    }
+
+    // UIkit
+    const uikitCount = countMatches('[class*="uk-"], [uk-grid], [uk-navbar]');
+    if (uikitCount > 3 || hasResource(/uikit\.min\.css|getuikit\.com/)) {
+      frameworks.push({ name: 'UIkit', confidence: 'high', evidence: `${uikitCount} uk- components` });
+    }
+
+    // shadcn/ui
+    const shadcnClasses = /\bcn\(|\bslot-\w+|\bdata-\[state=/.test(html);
+    const hasShadcnComponents = countMatches('[data-slot], [data-state]') > 5;
+    if (tailwindEvidence.length >= 2 && radixCount > 3 && (shadcnClasses || hasShadcnComponents)) {
+      frameworks.push({ name: 'shadcn/ui', confidence: 'medium', evidence: 'Tailwind + Radix + component patterns' });
+    }
+
+    // Headless UI
+    const headlessCount = document.querySelectorAll('[aria-controls][aria-expanded], [role="dialog"][data-headlessui]').length;
+    if (tailwindEvidence.length >= 2 && headlessCount > 2) {
+      frameworks.push({ name: 'Headless UI', confidence: 'high', evidence: `${headlessCount} headless components with Tailwind` });
+    }
+
+    // PrimeReact/Vue/NG
+    const primeCount = countMatches('[class*="p-"], .p-component, .p-button, .p-datatable');
+    if (primeCount > 5) frameworks.push({ name: 'PrimeReact/Vue/NG', confidence: 'high', evidence: `${primeCount} Prime components` });
+
+    // Mantine
+    const mantineCount = countMatches('[class*="mantine-"], [data-mantine]');
+    if (mantineCount > 3) frameworks.push({ name: 'Mantine', confidence: 'high', evidence: `${mantineCount} Mantine components` });
+
+    // Carbon Design System
+    const carbonCount = countMatches('[class*="cds--"], [class*="bx--"]');
+    if (carbonCount > 3) frameworks.push({ name: 'Carbon Design System', confidence: 'high', evidence: `${carbonCount} Carbon components` });
+
+    // Fluent UI
+    const fluentCount = countMatches('[class*="ms-"], .ms-Button, .ms-TextField');
+    if (fluentCount > 5) frameworks.push({ name: 'Fluent UI', confidence: 'high', evidence: `${fluentCount} Fluent components` });
+
+    // Quasar
+    const quasarCount = countMatches('[class*="q-"]');
+    if (quasarCount > 5 || body.classList.contains('q-app')) {
+      frameworks.push({ name: 'Quasar', confidence: 'high', evidence: `${quasarCount} q- components` });
+    }
+
+    // Element Plus/UI
+    const elementCount = countMatches('[class*="el-"]');
+    if (elementCount > 5) frameworks.push({ name: 'Element Plus/UI', confidence: 'high', evidence: `${elementCount} el- components` });
+
+    return frameworks;
+  });
+}
+
+export async function extractGradients(page) {
+  return await page.evaluate(() => {
+    const seen = new Map();
+
+    const els = document.querySelectorAll('*');
+    let checked = 0;
+    for (const el of els) {
+      if (checked++ > 2000) break;
+      if (el.style.backgroundImage === 'none') continue;
+      if (el.offsetWidth === 0 && el.offsetHeight === 0) continue;
+      const s = getComputedStyle(el);
+      const bg = s.backgroundImage;
+      if (!bg || bg === 'none') continue;
+
+      const gradients = [];
+      let depth = 0, start = 0;
+      for (let i = 0; i < bg.length; i++) {
+        if (bg[i] === '(') depth++;
+        else if (bg[i] === ')') depth--;
+        else if (bg[i] === ',' && depth === 0) {
+          gradients.push(bg.slice(start, i).trim());
+          start = i + 1;
+        }
+      }
+      gradients.push(bg.slice(start).trim());
+
+      for (const grad of gradients) {
+        if (!/^(repeating-)?(linear|radial|conic)-gradient/.test(grad)) continue;
+
+        const base = grad.replace(/^repeating-/, '');
+        const repeating = grad.startsWith('repeating-');
+        const type = (base.startsWith('linear') ? 'linear' : base.startsWith('radial') ? 'radial' : 'conic') + (repeating ? '-repeating' : '');
+
+        const key = grad.replace(/\s+/g, ' ');
+        if (seen.has(key)) {
+          seen.get(key).count++;
+          continue;
+        }
+
+        const stopColors = [];
+        const stopRe = /#[0-9a-f]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\)|oklch\([^)]+\)|oklab\([^)]+\)/gi;
+        let m;
+        while ((m = stopRe.exec(grad)) !== null) stopColors.push(m[0]);
+
+        seen.set(key, { gradient: key, type, stopColors, count: 1 });
+      }
+    }
+
+    return Array.from(seen.values())
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 20);
+  });
+}