@setsquare/review-sdk 0.0.1 → 0.1.0

package/dist/html-report.js

@@ -1,22 +1,50 @@
-import { BRAND_CSS, MASTHEAD_CSS, masthead } from './brand.js';
+import { BRAND_CSS, MASTHEAD_CSS, SYSTEM_CSS, masthead, viewportLegend } from './brand.js';
 import { esc } from './escape.js';
+import { REFLOW_RULE_ID } from './checks/reflow.js';
+import { VIEWPORT_BAND_NOTE, groupByBand, viewportSize, } from './viewports.js';
+/**
+ * One conformance level, one treatment, everywhere it appears.
+ *
+ * Three call sites in this file rendered `<span class="level">` and got bold
+ * mono text; the platform rendered the same thing four other ways. A reader
+ * cannot learn what a level looks like if it does not look like anything.
+ *
+ * The visible text stays short because it repeats on every row of the grid;
+ * the accessible name says "Level AA", because a bare "AA" read aloud in a
+ * list of criterion numbers is ambiguous with the numbers around it.
+ */
+function levelTag(level) {
+    const slug = level.toLowerCase().replace(/[^a-z]/g, '');
+    return `<span class="level level-${slug}"><span class="sr-only">Level </span>${esc(level)}</span>`;
+}
 import { humanInstant, shortCommit } from './human.js';
 import { insightBlocks } from './insights.js';
-import { renderScreensSection, SCREENS_CSS } from './screens.js';
+import { screenBands } from './screens.js';
 import { conformanceGrid, conformanceSummary, ruleSurfaceShare, stateCoverage, } from '@setsquare/schema/conformance';
 import { evidenceQuality, groupFindings, perfRows, surfaceRows, testOutcomes, totals, } from './summary.js';
+/*
+ * Two states here are the SUITE's claim rather than ours, and the wording has
+ * to keep that visible at a glance — "we ran a rule and it passed" and "you
+ * told us your test covers this" are not paraphrases of each other. Hence
+ * YOURS and YOURS✗ rather than a second OK and a second FAIL: a reader
+ * skimming the column must not be able to mistake one for the other.
+ */
 const STATE_WORD = {
     failed: 'FAIL',
+    assertedFailing: 'YOURS✗',
     cantTell: 'CHECK',
     rulesPassed: 'OK',
     inapplicable: 'N/A',
+    assertedBySuite: 'YOURS',
     untested: '—',
 };
 const STATE_LABEL = {
     failed: 'failed',
+    assertedFailing: 'your own test for this criterion did not pass',
     cantTell: 'needs a person',
     rulesPassed: 'every automated rule passed',
     inapplicable: 'checks ran; nothing to check on this surface',
+    assertedBySuite: 'covered by your own test; no rule ran',
     untested: 'untested',
 };
 function n(value) {
@@ -41,6 +69,201 @@ function partialReason(group) {
     }
     return `An invocation of run group “${group.id}” was cut short before it finished.`;
 }
+/**
+ * What the run can say about viewport coverage, which is a count and not a
+ * verdict.
+ *
+ * A RULE ONLY EVER SEES THE VIEWPORT IT RAN IN. That is not a limitation of
+ * axe-core, it is what an in-page analyser is: a menu that collapses into a
+ * hamburger at 767px is a different DOM, and a scan at 1280 has no opinion
+ * about it whatsoever. A conformance grid built entirely from desktop scans
+ * therefore reads as far more coverage than it is, and this block is what stops
+ * that inference — it is a mechanical statement about the customer's own
+ * configuration, which is squarely the free layer's job.
+ *
+ * It states what was observed and never a denominator. There is no "3 of 5
+ * viewports covered", because nothing declares how many viewports an
+ * application has; `CoverageAxis` carries surface, theme, persona and state for
+ * exactly that reason, and viewport is deliberately not one of them.
+ *
+ * ONE EXCEPTION IS NAMED WHEN IT APPLIES. `setsquare-reflow` measures WCAG
+ * 1.4.10 by resizing the page to 320px and putting the viewport back, so a
+ * single-viewport run does carry real narrow-width evidence — for that one
+ * criterion. Saying "nothing here is about a phone" without that caveat would
+ * be untrue of our own tool, so the sentence appears only when the rule
+ * actually ran, detected in the run rather than assumed from the config.
+ *
+ * Silent when no scan recorded a viewport at all: a run driving a real device
+ * controls none, and an absence device about a measurement nobody took is
+ * noise.
+ */
+function viewportScope(envelope) {
+    const widths = new Map();
+    for (const scan of envelope.scans) {
+        const viewport = scan.context.viewport;
+        if (viewport)
+            widths.set(viewportSize(viewport), viewport.width);
+    }
+    if (widths.size === 0)
+        return '';
+    const labels = [...widths]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([label]) => label);
+    if (labels.length > 1) {
+        /*
+         * Grouped into bands and named, because "1280×720, 768×1024, 640×512,
+         * 390×844" is four numbers a reader has to classify themselves. The legend
+         * is what keeps the names honest — they are widths, not devices.
+         */
+        const banded = groupByBand(envelope.scans, (scan) => scan.context.viewport).groups.map((group) => ({ band: group.band, sizes: group.sizes }));
+        const lines = banded
+            .map((group) => `      <li><strong>${esc(group.band.label)}</strong> — ` +
+            `${group.sizes.map(esc).join(', ')}</li>`)
+            .join('\n');
+        return `<p>Scanned at ${labels.length} viewports, in ${banded.length} ${banded.length === 1 ? 'band' : 'bands'}. A rule only sees the viewport it ran in, so a criterion is evidenced at
+    the widths listed here and nowhere else.</p>
+    <ul>
+${lines}
+    </ul>
+${viewportLegend(bandLegend(banded.map((group) => group.band)), VIEWPORT_BAND_NOTE)}`;
+    }
+    const reflowRan = envelope.scans.some((scan) => scan.passes.some((pass) => pass.ruleId === REFLOW_RULE_ID) ||
+        scan.findings.some((finding) => finding.ruleId === REFLOW_RULE_ID) ||
+        (scan.inapplicable ?? []).some((rule) => rule.ruleId === REFLOW_RULE_ID));
+    const reflowNote = reflowRan
+        ? ` One criterion is the exception: <code>${REFLOW_RULE_ID}</code> measures 1.4.10 Reflow by
+      resizing to 320&thinsp;px and putting the viewport back, so that row does carry narrow-width
+      evidence.`
+        : '';
+    return `<div class="absence">
+      <p class="absence__label">One viewport only</p>
+      <p>Every scan in this run ran at <strong>${esc(labels[0])}</strong>. A rule only
+      sees the viewport it ran in — a navigation that collapses below a breakpoint is a different
+      document, and nothing above looked at it — so this grid is not evidence about a tablet or a
+      phone.${reflowNote}</p>
+      <p>Setsquare cannot widen this for you: it scans the pages your suite drives, at the sizes
+      your suite drives them. A Playwright project per viewport is what does, and it needs no test
+      changes:</p>
+      <p><code>{ name: 'tablet', use: { ...devices['Desktop Chrome'], viewport: { width: 768, height: 1024 } } }</code></p>
+    </div>`;
+}
+/**
+ * A table body grouped into one row group per band, or one plain body when the
+ * run only ever used one.
+ *
+ * Shared by the surfaces table and the performance table: they had the same
+ * shape and the same traps, and a second copy is a second place for the column
+ * arithmetic to drift.
+ *
+ * THE HEADER CELL DOES NOT SPAN THE TABLE, AND THAT IS NOT A STYLING CHOICE.
+ * It did, and axe cannot resolve it: a `th` whose colspan covers every column
+ * sits in a row with no data cells at all, so `th-has-data-cells` cannot work
+ * out which cells it heads and reports `incomplete` — "we could not check".
+ * Verified by putting it back on a real table and re-running, not assumed.
+ *
+ * THE CELLS MUST ALSO ADD UP. The same grouping on this repository's public
+ * evidence page was written with seven cells in an eight-column table, which
+ * left the last column header with rows holding no cell under it — the same
+ * rule, a different cause, and the one that was actually biting. axe names the
+ * orphaned header in its related nodes, which is what points at the arithmetic
+ * rather than at the pattern. Hence `columns - 1` rather than a literal, and
+ * hence this function rather than two of them.
+ *
+ * One table per band with a caption also resolves cleanly and was rejected:
+ * several tables would need their columns pinned to stay aligned, and
+ * `scope="rowgroup"` is the semantic that makes the grouping reachable rather
+ * than decorative.
+ *
+ * A single-band run is rendered flat. One heading reading LAPTOP above every
+ * row is a label, not a grouping, and it would push the first row down for
+ * nothing.
+ *
+ * The size is dropped from rows inside a band that holds only one, because the
+ * band's heading already says it — that redundancy is what the grouping was
+ * for. A band holding two keeps it on every row, where it is the only thing
+ * telling two rows apart.
+ */
+function bandedBody(all, grouped, columns, renderRow) {
+    /*
+     * The name and its sizes are in the SAME cell, and the second cell is empty.
+     *
+     * Putting the sizes in the spanning cell read badly: the first column of both
+     * these tables is wide, so the size landed halfway across the bar with a gap
+     * between it and the band it belongs to. The filler exists to stop the header
+     * spanning every column and to make the row add up — not to hold anything.
+     * Both shapes were put in front of axe on the real report and both come back
+     * clean, so this is a layout choice and not a constrained one.
+     */
+    const header = (label, sizes) => `<tr class="band-row"><th scope="rowgroup">${esc(label)}` +
+        (sizes.length > 0 ? `<span class="sizes"> · ${sizes.map(esc).join(', ')}</span>` : '') +
+        `</th><td colspan="${columns - 1}"></td></tr>`;
+    if (grouped.groups.length <= 1) {
+        return `<tbody>
+        ${all.map((row) => renderRow(row, true)).join('\n        ')}
+        </tbody>`;
+    }
+    return [
+        ...grouped.groups.map((group) => `<tbody>
+          ${header(group.band.label, group.sizes)}
+          ${group.items.map((row) => renderRow(row, group.sizes.length > 1)).join('\n          ')}
+        </tbody>`),
+        // Rows the run recorded no viewport for are kept and labelled, never
+        // dropped to tidy the table: a run driving a real device controls none.
+        ...(grouped.unbanded.length > 0
+            ? [
+                `<tbody>
+          ${header('No viewport recorded', [])}
+          ${grouped.unbanded.map((row) => renderRow(row, false)).join('\n          ')}
+        </tbody>`,
+            ]
+            : []),
+    ].join('\n        ');
+}
+/**
+ * Links into the contact sheet, one per viewport band.
+ *
+ * "Open the contact sheet" answers a question nobody has. A reader who comes to
+ * this section has already decided which width they want to look at — it is
+ * almost always the narrow one, because that is the one they have never seen —
+ * and making them open a long page and scroll for the heading is the friction
+ * this whole grouping exists to remove.
+ *
+ * The fragments come from `screenBands`, which is also what writes the ids onto
+ * that page's headings. Deriving them twice is how a link ends up pointing at a
+ * heading that is not there.
+ *
+ * The plain link stays alongside, and is the only link when a run used one
+ * band: three links to one page, two of which go to the same place, is worse
+ * than one honest link.
+ */
+function screensLinks(rows, href) {
+    const bands = screenBands(rows);
+    const open = `      <p><a href="${esc(href)}">Open the contact sheet</a></p>`;
+    if (bands.length <= 1)
+        return open;
+    const links = bands
+        .map((band) => `        <li><a href="${esc(href)}#${esc(band.anchor)}">${esc(band.band.label)}</a>` +
+        ` <span class="muted">${band.captures} capture${band.captures === 1 ? '' : 's'}` +
+        ` at ${band.sizes.map(esc).join(', ')}</span></li>`)
+        .join('\n');
+    return `      <ul class="band-links">
+${links}
+      </ul>
+${open}`;
+}
+/**
+ * The bands to define for a reader, which is only the ones on the page.
+ *
+ * A run that never went below 1024 has no business telling anybody where
+ * "mobile" starts, and a legend listing bands that are not in the evidence
+ * reads as a list of things we looked at.
+ */
+function bandLegend(bands) {
+    const seen = new Map();
+    for (const band of bands)
+        seen.set(band.id, band);
+    return [...seen.values()];
+}
 /** `href` is allowed only for URLs that came out of the envelope itself. */
 function helpLink(url) {
     if (!url || !url.startsWith('https://'))
@@ -76,6 +299,7 @@ export function renderHtmlReport(input) {
         const notes = block.notes.map((note) => `    <p class="muted">${esc(note)}</p>`).join('\n');
         return `
   <section aria-labelledby="${id}">
+    <p class="eyebrow">Local evidence</p>
     <h2 id="${id}">${esc(block.heading)}</h2>
     <dl class="insight">
 ${rows}
@@ -124,6 +348,14 @@ ${notes}
             state = `failures detected — ${level.failing.length === 1 ? 'one criterion' : `${level.failing.length} criteria`}`;
             cls = 'bad';
         }
+        else if (level.assertedFailing.length > 0) {
+            // Neither good nor bad, and the ladder must not round it to either: we
+            // detected nothing, and the suite's own check for a criterion at this
+            // level is red. A green rung over the top of that is the failure mode
+            // this whole state exists to prevent.
+            state = `no failures detected, but ${level.assertedFailing.length === 1 ? 'a criterion your suite covers' : `${level.assertedFailing.length} criteria your suite covers`} did not pass`;
+            cls = 'check';
+        }
         else {
             state = 'no failures detected in what was scanned';
             cls = 'good';
@@ -131,7 +363,7 @@ ${notes}
         const scans = level.assessedScans
             ? ` <span class="muted">(assessed on ${level.assessedScans.aaa} of ${level.assessedScans.total} scans)</span>`
             : '';
-        return `<li><span class="level">${level.level}</span> <span class="${cls}">${state}</span>${scans}</li>`;
+        return `<li>${levelTag(level.level)} <span class="${cls}">${state}</span>${scans}</li>`;
     })
         .join('\n      ');
     /*
@@ -141,13 +373,26 @@ ${notes}
      */
     const coverageRows = stateCoverage(envelope);
     const scopeRows = coverageRows
-        .map((row) => `<tr><th scope="row">${esc(row.surface)}</th><td>${row.states.map(esc).join(', ')}${row.defaultOnly ? ' <span class="muted">(default state only)</span>' : ''}</td></tr>`)
+        .map((row) => 
+    /*
+     * The sublabel is NOT muted, and that is a contrast decision made on
+     * the element rather than in the stylesheet. This cell sits on the
+     * data-table zebra, where the palette's muted grey measures 5.53:1 in
+     * light and 5.31:1 in dark — under 1.4.6's 7:1, in the default state.
+     * The hierarchy it was buying is bought instead by size and case,
+     * which cost no contrast at all. The public site made the same fix, on
+     * the same table pattern, for the same reason.
+     */
+    `<tr><th scope="row">${esc(row.surface)}</th><td>${row.states.map(esc).join(', ')}${row.defaultOnly ? ' <span class="sublabel">(default state only)</span>' : ''}</td></tr>`)
         .join('\n        ');
     const defaultOnly = coverageRows.filter((row) => row.defaultOnly).length;
     const stateNote = defaultOnly > 0 && coverageRows.length > 0
-        ? `<p class="muted">${defaultOnly} of ${coverageRows.length} surfaces have evidence in their default
-    state only. Error, loading and empty states are where regressions hide —
-    <code>setsquare.scan(page, surface, { state })</code> captures them.</p>`
+        ? `<div class="absence">
+      <p class="absence__label">Only the default state</p>
+      <p>${defaultOnly} of ${coverageRows.length} surfaces have evidence in their default
+      state only. Error, loading and empty states are where regressions hide —
+      <code>setsquare.scan(page, surface, { state })</code> captures them.</p>
+    </div>`
         : '';
     const targets = [...new Set(envelope.scans.map((scan) => scan.wcagTarget))].sort().join(', ') || 'AA';
     /* The grid: criteria × surfaces, real table, state words in every cell. */
@@ -162,7 +407,7 @@ ${notes}
         const removed = row.removedIn22
             ? ' <span class="muted">(removed in WCAG 2.2 — counts toward no level)</span>'
             : '';
-        return `<tr><th scope="row">${row.criterion} ${esc(row.name)} <span class="level">${row.removedIn22 ? '—' : row.level}</span>${removed}</th>${cells}</tr>`;
+        return `<tr><th scope="row">${row.criterion} ${esc(row.name)} ${row.removedIn22 ? '<span class="level">—</span>' : levelTag(row.level)}${removed}</th>${cells}</tr>`;
     })
         .join('\n        ');
     const rollupDetail = (rollup) => {
@@ -180,6 +425,69 @@ ${notes}
         if (rollup.inapplicableSurfaces.length > 0) {
             parts.push(`<p><strong>Nothing to check</strong> (checks ran, no such content) on: ${rollup.inapplicableSurfaces.map(esc).join(', ')}</p>`);
         }
+        /*
+         * The declarations, named as the suite's own and attributed to the tests
+         * that made them. Test ids rather than a count, because the only useful
+         * next action is opening the file — "three tests cover 1.4.10" tells
+         * nobody which three.
+         *
+         * The surface list is stated only when there is one. A declaring test
+         * often has no scans at all (a reflow test measures `scrollWidth` and never
+         * calls `setsquare.scan`), and an empty list means "we cannot say which
+         * surfaces", never "none" — so it is omitted rather than rendered as zero.
+         */
+        /*
+         * A cross-surface disagreement names BOTH sides, because that is the only
+         * form of this finding anyone can act on: "the navigation is inconsistent"
+         * without saying between which two pages sends the reader to look at
+         * everything.
+         */
+        if (rollup.consistency && rollup.consistency.disagreements.length > 0) {
+            for (const row of rollup.consistency.disagreements) {
+                parts.push(`<p><strong>${esc(row.surfaces[0])} and ${esc(row.surfaces[1])} disagree</strong>: ` +
+                    `${esc(row.detail)}</p>`);
+            }
+        }
+        else if (rollup.consistency?.note) {
+            parts.push(`<p><strong>Across surfaces</strong>: ${esc(rollup.consistency.note)}</p>`);
+        }
+        else if (rollup.consistency && rollup.consistency.state === 'rulesPassed') {
+            parts.push(`<p><strong>Compared across ${rollup.consistency.surfaces.length} surfaces</strong> and ` +
+                `they agreed: ${rollup.consistency.surfaces.map(esc).join(', ')}.</p>`);
+        }
+        /*
+         * The curated position, rendered beside the criterion whatever state it is
+         * in. A criterion whose PRESENCE half we check still has an adequacy half
+         * nobody can, and saying so next to the finding is the point of the list —
+         * it is the concrete floor under "automated evidence is not conformance".
+         */
+        if (rollup.automationLimit) {
+            const limit = rollup.automationLimit;
+            parts.push(`<p class="muted"><strong>${limit.covered === 'presence'
+                ? 'Presence is checkable; adequacy is not'
+                : 'No automated rule can decide this'}</strong>: ${esc(limit.because)}. This would change if ${esc(limit.wouldChangeIf)}.</p>`);
+        }
+        const asserted = rollup.assertions;
+        if (asserted) {
+            const where = asserted.surfaces.length > 0
+                ? ` while scanning: ${asserted.surfaces.map(esc).join(', ')}`
+                : '';
+            if (asserted.notUpheld.length > 0) {
+                parts.push(`<p><strong>Your own test for this criterion did not pass</strong>: ` +
+                    `<code>${asserted.notUpheld.map(esc).join('</code>, <code>')}</code>${where}. ` +
+                    `Setsquare did not detect this — your suite declared it, and we do not verify the declaration.</p>`);
+            }
+            if (asserted.upheld.length > 0) {
+                parts.push(`<p><strong>Covered by your own test</strong>: ` +
+                    `<code>${asserted.upheld.map(esc).join('</code>, <code>')}</code>${where}. ` +
+                    `Your assertion that the test covers this criterion, and it passed. No rule ran; we did not check what the test checks.</p>`);
+            }
+            if (asserted.skipped.length > 0) {
+                parts.push(`<p><strong>Declared but skipped</strong>: ` +
+                    `<code>${asserted.skipped.map(esc).join('</code>, <code>')}</code>. ` +
+                    `The test that covers this criterion did not run.</p>`);
+            }
+        }
         if (rollup.failingRules.length > 0) {
             parts.push(`<p>Failing rules: <code>${rollup.failingRules.map(esc).join('</code>, <code>')}</code></p>`);
         }
@@ -223,6 +531,18 @@ ${notes}
             note: 'The checks ran and these pages contain nothing the criterion regulates.',
             rollups: summary.levels.flatMap((level) => level.inapplicable).sort(byNumber),
         },
+        {
+            heading: 'Your own test did not pass',
+            note: 'Your suite declared it covers these criteria and the test is red. This is your ' +
+                'assertion, not our finding — we did not observe a failure and cannot point at an element.',
+            rollups: summary.levels.flatMap((level) => level.assertedFailing).sort(byNumber),
+        },
+        {
+            heading: 'Covered by your own tests',
+            note: 'No automated rule reached these criteria; a passing test of yours declared it covers ' +
+                'them. We do not verify that it does — this is your claim, recorded as yours.',
+            rollups: summary.levels.flatMap((level) => level.assertedBySuite).sort(byNumber),
+        },
         {
             heading: 'Removed in WCAG 2.2',
             note: 'Kept for the record. These count toward no level.',
@@ -231,7 +551,7 @@ ${notes}
     ];
     const criterionDetail = (rollup) => `
       <details${rollup.state === 'failed' ? ' open' : ''}>
-        <summary><span class="s-${rollup.state} pill">${STATE_WORD[rollup.state]}</span> ${rollup.criterion} ${esc(rollup.name)} <span class="level">${rollup.removedIn22 ? 'removed in 2.2' : `Level ${rollup.level}`}</span></summary>
+        <summary><span class="s-${rollup.state} pill">${STATE_WORD[rollup.state]}</span> ${rollup.criterion} ${esc(rollup.name)} ${rollup.removedIn22 ? '<span class="level">removed in 2.2</span>' : levelTag(rollup.level)}</summary>
         <div>
           ${rollupDetail(rollup)}
         </div>
@@ -259,10 +579,34 @@ ${notes}
         coverage.push(`<li><strong>${inapplicableRollups.length}</strong> criteria: checks ran, nothing to check on these pages — ` +
             `${inapplicableRollups.map((r) => r.criterion).join(', ')}</li>`);
     }
-    if (untested.length > 0) {
+    const assertedRollups = countedLevels.flatMap((level) => level.assertedBySuite);
+    if (assertedRollups.length > 0) {
+        coverage.push(`<li><strong>${assertedRollups.length}</strong> criteria covered by your own tests — your assertion, no rule ran: ` +
+            `${assertedRollups.map((r) => r.criterion).join(', ')}</li>`);
+    }
+    const noRule = untested.filter((r) => r.untestedReason === 'noRuleCanDecide');
+    if (noRule.length > 0) {
+        coverage.push(`<li><strong>${noRule.length}</strong> criteria no automated rule can decide, whatever ` +
+            `anyone builds — these are what you still owe an auditor: ` +
+            `${noRule.map((r) => r.criterion).join(', ')}</li>`);
+    }
+    const singleSurface = untested.filter((r) => r.untestedReason === 'singleSurface');
+    if (singleSurface.length > 0) {
+        coverage.push(`<li><strong>${singleSurface.length}</strong> criteria are about a SET of pages and this run ` +
+            `had fewer than two surfaces to compare: ${singleSurface.map((r) => r.criterion).join(', ')}</li>`);
+    }
+    const skippedDeclarations = untested.filter((r) => r.untestedReason === 'declarationSkipped');
+    if (skippedDeclarations.length > 0) {
+        coverage.push(`<li><strong>${skippedDeclarations.length}</strong> criteria your suite covers were skipped and did not run: ` +
+            `${skippedDeclarations.map((r) => r.criterion).join(', ')}</li>`);
+    }
+    const untestedRest = untested.filter((r) => r.untestedReason !== 'declarationSkipped' &&
+        r.untestedReason !== 'singleSurface' &&
+        r.untestedReason !== 'noRuleCanDecide');
+    if (untestedRest.length > 0) {
         if (input.criterionRules) {
-            const noCheck = untested.filter((r) => r.untestedReason === 'notAutomatable');
-            const notRun = untested.filter((r) => r.untestedReason === 'notRun');
+            const noCheck = untestedRest.filter((r) => r.untestedReason === 'notAutomatable');
+            const notRun = untestedRest.filter((r) => r.untestedReason === 'notRun');
             if (noCheck.length > 0) {
                 coverage.push(`<li><strong>${noCheck.length}</strong> criteria have no automated check in this engine: ` +
                     `${noCheck.map((r) => r.criterion).join(', ')}</li>`);
@@ -273,20 +617,52 @@ ${notes}
             }
         }
         else {
-            coverage.push(`<li><strong>${untested.length}</strong> criteria not automatically checked in this run</li>`);
+            coverage.push(`<li><strong>${untestedRest.length}</strong> criteria not automatically checked in this run</li>`);
         }
     }
-    const surfacesBody = rows
-        .map((row) => {
+    /*
+     * The size is dropped from a row inside a band that has only one, because the
+     * band's own heading already says it — that redundancy is exactly what the
+     * grouping was for. A band holding two sizes keeps it on every row, because
+     * there it is the only thing telling two rows apart.
+     */
+    const surfaceRow = (row, showSize = true) => {
+        const label = showSize ? row.label : row.shortLabel;
         const state = row.violations > 0 ? 'failed' : row.incomplete > 0 ? 'cantTell' : 'rulesPassed';
-        const word = row.violations > 0 ? 'FAIL' : row.incomplete > 0 ? 'CHECK' : 'pass';
-        return (`<tr><th scope="row">${esc(row.label)}</th>` +
-            `<td class="s-${state}">${word}</td>` +
+        const word = row.violations > 0 ? 'FAIL' : row.incomplete > 0 ? 'CHECK' : 'PASS';
+        /*
+         * A pill, not coloured text. This table carries the data-table zebra, and
+         * a status colour as TEXT on that stripe measures about 5.3:1 in both
+         * themes — under the floor. A pill's fill is a role under its own -ink,
+         * which is a pair the palette measured, and it paints its own ground so
+         * the stripe underneath stops mattering.
+         */
+        return (`<tr><th scope="row">${esc(label)}</th>` +
+            `<td><span class="pill s-${state}">${word}</span></td>` +
             `<td class="num">${n(row.violations)}</td>` +
             `<td class="num">${n(row.incomplete)}</td>` +
             `<td>${row.rules.map((rule) => `<code>${esc(rule)}</code>`).join(', ')}</td></tr>`);
-    })
-        .join('\n        ');
+    };
+    /*
+     * ONE ROW GROUP PER BAND, and real table structure rather than a visual break.
+     *
+     * Each band is its own `tbody` opened by a header cell scoped to the row
+     * group, so a screen reader announces which band a row belongs to the same way
+     * it announces which column. A styled row with no header semantics would
+     * group the rows for sighted readers only, which on an accessibility report
+     * is a poor joke.
+     *
+     * Order inside a band is untouched: `surfaceRows` already leads with the
+     * worst, and regrouping must not quietly overrule that.
+     *
+     * A single-band run gets no grouping at all — one heading reading LAPTOP over
+     * every row of the table is a label, not a grouping, and it would push the
+     * first row down for nothing.
+     */
+    const SURFACE_COLUMNS = 5;
+    const surfaceBands = groupByBand(rows, (row) => row.viewport);
+    const bandedSurfaces = surfaceBands.groups.length > 1;
+    const surfacesBody = bandedBody(rows, surfaceBands, SURFACE_COLUMNS, surfaceRow);
     const ruleSections = (status) => groups
         .filter((group) => group.status === status)
         .map((group) => {
@@ -305,13 +681,21 @@ ${notes}
       </details>`;
     })
         .join('\n');
-    const perfBody = perf
-        .map((row) => `<tr><th scope="row">${esc(row.label)}</th>` +
+    /*
+     * The performance table groups by band for the same reason the surfaces table
+     * does, and with more at stake: LCP at 390 and LCP at 1280 are not the same
+     * measurement, and a column of times with no width beside them invites a
+     * reader to average things that cannot be averaged. A narrow viewport renders
+     * a different layout and often a different set of images.
+     */
+    const PERF_COLUMNS = 5;
+    const perfRow = (row, showSize = true) => `<tr><th scope="row">${esc(showSize ? row.label : row.shortLabel)}</th>` +
         `<td class="num">${row.lcpMs !== undefined ? `${n(Math.round(row.lcpMs))}ms` : '—'}</td>` +
         `<td class="num">${row.cls !== undefined ? row.cls.toFixed(2) : '—'}</td>` +
         `<td class="num">${row.loadMs !== undefined ? `${n(Math.round(row.loadMs))}ms` : '—'}</td>` +
-        `<td class="num">${row.ttfbMs !== undefined ? `${n(Math.round(row.ttfbMs))}ms` : '—'}</td></tr>`)
-        .join('\n        ');
+        `<td class="num">${row.ttfbMs !== undefined ? `${n(Math.round(row.ttfbMs))}ms` : '—'}</td></tr>`;
+    const perfGrouped = groupByBand(perf, (row) => row.viewport);
+    const perfBody = bandedBody(perf, perfGrouped, PERF_COLUMNS, perfRow);
     const testsLine = envelope.results.length > 0
         ? `Playwright: ${tests.passed} passed` +
             (tests.failed > 0 ? `, ${tests.failed} failed` : '') +
@@ -336,11 +720,12 @@ ${notes}
     const groupSection = group
         ? `
     <section aria-labelledby="h-group">
+      <p class="eyebrow">Provenance</p>
       <h2 id="h-group">Run group</h2>
       <p class="muted">This is the merged evidence of run group “${esc(group.id)}” — one logical run spanning
       ${n(group.completed)} Playwright invocation${group.completed === 1 ? '' : 's'}${group.expectedParts !== null ? ` of ${n(group.expectedParts)} declared` : ''}. Test ids are prefixed with each invocation's label.</p>
-      <div class="tablewrap">
-        <table>
+      <div class="tablewrap" role="region" aria-label="Invocations merged into this run group" tabindex="0">
+        <table class="data-table">
           <thead><tr><th scope="col">Invocation</th><th scope="col">Lane</th><th scope="col">Started</th><th scope="col">Duration</th><th scope="col">Playwright</th><th scope="col">Tests</th><th scope="col">Scans</th></tr></thead>
           <tbody>
           ${group.parts
@@ -360,16 +745,29 @@ ${notes}
      * above the conformance verdict would let a page of pictures answer a question
      * about WCAG that pictures cannot answer.
      */
-    const screensSection = input.screens && input.screens.rows.length > 0
-        ? `\n${renderScreensSection(input.screens)}`
+    const shotCount = input.screens?.rows.reduce((total, row) => total + row.groups.reduce((n, group) => n + group.shots.length, 0), 0) ?? 0;
+    const screensSection = input.screens && input.screens.rows.length > 0 && input.screensHref
+        ? `
+    <section aria-labelledby="h-screens">
+      <p class="eyebrow">Captures</p>
+      <h2 id="h-screens">Screenshots</h2>
+      <p>${shotCount} ${shotCount === 1 ? 'capture' : 'captures'} across ${input.screens.rows.length} ${input.screens.rows.length === 1 ? 'test' : 'tests'}${input.screens.testsWithoutShots > 0
+            ? `, and ${input.screens.testsWithoutShots} ${input.screens.testsWithoutShots === 1 ? 'test that produced' : 'tests that produced'} none`
+            : ''}. Playwright took them; Setsquare indexed them and compared nothing.</p>
+${screensLinks(input.screens.rows, input.screensHref)}
+    </section>`
         : '';
     const warningsBlock = input.warnings.length > 0
         ? `
     <section aria-labelledby="h-warnings">
+      <p class="eyebrow">Caveats</p>
       <h2 id="h-warnings">Worth knowing</h2>
-      <ul>
-        ${input.warnings.map((warning) => `<li>${esc(warning)}</li>`).join('\n        ')}
-      </ul>
+      <div class="absence">
+        <p class="absence__label">Not everything could be shown</p>
+        <ul>
+          ${input.warnings.map((warning) => `<li>${esc(warning)}</li>`).join('\n          ')}
+        </ul>
+      </div>
     </section>`
         : '';
     // `</script>`-proofing: `<` never appears raw inside the data block.
@@ -383,111 +781,142 @@ ${notes}
 <title>Setsquare — accessibility evidence, ${esc(humanInstant(envelope.generatedAt))}</title>
 <style>
 ${BRAND_CSS}
+${SYSTEM_CSS}
+${MASTHEAD_CSS}
   /*
-   * The page's own names, mapped onto brand roles rather than renaming every
-   * rule below: one block to read, one place to change.
-   *
-   * The status roles lost their tinted BACKGROUNDS in the process, deliberately.
-   * tokens.css verifies each status colour as text on a surface and as a fill
-   * under its own ink pair; it has no tints, and inventing a pale red would mean
-   * shipping a contrast ratio nobody measured into an accessibility report. So a
-   * failing cell is bold danger-coloured TEXT, and the solid fill is kept for the
-   * pills, where role-under-its-own-ink is a measured pair.
+   * WHAT IS LEFT IN THIS FILE, NOW THAT brand.ts CARRIES THE SYSTEM.
    *
-   * The faint --none-fg collapses into --ss-ink-muted: the palette has no second,
-   * fainter grey that clears 7:1, and the untested glyph is already distinct by
-   * content.
+   * The type ladder, the section spine, the absence device, the data-table
+   * treatment, the level tag, the pills and the base reset are all in
+   * SYSTEM_CSS, shared with the contact sheet and copied from the public site.
+   * What remains here is what only a conformance report has: the grid's sticky
+   * column, the stat strip, the insight list, and the drill-down disclosures.
    *
-   * (No backticks in this comment. It sits inside a template literal, so one
-   * would end the string and the parse error would surface pages away.)
+   * (No backticks in this block or its comments. It is inside a template
+   * literal, so one would end the string and the parse error would surface
+   * pages away.)
    */
-  :root {
-    --bg: var(--ss-surface); --fg: var(--ss-ink); --muted: var(--ss-ink-muted);
-    --line: var(--ss-border); --code-bg: var(--ss-surface-raised);
-    --bad-fg: var(--ss-danger); --warn-fg: var(--ss-warning); --good-fg: var(--ss-success);
-    --none-fg: var(--ss-ink-muted);
+  :root { --doc-width: 76rem; }
+
+  /* --------------------------------------------------------------- verdict */
+
+  /*
+   * The one sentence this document exists to deliver, so it is given the
+   * card radius and the raised ground rather than being a paragraph among
+   * paragraphs.
+   */
+  .verdict {
+    max-width: var(--ss-measure);
+    margin: 0 0 var(--ss-block);
+    padding: var(--ss-block);
+    background: var(--ss-surface-raised);
+    border: 1px solid var(--line);
+    border-radius: var(--ss-radius-card);
+    font-size: 1.05rem;
   }
-${MASTHEAD_CSS}
-  * { box-sizing: border-box; }
-  body {
-    margin: 0 auto; padding: 2rem 1.5rem 4rem; max-width: 72rem;
-    background: var(--bg); color: var(--fg);
-    font: 16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif;
+
+  ul.ladder { list-style: none; padding: 0; margin: 0 0 var(--ss-block); max-width: none; }
+  ul.ladder li { display: flex; align-items: baseline; gap: 10px; padding: .3rem 0; }
+
+  /* ----------------------------------------------------------- stat strip */
+
+  /*
+   * The run's four headline counts. Cards on the ladder rather than the loose
+   * bordered boxes they were: same radius as the verdict, same raised ground,
+   * and the figure set in the h3 step so a number reads as a number.
+   */
+  .figures {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(min(15rem, 100%), 1fr));
+    gap: var(--ss-block);
+    margin: 0 0 var(--ss-block);
+  }
+  .figures div {
+    padding: var(--ss-block);
+    background: var(--ss-surface-raised);
+    border: 1px solid var(--line);
+    border-radius: var(--ss-radius-card);
+    font-size: .9375rem;
+  }
+  .figures strong {
+    display: block; margin-bottom: 6px;
+    font-size: var(--ss-h3); line-height: 1.1; letter-spacing: -.02em;
+    font-variant-numeric: tabular-nums;
   }
-  h1 { font-size: 1.6rem; margin: 0 0 .25rem; }
-  h2 { font-size: 1.2rem; margin: 2.5rem 0 .75rem; }
-  a { color: inherit; }
-  :focus-visible { outline: 3px solid var(--fg); outline-offset: 2px; }
-  code { background: var(--code-bg); padding: .1em .35em; border-radius: 4px; font-size: .875em; overflow-wrap: anywhere; }
-  .muted { color: var(--muted); }
-  .verdict { font-size: 1.1rem; margin: 1rem 0; padding: 1rem; border: 1px solid var(--line); border-radius: 8px; }
-  ul.ladder { list-style: none; padding: 0; margin: .5rem 0; }
-  ul.ladder li { padding: .2rem 0; }
-  .level { display: inline-block; min-width: 3ch; font-weight: 700; }
-  .good { color: var(--good-fg); }
-  .bad { color: var(--bad-fg); font-weight: 600; }
-  .figures { display: flex; flex-wrap: wrap; gap: 1.5rem; margin: 1.5rem 0; }
-  .figures div { border: 1px solid var(--line); border-radius: 8px; padding: .75rem 1rem; }
-  .figures strong { display: block; font-size: 1.4rem; }
+
+  /* ------------------------------------------------------ insight blocks */
+
   /*
-   * The P1b insight blocks. A definition list, not the .figures stat strip:
-   * these rows carry prose under each figure, and a flex row of boxes would
-   * squeeze the caveats into columns nobody reads. The caveats are the point.
+   * The P1b insight blocks. A definition list, not the .figures strip: these
+   * rows carry prose under each figure, and a row of boxes would squeeze the
+   * caveats into columns nobody reads. The caveats are the point.
    */
-  .insight { margin: 1rem 0; }
-  .insight > div { display: grid; grid-template-columns: 5rem 1fr; gap: .25rem 1rem; padding: .5rem 0; border-top: 1px solid var(--line); }
+  .insight { margin: 0 0 var(--ss-block); }
+  .insight > div {
+    display: grid; grid-template-columns: 5rem 1fr; gap: .25rem 1rem;
+    padding: .6rem 0; border-top: 1px solid var(--line);
+  }
   .insight > div:first-child { border-top: 0; }
-  .insight dt { font-weight: 600; text-align: right; font-variant-numeric: tabular-nums; }
+  .insight dt {
+    font-family: var(--ss-mono); font-weight: 600;
+    text-align: right; font-variant-numeric: tabular-nums;
+  }
   .insight dd { margin: 0; }
-  .insight dd p { margin: .25rem 0 0; }
+  .insight dd p { margin: .25rem 0 0; max-width: 60ch; }
   @media (max-width: 34rem) {
-    /* One column below the fold width: a 5rem gutter beside wrapping prose stops
-       being a gutter and starts being a squeeze. */
+    /* One column below the fold width: a 5rem gutter beside wrapping prose
+       stops being a gutter and starts being a squeeze. */
     .insight > div { grid-template-columns: 1fr; }
     .insight dt { text-align: left; }
   }
-  .tablewrap { overflow-x: auto; }
-  table { border-collapse: collapse; width: 100%; margin: .75rem 0; }
-  th, td { border: 1px solid var(--line); padding: .4rem .6rem; text-align: left; vertical-align: top; }
+
+  /* ------------------------------------------------------ conformance grid */
 
   /*
-   * Row banding, and the sticky criterion column.
-   *
-   * Neither is required by WCAG. Rows are already delineated by a 1px border in
-   * --ss-border, which tokens.css measures at 3.00:1 and is therefore at the
-   * 1.4.11 non-text-contrast threshold; and state is carried by the WORD in each
-   * cell, not by its colour, which is what 1.4.1 actually asks. Both of these are
-   * readability, and they are worth doing anyway.
+   * THE GRID IS NOT A .data-table, AND THE REASON IS A MEASUREMENT.
    *
-   * The bands are the two surfaces the palette already verifies, alternating —
-   * no new colour, so nothing new to measure. Light bands #ffffff against
-   * #f2f2f2, dark #0a0a0a against #1a1a1a, and tokens.css records each theme's
-   * ratios against its WORSE case, so the better surface cannot fail: ink is
-   * 18.76:1 / 17.40:1 and every status colour clears 7:1 on both.
+   * It takes the filled ink header, because that is the site's language and it
+   * measures 21.00:1 in light and 19.80:1 in dark. It does NOT take the
+   * grid-line zebra, and this is the one place the two designs part company.
    *
-   * NB: no backticks anywhere in this style block — it is inside a template
-   * literal, so one ends the string and the parse error lands pages away.
+   * The site's stripe works because every cell in those tables is ink. This
+   * grid's cells are not: a state is carried by its WORD, which is what 1.4.1
+   * asks, and the colour on top of the word is how a reader finds a column of
+   * failures in sixty rows without reading any of them. On grid-line, danger
+   * measures 5.33:1 in light and 5.83:1 in dark, and the muted grey that
+   * fifty N/A cells depend on measures 5.53:1 and 5.31:1 — all of them under
+   * 1.4.6's 7:1. Two ways out were available and both are worse: full ink on
+   * every cell turns a grid that is mostly N/A into a wall of black, and a pill
+   * per cell puts nine hundred filled chips on one page.
    *
-   * The band travels as a custom property rather than a background on the row,
-   * because the sticky cell has to paint the SAME band or it shows the wrong
-   * colour the moment it detaches.
+   * So the grid keeps its colour and loses its stripe. What it lost with the
+   * stripe was nothing: the old banding was surface against surface-raised,
+   * which measures 1.12:1 in light and 1.14:1 in dark, and a stripe nobody can
+   * see is not a stripe. Row tracking is the 1px border, which tokens.css
+   * measures at 3.00:1, plus the pinned criterion column below.
    */
-  tr { --row-bg: var(--ss-surface); }
-  tbody tr:nth-child(even) { --row-bg: var(--ss-surface-raised); }
-  th, td { background: var(--row-bg); }
+  .grid thead th {
+    background: var(--ss-ink); color: var(--ss-surface); border-bottom: none;
+  }
+  .grid thead th:not(:first-child) { border-left-color: var(--ss-surface); }
+  .grid th[scope="row"] { font-weight: 600; }
 
   /*
-   * The grid is sixteen surfaces wide inside a horizontal scroller, and what you
-   * lose scrolling right is not which row you are on — the borders handle that —
-   * it is WHICH CRITERION, because the row header has left the viewport. Pinning
-   * it is the difference between a readable table and a wall of FAIL.
+   * The grid is sixteen surfaces wide inside a horizontal scroller, and what
+   * you lose scrolling right is not which row you are on — the borders handle
+   * that — it is WHICH CRITERION, because the row header has left the viewport.
+   * Pinning it is the difference between a readable table and a wall of FAIL.
    *
    * A box-shadow draws the right edge rather than border-right: under
    * border-collapse: collapse the border belongs to the table, not the cell, so
    * it does not travel with a sticky cell and the pinned column loses its edge.
+   *
+   * The pinned cells must paint an opaque ground or the columns they detach
+   * over show through them.
    */
   .grid th[scope="row"], .grid thead th:first-child {
     position: sticky; left: 0; z-index: 1;
+    background: var(--ss-surface);
     box-shadow: 1px 0 0 var(--line);
   }
   /*
@@ -497,30 +926,61 @@ ${MASTHEAD_CSS}
    * it looked broken in exactly the way you would expect: the surface headers
    * slid underneath the criterion labels.
    */
-  .grid thead th:first-child { z-index: 2; }
-  th[scope="col"] .idx { color: var(--muted); font-weight: 400; }
-  td.num { text-align: right; font-variant-numeric: tabular-nums; }
+  .grid thead th:first-child {
+    z-index: 2; background: var(--ss-ink); color: var(--ss-surface);
+  }
+  .grid th[scope="col"] .idx {
+    display: block; font-family: var(--ss-mono); font-size: 11px;
+    letter-spacing: .08em; font-weight: 400; opacity: .72;
+  }
+  /*
+   * State as a word plus a colour, never a colour alone. Every one of these is
+   * measured on the flat ground it sits on: in light, danger 7.90:1, warning
+   * 7.87:1, success 7.87:1 and the muted grey 8.19:1; in dark, 9.14:1, 9.11:1,
+   * 9.15:1 and 8.33:1.
+   */
+  .grid td {
+    font-family: var(--ss-mono); font-size: .8125rem; letter-spacing: .04em;
+  }
   td.s-failed { color: var(--bad-fg); font-weight: 700; }
   td.s-cantTell { color: var(--warn-fg); font-weight: 600; }
   td.s-rulesPassed { color: var(--good-fg); }
   td.s-inapplicable { color: var(--muted); }
-  /* Pills are the one solid fill: a role under its own -ink is a measured pair. */
-  .pill.s-failed { background: var(--ss-danger); color: var(--ss-danger-ink); font-weight: 700; }
-  .pill.s-cantTell { background: var(--ss-warning); color: var(--ss-warning-ink); font-weight: 600; }
-  .pill.s-rulesPassed { background: var(--ss-success); color: var(--ss-success-ink); }
-  .pill.s-inapplicable { background: var(--ss-surface-raised); color: var(--muted); border: 1px solid var(--line); }
   td.s-untested { color: var(--none-fg); }
-  h3.outcome { font-size: 1rem; margin: 1.75rem 0 .1rem; display: flex; align-items: baseline; gap: .5rem; }
+  /*
+   * The two DECLARED states borrow no new colour. Danger as text on the page
+   * ground is already measured and already used by td.s-failed, so a failing
+   * declaration reuses it rather than inventing a hue for a fifth state; the
+   * hollow pill elsewhere on the page is what says it is a claim rather than an
+   * observation.
+   */
+  td.s-assertedFailing { color: var(--bad-fg); font-weight: 700; }
+  td.s-assertedBySuite { color: var(--fg); }
+
+  /* ------------------------------------------------------- rule drill-downs */
+
+  /*
+   * A second line inside a data cell: smaller and letter-spaced, never a
+   * different colour. See the note beside the Scope rows for why.
+   */
+  .sublabel { font-size: .8125em; letter-spacing: .02em; white-space: nowrap; }
+
+  h3.outcome {
+    margin: var(--ss-block) 0 .1rem;
+    display: flex; align-items: baseline; gap: .5rem; flex-wrap: wrap;
+  }
   h3.outcome .count { font-weight: 400; color: var(--muted); font-size: .875rem; }
   .outcome-note { margin: 0 0 .5rem; font-size: .875rem; }
-  .pill { display: inline-block; min-width: 4.5ch; text-align: center; padding: 0 .4em; border-radius: 4px; }
-  details { border: 1px solid var(--line); border-radius: 8px; padding: .5rem .75rem; margin: .5rem 0; }
+
+  details {
+    max-width: var(--ss-measure);
+    border: 1px solid var(--line); border-radius: var(--ss-radius-block);
+    padding: .6rem .85rem; margin: 0 0 .5rem;
+    background: var(--ss-surface-raised);
+  }
   details > div { margin-top: .5rem; }
+  details p { max-width: none; }
   summary { cursor: pointer; }
-  footer { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid var(--line); color: var(--muted); font-size: .875rem; }
-  footer code { font-size: .8rem; }
-  .ok { color: var(--good-fg); }
-${SCREENS_CSS}
 </style>
 </head>
 <body>
@@ -536,6 +996,7 @@ ${masthead('Setsquare — accessibility evidence',
         `${testsLine ? ` · ${esc(testsLine)}` : ''}`)}${groupBanner}
 <main>
   <section aria-labelledby="h-verdict">
+    <p class="eyebrow">Verdict</p>
     <h2 id="h-verdict">Conformance — WCAG 2.2 <span class="muted">(includes every 2.0 and 2.1 criterion)</span></h2>
     <p class="verdict">${verdictLine()}</p>
     <ul class="ladder">
@@ -547,6 +1008,7 @@ ${masthead('Setsquare — accessibility evidence',
   </section>
 
   <section aria-labelledby="h-figures">
+    <p class="eyebrow">Counts</p>
     <h2 id="h-figures">This run</h2>
     <div class="figures">
       <div><strong>${n(count.surfaces)}</strong> surfaces scanned${count.themes > 0 ? ` in ${count.themes} theme${count.themes === 1 ? '' : 's'}` : ''}</div>
@@ -557,13 +1019,14 @@ ${masthead('Setsquare — accessibility evidence',
   </section>
 
   <section aria-labelledby="h-grid">
+    <p class="eyebrow">Criteria &times; surfaces</p>
     <h2 id="h-grid">Conformance grid</h2>
     <p class="muted">Criteria with evidence, per surface. A surface counts as failing if it fails in any scanned
     state or theme. <strong>OK</strong> means every automated rule for the criterion passed there — evidence,
     not criterion conformance; <strong>CHECK</strong> means automation could not decide; <strong>N/A</strong> means
     the checks ran and the surface contains nothing the criterion regulates; <strong>—</strong> means
     nothing looked.</p>
-    <div class="tablewrap">
+    <div class="tablewrap" role="region" aria-label="WCAG success criteria by surface" tabindex="0">
       <table class="grid">
         <caption class="muted">WCAG success criteria × surfaces</caption>
         <thead><tr><th scope="col">Criterion</th>${gridHead}</tr></thead>
@@ -576,11 +1039,13 @@ ${masthead('Setsquare — accessibility evidence',
   </section>
 
   <section aria-labelledby="h-scope">
+    <p class="eyebrow">What was looked at</p>
     <h2 id="h-scope">Scope</h2>
     <p>Assessed against WCAG 2.2 ${esc(targets)} with automated checks only, on the surfaces and states below.
     Anything not listed was not looked at.</p>
-    <div class="tablewrap">
-      <table>
+    ${viewportScope(envelope)}
+    <div class="tablewrap" role="region" aria-label="Surfaces and the states scanned on each" tabindex="0">
+      <table class="data-table">
         <thead><tr><th scope="col">Surface</th><th scope="col">States scanned</th></tr></thead>
         <tbody>
         ${scopeRows}
@@ -591,38 +1056,45 @@ ${masthead('Setsquare — accessibility evidence',
   </section>
 
   <section aria-labelledby="h-surfaces">
-    <h2 id="h-surfaces">Surfaces</h2>
-    <div class="tablewrap">
-      <table>
+    <p class="eyebrow">Per surface</p>
+    <h2 id="h-surfaces">Surfaces</h2>${bandedSurfaces
+        ? `
+    <p class="muted">Grouped by viewport band. The legend under Scope says what each name covers —
+    it is a width, not a device.</p>`
+        : ''}
+    <div class="tablewrap" role="region" aria-label="Results per surface" tabindex="0">
+      <table class="data-table">
         <thead><tr><th scope="col">Surface</th><th scope="col">State</th><th scope="col">Failing elements</th><th scope="col">Needs review</th><th scope="col">Rules failing</th></tr></thead>
-        <tbody>
         ${surfacesBody}
-        </tbody>
       </table>
     </div>
   </section>
 
   <section aria-labelledby="h-rules">
+    <p class="eyebrow">Failing rules</p>
     <h2 id="h-rules">Rules failing</h2>
     ${ruleSections('violation') || '<p class="muted">None.</p>'}
   </section>
 
   <section aria-labelledby="h-review">
+    <p class="eyebrow">Could not check</p>
     <h2 id="h-review">Needs review</h2>
-    <p class="muted">Automation could not decide these — usually contrast over an image or a gradient.
-    Not passes and not failures; a person has to look.</p>
+    <div class="absence">
+      <p class="absence__label">We could not check</p>
+      <p>Automation could not decide these — usually contrast over an image or a gradient.
+      Not passes and not failures; a person has to look.</p>
+    </div>
     ${ruleSections('incomplete') || '<p class="muted">None.</p>'}
   </section>
 ${perf.length > 0
         ? `
   <section aria-labelledby="h-perf">
+    <p class="eyebrow">Timing</p>
     <h2 id="h-perf">Performance <span class="muted">(CI lab, not real users)</span></h2>
-    <div class="tablewrap">
-      <table>
+    <div class="tablewrap" role="region" aria-label="Page load timings" tabindex="0">
+      <table class="data-table">
         <thead><tr><th scope="col">Page load</th><th scope="col">LCP</th><th scope="col">CLS</th><th scope="col">Load</th><th scope="col">TTFB</th></tr></thead>
-        <tbody>
         ${perfBody}
-        </tbody>
       </table>
     </div>
     <p class="muted">— means the engine did not report it: Firefox and WebKit implement neither LCP nor CLS.