designlang 1.0.0

package/src/formatters/markdown.js

@@ -0,0 +1,305 @@
+import { pxToRem } from '../utils.js';
+
+export function formatMarkdown(design) {
+  const lines = [];
+  const { meta, colors, typography, spacing, shadows, borders, variables, breakpoints, animations, components } = design;
+
+  lines.push(`# Design Language: ${meta.title || 'Unknown Site'}`);
+  lines.push('');
+  lines.push(`> Extracted from \`${meta.url}\` on ${new Date(meta.timestamp).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })}`);
+  lines.push(`> ${meta.elementCount} elements analyzed`);
+  lines.push('');
+  lines.push('This document describes the complete design language of the website. It is structured for AI/LLM consumption — use it to faithfully recreate the visual design in any framework.');
+  lines.push('');
+
+  // ── Colors ──
+  lines.push('## Color Palette');
+  lines.push('');
+  if (colors.primary) {
+    lines.push('### Primary Colors');
+    lines.push('');
+    lines.push('| Role | Hex | RGB | HSL | Usage Count |');
+    lines.push('|------|-----|-----|-----|-------------|');
+    if (colors.primary) lines.push(`| Primary | \`${colors.primary.hex}\` | rgb(${colors.primary.rgb.r}, ${colors.primary.rgb.g}, ${colors.primary.rgb.b}) | hsl(${colors.primary.hsl.h}, ${colors.primary.hsl.s}%, ${colors.primary.hsl.l}%) | ${colors.primary.count} |`);
+    if (colors.secondary) lines.push(`| Secondary | \`${colors.secondary.hex}\` | rgb(${colors.secondary.rgb.r}, ${colors.secondary.rgb.g}, ${colors.secondary.rgb.b}) | hsl(${colors.secondary.hsl.h}, ${colors.secondary.hsl.s}%, ${colors.secondary.hsl.l}%) | ${colors.secondary.count} |`);
+    if (colors.accent) lines.push(`| Accent | \`${colors.accent.hex}\` | rgb(${colors.accent.rgb.r}, ${colors.accent.rgb.g}, ${colors.accent.rgb.b}) | hsl(${colors.accent.hsl.h}, ${colors.accent.hsl.s}%, ${colors.accent.hsl.l}%) | ${colors.accent.count} |`);
+    lines.push('');
+  }
+
+  if (colors.neutrals.length > 0) {
+    lines.push('### Neutral Colors');
+    lines.push('');
+    lines.push('| Hex | HSL | Usage Count |');
+    lines.push('|-----|-----|-------------|');
+    for (const c of colors.neutrals.slice(0, 12)) {
+      lines.push(`| \`${c.hex}\` | hsl(${c.hsl.h}, ${c.hsl.s}%, ${c.hsl.l}%) | ${c.count} |`);
+    }
+    lines.push('');
+  }
+
+  if (colors.backgrounds.length > 0) {
+    lines.push('### Background Colors');
+    lines.push('');
+    lines.push(`Used on large-area elements: ${colors.backgrounds.map(h => `\`${h}\``).join(', ')}`);
+    lines.push('');
+  }
+
+  if (colors.text.length > 0) {
+    lines.push('### Text Colors');
+    lines.push('');
+    lines.push(`Text color palette: ${colors.text.map(h => `\`${h}\``).join(', ')}`);
+    lines.push('');
+  }
+
+  if (colors.gradients.length > 0) {
+    lines.push('### Gradients');
+    lines.push('');
+    for (const g of colors.gradients) {
+      lines.push('```css');
+      lines.push(`background-image: ${g};`);
+      lines.push('```');
+      lines.push('');
+    }
+  }
+
+  if (colors.all.length > 0) {
+    lines.push('### Full Color Inventory');
+    lines.push('');
+    lines.push('| Hex | Contexts | Count |');
+    lines.push('|-----|----------|-------|');
+    for (const c of colors.all.slice(0, 30)) {
+      lines.push(`| \`${c.hex}\` | ${c.contexts.join(', ')} | ${c.count} |`);
+    }
+    lines.push('');
+  }
+
+  // ── Typography ──
+  lines.push('## Typography');
+  lines.push('');
+
+  if (typography.families.length > 0) {
+    lines.push('### Font Families');
+    lines.push('');
+    for (const f of typography.families) {
+      lines.push(`- **${f.name}** — used for ${f.usage} (${f.count} elements)`);
+    }
+    lines.push('');
+  }
+
+  if (typography.scale.length > 0) {
+    lines.push('### Type Scale');
+    lines.push('');
+    lines.push('| Size (px) | Size (rem) | Weight | Line Height | Letter Spacing | Used On |');
+    lines.push('|-----------|------------|--------|-------------|----------------|---------|');
+    for (const s of typography.scale.slice(0, 15)) {
+      lines.push(`| ${s.size}px | ${pxToRem(s.size)}rem | ${s.weight} | ${s.lineHeight} | ${s.letterSpacing} | ${s.tags.slice(0, 4).join(', ')} |`);
+    }
+    lines.push('');
+  }
+
+  if (typography.headings.length > 0) {
+    lines.push('### Heading Scale');
+    lines.push('');
+    lines.push('```css');
+    for (const h of typography.headings) {
+      const tag = h.tags.find(t => /^h[1-6]$/.test(t)) || 'h';
+      lines.push(`${tag} { font-size: ${h.size}px; font-weight: ${h.weight}; line-height: ${h.lineHeight}; }`);
+    }
+    lines.push('```');
+    lines.push('');
+  }
+
+  if (typography.body) {
+    lines.push('### Body Text');
+    lines.push('');
+    lines.push('```css');
+    lines.push(`body { font-size: ${typography.body.size}px; font-weight: ${typography.body.weight}; line-height: ${typography.body.lineHeight}; }`);
+    lines.push('```');
+    lines.push('');
+  }
+
+  if (typography.weights.length > 0) {
+    lines.push('### Font Weights in Use');
+    lines.push('');
+    lines.push(typography.weights.map(w => `\`${w.weight}\` (${w.count}x)`).join(', '));
+    lines.push('');
+  }
+
+  // ── Spacing ──
+  lines.push('## Spacing');
+  lines.push('');
+  if (spacing.base) {
+    lines.push(`**Base unit:** ${spacing.base}px`);
+    lines.push('');
+  }
+  if (spacing.scale.length > 0) {
+    lines.push('| Token | Value | Rem |');
+    lines.push('|-------|-------|-----|');
+    for (const v of spacing.scale.slice(0, 20)) {
+      lines.push(`| spacing-${v} | ${v}px | ${pxToRem(v)}rem |`);
+    }
+    lines.push('');
+  }
+
+  // ── Borders ──
+  if (borders.radii.length > 0) {
+    lines.push('## Border Radii');
+    lines.push('');
+    lines.push('| Label | Value | Count |');
+    lines.push('|-------|-------|-------|');
+    for (const r of borders.radii) {
+      lines.push(`| ${r.label} | ${r.value}px | ${r.count} |`);
+    }
+    lines.push('');
+  }
+
+  // ── Shadows ──
+  if (shadows.values.length > 0) {
+    lines.push('## Box Shadows');
+    lines.push('');
+    for (const s of shadows.values) {
+      lines.push(`**${s.label}${s.inset ? ' (inset)' : ''}** — blur: ${s.blur}px`);
+      lines.push('```css');
+      lines.push(`box-shadow: ${s.raw};`);
+      lines.push('```');
+      lines.push('');
+    }
+  }
+
+  // ── CSS Variables ──
+  const varCategories = Object.entries(variables).filter(([, v]) => Object.keys(v).length > 0);
+  if (varCategories.length > 0) {
+    lines.push('## CSS Custom Properties');
+    lines.push('');
+    for (const [category, vars] of varCategories) {
+      lines.push(`### ${category.charAt(0).toUpperCase() + category.slice(1)}`);
+      lines.push('');
+      lines.push('```css');
+      for (const [name, value] of Object.entries(vars)) {
+        lines.push(`${name}: ${value};`);
+      }
+      lines.push('```');
+      lines.push('');
+    }
+  }
+
+  // ── Breakpoints ──
+  if (breakpoints.length > 0) {
+    lines.push('## Breakpoints');
+    lines.push('');
+    lines.push('| Name | Value | Type |');
+    lines.push('|------|-------|------|');
+    for (const bp of breakpoints) {
+      lines.push(`| ${bp.label} | ${bp.value}px | ${bp.type} |`);
+    }
+    lines.push('');
+  }
+
+  // ── Animations ──
+  if (animations.transitions.length > 0 || animations.keyframes.length > 0) {
+    lines.push('## Transitions & Animations');
+    lines.push('');
+
+    if (animations.easings.length > 0) {
+      lines.push(`**Easing functions:** ${animations.easings.map(e => `\`${e}\``).join(', ')}`);
+      lines.push('');
+    }
+    if (animations.durations.length > 0) {
+      lines.push(`**Durations:** ${animations.durations.map(d => `\`${d}\``).join(', ')}`);
+      lines.push('');
+    }
+
+    if (animations.transitions.length > 0) {
+      lines.push('### Common Transitions');
+      lines.push('');
+      lines.push('```css');
+      for (const t of animations.transitions.slice(0, 10)) {
+        lines.push(`transition: ${t};`);
+      }
+      lines.push('```');
+      lines.push('');
+    }
+
+    if (animations.keyframes.length > 0) {
+      lines.push('### Keyframe Animations');
+      lines.push('');
+      for (const kf of animations.keyframes.slice(0, 10)) {
+        lines.push(`**${kf.name}**`);
+        lines.push('```css');
+        lines.push(`@keyframes ${kf.name} {`);
+        for (const step of kf.steps) {
+          lines.push(`  ${step.offset} { ${step.style} }`);
+        }
+        lines.push('}');
+        lines.push('```');
+        lines.push('');
+      }
+    }
+  }
+
+  // ── Components ──
+  if (Object.keys(components).length > 0) {
+    lines.push('## Component Patterns');
+    lines.push('');
+    lines.push('Detected UI component patterns and their most common styles:');
+    lines.push('');
+
+    for (const [name, comp] of Object.entries(components)) {
+      lines.push(`### ${name.charAt(0).toUpperCase() + name.slice(1)} (${comp.count} instances)`);
+      lines.push('');
+      lines.push('```css');
+      lines.push(`.${name.slice(0, -1)} {`);
+      for (const [prop, val] of Object.entries(comp.baseStyle)) {
+        const cssProp = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+        lines.push(`  ${cssProp}: ${val};`);
+      }
+      lines.push('}');
+      lines.push('```');
+      lines.push('');
+    }
+  }
+
+  // ── Dark Mode ──
+  if (design.darkMode) {
+    lines.push('## Dark Mode');
+    lines.push('');
+    lines.push('The site has a distinct dark mode color scheme:');
+    lines.push('');
+    const dc = design.darkMode.colors;
+    if (dc.primary) lines.push(`- **Primary:** \`${dc.primary.hex}\``);
+    if (dc.secondary) lines.push(`- **Secondary:** \`${dc.secondary.hex}\``);
+    if (dc.backgrounds.length > 0) lines.push(`- **Backgrounds:** ${dc.backgrounds.map(h => `\`${h}\``).join(', ')}`);
+    if (dc.text.length > 0) lines.push(`- **Text:** ${dc.text.slice(0, 5).map(h => `\`${h}\``).join(', ')}`);
+    lines.push('');
+
+    const darkVars = Object.entries(design.darkMode.variables).filter(([, v]) => Object.keys(v).length > 0);
+    if (darkVars.length > 0) {
+      lines.push('### Dark Mode CSS Variables');
+      lines.push('');
+      lines.push('```css');
+      for (const [, vars] of darkVars) {
+        for (const [name, value] of Object.entries(vars)) {
+          lines.push(`${name}: ${value};`);
+        }
+      }
+      lines.push('```');
+      lines.push('');
+    }
+  }
+
+  // ── Quick Start ──
+  lines.push('## Quick Start');
+  lines.push('');
+  lines.push('To recreate this design in a new project:');
+  lines.push('');
+  if (typography.families.length > 0) {
+    const fontName = typography.families[0].name;
+    lines.push(`1. **Install fonts:** Add \`${fontName}\` from Google Fonts or your font provider`);
+  }
+  lines.push(`2. **Import CSS variables:** Copy \`variables.css\` into your project`);
+  lines.push(`3. **Tailwind users:** Use the generated \`tailwind.config.js\` to extend your theme`);
+  lines.push(`4. **Design tokens:** Import \`design-tokens.json\` for tooling integration`);
+  lines.push('');
+
+  return lines.join('\n');
+}

package/src/formatters/tailwind.js

@@ -0,0 +1,81 @@
+export function formatTailwind(design) {
+  const config = {
+    colors: {},
+    fontFamily: {},
+    fontSize: {},
+    spacing: {},
+    borderRadius: {},
+    boxShadow: {},
+    screens: {},
+    zIndex: {},
+    transitionDuration: {},
+    transitionTimingFunction: {},
+  };
+
+  // Colors
+  if (design.colors.primary) config.colors.primary = design.colors.primary.hex;
+  if (design.colors.secondary) config.colors.secondary = design.colors.secondary.hex;
+  if (design.colors.accent) config.colors.accent = design.colors.accent.hex;
+  for (let i = 0; i < design.colors.neutrals.length && i < 10; i++) {
+    config.colors[`neutral-${i * 100 || 50}`] = design.colors.neutrals[i].hex;
+  }
+  if (design.colors.backgrounds.length > 0) config.colors.background = design.colors.backgrounds[0];
+  if (design.colors.text.length > 0) config.colors.foreground = design.colors.text[0];
+
+  // Typography — first family becomes 'sans', second becomes 'mono' or 'heading'
+  for (let i = 0; i < design.typography.families.length; i++) {
+    const f = design.typography.families[i];
+    let key;
+    if (f.usage === 'headings') key = 'heading';
+    else if (f.usage === 'body') key = 'body';
+    else if (i === 0) key = 'sans';
+    else if (f.name.toLowerCase().includes('mono')) key = 'mono';
+    else key = i === 1 ? 'heading' : `font${i}`;
+    config.fontFamily[key] = [f.name, 'sans-serif'];
+  }
+
+  for (const s of design.typography.scale.slice(0, 15)) {
+    config.fontSize[`${s.size}`] = [`${s.size}px`, { lineHeight: s.lineHeight, letterSpacing: s.letterSpacing !== 'normal' ? s.letterSpacing : undefined }];
+  }
+
+  // Spacing
+  for (const [name, value] of Object.entries(design.spacing.tokens)) {
+    config.spacing[name] = value;
+  }
+
+  // Border radius
+  for (const r of design.borders.radii) {
+    config.borderRadius[r.label] = `${r.value}px`;
+  }
+
+  // Shadows
+  for (const s of design.shadows.values) {
+    config.boxShadow[s.label] = s.raw;
+  }
+
+  // Breakpoints
+  for (const bp of design.breakpoints) {
+    if (bp.type === 'min-width') {
+      config.screens[bp.label] = `${bp.value}px`;
+    }
+  }
+
+  // Clean empty objects
+  for (const [key, val] of Object.entries(config)) {
+    if (typeof val === 'object' && Object.keys(val).length === 0) delete config[key];
+  }
+
+  const configStr = JSON.stringify(config, null, 4)
+    // Unquote simple keys (letters, digits, underscores only)
+    .replace(/"([a-zA-Z_]\w*)":/g, '$1:')
+    // Replace double quotes with single quotes for values
+    .replace(/"/g, "'");
+
+  return `/** @type {import('tailwindcss').Config} */
+export default {
+  theme: {
+    extend: ${configStr},
+  },
+};
+`;
+}

package/src/formatters/tokens.js

@@ -0,0 +1,61 @@
+export function formatTokens(design) {
+  const tokens = {};
+
+  // Colors
+  tokens.color = {};
+  if (design.colors.primary) tokens.color.primary = { $value: design.colors.primary.hex, $type: 'color' };
+  if (design.colors.secondary) tokens.color.secondary = { $value: design.colors.secondary.hex, $type: 'color' };
+  if (design.colors.accent) tokens.color.accent = { $value: design.colors.accent.hex, $type: 'color' };
+
+  for (let i = 0; i < design.colors.neutrals.length && i < 10; i++) {
+    tokens.color[`neutral-${i}`] = { $value: design.colors.neutrals[i].hex, $type: 'color' };
+  }
+
+  for (let i = 0; i < design.colors.backgrounds.length; i++) {
+    tokens.color[`background-${i}`] = { $value: design.colors.backgrounds[i], $type: 'color' };
+  }
+
+  for (let i = 0; i < design.colors.text.length && i < 5; i++) {
+    tokens.color[`text-${i}`] = { $value: design.colors.text[i], $type: 'color' };
+  }
+
+  // Typography
+  tokens.fontFamily = {};
+  for (const f of design.typography.families) {
+    tokens.fontFamily[f.usage === 'headings' ? 'heading' : f.usage === 'body' ? 'body' : f.name.toLowerCase().replace(/\s+/g, '-')] = {
+      $value: f.name,
+      $type: 'fontFamily',
+    };
+  }
+
+  tokens.fontSize = {};
+  for (const s of design.typography.scale.slice(0, 15)) {
+    tokens.fontSize[`${s.size}`] = { $value: `${s.size}px`, $type: 'dimension' };
+  }
+
+  // Spacing
+  tokens.spacing = {};
+  for (const [name, value] of Object.entries(design.spacing.tokens)) {
+    tokens.spacing[name] = { $value: value, $type: 'dimension' };
+  }
+
+  // Border radius
+  tokens.borderRadius = {};
+  for (const r of design.borders.radii) {
+    tokens.borderRadius[r.label] = { $value: `${r.value}px`, $type: 'dimension' };
+  }
+
+  // Shadows
+  tokens.shadow = {};
+  for (const s of design.shadows.values) {
+    tokens.shadow[s.label] = { $value: s.raw, $type: 'shadow' };
+  }
+
+  // Breakpoints
+  tokens.breakpoint = {};
+  for (const bp of design.breakpoints) {
+    tokens.breakpoint[bp.label] = { $value: `${bp.value}px`, $type: 'dimension' };
+  }
+
+  return JSON.stringify(tokens, null, 2);
+}

package/src/index.js

@@ -0,0 +1,48 @@
+import { crawlPage } from './crawler.js';
+import { extractColors } from './extractors/colors.js';
+import { extractTypography } from './extractors/typography.js';
+import { extractSpacing } from './extractors/spacing.js';
+import { extractShadows } from './extractors/shadows.js';
+import { extractBorders } from './extractors/borders.js';
+import { extractVariables } from './extractors/variables.js';
+import { extractBreakpoints } from './extractors/breakpoints.js';
+import { extractAnimations } from './extractors/animations.js';
+import { extractComponents } from './extractors/components.js';
+
+export async function extractDesignLanguage(url, options = {}) {
+  const rawData = await crawlPage(url, options);
+  const styles = rawData.light.computedStyles;
+
+  const design = {
+    meta: {
+      url: rawData.url,
+      title: rawData.title,
+      timestamp: new Date().toISOString(),
+      elementCount: styles.length,
+    },
+    colors: extractColors(styles),
+    typography: extractTypography(styles),
+    spacing: extractSpacing(styles),
+    shadows: extractShadows(styles),
+    borders: extractBorders(styles),
+    variables: extractVariables(rawData.light.cssVariables),
+    breakpoints: extractBreakpoints(rawData.light.mediaQueries),
+    animations: extractAnimations(styles, rawData.light.keyframes),
+    components: extractComponents(styles),
+  };
+
+  if (rawData.dark) {
+    design.darkMode = {
+      colors: extractColors(rawData.dark.computedStyles),
+      variables: extractVariables(rawData.dark.cssVariables),
+    };
+  }
+
+  return design;
+}
+
+export { crawlPage } from './crawler.js';
+export { formatTokens } from './formatters/tokens.js';
+export { formatMarkdown } from './formatters/markdown.js';
+export { formatTailwind } from './formatters/tailwind.js';
+export { formatCssVars } from './formatters/css-vars.js';

package/src/utils.js

@@ -0,0 +1,179 @@
+// Named CSS colors (subset — the 17 standard + common extras)
+const NAMED_COLORS = {
+  transparent: { r: 0, g: 0, b: 0, a: 0 },
+  black: { r: 0, g: 0, b: 0, a: 1 },
+  white: { r: 255, g: 255, b: 255, a: 1 },
+  red: { r: 255, g: 0, b: 0, a: 1 },
+  green: { r: 0, g: 128, b: 0, a: 1 },
+  blue: { r: 0, g: 0, b: 255, a: 1 },
+  yellow: { r: 255, g: 255, b: 0, a: 1 },
+  cyan: { r: 0, g: 255, b: 255, a: 1 },
+  magenta: { r: 255, g: 0, b: 255, a: 1 },
+  gray: { r: 128, g: 128, b: 128, a: 1 },
+  grey: { r: 128, g: 128, b: 128, a: 1 },
+  orange: { r: 255, g: 165, b: 0, a: 1 },
+  purple: { r: 128, g: 0, b: 128, a: 1 },
+  pink: { r: 255, g: 192, b: 203, a: 1 },
+  navy: { r: 0, g: 0, b: 128, a: 1 },
+  teal: { r: 0, g: 128, b: 128, a: 1 },
+  silver: { r: 192, g: 192, b: 192, a: 1 },
+  maroon: { r: 128, g: 0, b: 0, a: 1 },
+};
+
+export function parseColor(str) {
+  if (!str || str === 'none' || str === 'currentcolor' || str === 'inherit' || str === 'initial') return null;
+  str = str.trim().toLowerCase();
+
+  if (NAMED_COLORS[str]) return { ...NAMED_COLORS[str] };
+
+  // hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
+  if (str.startsWith('#')) {
+    const hex = str.slice(1);
+    if (hex.length === 3) return { r: parseInt(hex[0] + hex[0], 16), g: parseInt(hex[1] + hex[1], 16), b: parseInt(hex[2] + hex[2], 16), a: 1 };
+    if (hex.length === 4) return { r: parseInt(hex[0] + hex[0], 16), g: parseInt(hex[1] + hex[1], 16), b: parseInt(hex[2] + hex[2], 16), a: parseInt(hex[3] + hex[3], 16) / 255 };
+    if (hex.length === 6) return { r: parseInt(hex.slice(0, 2), 16), g: parseInt(hex.slice(2, 4), 16), b: parseInt(hex.slice(4, 6), 16), a: 1 };
+    if (hex.length === 8) return { r: parseInt(hex.slice(0, 2), 16), g: parseInt(hex.slice(2, 4), 16), b: parseInt(hex.slice(4, 6), 16), a: parseInt(hex.slice(6, 8), 16) / 255 };
+  }
+
+  // rgb(r, g, b) or rgba(r, g, b, a)
+  const rgbMatch = str.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+))?\s*\)/);
+  if (rgbMatch) {
+    return { r: +rgbMatch[1], g: +rgbMatch[2], b: +rgbMatch[3], a: rgbMatch[4] !== undefined ? +rgbMatch[4] : 1 };
+  }
+
+  // Modern syntax: rgb(r g b / a)
+  const rgbModern = str.match(/rgba?\(\s*(\d+)\s+(\d+)\s+(\d+)\s*(?:\/\s*([\d.]+%?))?\s*\)/);
+  if (rgbModern) {
+    let a = 1;
+    if (rgbModern[4] !== undefined) {
+      a = rgbModern[4].endsWith('%') ? parseFloat(rgbModern[4]) / 100 : +rgbModern[4];
+    }
+    return { r: +rgbModern[1], g: +rgbModern[2], b: +rgbModern[3], a };
+  }
+
+  // hsl(h, s%, l%) or hsla(h, s%, l%, a)
+  const hslMatch = str.match(/hsla?\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*(?:,\s*([\d.]+))?\s*\)/);
+  if (hslMatch) {
+    const rgb = hslToRgb(+hslMatch[1], +hslMatch[2], +hslMatch[3]);
+    return { ...rgb, a: hslMatch[4] !== undefined ? +hslMatch[4] : 1 };
+  }
+
+  return null;
+}
+
+export function rgbToHex({ r, g, b }) {
+  const toHex = (n) => Math.round(n).toString(16).padStart(2, '0');
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+export function rgbToHsl({ r, g, b }) {
+  r /= 255; g /= 255; b /= 255;
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return { h: 0, s: 0, l: Math.round(l * 100) };
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+  else if (max === g) h = ((b - r) / d + 2) / 6;
+  else h = ((r - g) / d + 4) / 6;
+  return { h: Math.round(h * 360), s: Math.round(s * 100), l: Math.round(l * 100) };
+}
+
+function hslToRgb(h, s, l) {
+  h /= 360; s /= 100; l /= 100;
+  if (s === 0) { const v = Math.round(l * 255); return { r: v, g: v, b: v }; }
+  const hue2rgb = (p, q, t) => {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1/6) return p + (q - p) * 6 * t;
+    if (t < 1/2) return q;
+    if (t < 2/3) return p + (q - p) * (2/3 - t) * 6;
+    return p;
+  };
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  return {
+    r: Math.round(hue2rgb(p, q, h + 1/3) * 255),
+    g: Math.round(hue2rgb(p, q, h) * 255),
+    b: Math.round(hue2rgb(p, q, h - 1/3) * 255),
+  };
+}
+
+export function colorDistance(c1, c2) {
+  return Math.sqrt((c1.r - c2.r) ** 2 + (c1.g - c2.g) ** 2 + (c1.b - c2.b) ** 2);
+}
+
+export function isSaturated({ r, g, b }) {
+  const { s } = rgbToHsl({ r, g, b });
+  return s > 10;
+}
+
+export function clusterColors(colors, threshold = 15) {
+  const clusters = [];
+  for (const color of colors) {
+    const existing = clusters.find(c => colorDistance(c.representative, color.parsed) < threshold);
+    if (existing) {
+      existing.members.push(color);
+      existing.count += color.count;
+    } else {
+      clusters.push({ representative: color.parsed, hex: color.hex, members: [color], count: color.count });
+    }
+  }
+  return clusters.sort((a, b) => b.count - a.count);
+}
+
+export function clusterValues(values, threshold) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const groups = [];
+  for (const v of sorted) {
+    const last = groups[groups.length - 1];
+    if (last && Math.abs(v - last.representative) <= threshold) {
+      last.members.push(v);
+    } else {
+      groups.push({ representative: v, members: [v] });
+    }
+  }
+  return groups.map(g => g.representative);
+}
+
+export function parseCSSValue(str) {
+  if (!str || str === 'normal' || str === 'auto' || str === 'none') return null;
+  const match = str.match(/^([\d.]+)(px|rem|em|%|vw|vh|pt)?$/);
+  if (!match) return null;
+  return { value: parseFloat(match[1]), unit: match[2] || '' };
+}
+
+export function remToPx(rem, base = 16) {
+  return rem * base;
+}
+
+export function pxToRem(px, base = 16) {
+  return +(px / base).toFixed(4);
+}
+
+export function safeName(str) {
+  return str.replace(/[^a-zA-Z0-9-_]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').toLowerCase();
+}
+
+export function nameFromUrl(url) {
+  try {
+    const hostname = new URL(url).hostname;
+    return safeName(hostname.replace(/^www\./, ''));
+  } catch {
+    return 'unknown-site';
+  }
+}
+
+export function detectScale(values) {
+  if (values.length < 3) return { base: null, scale: values };
+  const candidates = [2, 4, 6, 8];
+  let bestBase = null;
+  let bestScore = 0;
+  for (const base of candidates) {
+    const score = values.filter(v => v > 0 && v % base === 0).length / values.length;
+    if (score > bestScore) { bestScore = score; bestBase = base; }
+  }
+  if (bestScore >= 0.6) return { base: bestBase, scale: values };
+  return { base: null, scale: values };
+}