dembrandt 0.12.5 → 0.12.6

package/README.md

@@ -45,11 +45,12 @@ Or add to your project's `.mcp.json`:
 
 ## What to expect from extraction?
 
-- Colors (semantic, palette, CSS variables)
+- Colors (semantic, palette, CSS variables, gradients)
 - Typography (fonts, sizes, weights, sources)
 - Spacing (margin/padding scales)
 - Borders (radius, widths, styles, colors)
 - Shadows
+- Motion (duration scale, easing curves, hover patterns per component type)
 - Components (buttons, badges, inputs, links)
 - Breakpoints
 - Icons & frameworks
@@ -134,13 +135,15 @@ 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. The export follows Google's DESIGN.md draft format: YAML design tokens in front matter plus ordered Markdown guidance sections.
 
 ```bash
 dembrandt example.com --design-md
 # Saves to: output/example.com/DESIGN.md
 ```
 
+DESIGN.md reports only what Dembrandt observed on the source site. Exact values (colors, typography, spacing, radii, shadows) live in the YAML front matter when available, and the Markdown body adds human-readable context. Sections with no extracted evidence are omitted rather than filled with invented defaults. For example, the elevation section is dropped when the site uses no box-shadow tokens.
+
 ### 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.
@@ -151,6 +154,24 @@ 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`.
 
+Also captures **interactive state contrast**: dembrandt simulates hover, focus, and disabled states on buttons, links, and inputs and checks contrast on each state. State pairs are tagged `[hover]`, `[focus]`, or `[disabled]` in output so you can catch contrast failures that only appear on interaction.
+
+### Motion Tokens
+
+Motion tokens are extracted automatically on every run — no flag needed. Dembrandt analyzes CSS transitions and animations across the page and returns a structured motion profile.
+
+```bash
+dembrandt stripe.com
+```
+
+Returns:
+- **Duration scale**: all unique animation durations found on the page
+- **Easing curves**: named easing types (ease-out, spring, custom cubic-bezier) with usage counts
+- **Per-context profiles**: motion behavior by component type (button, nav, card, modal, hero)
+- **Hover interaction deltas**: which properties animate on hover (transform, opacity, background, color) and the pattern (scale-up, fade-in, color-shift, slide-y)
+
+Motion data is included in JSON output as `motion` and printed in terminal under a dedicated Motion section.
+
 ### 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.

package/lib/formatters/markdown.js

@@ -1,8 +1,8 @@
 /**
  * DESIGN.md generator
  *
- * Converts dembrandt extraction results into the DESIGN.md format
- * as defined by Google Stitch — prose-first, human + AI readable.
+ * Converts dembrandt extraction results into Google's DESIGN.md draft format:
+ * YAML design tokens in front matter plus ordered markdown rationale sections.
  */
 import { convertColor, deltaE } from '../colors.js';
 
@@ -11,239 +11,570 @@ import { convertColor, deltaE } from '../colors.js';
  * @returns {string} DESIGN.md content
  */
 export function generateDesignMd(result) {
-  const sections = [];
-
-  const domain = (() => {
-    try { return new URL(result.url).hostname.replace('www.', ''); } catch { return result.url ?? 'unknown'; }
-  })();
-
-  // --- Overview ---
-  sections.push(`# Design System\n\n## Overview\nDesign tokens extracted from ${domain}.`);
-
-  // --- Colors ---
-  {
-    const semantic = result.colors?.semantic;
-    const palette = result.colors?.palette;
-
-    // Collect all candidate colors from palette + buttons + links, normalised to hex
-    const allCandidates = new Map();
-    const addCandidate = (raw, source) => {
-      if (raw == null) return;
-      const parsed = convertColor(String(raw));
-      if (!parsed) return;
-      const hex = parsed.hex; // canonical 6-digit lowercase hex
-      const r = parseInt(hex.slice(1, 3), 16) / 255;
-      const g = parseInt(hex.slice(3, 5), 16) / 255;
-      const b = parseInt(hex.slice(5, 7), 16) / 255;
-      const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
-      const sat = Math.max(r, g, b) - Math.min(r, g, b);
-      if (!allCandidates.has(hex)) allCandidates.set(hex, { hex, lum, sat, source });
-    };
+  const domain = getDomain(result);
+  const name = getName(result, domain);
+  const colorRoles = buildColorRoles(result);
+  const typographyTokens = buildTypographyTokens(result);
+  const spacingTokens = buildSpacingTokens(result);
+  const roundedTokens = buildRoundedTokens(result);
+  const componentTokens = buildComponentTokens(result, colorRoles, roundedTokens);
+
+  const frontMatter = compactObject({
+    name,
+    description: `Design tokens extracted from ${result.url ?? domain}`,
+    colors: hasKeys(colorRoles) ? colorRoles : null,
+    typography: hasKeys(typographyTokens) ? typographyTokens : null,
+    spacing: hasKeys(spacingTokens) ? spacingTokens : null,
+    rounded: hasKeys(roundedTokens) ? roundedTokens : null,
+    components: hasKeys(componentTokens) ? componentTokens : null,
+  });
+
+  const sections = [
+    '# Design System',
+    buildOverviewSection(domain),
+    hasKeys(colorRoles) ? buildColorsSection(colorRoles) : null,
+    hasKeys(typographyTokens) ? buildTypographySection(result, typographyTokens) : null,
+    hasLayoutEvidence(result, spacingTokens) ? buildLayoutSection(result, spacingTokens) : null,
+    hasElevationEvidence(result) ? buildElevationSection(result) : null,
+    hasKeys(roundedTokens) ? buildShapesSection(roundedTokens) : null,
+    hasComponentEvidence(result) ? buildComponentsSection(result) : null,
+  ].filter(Boolean);
+
+  return `---\n${toYaml(frontMatter)}---\n\n${sections.join('\n\n')}\n`;
+}
 
-    const highConf = palette?.filter(c => c.confidence === 'high' || c.confidence === 'medium') ?? [];
-    for (const c of (highConf.length ? highConf : palette ?? [])) addCandidate(c.normalized || c.color, 'palette');
-    for (const btn of result.components?.buttons ?? []) {
-      const bg = btn.states?.default?.backgroundColor;
-      if (bg && bg !== 'transparent') addCandidate(bg, 'button');
-    }
-    for (const link of result.components?.links ?? []) addCandidate(link.color, 'link');
-
-    // Build semantic roles
-    const roles = {};
-    if (semantic && Object.values(semantic).some(Boolean)) {
-      // Extractor already resolved primary/secondary from class names — most authoritative
-      for (const [role, val] of Object.entries(semantic)) {
-        if (val) roles[role] = toHex(val) || val;
-      }
+function getDomain(result) {
+  try {
+    return new URL(result.url).hostname.replace('www.', '');
+  } catch {
+    return result.url ?? 'unknown';
+  }
+}
+
+function getName(result, domain) {
+  return result.siteName?.trim() || domain;
+}
+
+function buildOverviewSection(domain) {
+  return `## Overview\nDesign tokens extracted from ${domain}. The YAML front matter contains machine-readable values observed by Dembrandt when available; the sections below summarize the extracted evidence without redesigning or correcting the source site.`;
+}
+
+function buildColorRoles(result) {
+  const semantic = result.colors?.semantic;
+  const palette = result.colors?.palette;
+
+  const allCandidates = new Map();
+  const addCandidate = (raw, source) => {
+    if (raw == null) return;
+    if (isTransparentColor(raw)) return;
+    const parsed = convertColor(String(raw));
+    if (!parsed) return;
+    const hex = normalizeHex(parsed.hex);
+    const r = parseInt(hex.slice(1, 3), 16) / 255;
+    const g = parseInt(hex.slice(3, 5), 16) / 255;
+    const b = parseInt(hex.slice(5, 7), 16) / 255;
+    const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    const sat = Math.max(r, g, b) - Math.min(r, g, b);
+    if (!allCandidates.has(hex)) allCandidates.set(hex, { hex, lum, sat, source });
+  };
+
+  const highConf = palette?.filter(c => c.confidence === 'high' || c.confidence === 'medium') ?? [];
+  for (const c of (highConf.length ? highConf : palette ?? [])) addCandidate(c.normalized || c.color, 'palette');
+  for (const btn of result.components?.buttons ?? []) {
+    const state = btn.states?.default ?? btn;
+    const bg = state.backgroundColor;
+    if (bg && bg !== 'transparent' && !isTransparentColor(bg)) addCandidate(bg, 'button');
+  }
+  for (const link of result.components?.links ?? []) addCandidate(link.color, 'link');
+
+  const roles = {};
+  if (semantic && Object.values(semantic).some(Boolean)) {
+    for (const [role, val] of Object.entries(semantic)) {
+      const hex = toHex(typeof val === 'string' ? val : val?.color);
+      if (hex) roles[sanitizeTokenName(role)] = hex;
     }
+  }
 
-    // Fill any missing roles from candidates, ranked by palette confidence then saturation
-    if (allCandidates.size) {
-      // Score candidates: high-confidence palette colors rank above button/link colors
-      const confScore = { high: 3, medium: 2, low: 1 };
-      const paletteConf = new Map();
-      for (const c of palette ?? []) {
-        const hex = toHex(c.normalized || c.color);
-        if (hex) paletteConf.set(hex, confScore[c.confidence] ?? 0);
-      }
+  if (allCandidates.size) {
+    const confScore = { high: 3, medium: 2, low: 1 };
+    const paletteConf = new Map();
+    for (const c of palette ?? []) {
+      const hex = toHex(c.normalized || c.color);
+      if (hex) paletteConf.set(hex, confScore[c.confidence] ?? 0);
+    }
 
-      const candidates = Array.from(allCandidates.values()).map(c => ({
+    const ranked = Array.from(allCandidates.values())
+      .map(c => ({
         ...c,
-        // For primary/secondary selection, saturation dominates — a grey with high
-        // palette confidence should not beat a vivid brand color from buttons/links.
-        // Saturation scaled 0–1, confidence adds a small tiebreaker.
         rank: c.sat * 100 + (paletteConf.get(c.hex) ?? 0),
-      }));
-
-      // Sort by rank before dedup so the best candidate per cluster is kept, not the first-seen
-      const ranked = [...candidates].sort((a, b) => b.rank - a.rank);
-      const deduped = [];
-      for (const c of ranked) {
-        const tooClose = deduped.some(d => deltaE(c.hex, d.hex) < 15);
-        if (!tooClose) deduped.push(c);
+      }))
+      .sort((a, b) => b.rank - a.rank);
+
+    const deduped = [];
+    for (const c of ranked) {
+      const tooClose = deduped.some(d => deltaE(c.hex, d.hex) < 15);
+      if (!tooClose) deduped.push(c);
+    }
+
+    const used = new Set(Object.values(roles).map(h => h?.toLowerCase()));
+    const byRank = [...deduped].sort((a, b) => b.rank - a.rank);
+    const byLum = [...deduped].sort((a, b) => a.lum - b.lum);
+
+    const pick = (arr) => {
+      const c = arr.find(x => !used.has(x.hex.toLowerCase()));
+      if (c) {
+        used.add(c.hex.toLowerCase());
+        return c.hex;
       }
+      return null;
+    };
 
-      const used = new Set(Object.values(roles).map(h => h?.toLowerCase()));
-      const byRank = [...deduped].sort((a, b) => b.rank - a.rank);
-      const byLum = [...deduped].sort((a, b) => a.lum - b.lum);
+    if (!roles.primary) roles.primary = pick(byRank);
+    if (!roles.secondary) roles.secondary = pick(byRank);
+    if (!roles.surface) roles.surface = pick([...byLum].reverse());
+    if (!roles['on-surface']) roles['on-surface'] = pick(byLum);
+  }
 
-      const pick = (arr) => {
-        const c = arr.find(x => !used.has(x.hex.toLowerCase()));
-        if (c) { used.add(c.hex.toLowerCase()); return c.hex; }
-        return null;
-      };
+  return compactObject({
+    primary: roles.primary,
+    secondary: roles.secondary,
+    tertiary: roles.tertiary ?? roles.accent,
+    surface: roles.surface ?? roles.background,
+    'on-surface': roles['on-surface'] ?? roles.text,
+    error: roles.error,
+  }) ?? {};
+}
 
-      if (!roles.primary) { const h = pick(byRank); if (h) roles.primary = h; }
-      if (!roles.secondary) { const h = pick(byRank); if (h) roles.secondary = h; }
-      if (!roles.surface) { const h = pick([...byLum].reverse()); if (h) roles.surface = h; }
-      if (!roles['on-surface']) { const h = pick(byLum); if (h) roles['on-surface'] = h; }
-    }
+function buildTypographyTokens(result) {
+  const styles = result.typography?.styles ?? [];
+  const tokens = {};
+  const usedNames = new Set();
+
+  for (const [index, style] of styles.entries()) {
+    const token = compactObject({
+      fontFamily: normalizeFontFamily(style.fontFamily ?? style.family),
+      fontSize: normalizeDimension(style.fontSize ?? style.size),
+      fontWeight: normalizeFontWeight(style.fontWeight ?? style.weight),
+      lineHeight: normalizeLineHeight(style.lineHeight),
+      letterSpacing: normalizeDimension(style.letterSpacing),
+    });
+
+    if (!token || !token.fontFamily && !token.fontSize) continue;
+
+    const baseName = typographyTokenName(style, index);
+    const name = uniqueTokenName(baseName, usedNames);
+    tokens[name] = token;
+  }
 
-    const usageHints = {
-      primary: 'CTAs, active states, key interactive elements',
-      secondary: 'Supporting UI, secondary actions',
-      surface: 'Page backgrounds',
-      'on-surface': 'Primary text',
-      background: 'Page backgrounds',
-      text: 'Primary text',
-      error: 'Validation errors, destructive actions',
-      accent: 'Accent highlights, badges',
-    };
+  return tokens;
+}
 
-    const lines = ['## Colors'];
-    for (const [role, hex] of Object.entries(roles)) {
-      if (!hex) continue;
-      const hint = usageHints[role.toLowerCase()] ?? '';
-      lines.push(`- **${capitalize(role)}** (${hex})${hint ? `: ${hint}` : ''}`);
-    }
+function buildSpacingTokens(result) {
+  const values = new Set();
+  const base = normalizeDimension(result.spacing?.scaleType);
+  if (base) values.add(base);
 
-    if (lines.length > 1) sections.push(lines.join('\n'));
-    else sections.push('## Colors\n- **Primary** (#000000): CTAs, active states, key interactive elements\n- **Surface** (#ffffff): Page backgrounds\n- **On-surface** (#000000): Primary text');
+  for (const entry of result.spacing?.commonValues ?? []) {
+    const value = normalizeDimension(entry.px ?? entry);
+    if (value) values.add(value);
   }
 
-  // --- Typography ---
-  {
-    const SKIP = /^(fontawesome|font.awesome|material.icon|glyphicon|icomoon|dashicons|built_rg|piepie|sans-serif|serif|monospace|cursive|fantasy|-apple-system|system-ui|segoe.ui|helvetica\b|arial|georgia|times|courier)/i;
-    const styles = result.typography?.styles ?? [];
-    const families = new Map();
-    for (const s of styles) {
-      if (s.family && !SKIP.test(s.family) && !families.has(s.family)) families.set(s.family, []);
-      if (s.family && !SKIP.test(s.family)) families.get(s.family).push(s);
-    }
+  const sorted = [...values].sort((a, b) => parseFloat(a) - parseFloat(b)).slice(0, 8);
+  const names = ['xs', 'sm', 'md', 'lg', 'xl', 'xxl', 'xxxl', 'xxxxl'];
+  const tokens = {};
 
-    if (!families.size) {
-      sections.push('## Typography\n- **Headlines**: System font, semi-bold\n- **Body**: System font, regular, 14–16px');
-    } else {
-      const lines = ['## Typography'];
-      const roleLabels = ['Headlines', 'Body', 'Labels'];
-      let i = 0;
-      for (const [family, styleList] of families) {
-        const role = roleLabels[i] ?? 'Labels';
-        // Summarise weights
-        const weights = [...new Set(styleList.map(s => s.weight).filter(Boolean))];
-        const weightDesc = humanWeight(weights[0]);
-        // Summarise sizes
-        const sizes = styleList.map(s => parseFloat(s.size)).filter(Boolean).sort((a, b) => a - b);
-        const sizeDesc = sizes.length > 1
-          ? `${sizes[0]}–${sizes[sizes.length - 1]}px`
-          : sizes.length === 1 ? `${sizes[0]}px` : '';
-        const parts = [family];
-        if (weightDesc) parts.push(weightDesc);
-        if (sizeDesc) parts.push(sizeDesc);
-        lines.push(`- **${role}**: ${parts.join(', ')}`);
-        i++;
-      }
-      sections.push(lines.join('\n'));
-    }
+  if (base) tokens.base = base;
+  for (let i = 0; i < sorted.length; i++) {
+    const name = names[i] ?? `space-${i + 1}`;
+    if (tokens[name] !== sorted[i]) tokens[name] = sorted[i];
   }
 
-  // --- Components ---
-  {
-    const lines = ['## Components'];
-    let hasContent = false;
-
-    const buttons = result.components?.buttons ?? [];
-    if (buttons.length) {
-      const btn = buttons[0].states?.default ?? buttons[0];
-      const parts = [];
-      if (btn.borderRadius) {
-        const r = parseFloat(btn.borderRadius);
-        parts.push(r > 20 ? 'fully rounded' : r > 0 ? `rounded (${btn.borderRadius})` : 'square corners');
-      }
-      if (btn.backgroundColor && btn.backgroundColor !== 'transparent') {
-        const hex = toHex(btn.backgroundColor);
-        parts.push(`primary uses ${hex ? hex + ' fill' : 'colored fill'}`);
-      }
-      if (btn.border && btn.border !== 'none') parts.push('outlined variant available');
-      if (parts.length) { lines.push(`- **Buttons**: ${capitalize(parts.join(', '))}`); hasContent = true; }
+  return tokens;
+}
+
+function buildRoundedTokens(result) {
+  const radii = result.borderRadius?.values ?? [];
+  const values = [...new Set(radii
+    .map(entry => normalizeRadius(entry.value))
+    .filter(Boolean))]
+    .sort((a, b) => parseFloat(a) - parseFloat(b));
+
+  const tokens = {};
+  if (values.includes('0px')) tokens.none = '0px';
+
+  const nonZero = values.filter(value => value !== '0px' && value !== '9999px').slice(0, 4);
+  const names = ['sm', 'md', 'lg', 'xl'];
+  for (let i = 0; i < nonZero.length; i++) tokens[names[i]] = nonZero[i];
+  if (values.includes('9999px')) tokens.full = '9999px';
+
+  return tokens;
+}
+
+function buildComponentTokens(result, colorRoles, roundedTokens) {
+  const components = {};
+  const button = (result.components?.buttons ?? [])
+    .map(btn => btn.states?.default ?? btn)
+    .find(btn => btn.backgroundColor && !isTransparentColor(btn.backgroundColor));
+
+  if (button) {
+    const background = tokenReferenceForColor(button.backgroundColor, colorRoles);
+    const text = tokenReferenceForColor(button.color ?? button.textColor, colorRoles);
+    const rounded = tokenReferenceForRadius(button.borderRadius, roundedTokens);
+
+    const token = compactObject({
+      backgroundColor: background ?? toHex(button.backgroundColor),
+      textColor: text ?? toHex(button.color ?? button.textColor),
+      rounded: rounded ?? normalizeRadius(button.borderRadius),
+      padding: normalizePadding(button.padding),
+      height: normalizeDimension(button.height),
+    });
+    if (token) components['button-observed'] = token;
+  }
+
+  const input = firstInput(result.components?.inputs);
+  if (input) {
+    const state = input.states?.default ?? input;
+    const token = compactObject({
+      backgroundColor: tokenReferenceForColor(state.backgroundColor, colorRoles) ?? toHex(state.backgroundColor),
+      textColor: tokenReferenceForColor(state.color ?? state.textColor, colorRoles) ?? toHex(state.color ?? state.textColor),
+      rounded: tokenReferenceForRadius(state.borderRadius, roundedTokens) ?? normalizeRadius(state.borderRadius),
+      padding: normalizePadding(state.padding),
+    });
+    if (token) components['input-observed'] = token;
+  }
+
+  return components;
+}
+
+function buildColorsSection(colorRoles) {
+  const lines = ['## Colors'];
+  for (const [role, hex] of Object.entries(colorRoles)) {
+    lines.push(`- **${titleize(role)}** (${hex}): Observed color token extracted from the site's palette, semantic CSS, or component styles.`);
+  }
+  return lines.join('\n');
+}
+
+function buildTypographySection(result, typographyTokens) {
+  const lines = ['## Typography'];
+  const tokenEntries = Object.entries(typographyTokens).slice(0, 6);
+
+  for (const [name, token] of tokenEntries) {
+    const parts = [token.fontFamily, token.fontSize, humanWeight(token.fontWeight)]
+      .filter(Boolean);
+    lines.push(`- **${titleize(name)}**: ${parts.join(', ')}`);
+  }
+
+  if (result.typography?.sources?.googleFonts?.length) {
+    lines.push(`- **Font source**: Google Fonts (${result.typography.sources.googleFonts.join(', ')})`);
+  }
+
+  return lines.join('\n');
+}
+
+function buildLayoutSection(result, spacingTokens) {
+  const scale = result.spacing?.scaleType ? `${result.spacing.scaleType} spacing scale` : null;
+  const breakpoints = (result.breakpoints ?? []).map(bp => bp.px).filter(Boolean).slice(0, 6);
+  const lines = ['## Layout'];
+
+  if (scale) {
+    lines.push(`Observed spacing scale: ${scale}.`);
+  }
+
+  if (Object.keys(spacingTokens).length) {
+    lines.push(`- **Spacing tokens**: ${Object.entries(spacingTokens).map(([name, value]) => `${name} ${value}`).join(', ')}`);
+  }
+
+  if (breakpoints.length) {
+    lines.push(`- **Responsive breakpoints**: ${breakpoints.join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+function buildElevationSection(result) {
+  const shadows = result.shadows ?? [];
+  const lines = ['## Elevation & Depth'];
+  lines.push(`Observed box-shadow styles: ${shadows.slice(0, 3).map(s => s.shadow).join('; ')}`);
+  return lines.join('\n');
+}
+
+function buildShapesSection(roundedTokens) {
+  const lines = ['## Shapes'];
+  const rounded = Object.entries(roundedTokens).map(([name, value]) => `${name} ${value}`).join(', ');
+  lines.push(`Observed rounded-corner tokens: ${rounded}.`);
+  return lines.join('\n');
+}
+
+function buildComponentsSection(result) {
+  const lines = ['## Components'];
+
+  const button = firstButton(result.components?.buttons);
+  if (button) {
+    const btn = button.states?.default ?? button;
+    const parts = [];
+    if (btn.borderRadius) {
+      parts.push(`radius ${btn.borderRadius}`);
+    }
+    if (btn.backgroundColor && !isTransparentColor(btn.backgroundColor)) {
+      const hex = toHex(btn.backgroundColor);
+      parts.push(`background ${hex ?? btn.backgroundColor}`);
+    }
+    if (btn.color ?? btn.textColor) parts.push(`text ${toHex(btn.color ?? btn.textColor) ?? (btn.color ?? btn.textColor)}`);
+    if (btn.padding) parts.push(`padding ${btn.padding}`);
+    if (hasVisibleBorder(btn.border)) parts.push(`border ${btn.border}`);
+    if (parts.length) {
+      lines.push(`- **Buttons**: Observed sample with ${parts.join(', ')}`);
     }
+  }
 
-    const inputs = result.components?.inputs;
-    const firstInput = inputs?.text?.[0] ?? (Array.isArray(inputs) ? inputs[0] : null);
-    if (firstInput) {
-      const inp = firstInput.states?.default ?? firstInput;
-      const parts = [];
-      if (inp.border) parts.push(`${inp.border.split(' ').slice(0, 2).join(' ')} border`);
-      if (inp.borderRadius) parts.push(`${inp.borderRadius} radius`);
-      if (parts.length) { lines.push(`- **Inputs**: ${capitalize(parts.join(', '))}`); hasContent = true; }
+  const input = firstInput(result.components?.inputs);
+  if (input) {
+    const inp = input.states?.default ?? input;
+    const parts = [];
+    if (hasVisibleBorder(inp.border)) parts.push(`${inp.border.split(' ').slice(0, 2).join(' ')} border`);
+    if (inp.borderRadius) parts.push(`${inp.borderRadius} radius`);
+    if (parts.length) {
+      lines.push(`- **Inputs**: Observed sample with ${parts.join(', ')}`);
     }
+  }
 
-    const radiiAll = result.borderRadius?.values ?? [];
-    const radii = radiiAll.filter(v => v.value && !v.value.trim().includes(' ')).slice(0, 4).map(v => v.value);
-    if (radii.length) { lines.push(`- **Border radius scale**: ${radii.join(', ')}`); hasContent = true; }
+  return lines.length > 1 ? lines.join('\n') : null;
+}
 
-    const shadows = result.shadows ?? [];
-    if (shadows.length) {
-      lines.push(`- **Elevation**: uses box shadows for depth`);
-      hasContent = true;
+function toYaml(value, indent = 0) {
+  const pad = '  '.repeat(indent);
+  let yaml = '';
+
+  for (const [key, child] of Object.entries(value)) {
+    if (child == null) continue;
+    if (typeof child === 'object' && !Array.isArray(child)) {
+      if (!Object.keys(child).length) continue;
+      yaml += `${pad}${yamlKey(key)}:\n${toYaml(child, indent + 1)}`;
     } else {
-      lines.push(`- **Elevation**: flat design, no shadows`);
-      hasContent = true;
+      yaml += `${pad}${yamlKey(key)}: ${yamlScalar(child)}\n`;
     }
+  }
 
-    if (hasContent) sections.push(lines.join('\n'));
+  return yaml;
+}
+
+function yamlKey(key) {
+  return /^[A-Za-z_][A-Za-z0-9_-]*$/.test(key) ? key : JSON.stringify(key);
+}
+
+function yamlScalar(value) {
+  if (typeof value === 'number') return String(value);
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  return JSON.stringify(String(value));
+}
+
+function typographyTokenName(style, index) {
+  const contexts = style.contexts ?? (style.context ? [style.context] : []);
+  const normalized = contexts.map(c => String(c).toLowerCase());
+
+  if (normalized.some(c => /^h1$/.test(c))) return 'headline-display';
+  if (normalized.some(c => /^h2$/.test(c))) return 'headline-lg';
+  if (normalized.some(c => /^h3$/.test(c))) return 'headline-md';
+  if (normalized.some(c => /^h[4-6]$/.test(c))) return 'headline-sm';
+  if (normalized.some(c => c === 'button')) return 'label-lg';
+  if (normalized.some(c => c === 'a')) return 'label-md';
+  if (normalized.some(c => c === 'p' || c === 'div')) return 'body-md';
+
+  return `text-${index + 1}`;
+}
+
+function uniqueTokenName(baseName, usedNames) {
+  let name = sanitizeTokenName(baseName);
+  let suffix = 2;
+  while (usedNames.has(name)) {
+    name = `${sanitizeTokenName(baseName)}-${suffix}`;
+    suffix++;
   }
+  usedNames.add(name);
+  return name;
+}
 
-  // --- Do's and Don'ts ---
-  {
-    const dos = [];
-    const donts = [];
-
-    // Infer from border radius
-    const radiiAll = result.borderRadius?.values ?? [];
-    const radii = radiiAll.filter(v => v.value && !v.value.trim().includes(' ')).map(v => parseFloat(v.value));
-    if (radii.length) {
-      const hasZero = radii.some(r => r === 0);
-      const hasLarge = radii.some(r => r >= 20);
-      if (hasZero && hasLarge) donts.push("Don't mix fully rounded and sharp corners in the same view");
-      else if (hasLarge) dos.push('Do use rounded corners consistently across interactive elements');
-      else if (hasZero) dos.push('Do maintain sharp corners for a precise, technical feel');
-    }
+function sanitizeTokenName(name) {
+  return String(name)
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[^a-zA-Z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase() || 'token';
+}
 
-    // Infer from colors
-    dos.push('Do use the primary color sparingly — only for the most important action per screen');
-    dos.push('Do maintain 4.5:1 contrast ratio for all body text (WCAG AA)');
+function normalizeFontFamily(value) {
+  if (!value) return null;
+  return String(value).trim().replace(/\s+/g, ' ');
+}
 
-    // Infer from shadows
-    if (!(result.shadows?.length)) {
-      dos.push('Do convey depth through background and border contrast rather than shadows');
-    }
+function normalizeFontWeight(value) {
+  if (value == null) return null;
+  const parsed = parseInt(value, 10);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+function normalizeLineHeight(value) {
+  if (value == null) return null;
+  const raw = String(value).trim();
+  const dimension = normalizeDimension(raw);
+  if (dimension) return dimension;
+  const parsed = parseFloat(raw);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+function normalizeDimension(value) {
+  if (value == null) return null;
+  if (typeof value === 'number') return `${value}px`;
+
+  const clean = String(value).split('(')[0].trim();
+  const match = clean.match(/^(-?\d*\.?\d+)(px|em|rem)$/i);
+  if (!match) return null;
+  return `${trimNumber(match[1])}${match[2].toLowerCase()}`;
+}
+
+function normalizeRadius(value) {
+  if (value == null) return null;
+  const raw = String(value).trim();
+  if (raw === '50%' || raw === '100%') return '9999px';
+  return normalizeDimension(raw);
+}
 
-    const lines = ['## Do\'s and Don\'ts', ...dos.map(d => `- ${d}`), ...donts.map(d => `- ${d}`)];
-    sections.push(lines.join('\n'));
+function normalizePadding(value) {
+  if (value == null) return null;
+  const parts = String(value).trim().split(/\s+/).map(normalizeDimension);
+  if (parts.some(part => !part)) return null;
+  return parts.join(' ');
+}
+
+function tokenReferenceForColor(raw, colorRoles) {
+  const hex = toHex(raw);
+  if (!hex) return null;
+  const match = Object.entries(colorRoles).find(([, value]) => value.toLowerCase() === hex.toLowerCase());
+  return match ? `{colors.${match[0]}}` : null;
+}
+
+function tokenReferenceForRadius(raw, roundedTokens) {
+  const radius = normalizeRadius(raw);
+  if (!radius) return null;
+  const match = Object.entries(roundedTokens).find(([, value]) => value === radius);
+  return match ? `{rounded.${match[0]}}` : null;
+}
+
+function hasKeys(object) {
+  return Boolean(object && Object.keys(object).length);
+}
+
+function hasLayoutEvidence(result, spacingTokens) {
+  return hasKeys(spacingTokens) || (result.breakpoints ?? []).some(bp => bp.px);
+}
+
+function hasElevationEvidence(result) {
+  return result.shadows?.length > 0;
+}
+
+function hasComponentEvidence(result) {
+  return Boolean(firstButton(result.components?.buttons) || firstInput(result.components?.inputs));
+}
+
+function firstButton(buttons) {
+  if (!Array.isArray(buttons)) return null;
+  const normalized = buttons.map(button => button.states?.default ?? button);
+  return normalized.find(button =>
+    button.backgroundColor && !isTransparentColor(button.backgroundColor) ||
+    positiveDimension(button.borderRadius) ||
+    meaningfulPadding(button.padding) ||
+    hasVisibleBorder(button.border)
+  ) ?? normalized.find(button =>
+    button.backgroundColor ||
+    button.color ||
+    button.textColor ||
+    button.padding ||
+    button.borderRadius ||
+    hasVisibleBorder(button.border)
+  ) ?? null;
+}
+
+function firstInput(inputs) {
+  if (!inputs) return null;
+  if (Array.isArray(inputs)) return inputs[0] ?? null;
+  return inputs.text?.[0] ?? inputs.search?.[0] ?? Object.values(inputs).flat()[0] ?? null;
+}
+
+function compactObject(object) {
+  const entries = Object.entries(object).filter(([, value]) => value != null && value !== '');
+  return entries.length ? Object.fromEntries(entries) : null;
+}
+
+function isTransparentColor(value) {
+  if (!value) return true;
+  const raw = String(value).trim().toLowerCase();
+  if (raw === 'transparent') return true;
+
+  const hexAlpha = raw.match(/^#(?:[0-9a-f]{4}|[0-9a-f]{8})$/i);
+  if (hexAlpha) {
+    const alpha = raw.length === 5 ? raw[4] + raw[4] : raw.slice(7, 9);
+    return alpha === '00';
   }
 
-  return sections.join('\n\n') + '\n';
+  const functional = raw.match(/^rgba?\((.*)\)$/);
+  if (!functional) return false;
+
+  const body = functional[1].trim();
+  const slashParts = body.split('/');
+  if (slashParts.length === 2) return isZeroAlpha(slashParts[1]);
+
+  const commaParts = body.split(',');
+  return commaParts.length === 4 && isZeroAlpha(commaParts[3]);
+}
+
+function isZeroAlpha(value) {
+  const raw = String(value).trim();
+  const parsed = parseFloat(raw);
+  return !Number.isNaN(parsed) && parsed === 0;
+}
+
+function hasVisibleBorder(value) {
+  if (!value) return false;
+  const raw = String(value).trim().toLowerCase();
+  return raw !== 'none' && !raw.includes(' none ') && !raw.startsWith('0px none');
 }
 
-function capitalize(s) {
-  if (!s) return s;
-  return s.charAt(0).toUpperCase() + s.slice(1);
+function meaningfulPadding(value) {
+  if (!value) return false;
+  return String(value).split(/\s+/).some(part => positiveDimension(part));
+}
+
+function positiveDimension(value) {
+  if (!value) return false;
+  const match = String(value).match(/^(\d*\.?\d+)px$/);
+  return Boolean(match && parseFloat(match[1]) > 0);
+}
+
+function toHex(raw) {
+  if (raw == null) return null;
+  if (isTransparentColor(raw)) return null;
+  const parsed = convertColor(String(raw));
+  return parsed ? normalizeHex(parsed.hex) : null;
+}
+
+function normalizeHex(hex) {
+  return hex.toUpperCase();
+}
+
+function trimNumber(value) {
+  return String(parseFloat(value));
+}
+
+function titleize(s) {
+  return String(s)
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, c => c.toUpperCase());
 }
 
 function humanWeight(w) {
   if (!w) return '';
-  const n = parseInt(w);
+  const n = parseInt(w, 10);
   if (n <= 300) return 'light';
   if (n <= 400) return 'regular';
   if (n <= 500) return 'medium';
@@ -251,9 +582,3 @@ function humanWeight(w) {
   if (n <= 700) return 'bold';
   return 'extra-bold';
 }
-
-function toHex(raw) {
-  if (raw == null) return null;
-  const parsed = convertColor(String(raw));
-  return parsed ? parsed.hex : null;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dembrandt",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "description": "Extract design tokens and publicly visible CSS information from any website",
   "mcpName": "io.github.dembrandt/dembrandt",
   "main": "index.js",