scenescout 3.14.1 → 3.16.0

package/dist/engine/design.js

@@ -21,6 +21,17 @@
  * grays, a focused accent palette, one elevation system, consistent
  * controls, visible keyboard focus.
  */
+import { missingName, NAME_SRC, placeholderOnly } from "./collector.js";
+/**
+ * Whether some text names a filter or a facet, as page-side source: one of its
+ * words, split at camelCase and punctuation, is filter(s) or facet(s). Whole
+ * words only, so "filterable-list" or "unfiltered" says nothing.
+ */
+export const FILTER_WORDS_SRC = `(s) => (s || "").replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z]+/).some((w) => w === "filter" || w === "filters" || w === "facet" || w === "facets")`;
+/** FILTER_WORDS_SRC run outside a page, from the same source, so a table test exercises the rule the collector ships. */
+export function namesFilter(text) {
+    return new Function(`return (${FILTER_WORDS_SRC});`)()(text);
+}
 /**
  * In-page collector, shipped as a string expression (immune to loader
  * transforms — same rationale as the interactables collector).
@@ -79,7 +90,38 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
     }
     return false;
   };
+  const nameOf = ${NAME_SRC};
+  const namesFilter = ${FILTER_WORDS_SRC};
+  // A filter panel names itself one somewhere on the way up: its test id, id,
+  // label, the element its aria-labelledby points at, or a fieldset's legend.
+  const inFilterOf = (el) => {
+    for (let n = el, i = 0; n && n !== document.body && i < 15; n = n.parentElement, i++) {
+      const legend = n.tagName === "FIELDSET" ? n.querySelector(":scope > legend") : null;
+      const labelledBy = (n.getAttribute("aria-labelledby") || "").split(/\\s+/).filter(Boolean)
+        .map((id) => { const t = document.getElementById(id); return t ? t.textContent || "" : ""; }).join(" ");
+      const said = [n.getAttribute("data-testid"), n.id, n.getAttribute("aria-label"), labelledBy, legend ? legend.textContent : ""].join(" ");
+      if (namesFilter(said)) return true;
+    }
+    return false;
+  };
   const interactiveSel = 'a[href], button, input, select, textarea, [role="button"], [role="link"], [onclick]';
+  // The app shell, as the markup declares it. A <header>/<footer> inside a
+  // <section> is that section's own heading block, not the page banner (the
+  // HTML banner/contentinfo rule), and nothing inside the main content, an
+  // article or a dialog is shell however it is marked up.
+  const shellSel = 'nav, aside, header, footer, [role="navigation"], [role="banner"], [role="complementary"], [role="contentinfo"]';
+  const inShell = (el) => {
+    if (el.closest('main, [role="main"], article, [role="article"], dialog, [role="dialog"], [role="alertdialog"]')) return false;
+    for (let lm = el.closest(shellSel); lm; lm = lm.parentElement ? lm.parentElement.closest(shellSel) : null) {
+      const sectional = (lm.tagName === "HEADER" || lm.tagName === "FOOTER") && !lm.hasAttribute("role");
+      if (!sectional || !(lm.parentElement && lm.parentElement.closest("section"))) return true;
+    }
+    return false;
+  };
+  const ownFill = (s) => {
+    const c = parseColor(s.backgroundColor);
+    return (c !== null && c[3] > 0) || (!!s.backgroundImage && s.backgroundImage !== "none");
+  };
   // Saturated (non-gray) color test on a parsed [r,g,b,a].
   const isSaturated = (p) => p && (Math.max(p[0], p[1], p[2]) - Math.min(p[0], p[1], p[2])) > 40;
   const hueDeg = (p) => {
@@ -91,6 +133,33 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
     else h = (r - g) / (max - min) + 4;
     return ((h * 60) + 360) % 360;
   };
+  // The box a pointer user hits to operate a native input (StyleRecord.target).
+  const unionBox = (boxes) => {
+    let l = Infinity, t = Infinity, r = -Infinity, b = -Infinity;
+    for (const x of boxes) { l = Math.min(l, x.left); t = Math.min(t, x.top); r = Math.max(r, x.right); b = Math.max(b, x.bottom); }
+    return { x: Math.round(l), y: Math.round(t), w: Math.round(r - l), h: Math.round(b - t) };
+  };
+  const gapBetween = (a, b) => Math.max(a.left - b.right, b.left - a.right, a.top - b.bottom, b.top - a.bottom, 0);
+  const targetOf = (el, rect, hiddenInput) => {
+    if (el.tagName !== "INPUT") return null;
+    const boxes = [];
+    for (const label of Array.from(el.labels || [])) {
+      const lr = label.getBoundingClientRect();
+      if (lr.width === 0 || lr.height === 0) continue;
+      // A label elsewhere on the page also operates the input, but it is a
+      // second target, not a bigger one; only a label that wraps or touches
+      // the input makes one box with it. A hidden input has no box of its own,
+      // so any label of it is the target.
+      if (hiddenInput || label.contains(el) || gapBetween(lr, rect) <= 4) boxes.push(lr);
+    }
+    if (hiddenInput && boxes.length === 0 && el.parentElement) {
+      const zone = el.parentElement.closest('button, [role="button"], [onclick], [tabindex]:not([tabindex="-1"])');
+      if (zone) boxes.push(zone.getBoundingClientRect());
+    }
+    if (boxes.length === 0) return null;
+    if (!hiddenInput) boxes.push(rect);
+    return unionBox(boxes);
+  };
   const vh = window.innerHeight;
   let density = 0;
   const all = document.querySelectorAll("body *");
@@ -138,6 +207,8 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
     const slop = sideStripe || gradientText || glass || glow || aiGradient;
     if (!interactive && !ownText && !slop) continue;
     const fullText = ownText ? (el.textContent || "").trim().replace(/\\s+/g, " ") : "";
+    const target = interactive ? targetOf(el, rect, srOnly || s.opacity === "0") : null;
+    const named = interactive ? nameOf(el) : null;
     out.push({
       tag: el.tagName.toLowerCase(),
       testid: el.getAttribute("data-testid"),
@@ -157,14 +228,25 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
       padding: [px(s.paddingTop), px(s.paddingRight), px(s.paddingBottom), px(s.paddingLeft)],
       marginV: [px(s.marginTop), px(s.marginBottom)],
       radius: px(s.borderTopLeftRadius),
-      shadow: s.boxShadow && s.boxShadow !== "none" ? s.boxShadow.replace(/\\s+/g, " ").slice(0, 80) : "",
+      shadow: s.boxShadow && s.boxShadow !== "none" ? s.boxShadow.replace(/\\s+/g, " ").slice(0, 400) : "",
       // srOnly text is DELIBERATELY a 1px box with overflow hidden — the exact
       // signature of "text wider than its box". Flagging it reported the
       // accessibility affordance itself as an accessibility defect.
       clipped: !srOnly && el.scrollWidth > el.clientWidth + 2 && /hidden|clip/.test(s.overflowX) && s.textOverflow !== "ellipsis" && ownText,
+      ...(target ? { target } : {}),
       fixed: s.position === "fixed" || s.position === "sticky",
       required: el.hasAttribute("required") || el.getAttribute("aria-required") === "true",
       submitish: el.matches('button[type="submit"], input[type="submit"]') || /\\b(save|submit|create|send|confirm|apply|continue|next|finish|approve|sign)\\b/i.test(fullText),
+      ...(named ? { name: named.name, nameFrom: named.from, ariaHidden: el.closest('[aria-hidden="true"]') !== null } : {}),
+      inputType: el.tagName === "INPUT" ? (el.getAttribute("type") || "text").toLowerCase() : "",
+      role: (el.getAttribute("role") || "").toLowerCase(),
+      filled: ownFill(s),
+      inForm: !!el.closest('form, [role="form"]'),
+      inRow: !!el.closest('tr, [role="row"]'),
+      inSearch: !!el.closest('search, [role="search"]'),
+      inBreadcrumb: !!el.closest('[aria-label*="breadcrumb" i], [class*="breadcrumb" i]'),
+      inFilter: interactive && inFilterOf(el),
+      shell: inShell(el),
       sideStripe, gradientText, glass, glow, aiGradient,
     });
   }
@@ -231,10 +313,23 @@ function hueOf([r, g, b]) {
         h = (r - g) / (max - min) + 4;
     return Math.round((h * 60 + 360) % 360);
 }
-const label = (r) => (r.testid ? `[${r.testid}]` : `<${r.tag}> "${r.text.slice(0, 30) || "(no text)"}"`);
+/**
+ * How an audit line names an element: its test id, else what a user hears for
+ * a control (its accessible name, the snapshot's), else its own text. A name
+ * that is only the field's name attribute or type is not one anybody hears,
+ * so it gives way to the text.
+ */
+const label = (r) => {
+    if (r.testid)
+        return `[${r.testid}]`;
+    const heard = r.name && r.nameFrom !== "fallback" ? r.name : r.text;
+    return `<${r.tag}> "${heard.slice(0, 30) || "(no text)"}"`;
+};
 /** One wording for a small target, page or shell alike: the shell section's, so its prose is unchanged. */
-const tinyTargetDetail = (r) => `${label(r)} — ${Math.round(r.rect.w)}×${Math.round(r.rect.h)}px tap target`;
+const tinyTargetDetail = (r) => `${label(r)} — ${Math.round(targetBox(r).w)}×${Math.round(targetBox(r).h)}px tap target`;
 const clippedTextDetail = (r) => `${label(r)} — text is clipped by its container`;
+/** One wording for body-coloured links, page or shell alike. */
+const indistinctDetail = (bodyColor) => `links with no underline in the body-text colour ${bodyColor}`;
 /**
  * Stable identity for one styled element, used to recognise the SAME component
  * across routes.
@@ -282,9 +377,202 @@ function gridValues(top) {
         .map((v) => `${v}px`)
         .join(", ");
 }
+/** The box a pointer user hits to operate the control: its label or drop zone where one operates it, else its own. */
+export function targetBox(r) {
+    return r.target ?? r.rect;
+}
+/** The WCAG 2.2 target-size minimum, in CSS pixels. */
+const MIN_TARGET = 24;
+/** Inputs that are buttons, not fields. */
+const BUTTON_INPUT_TYPES = new Set(["submit", "button", "reset", "image"]);
+/** Inputs a user types into. Every other type (a checkbox, radio, range, colour or file) is picked rather than typed, and outside a form most of those apply at once. */
+const TYPED_INPUT_TYPES = new Set(["text", "email", "number", "tel", "url", "password", "date", "datetime-local", "month", "week", "time"]);
+/** A button, or a link painted as one. Fields, selects and plain links never compete as actions. */
+function buttonLike(r) {
+    if (r.tag === "button" || r.role === "button")
+        return true;
+    if (r.tag === "input")
+        return BUTTON_INPUT_TYPES.has(r.inputType);
+    return r.tag === "a" && r.filled;
+}
+/**
+ * The fields a user is asked to fill in and submit. Excluded: controls in a
+ * table row (a selection checkbox, or a select that edits the row in place),
+ * search boxes, controls in a panel that names itself a filter, and inputs
+ * that are buttons. When some fields sit in a <form>, only those count: the
+ * rest of the page (filters, toolbars) is not part of what gets submitted. A
+ * page with no <form> at all is judged on the fields a user types into,
+ * because many apps build their forms without the element; its selects and
+ * every input not in TYPED_INPUT_TYPES (checkboxes, radios, file pickers) are
+ * left out, since outside a form those are most often filters and settings
+ * that apply as they change.
+ */
+function formFields(records) {
+    const candidates = records.filter((r) => r.interactive &&
+        (r.tag === "input" || r.tag === "select" || r.tag === "textarea") &&
+        !BUTTON_INPUT_TYPES.has(r.inputType) &&
+        r.inputType !== "search" &&
+        !r.inSearch &&
+        !r.inRow &&
+        !r.inFilter);
+    const inForm = candidates.filter((r) => r.inForm);
+    return inForm.length > 0 ? inForm : candidates.filter(typedField);
+}
+/** A field a user types into: a text-like input or a textarea. */
+function typedField(r) {
+    return r.tag === "textarea" || (r.tag === "input" && TYPED_INPUT_TYPES.has(r.inputType || "text"));
+}
+/**
+ * The layers of a computed box-shadow that draw something: a layer with no
+ * offset, blur or spread, or a transparent colour, paints nothing. Utility CSS
+ * stacks such placeholder layers (empty rings) in front of the real shadow on
+ * every element, so a census keyed on the raw value counts the placeholders.
+ * Returned in order, whitespace normalized; empty when nothing is drawn.
+ */
+export function shadowLayers(shadow) {
+    const layers = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of shadow) {
+        if (ch === "(")
+            depth += 1;
+        if (ch === ")")
+            depth = Math.max(0, depth - 1);
+        if (ch === "," && depth === 0) {
+            layers.push(current);
+            current = "";
+        }
+        else
+            current += ch;
+    }
+    layers.push(current);
+    return layers
+        .map((l) => l.replace(/\s+/g, " ").trim())
+        .filter((l) => {
+        if (!l || l === "none")
+            return false;
+        const lengths = (l.match(/-?[0-9.]+px/g) ?? []).map(parseFloat);
+        if (lengths.every((n) => n === 0))
+            return false;
+        if (/\btransparent\b/.test(l))
+            return false;
+        const colour = l.match(/rgba?\([^)]*\)/);
+        return !(colour && parseRgb(colour[0])?.[3] === 0);
+    });
+}
+/** The elevation a box-shadow draws, as one key: its drawing layers. "" for none. */
+export function elevationKey(shadow) {
+    return shadowLayers(shadow).join(", ");
+}
+/**
+ * The layer that tells one elevation from the others listed beside it: its
+ * first layer that not every other key has. Shown in place of the whole value,
+ * whose differences often begin past any width an example can be given.
+ */
+export function distinguishingLayer(key, others) {
+    const layers = shadowLayers(key);
+    const rest = others.filter((o) => o !== key).map(shadowLayers);
+    return layers.find((l) => rest.some((o) => !o.includes(l))) ?? layers[0] ?? "";
+}
+/**
+ * A colour with no hue family is a gray: neutral or tinted (a slate or a warm
+ * stone), the shades text and surfaces are built from. Near-white and
+ * near-black are left out, as before: every page has them.
+ */
+export function grayOf(rgb) {
+    const avg = (rgb[0] + rgb[1] + rgb[2]) / 3;
+    return hueOf(rgb) === null && avg > 20 && avg < 245;
+}
+/**
+ * Grays counted as the steps of a scale: colours within GRAY_STEP of one in
+ * every channel are one step (a translucent text colour composited over two
+ * backgrounds lands a unit or two apart). Commonest first, each with its use count.
+ */
+export function grayCensus(colours) {
+    const freq = new Map();
+    for (const c of colours) {
+        if (!grayOf(c))
+            continue;
+        const k = c.join(",");
+        const e = freq.get(k) ?? { rgb: c, n: 0 };
+        e.n += 1;
+        freq.set(k, e);
+    }
+    const steps = [];
+    for (const e of [...freq.values()].sort((a, b) => b.n - a.n)) {
+        const near = steps.find((s) => s.rgb.every((v, i) => Math.abs(v - e.rgb[i]) <= GRAY_STEP));
+        if (near)
+            near.n += e.n;
+        else
+            steps.push({ ...e });
+    }
+    return steps.sort((a, b) => b.n - a.n);
+}
+/** How far apart, per channel, two grays may be and still be one step of a scale. */
+const GRAY_STEP = 4;
+/**
+ * The page's controls a screen-reader user cannot tell apart: fields and
+ * controls with no name, and fields whose only label is the placeholder. The
+ * snapshot's own predicates (collector.ts), over the snapshot's own name, so
+ * the audit and the snapshot agree on a page. Records with no name read are
+ * left out rather than guessed.
+ */
+export function unnamedControls(records) {
+    const named = records.filter((r) => r.interactive && typeof r.name === "string");
+    const asSnapshot = (r) => ({
+        role: r.role,
+        name: r.name ?? "",
+        nameFrom: r.nameFrom ?? null,
+        interactive: true,
+        ariaHidden: r.ariaHidden === true,
+    });
+    return {
+        unnamed: named.filter((r) => missingName(asSnapshot(r))),
+        placeholder: named.filter((r) => placeholderOnly(asSnapshot(r))),
+    };
+}
 /** Below the WCAG 2.2 target-size minimum; inline links are exempt by that rule. */
-function tooSmall(r) {
-    return r.tag !== "a" && (r.rect.h < 24 || r.rect.w < 24) && r.rect.h > 0;
+function undersized(r) {
+    const b = targetBox(r);
+    return r.interactive && r.tag !== "a" && (b.h < MIN_TARGET || b.w < MIN_TARGET) && b.h > 0;
+}
+const centreOf = (b) => [b.x + b.w / 2, b.y + b.h / 2];
+/** Distance from a point to the nearest edge of a box; 0 inside it. */
+function distanceToBox([px, py], b) {
+    const dx = Math.max(b.x - px, 0, px - (b.x + b.w));
+    const dy = Math.max(b.y - py, 0, py - (b.y + b.h));
+    return Math.hypot(dx, dy);
+}
+/**
+ * The WCAG 2.5.8 spacing exception: an undersized target passes when a 24px
+ * circle on its centre touches no other target and no other undersized
+ * target's circle. `others` is every interactive record on the page, shell
+ * included, since a neighbour in the shell is as easy to hit by mistake.
+ */
+export function spacedApart(r, others) {
+    const c = centreOf(targetBox(r));
+    for (const o of others) {
+        if (o === r || !o.interactive)
+            continue;
+        const ob = targetBox(o);
+        if (ob.w === 0 || ob.h === 0)
+            continue;
+        if (undersized(o)) {
+            const [ox, oy] = centreOf(ob);
+            if (Math.hypot(ox - c[0], oy - c[1]) < MIN_TARGET)
+                return false;
+        }
+        else if (distanceToBox(c, ob) < MIN_TARGET / 2)
+            return false;
+    }
+    return true;
+}
+/**
+ * A target that fails WCAG 2.5.8: under 24px, measured on what the user hits
+ * (targetBox), and not saved by the spacing exception.
+ */
+export function tooSmall(r, all) {
+    return undersized(r) && !spacedApart(r, all);
 }
 /**
  * Reduce raw style records + page facts to a judgeable design digest + score.
@@ -307,11 +595,16 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
         return { report: "DESIGN AUDIT: no visible styled elements found (page empty or not hydrated).", score: null, signatures: [], defects: [] };
     }
     const signatures = allRecords.map(styleSignature);
-    const isChrome = (r) => chromeKeys.has(styleSignature(r));
+    // Chrome is what the census has seen on most routes OR what the markup puts
+    // in a shell landmark. The census alone needs several audited routes before
+    // it knows anything, so the first pages of a run were scored with the whole
+    // shell in them and later ones without — a page's score depended on when it
+    // was audited. The landmark half is known from the first audit on.
+    const isChrome = (r) => r.shell || chromeKeys.has(styleSignature(r));
     const chromeRecords = allRecords.filter(isChrome);
     // Everything below scores THIS page. `records` deliberately shadows the full
     // set so no rule can accidentally reach past the page's own content.
-    const records = chromeKeys.size > 0 ? allRecords.filter((r) => !isChrome(r)) : allRecords;
+    const records = allRecords.filter((r) => !isChrome(r));
     if (records.length === 0) {
         return { report: "DESIGN AUDIT: this page is entirely shared layout chrome — nothing page-specific to score.", score: null, signatures, defects: [] };
     }
@@ -391,14 +684,16 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
         spacingLines.push(`${mar.pct}% of vertical margins are off a 4px grid — ad-hoc values: ${mar.top.map(([v, n]) => `${v}px×${n}`).join(", ")}`);
     if (spacingLines.length > 0)
         sections.push(`SPACING: ` + spacingLines.join("\n  "));
-    // ---- 5. Touch/click targets below ~24px are hard to hit. Inline links are
-    //      exempt (mirrors the WCAG 2.2 target-size exception); worst offenders first.
-    const tiny = records.filter((r) => r.interactive && tooSmall(r)).sort((a, b) => a.rect.w * a.rect.h - b.rect.w * b.rect.h);
+    // ---- 5. Touch/click targets below ~24px are hard to hit (WCAG 2.5.8). Measured
+    //      on what the user hits (a native input's label or drop zone), with
+    //      that rule's exceptions: inline links, and a small target with nothing
+    //      else within its 24px circle. Worst offenders first.
+    const tiny = records.filter((r) => tooSmall(r, allRecords)).sort((a, b) => targetBox(a).w * targetBox(a).h - targetBox(b).w * targetBox(b).h);
     if (tiny.length > 0) {
         sections.push(`TINY targets (${tiny.length}, smallest first):\n` +
             tiny
                 .slice(0, 6)
-                .map((r) => `  ⚠ ${label(r)} — ${r.rect.w}×${r.rect.h}px`)
+                .map((r) => `  ⚠ ${label(r)} — ${targetBox(r).w}×${targetBox(r).h}px`)
                 .join("\n"));
     }
     // ---- 6. Clipped text (overflow hidden without ellipsis) — content silently cut off.
@@ -443,15 +738,16 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     if (buttonHeights.length > 3) {
         consistency.push(`→ buttons render at ${buttonHeights.length} different heights (${buttonHeights.slice(0, 8).join(", ")}px) — 1–2 control sizes read as a system`);
     }
+    // Keyed on the layers that draw something (elevationKey); each example shows the layer that sets it apart.
     const shadows = new Map();
-    for (const r of records)
-        if (r.shadow)
-            shadows.set(r.shadow, (shadows.get(r.shadow) ?? 0) + 1);
+    for (const r of records) {
+        const key = elevationKey(r.shadow);
+        if (key)
+            shadows.set(key, (shadows.get(key) ?? 0) + 1);
+    }
     if (shadows.size > 4) {
-        const top = [...shadows.entries()]
-            .sort((a, b) => b[1] - a[1])
-            .slice(0, 3)
-            .map(([s]) => `"${s.slice(0, 40)}"`);
+        const keys = [...shadows.entries()].sort((a, b) => b[1] - a[1]).map(([k]) => k);
+        const top = keys.slice(0, 3).map((k) => `"${distinguishingLayer(k, keys.slice(0, 3)).slice(0, 60)}"`);
         consistency.push(`→ ${shadows.size} distinct box-shadow styles (${top.join(", ")}…) — an elevation system needs 2–3 levels, not one per component`);
     }
     if (consistency.length > 0)
@@ -462,20 +758,15 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     if (pureBlack.length > 0) {
         palette.push(`→ pure #000-on-#fff body text (${pureBlack.length} block(s), e.g. ${label(pureBlack[0])}) — near-black (rgb(23,23,23)-ish) reads softer at length`);
     }
-    const grayFreq = new Map();
     const hueFamilies = new Map();
+    const colours = [];
     for (const r of records) {
         for (const c of [r.color, r.bg]) {
             const p = parseRgb(c);
             if (!p)
                 continue;
             const rgb = [p[0], p[1], p[2]];
-            const spread = Math.max(...rgb) - Math.min(...rgb);
-            const avg = (rgb[0] + rgb[1] + rgb[2]) / 3;
-            if (spread <= 10 && avg > 20 && avg < 245) {
-                const key = rgb.join(",");
-                grayFreq.set(key, (grayFreq.get(key) ?? 0) + 1);
-            }
+            colours.push(rgb);
             const hue = hueOf(rgb);
             if (hue !== null) {
                 const bucket = (Math.round(hue / 30) * 30) % 360;
@@ -483,12 +774,10 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
             }
         }
     }
-    if (grayFreq.size > 6) {
-        const top = [...grayFreq.entries()]
-            .sort((a, b) => b[1] - a[1])
-            .slice(0, 5)
-            .map(([k]) => `rgb(${k})`);
-        palette.push(`→ ${grayFreq.size} distinct grays (${top.join(", ")}…) — a deliberate gray scale runs 4–6 steps; near-duplicates suggest ad-hoc values`);
+    const grays = grayCensus(colours);
+    if (grays.length > 6) {
+        const top = grays.slice(0, 5).map((g) => `rgb(${g.rgb.join(",")})`);
+        palette.push(`→ ${grays.length} distinct grays (${top.join(", ")}…) — a deliberate gray scale runs 4–6 steps; near-duplicates suggest ad-hoc values`);
     }
     if (hueFamilies.size > 5) {
         const hues = [...hueFamilies.keys()].sort((a, b) => a - b);
@@ -553,6 +842,20 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     }
     if (structure.length > 0)
         sections.push(`STRUCTURE:\n` + structure.map((s) => `  ${s}`).join("\n"));
+    // ---- 10b. NAMES: a control a screen reader cannot name, or a field labelled
+    //      only by a placeholder that disappears as the user types.
+    const names = unnamedControls(records);
+    const nameLines = [
+        ...names.unnamed.map((r) => `⚠ ${label(r)} — ${r.tag === "input" || r.tag === "select" || r.tag === "textarea" ? "field" : "control"} with no accessible name`),
+        ...names.placeholder.map((r) => `⚠ ${label(r)} — labelled only by its placeholder, which is gone once the user types`),
+    ];
+    if (nameLines.length > 0) {
+        sections.push(`NAMES (${nameLines.length}):\n` +
+            nameLines
+                .slice(0, 6)
+                .map((s) => `  ${s}`)
+                .join("\n"));
+    }
     // ---- 11. AFFORDANCES: keyboard focus visibility (trusted-Tab sampled engine-side) + indistinguishable links.
     const affordances = [];
     const focusless = page.focusSamples.filter((f) => !f.indicator);
@@ -567,7 +870,12 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
         if (r.textLen > 40 && r.tag !== "a" && r.color !== "unknown")
             bodyColorFreq.set(r.color, (bodyColorFreq.get(r.color) ?? 0) + 1);
     const dominantBody = [...bodyColorFreq.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
-    const indistinct = dominantBody ? records.filter((r) => r.tag === "a" && r.textLen > 0 && !r.underline && r.color === dominantBody) : [];
+    const looksLikeBody = (r) => r.tag === "a" && r.textLen > 0 && !r.underline && r.color === dominantBody;
+    const indistinct = dominantBody ? records.filter(looksLikeBody) : [];
+    // Navigation links are this rule's commonest subject and usually sit in the
+    // shell, so the shell's are measured too, against the page's body colour, and
+    // reported as the shell's.
+    const chromeIndistinct = dominantBody ? chromeRecords.filter(looksLikeBody) : [];
     if (dominantBody) {
         if (indistinct.length > 0) {
             affordances.push(`→ ${indistinct.length} link(s) with no underline AND the same color as body text (e.g. ${label(indistinct[0])}) — invisible as links`);
@@ -619,11 +927,14 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     //      suite never answers.
     const effort = [];
     const pageBg = parseRgb(records.find((r) => r.bg && r.bg.startsWith("rgb"))?.bg ?? "") ?? [255, 255, 255, 1];
-    // A "prominent" action = filled control whose background clearly departs
-    // from the page background, at a clickable size. That is what the eye lands
-    // on, so it is the page's implied primary action.
+    // A "prominent" action = a button (or a link painted as one) that paints its
+    // own background, clearly departing from the page background, at a clickable
+    // size. That is what the eye lands on, so it is the page's implied primary
+    // action. Fields never qualify — a white text field on a grey page departs
+    // from the page background too — nor does a ghost button showing a card's
+    // background, nor a breadcrumb, which is a way back rather than an action.
     const prominent = records.filter((r) => {
-        if (!r.interactive || r.rect.w < 60 || r.rect.h < 24)
+        if (!r.interactive || !buttonLike(r) || !r.filled || r.inBreadcrumb || r.rect.w < 60 || r.rect.h < 24)
             return false;
         const bg = parseRgb(r.bg);
         if (!bg)
@@ -647,7 +958,7 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
         effort.push(`→ the primary action (${label(nearest)}) sits ${Math.round(nearest.rect.y - foldH)}px below the fold — the user must scroll before seeing what this page is for`);
     }
     // Form burden: how much is being asked, and how much of it is actually needed.
-    const fields = records.filter((r) => r.interactive && /input|select|textarea/.test(r.tag));
+    const fields = formFields(records);
     if (fields.length >= 5) {
         const req = fields.filter((r) => r.required).length;
         if (req === 0) {
@@ -672,13 +983,13 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     const gridPct = pad.n > 0 ? 100 - pad.pct : 100;
     const summary = `SYSTEM SUMMARY: ${sizes.length} font sizes (≤7 healthy) · ${families.length} families (≤2) · ` +
         `${buttonRadii.length} button radii (1–2) · ${buttonHeights.length} button heights (1–3) · ${shadows.size} shadow styles (≤3) · ` +
-        `${grayFreq.size} grays (4–6) · ${hueFamilies.size} accent hue families (1–3 + status) · ${gridPct}% spacing on 4px grid · ` +
+        `${grays.length} grays (4–6) · ${hueFamilies.size} accent hue families (1–3 + status) · ${gridPct}% spacing on 4px grid · ` +
         `${page.density} interactive elements in first viewport${page.density > 40 ? " (dense — consider progressive disclosure)" : ""}`;
     // ---- Multi-indicator PAGE SCORE. Deductive: start at 100 per dimension,
     //      subtract per measured issue, floor at 0. Weights favour a11y and
     //      task clarity — a page can be pretty and still hard to use.
     const floor0 = (n) => Math.max(0, Math.round(n));
-    const a11yScore = floor0(100 - contrastFails.length * 4 - focusless.length * 6 - tiny.length * 3);
+    const a11yScore = floor0(100 - contrastFails.length * 4 - focusless.length * 6 - tiny.length * 3 - names.unnamed.length * 6 - names.placeholder.length * 4);
     const craftScore = floor0(100 - readability.length * 4 - palette.length * 4 - slopTells.length * 5 - clipped.length * 3 - distorted.length * 4);
     const consistencyScore = floor0(100 -
         consistency.length * 8 -
@@ -703,13 +1014,14 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     const chromeSection = [];
     const chromeDefects = [];
     if (chromeRecords.length > 0) {
-        chromeDefects.push(...contrastFailures(chromeRecords).map((detail) => ({ rule: "contrast", detail, chrome: true })), ...chromeRecords.filter((r) => r.interactive && tooSmall(r)).map((r) => ({ rule: "tiny-target", detail: tinyTargetDetail(r), chrome: true })), ...chromeRecords.filter((r) => r.clipped && r.textLen > 0).map((r) => ({ rule: "clipped-text", detail: clippedTextDetail(r), chrome: true })));
-        const chromeIssues = chromeDefects.map((d) => d.detail);
+        chromeDefects.push(...contrastFailures(chromeRecords).map((detail) => ({ rule: "contrast", detail, chrome: true })), ...chromeRecords.filter((r) => tooSmall(r, allRecords)).map((r) => ({ rule: "tiny-target", detail: tinyTargetDetail(r), chrome: true })), ...chromeRecords.filter((r) => r.clipped && r.textLen > 0).map((r) => ({ rule: "clipped-text", detail: clippedTextDetail(r), chrome: true })), ...(chromeIndistinct.length > 0 ? [{ rule: "indistinct-link", detail: indistinctDetail(dominantBody ?? ""), chrome: true }] : []));
+        // A convention (indistinct-link) is a → line, as it is on the page; the rest are measurable defects.
+        const chromeIssues = chromeDefects.map((d) => `${d.rule === "indistinct-link" ? "→" : "⚠"} ${d.detail}`);
         if (chromeIssues.length > 0) {
             chromeSection.push(`SHARED CHROME (${chromeRecords.length} shell elements, excluded from this page's score and reported here instead):\n` +
                 [...new Set(chromeIssues)]
                     .slice(0, CHROME_ISSUE_CAP)
-                    .map((s) => `  ⚠ ${s}`)
+                    .map((s) => `  ${s}`)
                     .join("\n") +
                 `\n  → these belong to the app shell and recur on every page that renders it. File ONE finding for the shell, not one per page.`);
         }
@@ -739,7 +1051,7 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
         // values on ten pages are one entry on ten routes, and the entry's fingerprint does not move when content does.
         ...(pad.n > 10 && pad.pct > 20 ? [{ rule: "off-grid-spacing", detail: `paddings off a 4px grid: ${gridValues(pad.top)}` }] : []),
         ...(mar.n > 10 && mar.pct > 20 ? [{ rule: "off-grid-spacing", detail: `vertical margins off a 4px grid: ${gridValues(mar.top)}` }] : []),
-        ...(indistinct.length > 0 ? [{ rule: "indistinct-link", detail: `links with no underline in the body-text colour ${dominantBody}` }] : []),
+        ...(indistinct.length > 0 ? [{ rule: "indistinct-link", detail: indistinctDetail(dominantBody ?? "") }] : []),
         ...chromeDefects,
     ];
     return { report, score, signatures, defects };