dembrandt 0.6.1 → 0.7.1

package/README.md

@@ -6,7 +6,19 @@
 
 Extract any website’s design system into design tokens in a few seconds: logo, colors, typography, borders, and more. One command.
 
-![Dembrandt Demo](showcase.png)
+![Dembrandt — Any website to design tokens](https://raw.githubusercontent.com/dembrandt/dembrandt/main/docs/images/banner.png)
+
+**CLI output**
+
+![CLI extraction of netflix.com](https://raw.githubusercontent.com/dembrandt/dembrandt/main/docs/images/cli-output.png)
+
+**Brand Guide PDF**
+
+![Brand guide PDF extracted from any URL](https://raw.githubusercontent.com/dembrandt/dembrandt/main/docs/images/brand-guide.png)
+
+**Local UI**
+
+![Local UI showing extracted brand](https://raw.githubusercontent.com/dembrandt/dembrandt/main/docs/images/local-ui.png)
 
 ## Install
 
@@ -41,6 +53,7 @@ dembrandt bmw.de --dtcg            # Export in W3C Design Tokens (DTCG) format (
 dembrandt bmw.de --dark-mode       # Extract colors from dark mode variant
 dembrandt bmw.de --mobile          # Use mobile viewport (390x844, iPhone 12/13/14/15) for responsive analysis
 dembrandt bmw.de --slow            # 3x longer timeouts (24s hydration) for JavaScript-heavy sites
+dembrandt bmw.de --brand-guide      # Generate a brand guide PDF
 dembrandt bmw.de --no-sandbox      # Disable Chromium sandbox (required for Docker/CI)
 dembrandt bmw.de --browser=firefox # Use Firefox instead of Chromium (better for Cloudflare bypass)
 ```
@@ -82,6 +95,37 @@ dembrandt stripe.com --dtcg
 
 The DTCG format is an industry-standard JSON schema that can be consumed by design tools and token transformation libraries like [Style Dictionary](https://styledictionary.com).
 
+## Local UI
+
+Browse your extracted brands in a visual interface.
+
+### Setup
+
+```bash
+cd local-ui
+npm install
+```
+
+### Running
+
+```bash
+npm start
+```
+
+Opens http://localhost:5173 with API on port 3002.
+
+### Features
+
+- Visual grid of all extracted brands
+- Color palettes with click-to-copy
+- Typography specimens
+- 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
+
+Extractions are performed via CLI (`dembrandt <url> --save-output`) and automatically appear in the UI.
+
 ## Use Cases
 
 - Brand audits & competitive analysis

package/index.js

@@ -14,13 +14,14 @@ 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 { writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
 
 program
   .name("dembrandt")
   .description("Extract design tokens from any website")
-  .version("0.6.1")
+  .version("0.7.1")
   .argument("<url>")
   .option("--browser <type>", "Browser to use (chromium|firefox)", "chromium")
   .option("--json-only", "Output raw JSON")
@@ -29,7 +30,10 @@ program
   .option("--dark-mode", "Extract colors from dark mode")
   .option("--mobile", "Extract from mobile viewport")
   .option("--slow", "3x longer timeouts for slow-loading sites")
+  .option("--brand-guide", "Export a brand guide PDF")
   .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")
   .action(async (input, opts) => {
     let url = input;
     if (!url.startsWith("http://") && !url.startsWith("https://")) {
@@ -68,6 +72,7 @@ program
             darkMode: opts.darkMode,
             mobile: opts.mobile,
             slow: opts.slow,
+            screenshotPath: opts.screenshot,
           });
           break;
         } catch (err) {
@@ -95,11 +100,16 @@ program
 
       console.log();
 
+      // Strip raw colors unless --raw-colors flag is set
+      if (!opts.rawColors && result.colors && result.colors.rawColors) {
+        delete result.colors.rawColors;
+      }
+
       // Convert to W3C format if requested
       const outputData = opts.dtcg ? toW3CFormat(result) : result;
 
       // Save JSON output if --save-output or --dtcg is specified
-      if ((opts.saveOutput || opts.dtcg) && !opts.jsonOnly) {
+      if (opts.saveOutput || opts.dtcg) {
         try {
           const domain = new URL(url).hostname.replace("www.", "");
           const timestamp = new Date()
@@ -129,6 +139,35 @@ program
         }
       }
 
+      // Generate PDF brand guide
+      if (opts.brandGuide) {
+        try {
+          const pdfDomain = new URL(url).hostname.replace("www.", "");
+          const now = new Date();
+          const pdfDate = now.toISOString().slice(0, 10);
+          const pdfTime = `${String(now.getHours()).padStart(2, '0')}-${String(now.getMinutes()).padStart(2, '0')}`;
+          const pdfDir = join(process.cwd(), "output", pdfDomain);
+          mkdirSync(pdfDir, { recursive: true });
+          const pdfFilename = `${pdfDomain}-brand-guide-${pdfDate}-${pdfTime}.pdf`;
+          const pdfPath = join(pdfDir, pdfFilename);
+          spinner.start("Generating PDF brand guide...");
+          await generatePDF(result, pdfPath, browser);
+          spinner.stop();
+          console.log(
+            chalk.dim(
+              `PDF saved to: ${chalk.hex('#8BE9FD')(
+                `output/${pdfDomain}/${pdfFilename}`
+              )}`
+            )
+          );
+        } catch (err) {
+          spinner.stop();
+          console.log(
+            chalk.hex('#FFB86C')(`Could not generate PDF: ${err.message}`)
+          );
+        }
+      }
+
       // Output to terminal
       if (opts.jsonOnly) {
         console.log(JSON.stringify(outputData, null, 2));

package/lib/extractors.js

@@ -206,7 +206,7 @@ export async function extractBranding(
     spinner.stop();
     console.log(chalk.hex('#8BE9FD')("\n  Extracting design tokens...\n"));
 
-    spinner.start("Analyzing design system (14 parallel tasks)...");
+    spinner.start("Analyzing design system (15 parallel tasks)...");
     const [
       { logo, favicons },
       colors,
@@ -222,6 +222,7 @@ export async function extractBranding(
       breakpoints,
       iconSystem,
       frameworks,
+      siteName,
     ] = await Promise.all([
       extractLogo(page, url),
       extractColors(page),
@@ -237,6 +238,7 @@ export async function extractBranding(
       extractBreakpoints(page),
       detectIconSystem(page),
       detectFrameworks(page),
+      extractSiteName(page),
     ]);
 
     spinner.stop();
@@ -584,6 +586,7 @@ export async function extractBranding(
     const result = {
       url: page.url(),
       extractedAt: new Date().toISOString(),
+      siteName,
       logo,
       favicons,
       colors,
@@ -616,6 +619,18 @@ export async function extractBranding(
       result.isCanvasOnly = true;
     }
 
+    // Save page screenshot if requested
+    if (options.screenshotPath) {
+      try {
+        const { mkdirSync } = await import("fs");
+        const { dirname } = await import("path");
+        mkdirSync(dirname(options.screenshotPath), { recursive: true });
+        await page.screenshot({ path: options.screenshotPath, fullPage: false });
+      } catch (err) {
+        console.error(chalk.dim(`  ↳ Screenshot failed: ${err.message}`));
+      }
+    }
+
     return result;
   } catch (error) {
     spinner.fail("Extraction failed");
@@ -626,6 +641,47 @@ export async function extractBranding(
   }
 }
 
+/**
+ * Extract the site/company name from meta tags, title, or structured data
+ */
+async function extractSiteName(page) {
+  return await page.evaluate(() => {
+    // 1. og:site_name - most reliable
+    const ogSiteName = document.querySelector('meta[property="og:site_name"]');
+    if (ogSiteName?.content?.trim()) return ogSiteName.content.trim();
+
+    // 2. application-name
+    const appName = document.querySelector('meta[name="application-name"]');
+    if (appName?.content?.trim()) return appName.content.trim();
+
+    // 3. JSON-LD structured data
+    const ldScripts = document.querySelectorAll('script[type="application/ld+json"]');
+    for (const s of ldScripts) {
+      try {
+        const data = JSON.parse(s.textContent);
+        const items = Array.isArray(data) ? data : data?.['@graph'] || [data];
+        for (const obj of items) {
+          if (obj?.name && typeof obj.name === 'string') return obj.name;
+          if (obj?.organization?.name) return obj.organization.name;
+        }
+      } catch {}
+    }
+
+    // 4. Title tag - take part before separator
+    const title = document.title?.trim();
+    if (title) {
+      const sep = title.match(/(.+?)\s*[|\-–—:]\s*/);
+      if (sep && sep[1].length > 1 && sep[1].length < 40) return sep[1].trim();
+    }
+
+    // 5. Logo alt text
+    const logoImg = document.querySelector('img[class*="logo"], img[id*="logo"], a[class*="logo"] img');
+    if (logoImg?.alt?.trim() && logoImg.alt.length < 40) return logoImg.alt.trim();
+
+    return null;
+  });
+}
+
 /**
  * Extract logo information from the page
  * Looks for common logo patterns: img with logo in class/id, SVG logos, etc.
@@ -668,13 +724,91 @@ async function extractLogo(page, url) {
           }
         }
 
+        // Include header SVGs/images that link to homepage (likely site logo)
+        const inHeader = el.closest('header, nav, [role="banner"], [class*="header"], [class*="Header"], [id*="header"]');
+        if (inHeader) {
+          const parentLink = el.closest('a');
+          if (parentLink) {
+            const href = parentLink.getAttribute('href') || '';
+            const ariaLabel = (parentLink.getAttribute('aria-label') || '').toLowerCase();
+            // Check for homepage link patterns (including /country/ paths like /fi/, /en-us/)
+            if (href === '/' || href === baseUrl || href === baseUrl + '/' ||
+                href.match(/^https?:\/\/[^/]+\/?$/) ||
+                href.match(/^https?:\/\/[^/]+\/[a-z]{2}(-[a-z]{2})?\/?$/) ||
+                ariaLabel.includes('homepage') || ariaLabel.includes('home page')) {
+              return true;
+            }
+          }
+        }
+
         return false;
       }
     );
 
     let logoData = null;
     if (candidates.length > 0) {
-      const logo = candidates[0];
+      // Extract site domain for matching
+      const siteDomain = new URL(baseUrl).hostname.replace('www.', '').split('.')[0].toLowerCase();
+
+      // Score each candidate
+      const scored = candidates.map(el => {
+        let score = 0;
+        const rect = el.getBoundingClientRect();
+        const parentLink = el.closest('a');
+        const linkHref = parentLink?.getAttribute('href') || '';
+        const imgSrc = el.tagName === 'IMG' ? (el.src || '') : '';
+        const altText = (el.getAttribute('alt') || '').toLowerCase();
+        const className = (typeof el.className === 'string' ? el.className : el.className.baseVal || '').toLowerCase();
+
+        // 1. Prioritize logos in header/nav (+50)
+        const inHeader = el.closest('header, nav, [role="banner"], [class*="header"], [class*="nav"], [id*="header"], [id*="nav"]');
+        if (inHeader) score += 50;
+
+        // 2. URL/alt contains site domain (+40)
+        if (imgSrc.toLowerCase().includes(siteDomain) || altText.includes(siteDomain) || className.includes(siteDomain)) {
+          score += 40;
+        }
+
+        // 3. Links to homepage (+30)
+        if (parentLink) {
+          const href = linkHref.toLowerCase();
+          if (href === '/' || href === baseUrl || href === baseUrl + '/' || href.endsWith('://' + new URL(baseUrl).hostname + '/') || href.endsWith('://' + new URL(baseUrl).hostname)) {
+            score += 30;
+          }
+        }
+
+        // 4. Position scoring - top-left bias (+20 max)
+        // Logos in top 200px get bonus, left 400px gets bonus
+        if (rect.top < 200) score += 10;
+        if (rect.left < 400) score += 10;
+
+        // Penalty for logos far down the page
+        if (rect.top > 600) score -= 20;
+
+        // Penalty for very small or very large images (likely not logos)
+        const width = el.naturalWidth || el.width?.baseVal?.value || rect.width;
+        const height = el.naturalHeight || el.height?.baseVal?.value || rect.height;
+        if (width < 20 || height < 20) score -= 30;
+        if (width > 500 || height > 300) score -= 40;
+
+        // Penalty for descriptive alt text (likely content images, not logos)
+        if (altText.length > 50) score -= 30;
+        if (altText.includes(' the ') || altText.includes(' a ') || altText.includes(' of ')) score -= 20;
+
+        // Bonus for typical logo dimensions (width > height, reasonable size)
+        if (width > height && width < 300 && width > 40 && height > 15 && height < 100) score += 15;
+
+        // Strong penalty if not in header and no domain match
+        if (!inHeader && !imgSrc.toLowerCase().includes(siteDomain) && !altText.includes(siteDomain)) {
+          score -= 30;
+        }
+
+        return { el, score };
+      });
+
+      // Sort by score descending and pick the best
+      scored.sort((a, b) => b.score - a.score);
+      const logo = scored[0].el;
       const computed = window.getComputedStyle(logo);
       const parent = logo.parentElement;
       const parentComputed = parent ? window.getComputedStyle(parent) : null;
@@ -695,6 +829,18 @@ async function extractLogo(page, url) {
           (parentComputed ? parseFloat(parentComputed.paddingLeft) : 0),
       };
 
+      // Walk up the DOM to find the actual rendered background behind the logo
+      let logoBg = null;
+      let walker = logo;
+      while (walker) {
+        const bg = window.getComputedStyle(walker).backgroundColor;
+        if (bg && bg !== 'rgba(0, 0, 0, 0)' && bg !== 'transparent') {
+          logoBg = bg;
+          break;
+        }
+        walker = walker.parentElement;
+      }
+
       if (logo.tagName === "IMG") {
         logoData = {
           source: "img",
@@ -703,6 +849,7 @@ async function extractLogo(page, url) {
           height: logo.naturalHeight || logo.height,
           alt: logo.alt,
           safeZone: safeZone,
+          background: logoBg,
         };
       } else {
         // SVG logo - try to get the parent link or closest anchor
@@ -713,6 +860,7 @@ async function extractLogo(page, url) {
           width: logo.width?.baseVal?.value,
           height: logo.height?.baseVal?.value,
           safeZone: safeZone,
+          background: logoBg,
         };
       }
     }
@@ -1124,6 +1272,17 @@ async function extractColors(page) {
       return Math.sqrt(deltaL * deltaL + deltaA * deltaA + deltaB * deltaB);
     }
 
+    // Capture all colors before filtering (for QA/debugging)
+    const rawColors = Array.from(colorMap.entries())
+      .map(([normalizedColor, data]) => ({
+        color: data.original,
+        normalized: normalizedColor,
+        count: data.count,
+        score: data.score,
+        sources: Array.from(data.sources).slice(0, 3),
+      }))
+      .sort((a, b) => b.count - a.count);
+
     const palette = Array.from(colorMap.entries())
       .filter(([normalizedColor, data]) => {
         // Filter out colors below threshold
@@ -1212,6 +1371,7 @@ async function extractColors(page) {
     return {
       semantic: semanticColors,
       palette: perceptuallyDeduped,
+      rawColors,
       cssVariables: filteredCssVariables,
     };
   });
@@ -1630,7 +1790,7 @@ async function extractButtonStyles(page) {
         color: computed.color,
         padding: computed.padding,
         borderRadius: computed.borderRadius,
-        border: computed.border,
+        border: computed.border || `${computed.borderWidth} ${computed.borderStyle} ${computed.borderColor}`,
         boxShadow: computed.boxShadow,
         outline: computed.outline,
         transform: computed.transform,
@@ -1653,11 +1813,25 @@ async function extractButtonStyles(page) {
       const bg = computed.backgroundColor;
       const border = computed.border;
       const borderWidth = computed.borderWidth;
-      const hasBorder = borderWidth && parseFloat(borderWidth) > 0 && border !== 'none';
-      const hasBackground = bg && bg !== 'rgba(0, 0, 0, 0)' && bg !== 'transparent';
-
-      // Skip only if BOTH background and border are missing/transparent
-      if (!hasBackground && !hasBorder) {
+      const borderColor = computed.borderColor;
+      const boxShadow = computed.boxShadow;
+      
+      const hasBorder = borderWidth && 
+                        parseFloat(borderWidth) > 0 && 
+                        border !== 'none' && 
+                        borderColor !== 'rgba(0, 0, 0, 0)' && 
+                        borderColor !== 'transparent';
+      
+      const hasBackground = bg && 
+                            bg !== 'rgba(0, 0, 0, 0)' && 
+                            bg !== 'transparent';
+      
+      const hasShadow = boxShadow && 
+                        boxShadow !== 'none' && 
+                        boxShadow !== 'rgba(0, 0, 0, 0)';
+
+      // Skip only if background, border, and shadow are all missing/transparent
+      if (!hasBackground && !hasBorder && !hasShadow) {
         return;
       }
 
@@ -1755,7 +1929,9 @@ async function extractButtonStyles(page) {
     const seen = new Set();
 
     for (const btn of buttonStyles) {
-      const key = btn.states.default.backgroundColor;
+      const s = btn.states.default;
+      // Key includes background, border (width/style), and shadow to distinguish variants
+      const key = `${s.backgroundColor}|${s.border}|${s.boxShadow}`;
       if (!seen.has(key)) {
         seen.add(key);
         uniqueButtons.push(btn);
@@ -1825,7 +2001,7 @@ async function extractInputStyles(page) {
       const defaultState = {
         backgroundColor: computed.backgroundColor,
         color: computed.color,
-        border: computed.border,
+        border: computed.border || `${computed.borderWidth} ${computed.borderStyle} ${computed.borderColor}`,
         borderRadius: computed.borderRadius,
         padding: computed.padding,
         boxShadow: computed.boxShadow,