dembrandt 0.12.0 → 0.12.2

package/README.md

@@ -71,6 +71,7 @@ dembrandt example.com --sitemap        # Discover pages from sitemap.xml instead
 dembrandt example.com --pages 10 --sitemap # Combine: up to 10 pages discovered via sitemap
 dembrandt example.com --no-sandbox     # Disable Chromium sandbox (required for Docker/CI)
 dembrandt example.com --browser=firefox # Use Firefox instead of Chromium (better for Cloudflare bypass)
+dembrandt example.com --wcag           # WCAG 2.1 contrast analysis — real DOM pairs, AA/AAA grades
 ```
 
 Default: formatted terminal display only. Use `--save-output` to persist results as JSON files. Browser automatically retries in visible mode if headless extraction fails.
@@ -140,6 +141,16 @@ dembrandt example.com --design-md
 # Saves to: output/example.com/DESIGN.md
 ```
 
+### WCAG Contrast Analysis
+
+Use `--wcag` to check accessibility contrast ratios across the page. Unlike palette-based checkers, dembrandt walks the actual DOM and finds what color is rendered on top of what background — per element.
+
+```bash
+dembrandt stripe.com --wcag
+```
+
+Returns every text/background pair with contrast ratio and WCAG 2.1 grade (AA, AA-Large, AAA, or fail), sorted by how often each pair appears. Results are shown in terminal and included in JSON output as `wcag`.
+
 ### 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.
@@ -180,6 +191,64 @@ Opens http://localhost:5173 with API on port 3002.
 
 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
+```
+
+**Accessibility audit** — check contrast on any live URL
+```bash
+dembrandt stripe.com --wcag
+```
+
+**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

package/index.js

@@ -11,21 +11,25 @@ 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); set BROWSER_CDP_ENDPOINT env var to connect to an existing Chromium instance via CDP", "chromium")
   .option("--json-only", "Output raw JSON")
@@ -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}`);
@@ -116,6 +121,7 @@ program
             slow: opts.slow,
             screenshotPath: opts.screenshot,
             discoverLinks: isMultiPage && !opts.sitemap ? maxPages : null,
+            wcag: opts.wcag,
           });
 
           // Multi-page crawl

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