bigpowers 2.42.1 → 2.43.0

package/extract-design/scripts/collect-styles.js

@@ -0,0 +1,149 @@
+// Browser sensor — collects computed styles inside Puppeteer page.
+// Returns raw JSON. No classification logic here.
+
+export function collect(page) {
+  return page.evaluate(() => {
+    const styles = [];
+    const title = document.title || '';
+
+    // Collect computed styles from every visible element
+    document.querySelectorAll('body, body *').forEach(el => {
+      const cs = getComputedStyle(el);
+      const tag = el.tagName.toLowerCase();
+      const rect = el.getBoundingClientRect();
+
+      if (rect.width === 0 && rect.height === 0 && tag !== 'body') return;
+
+      styles.push({
+        tag,
+        text: (el.textContent || '').trim().slice(0, 100),
+        backgroundColor: cs.backgroundColor,
+        color: cs.color,
+        borderColor: cs.borderColor,
+        fontFamily: cs.fontFamily,
+        fontSize: cs.fontSize,
+        fontWeight: cs.fontWeight,
+        lineHeight: cs.lineHeight,
+        letterSpacing: cs.letterSpacing,
+        padding: cs.padding,
+        margin: cs.margin,
+        gap: cs.gap,
+        borderRadius: cs.borderRadius,
+        boxShadow: cs.boxShadow,
+        backdropFilter: cs.backdropFilter,
+        cursor: cs.cursor,
+        zIndex: cs.zIndex,
+        width: rect.width,
+        height: rect.height,
+        isButton: tag === 'button' || el.getAttribute('role') === 'button',
+        isInput: tag === 'input' || tag === 'textarea' || tag === 'select',
+        isHeading: /^h[1-6]$/.test(tag),
+      });
+    });
+
+    // Collect declared fonts from <link> tags
+    const declaredFonts = [];
+    document.querySelectorAll('link[rel="stylesheet"]').forEach(l => {
+      declaredFonts.push(l.href);
+    });
+
+    // Collect @font-face declarations from stylesheets
+    const fontFaceFamilies = new Set();
+    try {
+      for (const sheet of document.styleSheets) {
+        try {
+          for (const rule of sheet.cssRules || []) {
+            if (rule.constructor.name === 'CSSFontFaceRule' && rule.style) {
+              const family = rule.style.getPropertyValue('font-family');
+              if (family) fontFaceFamilies.add(family.replace(/['"]/g, '').trim());
+            }
+          }
+        } catch {
+          // Cross-origin stylesheets can't be inspected — skip
+        }
+      }
+    } catch {
+      // Some browsers throw on styleSheets access — skip
+    }
+
+    return { title, styles, declaredFonts, fontFaceFamilies: [...fontFaceFamilies] };
+  });
+}
+
+/**
+ * Collect pseudo-state variants for detected component elements.
+ * Forces :hover state and reads computed styles.
+ * @param {Object} page — Puppeteer page
+ * @param {Array<Object>} componentStyles — array of { styleSignature, componentName }
+ * @returns {Promise<Record<string, Object>>} — variant component tokens
+ */
+export async function collectPseudoStates(page, componentStyles) {
+  const variants = {};
+
+  for (const comp of componentStyles) {
+    // Hover state
+    try {
+      const hoverStyles = await page.evaluate((signature) => {
+        const elements = document.querySelectorAll('body, body *');
+        for (const el of elements) {
+          const cs = getComputedStyle(el);
+          const bg = cs.backgroundColor;
+          const rect = el.getBoundingClientRect();
+          const w = Math.round(rect.width);
+          const h = Math.round(rect.height);
+
+          if (bg === signature.bg &&
+              Math.abs(w - signature.width) < 10 &&
+              Math.abs(h - signature.height) < 10) {
+            return {
+              index: Array.from(document.querySelectorAll('body, body *')).indexOf(el),
+              exists: true,
+            };
+          }
+        }
+        return { exists: false };
+      }, { bg: comp.backgroundColor, width: comp.width || 0, height: comp.height || 0 });
+
+      if (hoverStyles.exists) {
+        // Use Puppeteer's hover API (not page.evaluate for pseudo-classes)
+        const elements = await page.$$('body, body *');
+        const el = elements[hoverStyles.index];
+        if (el) {
+          await el.hover();
+          await page.waitForTimeout(100); // Wait for transition
+
+          const hoverComputed = await page.evaluate((idx) => {
+            const els = document.querySelectorAll('body, body *');
+            const target = els[idx];
+            if (!target) return null;
+            const cs = getComputedStyle(target);
+            return { backgroundColor: cs.backgroundColor, color: cs.color, borderColor: cs.borderColor, boxShadow: cs.boxShadow };
+          }, hoverStyles.index);
+
+          if (hoverComputed) {
+            const changed = {};
+            if (hoverComputed.backgroundColor !== comp.backgroundColor && hoverComputed.backgroundColor !== 'rgba(0, 0, 0, 0)') {
+              changed.backgroundColor = hoverComputed.backgroundColor;
+            }
+            if (hoverComputed.color !== comp.textColor) {
+              changed.textColor = hoverComputed.color;
+            }
+            if (hoverComputed.borderColor !== comp.borderColor) {
+              changed.borderColor = hoverComputed.borderColor;
+            }
+            if (Object.keys(changed).length > 0) {
+              variants[`${comp.componentName}-hover`] = changed;
+            }
+          }
+
+          // Move mouse away to reset
+          await page.mouse.move(0, 0);
+        }
+      }
+    } catch {
+      // Pseudo-state detection is best-effort. Skip on failure.
+    }
+  }
+
+  return variants;
+}

package/extract-design/scripts/detect-components.js

@@ -0,0 +1,12 @@
+function extract(st) { const t = {}; if (st.backgroundColor && st.backgroundColor !== 'rgba(0, 0, 0, 0)') t.backgroundColor = st.backgroundColor; if (st.color && st.color !== 'rgba(0, 0, 0, 0)') t.textColor = st.color; if (st.borderRadius && st.borderRadius !== '0px') t.rounded = st.borderRadius; if (st.padding && st.padding !== '0px') { const p = st.padding.split(/\s+/); t.padding = p.length === 2 && p[0] === p[1] ? p[0] : st.padding; } if (st.height > 0) t.height = `${Math.round(st.height)}px`; return t; }
+export async function detectComponents(styles, page = null) { const u = []; const comp = {}; const pat = [];
+  const btnCands = styles.filter(s => { if (!s.width && !s.height) return false; return s.isButton || (s.width < 300 && s.height < 64 && s.height > 20 && s.backgroundColor && s.backgroundColor !== 'rgba(0, 0, 0, 0)' && s.borderRadius && s.borderRadius !== '0px' && s.text.length > 0 && s.text.length < 50); });
+  const uqBtns = new Map(); for (const c of btnCands) { const k = `${c.backgroundColor}|${c.color}|${c.borderRadius}`; if (!uqBtns.has(k)) uqBtns.set(k, c); }
+  const btns = [...uqBtns.values()]; if (btns.length) { comp['button-primary'] = extract(btns[0]); pat.push('button-primary'); if (btns.length > 1) { comp['button-secondary'] = extract(btns[1]); pat.push('button-secondary'); } }
+  const cardCands = styles.filter(s => s.backgroundColor && s.backgroundColor !== 'rgba(0, 0, 0, 0)' && s.borderRadius && s.borderRadius !== '0px' && s.padding && s.padding !== '0px' && (s.width > 200 || s.height > 100));
+  const uqCards = new Map(); for (const c of cardCands) { const k = `${c.backgroundColor}|${c.borderRadius}|${c.padding}`; if (!uqCards.has(k)) uqCards.set(k, c); }
+  const cards = [...uqCards.values()]; if (cards.length) { comp['card-standard'] = extract(cards[0]); pat.push('card-standard'); if (cards.length > 1) { comp['card-elevated'] = extract(cards[1]); pat.push('card-elevated'); } }
+  const inputs = styles.filter(s => s.isInput); if (inputs.length) { comp['input-field'] = extract(inputs[0]); pat.push('input-field'); }
+  if (!Object.keys(comp).length) u.push('No components detected.');
+  return { components: comp, detectedPatterns: pat, uncertain: u };
+}

package/extract-design/scripts/extract.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// extract-design — entry point
+// Orchestrates: Puppeteer → token classification → prose → DESIGN.md → lint → handoff
+
+import { existsSync, renameSync, copyFileSync, unlinkSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { log } from './lib/logging.js';
+import { BrowserExtractor } from './lib/browser.js';
+import { DesignValidator } from './lib/validator.js';
+import { classifyColors } from './classify-colors.js';
+import { classifyTypography } from './classify-typography.js';
+import { classifySpacing } from './classify-spacing.js';
+import { classifyRounded } from './classify-rounded.js';
+import { detectComponents } from './detect-components.js';
+import { generateProse } from './generate-prose.js';
+import { writeDESIGNmd } from './write-designd.js';
+import { writeGrillMeHandoff } from './lib/state.js';
+import { COVERAGE_MINIMUMS, OUTPUT_PATH } from './lib/constants.js';
+
+function parseArgs(argv) {
+  const a = { lintOnly: false };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--source' && argv[i + 1]) a.source = argv[++i];
+    else if (argv[i] === '--name' && argv[i + 1]) a.name = argv[++i];
+    else if (argv[i] === '--lint-only') a.lintOnly = true;
+  }
+  return a;
+}
+
+function buildHints(styles, colors, components) {
+  const glass = styles.some(s => s.backdropFilter && s.backdropFilter !== 'none');
+  const darkBg = styles.some(s => {
+    if (s.tag !== 'body') return false;
+    const m = s.backgroundColor?.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+    return m && parseInt(m[1]) + parseInt(m[2]) + parseInt(m[3]) < 100;
+  });
+  const ss = [];
+  if (glass) ss.push('glassmorphism');
+  if (darkBg) ss.push('dark');
+  const hasGrot = styles.some(s => {
+    const ff = (s.fontFamily || '').toLowerCase();
+    return ff.includes('inter') || ff.includes('helvetica') || ff.includes('grotesk') || ff.includes('archivo');
+  });
+  if (hasGrot && Object.keys(colors).length <= 8 && !glass) ss.push('swiss');
+  const ff = new Set(styles.map(s => s.fontFamily).filter(Boolean));
+  return {
+    dominantColorFamily: darkBg ? 'dark' : 'light',
+    styleSignals: ss.length ? ss : ['minimalist'],
+    fontCount: ff.size,
+    glassDetected: glass,
+    elevationStrategy: glass ? 'glass' : 'flat',
+  };
+}
+
+/**
+ * Check if the extraction returned usable data.
+ */
+function validateExtraction(light) {
+  const styles = light?.styles || [];
+  const hasStyledElements = styles.filter(s => {
+    const hasBg = s.backgroundColor && s.backgroundColor !== 'rgba(0, 0, 0, 0)';
+    const hasText = s.fontFamily && s.fontSize;
+    return (s.width > 0 || s.height > 0) && (hasBg || hasText);
+  }).length;
+
+  if (styles.length === 0) {
+    return {
+      tier: 'Tier 2 — Degraded',
+      message: 'No styled elements found. The prototype may be empty, JS-rendered (SPA shell), or contain no CSS.',
+      fix: 'Verify the HTML file contains visible styled elements. For SPAs, use a published URL with server-side rendering.',
+    };
+  }
+
+  if (hasStyledElements === 0) {
+    return {
+      tier: 'Tier 2 — Degraded',
+      message: `${styles.length} elements found but none have visible styles (all inherit/browser defaults).`,
+      fix: 'Add explicit CSS rules to the prototype before extraction.',
+    };
+  }
+
+  return null; // OK
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const start = Date.now();
+
+  // --- Lint-only mode ---
+  if (args.lintOnly) {
+    if (!existsSync(OUTPUT_PATH)) {
+      log.user(`Error: DESIGN_LATEST.md not found at ${OUTPUT_PATH}. Run without --lint-only first.`);
+      process.exit(1);
+    }
+    const v = new DesignValidator();
+    const r = v.lint(OUTPUT_PATH);
+    log.user(formatLint(r));
+    process.exit(r.summary.errors > 0 ? 1 : 0);
+  }
+
+  // --- Validate inputs ---
+  if (!args.source) {
+    log.user('Usage: node extract-design/scripts/extract.js --source <file|url> [--name "Name"] [--lint-only]');
+    process.exit(1);
+  }
+
+  const name = args.name || basename(args.source, '.html');
+
+  // --- Check if this is an update (existing DESIGN_LATEST.md) ---
+  const isUpdate = existsSync(OUTPUT_PATH);
+  const oldSnapshotPath = isUpdate ? `${OUTPUT_PATH}.pre-update` : null;
+
+  if (isUpdate) {
+    copyFileSync(OUTPUT_PATH, oldSnapshotPath);
+    log.info('update-detected', { existingPath: OUTPUT_PATH, snapshot: oldSnapshotPath });
+  }
+
+  // --- Launch Puppeteer ---
+  let pm;
+  try { pm = await import('puppeteer-core'); } catch { try { pm = await import('puppeteer'); } catch {} }
+
+  if (!pm) {
+    log.user('Error: Puppeteer not found. Install with: npm install puppeteer');
+    log.user('Or if you have Chrome installed: npm install puppeteer-core');
+    process.exit(1);
+  }
+
+  const extractor = new BrowserExtractor({ puppeteer: pm.default || pm });
+  let extraction;
+  try {
+    extraction = await extractor.extract(args.source);
+  } catch (err) {
+    log.user(`\nFATAL — Extraction failed:\n  ${err.message}`);
+    log.user('\nTroubleshooting:');
+    log.user('  • Verify the source is accessible (URL reachable, file exists)');
+    log.user('  • For SPAs, try a server-rendered or published URL');
+    log.user('  • Check that Chrome/Chromium is installed (npm install puppeteer)');
+    process.exit(1);
+  }
+
+  const styles = extraction.light.styles || [];
+
+  // --- Validate extraction quality ---
+  const validation = validateExtraction(extraction.light);
+  if (validation) {
+    log.user(`\n${validation.tier}`);
+    log.user(`  ${validation.message}`);
+    log.user(`  Fix: ${validation.fix}`);
+  }
+
+  // --- Classify tokens ---
+  const cr = classifyColors(styles, 'light');
+  const tr = classifyTypography(styles);
+  const sr = classifySpacing(styles);
+  const rr = classifyRounded(styles);
+  const compR = await detectComponents(styles, null);
+
+  // --- Detect pseudo-state variants (while browser is open) ---
+  let pseudoVariants = {};
+  try {
+    const compArr = Object.entries(compR.components).map(([name, tokens]) => ({
+      componentName: name,
+      backgroundColor: tokens.backgroundColor,
+      textColor: tokens.textColor,
+      width: parseInt(tokens.width) || 0,
+      height: parseInt(tokens.height) || 0,
+    })).filter(c => c.backgroundColor);
+
+    if (compArr.length > 0) {
+      pseudoVariants = await extractor.detectPseudoStates(compArr);
+      Object.assign(compR.components, pseudoVariants);
+      if (Object.keys(pseudoVariants).length > 0) {
+        log.info('pseudo-variants-detected', { variantCount: Object.keys(pseudoVariants).length });
+      }
+    }
+  } catch (err) {
+    log.warn('pseudo-states-skipped', { error: err.message });
+  }
+
+  // --- Font warnings ---
+  const fontWarnings = extraction.fontWarnings || [];
+
+  // --- Aggregate uncertain decisions ---
+  const allU = [
+    ...cr.uncertain, ...tr.uncertain, ...sr.uncertain, ...rr.uncertain, ...compR.uncertain, ...fontWarnings,
+  ];
+
+  const degraded = Object.keys(cr.colors).length < COVERAGE_MINIMUMS.MIN_COLORS ||
+                   Object.keys(tr.typography).length < COVERAGE_MINIMUMS.MIN_TYPOGRAPHY_LEVELS;
+
+  const hints = buildHints(styles, cr.colors, compR.components);
+
+  const prose = generateProse({
+    name, colors: cr.colors, typography: tr.typography,
+    spacing: sr.spacing, rounded: rr.rounded,
+    components: compR.components, hints,
+    detectedPatterns: compR.detectedPatterns,
+  });
+
+  // --- Dark mode ---
+  let cd;
+  if (extraction.dark?.styles) {
+    const dr = classifyColors(extraction.dark.styles, 'dark');
+    if (Object.keys(dr.colors).length) cd = dr.colors;
+  }
+
+  // --- Write DESIGN.md ---
+  writeDESIGNmd({
+    name, colors: cr.colors, typography: tr.typography,
+    spacing: sr.spacing, rounded: rr.rounded,
+    components: compR.components, prose, colorsDark: cd,
+  });
+
+  // --- Diff on update ---
+  let diffResult = null;
+  if (isUpdate && oldSnapshotPath && existsSync(oldSnapshotPath)) {
+    const validator = new DesignValidator();
+    try {
+      diffResult = validator.diff(oldSnapshotPath, OUTPUT_PATH);
+    } catch {
+      // Diff unavailable — skip
+    }
+    // Clean up snapshot
+    try { unlinkSync(oldSnapshotPath); } catch {}
+  }
+
+  // --- Lint ---
+  const validator = new DesignValidator();
+  let lr;
+  try { lr = validator.lint(OUTPUT_PATH); } catch {}
+
+  // --- Terminal summary ---
+  const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+  log.user(`\n=== extract-design complete ===`);
+  log.user(`Design: ${name}  |  Output: ${OUTPUT_PATH}`);
+  log.user(`Colors: ${Object.keys(cr.colors).length}  Typo: ${Object.keys(tr.typography).length}  Spacing: ${Object.keys(sr.spacing).length}  Rounded: ${Object.keys(rr.rounded).length}  Components: ${Object.keys(compR.components).length}`);
+  if (Object.keys(pseudoVariants).length > 0) log.user(`Pseudo-states: ${Object.keys(pseudoVariants).length} variants detected`);
+  if (cd) log.user(`Dark mode: ${Object.keys(cd).length} colors (differs from light)`);
+
+  if (isUpdate && diffResult && !diffResult.skipped) {
+    log.user(`\n--- Diff (update) ---`);
+    log.user(formatDiff(diffResult));
+  }
+
+  if (validation) log.user(`\n⚠️  ${validation.tier}: ${validation.message}`);
+
+  if (fontWarnings.length) {
+    log.user(`\n⚠️  Font declaration mismatches:`);
+    fontWarnings.forEach(w => log.user(`  • ${w}`));
+  }
+
+  if (allU.length) {
+    log.user(`\n⚠️  ${allU.length} uncertain decisions — run grill-me to validate:`);
+    allU.slice(0, 5).forEach(d => log.user(`  • ${d}`));
+    if (allU.length > 5) log.user(`  ... and ${allU.length - 5} more`);
+  }
+
+  if (lr && !lr.skipped) log.user(`\n${formatLint(lr)}`);
+  else log.user('\nValidation skipped (@google/design.md not available).');
+
+  log.user(`\nDuration: ${elapsed}s  |  Next: grill-me`);
+
+  // --- Handoff ---
+  writeGrillMeHandoff({
+    tokenCount: Object.keys(cr.colors).length + Object.keys(tr.typography).length,
+    componentCount: Object.keys(compR.components).length,
+    uncertainCount: allU.length,
+    uncertainDecisions: allU.slice(0, 10),
+  });
+
+  log.info('extraction-complete', {
+    totalDurationMs: Date.now() - start,
+    outputPath: OUTPUT_PATH,
+  });
+
+  process.exit(degraded ? 2 : 0);
+}
+
+function formatLint(r) {
+  if (r.skipped) return 'Lint skipped.';
+  return `Lint: ${r.summary.errors} errors, ${r.summary.warnings} warnings, ${r.summary.info} info`;
+}
+
+function formatDiff(dr) {
+  const lines = [];
+  if (dr.tokens?.colors) {
+    const c = dr.tokens.colors;
+    if (c.added?.length) lines.push(`  Colors added: ${c.added.join(', ')}`);
+    if (c.removed?.length) lines.push(`  Colors removed: ${c.removed.join(', ')}`);
+    if (c.modified?.length) lines.push(`  Colors modified: ${c.modified.join(', ')}`);
+  }
+  if (dr.tokens?.typography) {
+    const t = dr.tokens.typography;
+    if (t.added?.length) lines.push(`  Typography added: ${t.added.join(', ')}`);
+    if (t.removed?.length) lines.push(`  Typography removed: ${t.removed.join(', ')}`);
+    if (t.modified?.length) lines.push(`  Typography modified: ${t.modified.join(', ')}`);
+  }
+  if (dr.regression) lines.push('  ⚠️  REGRESSION detected — more errors in new version.');
+  return lines.length ? lines.join('\n') : '  No token-level changes detected.';
+}
+
+main().catch(err => {
+  log.user(`\nFATAL — Unexpected error:\n  ${err.message}`);
+  log.error('unhandled', { error: err.message, stack: err.stack });
+  process.exit(1);
+});

package/extract-design/scripts/generate-prose.js

@@ -0,0 +1,38 @@
+import { AGENT_NOTE_LOW_CONFIDENCE } from './lib/constants.js';
+export function generateProse(ctx) {
+  const { name, colors, typography, spacing, rounded, components, hints, detectedPatterns } = ctx;
+  const glass = hints?.glassDetected, dark = hints?.dominantColorFamily === 'dark', swiss = (hints?.styleSignals||[]).includes('swiss');
+  let personality = 'modern and functional';
+  if (glass && dark) personality = 'ethereal and depth-driven, using glassmorphism for layered space';
+  else if (swiss) personality = 'architectural and editorial, rooted in International Typographic Style';
+  else if (dark) personality = 'dark, sophisticated, and focused';
+
+  const secs = [];
+  secs.push(`## Overview\n\n${AGENT_NOTE_LOW_CONFIDENCE}\n\n${name} is a ${personality} design system.${glass ? ' The UI relies on frosted glass surfaces and blurred backgrounds to create physical depth through transparency.' : ''}${hints?.fontCount===1?' It uses a single type family.':''}`);
+
+  let cl = ['## Colors',''];
+  for (const [k,v] of Object.entries(colors||{})) { if (k==='surface') cl.push(`**Surface (${v}):** Foundational background.`); else if (k==='on-surface') cl.push(`**On Surface (${v}):** Primary text.`); else if (k==='tertiary') cl.push(`**Tertiary (${v}):** Primary accent for CTAs.`); else if (k==='error') cl.push(`**Error (${v}):** Destructive actions.`); else if (k.includes('container')) cl.push(`**${k} (${v}):** Elevated surface.`); else cl.push(`**${k} (${v}):** Used throughout.`); }
+  cl.push('','Maintain WCAG AA contrast (4.5:1).'); secs.push(cl.join('\n'));
+
+  let tl = ['## Typography',''];
+  for (const [k,v] of Object.entries(typography||{})) tl.push(`**${k}:** ${v.fontFamily} at ${v.fontSize}${v.fontWeight!=='400'?`, weight ${v.fontWeight}`:''}.`);
+  secs.push(tl.join('\n'));
+
+  if (spacing?.unit) secs.push(`## Layout\n\nLayout follows a ${spacing.unit} base grid${spacing.half?` with a ${spacing.half} half-step`:''}. Components use containment principles.`);
+  secs.push(`## Elevation & Depth\n\n${glass?'Depth is achieved through glassmorphism — frosted surfaces with backdrop blur.':'A flat design with hierarchy via typography, spacing, and color contrast.'}`);
+  const re = Object.entries(rounded||{}).filter(([k])=>k!=='none');
+  secs.push(`## Shapes\n\n${re.length?`Elements use rounded corners (${re.map(([,v])=>v).join(', ')}).`:'Sharp corners — engineered aesthetic.'}`);
+
+  let cpl = ['## Components','',AGENT_NOTE_LOW_CONFIDENCE,''];
+  if (detectedPatterns?.includes('button-primary')) cpl.push('**Buttons:** Primary buttons use accent color.','');
+  if (detectedPatterns?.includes('card-standard')) cpl.push('**Cards:** Containers with rounded corners group content.','');
+  if (detectedPatterns?.includes('input-field')) cpl.push('**Inputs:** Distinct background separates editable areas.','');
+  secs.push(cpl.join('\n'));
+
+  const dos = ['Maintain WCAG AA contrast','Use consistent spacing','Keep typography hierarchy clear','Treat interactive elements consistently'];
+  const donts = ["Don't mix rounded and sharp corners","Don't use more than two font weights per screen"];
+  if (glass) { dos.push('Use backdrop-filter on elevated surfaces'); donts.push("Don't use solid backgrounds on cards"); }
+  if (dark) donts.push("Don't introduce light backgrounds");
+  secs.push(`## Do's and Don'ts\n\n${AGENT_NOTE_LOW_CONFIDENCE}\n\n${dos.map(d=>'- '+d).join('\n')}\n${donts.map(d=>'- '+d).join('\n')}`);
+  return secs.join('\n\n');
+}