styleproof 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,72 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [1.7.0]
+
+Colour changes are named by their theme token, shown as hex with a live swatch,
+and the bullets stay a glance.
+
+### Added
+
+- **Theme-token linking.** A colour change now names the design token behind it —
+  ``background `red-100` (`#fee2e2`) → `red-200` (`#fecaca`)`` — not just the raw
+  value. Computed styles lose the `var(--token)` reference, so the capture now
+  records the colour-valued `:root` custom properties (`StyleMap.tokens`,
+  normalised to `rgb`) and the report matches a changed value back to its token by
+  value, preferring the scale step (`red-200`) over an alias.
+- **Hex everywhere, with swatches.** Every colour renders as `#hex` (translucent
+  ones stay `rgba`), in both the bullets and the property tables, so GitHub draws
+  its live colour swatch next to each value in the PR comment.
+- **Click any crop to enlarge.** Each before/after composite is wrapped in a link
+  to the full-resolution image, so a click opens it full size to zoom.
+
+### Changed
+
+- **Tighter bullets.** Each element is capped to its few most-visible changes
+  (then `+N more`); low-signal props (`font-family`, `letter-spacing`, …) are kept
+  out of the count; near-identical same-label elements fold to one `×N` line with
+  their shared changes (`details vary` when they don't match).
+- **No more `white → white`.** When two colours round to the same word, the bullet
+  shows just the hex so a subtle change doesn't read as a no-op.
+- **Headline drops zero counts** (`0 state-delta difference(s)` was noise), and a
+  grid that becomes flex no longer prints a confusing `columns: 3 → 0` — the layout
+  rule names it.
+
+## [1.6.0]
+
+The report tells you what to look for, in plain English, and stops being a
+spot-the-difference puzzle.
+
+### Added
+
+- **Plain-English change bullets.** Each crop now leads with a few bullets that
+  name the change the way a person would — `**columns: 2 → 3**`, `becomes a
+centered flex layout`, `corners squared off (50% → 8px)`, `recoloured light
+yellow → cyan` — instead of a raw list of computed-style deltas. A deterministic
+  rule set over the summarised properties (no LLM, no network); the exact
+  before→after tables still live in the fold for when you want them. New
+  `describeChange` / `colorName` helpers in `src/describe.ts`.
+
+### Changed
+
+- **Before/after crops line up exactly.** Both sides are now cropped from the
+  SAME page rectangle (the union of where the change sits on each side), so the
+  backgrounds align and the bullet tells you where to look — no more comparing
+  two differently-framed screenshots.
+- **Forced-state noise is gone.** The `:hover`/`:focus`/`:active` layer was
+  drowning real changes in echoes — on one PR, 3135 "state-delta differences"
+  across 8 elements. Now:
+  - a state delta the **base style already changed** is suppressed (a `:hover
+color` that just follows a recoloured base is an echo, not a dropped variant);
+  - layout/grid-track props are stripped from state deltas (a forced relayout
+    isn't interaction feedback);
+  - a change between two "no value" markers (`— → (gone)`) is dropped — it never
+    meant anything;
+  - the `outline` shorthand no longer renders `(state no longer changes it)`
+    three times in a row.
+- `summarizeProps` drops no-op and non-value↔non-value rows, so counts and tables
+  reflect only real, reviewable changes.
+
 ## [1.5.0]
 
 Live regions are handled automatically, so a dashboard with streaming data,

package/README.md

@@ -14,7 +14,7 @@ Pixel-snapshot tools miss most CSS regressions: they can't force `:hover` / `:fo
 
 On every PR, StyleProof captures a `StyleMap` from the HEAD and from the base branch, diffs them, and posts a Markdown comment:
 
-- A summary line, then **one section per distinct change**, with a side-by-side before/after cropped screenshot and the property changes folded under a toggle.
+- A summary line, then **one section per distinct change**, with a side-by-side before/after cropped screenshot (both sides cropped from the same rectangle, so they line up exactly) and **plain-English bullets that tell you what to look for** (`columns: 2 → 3`, `recoloured cyan → amber`) above the exact property changes, folded under a toggle.
 - An **approval checkbox per change**, driving a `StyleProof` commit status: red until every change is signed off, green when there are none.
 - **New surfaces don't block.** A surface that exists only on the PR head (no baseline to diff — e.g. the bootstrap PR that first adds the capture spec, or a brand-new page) is shown with its screenshot under a `🆕 new surface` heading and an _optional_ approval box, but it never holds the status red. It becomes part of the baseline once merged.
 - No committed baseline to maintain — the diff is HEAD-vs-base, so the report is _exactly what this PR changes_.
@@ -25,17 +25,17 @@ One change — the hero CTA recoloured cyan → amber — posts as a single sect
 
 ![A StyleProof report: the CTA button before (cyan) and after (amber), side by side](docs/demo-composite.png)
 
-As it renders in the PR comment (colours become live swatches; the full table sits inside the toggle):
+As it renders in the PR comment (a plain-English bullet first — naming the theme token and showing the hex with a live colour swatch — then the exact table inside the toggle):
 
 ```text
 ### `a.btn-solid` · 1 element restyled
 _landing @ 1280_
 
-`background-color` `rgb(95, 202, 219)` → `rgb(245, 158, 11)`
+- **`a.btn-solid`** — background `brand-cyan` (`#5fcadb`) → `brand-amber` (`#f59e0b`)
 
 ▾ Show the property change
-   | Property         | Before            | After             |
-   | background-color | rgb(95, 202, 219) | rgb(245, 158, 11) |
+   | Property         | Before    | After     |
+   | background-color | #5fcadb   | #f59e0b   |
 ```
 
 ## Works with any styling system

package/dist/capture.d.ts

@@ -53,6 +53,14 @@ export type StyleMap = {
      * stream/ticker never reads as a change. Empty/absent on a fully-settled page.
      */
     volatile?: string[];
+    /**
+     * Colour-valued `:root` custom properties (design/theme tokens), normalised to
+     * the same `rgb(...)` form the longhands resolve to — `{ "--red-200": "rgb(254,
+     * 202, 202)" }`. Lets the report name the token behind a colour change
+     * (`red-100 → red-200`) instead of only the raw value. Captured once per
+     * surface from the document root; per-subtree overrides aren't tracked.
+     */
+    tokens?: Record<string, string>;
 };
 export type CaptureOptions = {
     /**

package/dist/capture.js

@@ -300,6 +300,34 @@ async function stabilizePage(page, ignore, interval, quietFor, timeout) {
     }
     return recent; // never went quiet for quietFor within budget → still-moving paths are live
 }
+// Serialized into the browser by page.evaluate; cannot call module helpers.
+// Colour-valued `:root` custom properties (theme tokens), each normalised to the
+// browser's `rgb(...)` form (via a probe element) so they match the resolved
+// longhand values the diff compares — letting the report name `red-200` behind a
+// colour. Non-colour tokens (spacing, etc.) are skipped.
+function capturePageTokens() {
+    const root = document.documentElement;
+    const cs = getComputedStyle(root);
+    const probe = document.createElement('span');
+    probe.style.cssText = 'position:absolute;left:-9999px';
+    document.body.appendChild(probe);
+    const tokens = {};
+    for (let i = 0; i < cs.length; i++) {
+        const name = cs.item(i);
+        if (!name.startsWith('--'))
+            continue;
+        const raw = cs.getPropertyValue(name).trim();
+        if (!raw)
+            continue;
+        probe.style.color = '';
+        probe.style.color = raw; // invalid (non-colour) values leave it empty
+        if (!probe.style.color)
+            continue;
+        tokens[name] = getComputedStyle(probe).color; // canonical rgb(a)(...)
+    }
+    probe.remove();
+    return tokens;
+}
 /**
  * Capture the page's complete style map. Drive the page to the state you want
  * first (navigate, open menus); by default the capture then auto-settles the
@@ -362,12 +390,14 @@ export async function captureStyleMap(page, options = {}) {
         states = forced.states;
         statesSkipped = forced.skipped;
     }
+    const tokens = await page.evaluate(capturePageTokens);
     return {
         defaults: base.defaults,
         elements: base.elements,
         states,
         ...(statesSkipped ? { statesSkipped: true } : {}),
         ...(volatile.length ? { volatile } : {}),
+        ...(Object.keys(tokens).length ? { tokens } : {}),
     };
 }
 /** Write a style map to disk; gzipped when the path ends in `.gz`. */

package/dist/describe.d.ts

@@ -0,0 +1,38 @@
+import type { PropChange } from './diff.js';
+/**
+ * Deterministic, offline plain-English summariser for a crop's changes. Turns a
+ * wall of computed-style deltas into a few bullets that tell a reviewer WHAT to
+ * look for ("Grid: 2 → 3 columns", "Accent recoloured cyan → red") instead of
+ * leaving them to spot the difference. No LLM — just curated rules over the
+ * already-summarised property changes, so the same input always yields the same
+ * words and it runs with no network.
+ */
+/** One changed element, with its property deltas already run through summarizeProps. */
+export type ElementChange = {
+    label: string;
+    added?: boolean;
+    removed?: boolean;
+    retagged?: boolean;
+    /** Base/computed-style deltas (not interactive-state ones). */
+    props: PropChange[];
+    /** Interactive states this element gained/changed/dropped, by name. */
+    states?: string[];
+};
+/** A short colour word for an rgb/rgba value: "cyan", "dark blue", "transparent". */
+export declare function colorName(v: string): string | null;
+/** rgb/rgba → `#rrggbb` (opaque) or the rgba string (translucent); non-colours pass through. */
+export declare function toHex(v: string): string;
+/** Reverse-index a token map (`--red-200` → `rgb(...)`) to value → token name,
+ *  preferring a scale step (`red-200`) over an alias, then the shorter name. */
+export declare function tokenIndex(tokens?: Record<string, string>): Map<string, string>;
+/** Token reverse-indexes for each side, so colour rules can name `red-200`. */
+export type DescribeCtx = {
+    tokensBefore?: Map<string, string>;
+    tokensAfter?: Map<string, string>;
+};
+/**
+ * Plain-English bullets for a crop's changes — DOM verbs, then labelled restyle
+ * phrases, then a flag for interaction-state changes a static screenshot can't
+ * show. Capped so the summary stays a glance (the exact tables live in the fold).
+ */
+export declare function describeChange(els: ElementChange[], ctx?: DescribeCtx, maxBullets?: number): string[];

package/dist/describe.js

@@ -0,0 +1,365 @@
+// --- colour naming: nearest of a small, legible palette -----------------------
+const PALETTE = [
+    ['black', [0, 0, 0]],
+    ['white', [255, 255, 255]],
+    ['gray', [128, 128, 128]],
+    ['red', [229, 57, 53]],
+    ['orange', [245, 124, 0]],
+    ['amber', [255, 179, 0]],
+    ['yellow', [253, 216, 53]],
+    ['lime', [124, 179, 66]],
+    ['green', [56, 142, 60]],
+    ['teal', [0, 150, 136]],
+    ['cyan', [38, 198, 218]],
+    ['blue', [33, 110, 233]],
+    ['indigo', [57, 73, 171]],
+    ['purple', [142, 68, 173]],
+    ['magenta', [216, 27, 170]],
+    ['pink', [236, 64, 122]],
+];
+function parseColor(v) {
+    const m = v.match(/rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)(?:[,/\s]+([\d.]+))?\s*\)/i);
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3]), m[4] === undefined ? 1 : Number(m[4])];
+}
+/** Nearest palette word to an rgb point, by squared distance. */
+function nearest(r, g, b) {
+    let best = PALETTE[0][0];
+    let bestD = Infinity;
+    for (const [name, [pr, pg, pb]] of PALETTE) {
+        const d = (r - pr) ** 2 + (g - pg) ** 2 + (b - pb) ** 2;
+        if (d < bestD)
+            [bestD, best] = [d, name];
+    }
+    return best;
+}
+/** A short colour word for an rgb/rgba value: "cyan", "dark blue", "transparent". */
+export function colorName(v) {
+    if (v === 'transparent')
+        return 'transparent';
+    const c = parseColor(v);
+    if (!c)
+        return null;
+    const [r, g, b, a] = c;
+    if (a === 0)
+        return 'transparent';
+    const best = nearest(r, g, b);
+    // Light/dark qualifier for the chromatic colours, where it reads naturally.
+    const lum = 0.299 * r + 0.587 * g + 0.114 * b;
+    const chromatic = best !== 'black' && best !== 'white' && best !== 'gray';
+    const qual = chromatic ? (lum > 200 ? 'light ' : lum < 70 ? 'dark ' : '') : '';
+    return `${qual}${best}`;
+}
+/** rgb/rgba → `#rrggbb` (opaque) or the rgba string (translucent); non-colours pass through. */
+export function toHex(v) {
+    const c = parseColor(v);
+    if (!c)
+        return v;
+    const [r, g, b, a] = c;
+    if (a < 1)
+        return `rgba(${r}, ${g}, ${b}, ${a})`;
+    const h = (n) => n.toString(16).padStart(2, '0');
+    return `#${h(r)}${h(g)}${h(b)}`;
+}
+/** Canonical key for matching a colour value against the token index. */
+function colorKey(v) {
+    const c = parseColor(v);
+    return c ? c.join(',') : null;
+}
+/** Reverse-index a token map (`--red-200` → `rgb(...)`) to value → token name,
+ *  preferring a scale step (`red-200`) over an alias, then the shorter name. */
+export function tokenIndex(tokens) {
+    const idx = new Map();
+    if (!tokens)
+        return idx;
+    const isScale = (n) => /-\d+$/.test(n);
+    for (const [rawName, value] of Object.entries(tokens)) {
+        const key = colorKey(value);
+        if (!key)
+            continue;
+        const name = rawName.replace(/^--/, '');
+        const cur = idx.get(key);
+        if (!cur) {
+            idx.set(key, name);
+        }
+        else if ((isScale(name) && !isScale(cur)) || (isScale(name) === isScale(cur) && name.length < cur.length)) {
+            idx.set(key, name);
+        }
+    }
+    return idx;
+}
+/** Resolve one colour value to its token (if any), colour word, and `#hex`. */
+function describeColor(value, idx) {
+    if (value === 'transparent')
+        return { token: null, word: 'transparent', full: 'transparent', hex: 'transparent' };
+    const key = colorKey(value);
+    if (!key)
+        return { token: null, word: null, full: value, hex: value }; // not a colour
+    const token = idx?.get(key) ?? null;
+    const hex = toHex(value);
+    const word = colorName(value);
+    const full = token ? `\`${token}\` (\`${hex}\`)` : `${word} (\`${hex}\`)`;
+    return { token, word, full, hex };
+}
+// One side's rendering: hex-only when it's a word-level no-op, else token/word + hex.
+const sidePart = (c, noop) => (noop && c.hex !== 'transparent' ? `\`${c.hex}\`` : c.full);
+/** `red-100 (#fee2e2) → red-200 (#fecaca)`. When neither side has a token and the
+ *  colour WORD is unchanged (two near-whites), show just the hex so a subtle change
+ *  doesn't read as a no-op. */
+const shift = (before, after, idxB, idxA) => {
+    const b = describeColor(before, idxB);
+    const a = describeColor(after, idxA);
+    if (b.word === null && a.word === null)
+        return `${before} → ${after}`; // neither is a colour
+    const noop = !b.token && !a.token && b.word !== null && b.word === a.word;
+    return `${sidePart(b, noop)} → ${sidePart(a, noop)}`;
+};
+// --- track counting for grid columns/rows ------------------------------------
+/** Count grid tracks in a `grid-template-*` value, honouring the `Npx ×K` form. */
+function trackCount(v) {
+    if (v === 'none' || !v)
+        return 0;
+    const rep = v.match(/×(\d+)/); // summarizeProps collapses "8px 8px 8px" → "8px ×3"
+    if (rep)
+        return Number(rep[1]);
+    return v.split(/\s+/).filter((t) => t && t !== '0px' && t !== '0').length;
+}
+const round = (v) => /50%|9999|999px/.test(v);
+const flexPhrase = (m, before) => {
+    const col = m.get('flex-direction')?.after?.startsWith('column') ? 'vertical ' : '';
+    const centered = m.get('justify-content')?.after === 'center' || m.get('align-items')?.after === 'center';
+    return `becomes a${centered ? ' centered' : ''} ${col}flex layout (was ${before})`;
+};
+const layoutRule = (m, mark) => {
+    const d = m.get('display');
+    if (!d)
+        return [];
+    mark('display', 'justify-content', 'align-items', 'flex-direction');
+    if (d.after === 'none')
+        return ['**hidden**'];
+    if (d.before === 'none')
+        return ['**shown**'];
+    if (/flex/.test(d.after))
+        return [flexPhrase(m, d.before)];
+    if (/grid/.test(d.after))
+        return [`becomes a grid (was ${d.before})`];
+    return [`display ${d.before} → ${d.after}`];
+};
+const gridRule = (m, mark) => {
+    const out = [];
+    for (const [prop, word] of [
+        ['grid-template-columns', 'columns'],
+        ['grid-template-rows', 'rows'],
+    ]) {
+        const g = m.get(prop);
+        if (!g)
+            continue;
+        mark(prop);
+        const [b, a] = [trackCount(g.before), trackCount(g.after)];
+        // A 0-track side that coincides with a display change is the grid becoming
+        // (or leaving) a grid — the layout rule already names that, so don't add a
+        // confusing "columns: 3 → 0". Only emit a genuine track-count change.
+        if (b !== a && (b > 0 || a > 0) && !(m.has('display') && (b === 0 || a === 0))) {
+            out.push(`**${word}: ${b} → ${a}**`);
+        }
+    }
+    return out;
+};
+const noBorder = (v) => /^0/.test(v) || v === '(unset)';
+const borderWidthRule = (m, mark) => {
+    const bw = m.get('border-width');
+    if (!bw)
+        return [];
+    mark('border-width', 'border-style', 'border-color');
+    const wasZero = noBorder(bw.before);
+    const isZero = noBorder(bw.after);
+    if (wasZero && !isZero)
+        return [`gains a ${bw.after} border`];
+    if (!wasZero && isZero)
+        return ['loses its border'];
+    return [`border ${bw.before} → ${bw.after}`];
+};
+const borderRadiusRule = (m, mark) => {
+    const r = m.get('border-radius');
+    if (!r)
+        return [];
+    mark('border-radius');
+    if (round(r.before) && !round(r.after))
+        return [`corners squared off (${r.before} → ${r.after})`];
+    if (!round(r.before) && round(r.after))
+        return ['corners fully rounded'];
+    return [`corner radius ${r.before} → ${r.after}`];
+};
+const colorRule = (m, mark, ctx) => {
+    const fields = [
+        ['color', 'text'],
+        ['background-color', 'background'],
+        ['border-color', 'border colour'],
+    ];
+    const sh = (c) => shift(c.before, c.after, ctx.tokensBefore, ctx.tokensAfter);
+    const present = fields.map(([p, w]) => [m.get(p), w]).filter(([c]) => c);
+    if (!present.length)
+        return [];
+    const [first] = present;
+    const same = present.length > 1 && present.every(([c]) => c.before === first[0].before && c.after === first[0].after);
+    fields.forEach(([p]) => m.has(p) && mark(p));
+    if (same)
+        return [`recoloured ${sh(first[0])}`];
+    return present.map(([c, w]) => `${w} ${sh(c)}`);
+};
+const fillRule = (m, mark) => {
+    const bgi = m.get('background-image');
+    if (!bgi)
+        return [];
+    mark('background-image');
+    const kind = (v) => /gradient/.test(v) ? 'a gradient' : /url\(/.test(v) ? 'an image' : v === 'none' ? 'no fill' : v;
+    return [`fill → ${kind(bgi.after)} (was ${kind(bgi.before)})`];
+};
+const effectsRule = (m, mark) => {
+    const out = [];
+    const sh = m.get('box-shadow');
+    if (sh) {
+        mark('box-shadow');
+        out.push(sh.before === 'none' ? 'gains a shadow' : sh.after === 'none' ? 'loses its shadow' : 'shadow changes');
+    }
+    const op = m.get('opacity');
+    if (op) {
+        mark('opacity');
+        out.push(`opacity ${op.before} → ${op.after}`);
+    }
+    return out;
+};
+const weight = (v) => Number(v) || (v === 'bold' ? 700 : v === 'normal' ? 400 : NaN);
+const typographyRule = (m, mark) => {
+    const out = [];
+    const fs = m.get('font-size');
+    if (fs) {
+        mark('font-size');
+        out.push(`text size ${fs.before} → ${fs.after}`);
+    }
+    const fw = m.get('font-weight');
+    if (fw) {
+        mark('font-weight');
+        const d = weight(fw.after) - weight(fw.before);
+        out.push(Number.isNaN(d) ? `weight ${fw.before} → ${fw.after}` : d > 0 ? 'bolder text' : 'lighter text');
+    }
+    return out;
+};
+const spacingRule = (m, mark) => {
+    const spacing = ['padding', 'margin', 'gap'].filter((p) => m.has(p));
+    spacing.forEach((p) => mark(p));
+    return spacing.length ? [`${spacing.join(' & ')} adjusted`] : [];
+};
+const RULES = [
+    layoutRule,
+    gridRule,
+    borderWidthRule,
+    borderRadiusRule,
+    colorRule,
+    fillRule,
+    effectsRule,
+    typographyRule,
+    spacingRule,
+];
+// Props that rarely matter to a visual reviewer — excluded from the "+N more"
+// tail (they're still in the table) so a bullet stays signal, not noise.
+const LOW_SIGNAL = new Set([
+    'font-family',
+    'letter-spacing',
+    'word-spacing',
+    'flex-grow',
+    'flex-shrink',
+    'flex-basis',
+    'object-fit',
+    'white-space',
+    'text-rendering',
+    '-webkit-font-smoothing',
+    '-webkit-box-orient',
+    'text-overflow',
+    'word-break',
+    'overflow-wrap',
+]);
+/** Build the English phrases for ONE element's deltas, capped so a bullet stays a
+ *  glance: the top `cap` rule phrases (rules are priority-ordered), then a single
+ *  "+N more" counting the rest (low-signal props excluded — they're in the table). */
+function phrasesFor(props, ctx, cap = 4) {
+    const m = new Map(props.map((p) => [p.prop, p]));
+    const used = new Set();
+    const mark = (...ps) => ps.forEach((p) => used.add(p));
+    const phrases = RULES.flatMap((rule) => rule(m, mark, ctx));
+    const rest = [...m.keys()].filter((p) => !used.has(p) && !LOW_SIGNAL.has(p)).length;
+    const shown = phrases.slice(0, cap);
+    const overflow = phrases.length - shown.length + rest;
+    if (overflow > 0)
+        shown.push(`+${overflow} more`);
+    return shown;
+}
+/** Tally added/removed/retagged elements into "3 added" style lines. */
+function domVerbLines(els) {
+    const verbs = {};
+    for (const el of els) {
+        const v = el.added ? 'added' : el.removed ? 'removed' : el.retagged ? 'retagged' : null;
+        if (v)
+            verbs[v] = (verbs[v] ?? 0) + 1;
+    }
+    return Object.entries(verbs).map(([verb, n]) => `**${n}** element${n === 1 ? '' : 's'} ${verb}`);
+}
+const sig = (phrases) => phrases.join(', ');
+/** One line for a same-label group: the shared phrases (or the single line),
+ *  flagged `(details vary)` when members aren't identical. */
+function foldedLine(group, ctx) {
+    const lists = group.map((el) => phrasesFor(el.props, ctx));
+    if (lists.every((l) => sig(l) === sig(lists[0])))
+        return sig(lists[0]);
+    const common = lists[0].filter((p) => lists.every((l) => l.includes(p)));
+    return common.length ? `${common.join(', ')} _(details vary)_` : 'restyled _(details vary)_';
+}
+/** Restyle phrases, folded by element label (so two near-identical `span.led`s
+ *  become one `×2` line with their shared changes), then deduped across labels (so
+ *  the same line on different labels collapses to `… (×N)`). */
+function restyleLines(els, ctx) {
+    const byLabel = new Map();
+    for (const el of els) {
+        if (el.added || el.removed)
+            continue; // values, not deltas — heading covers them
+        if (!phrasesFor(el.props, ctx).length)
+            continue;
+        const arr = byLabel.get(el.label) ?? [];
+        arr.push(el);
+        byLabel.set(el.label, arr);
+    }
+    const byLine = new Map();
+    const order = [];
+    for (const [label, group] of byLabel) {
+        const line = foldedLine(group, ctx);
+        if (!byLine.has(line)) {
+            byLine.set(line, { count: 0, labels: new Set() });
+            order.push(line);
+        }
+        const e = byLine.get(line);
+        e.count += group.length;
+        e.labels.add(label);
+    }
+    return order.map((line) => {
+        const { count, labels } = byLine.get(line);
+        if (labels.size > 1)
+            return `${line} _(×${count})_`;
+        const label = [...labels][0];
+        return `**\`${label}\`**${count > 1 ? ` ×${count}` : ''} — ${line}`;
+    });
+}
+/**
+ * Plain-English bullets for a crop's changes — DOM verbs, then labelled restyle
+ * phrases, then a flag for interaction-state changes a static screenshot can't
+ * show. Capped so the summary stays a glance (the exact tables live in the fold).
+ */
+export function describeChange(els, ctx = {}, maxBullets = 6) {
+    const lines = [...domVerbLines(els), ...restyleLines(els, ctx)];
+    const states = [...new Set(els.flatMap((e) => e.states ?? []))];
+    if (states.length)
+        lines.push(`interaction states changed: ${states.map((s) => `\`:${s}\``).join(', ')}`);
+    if (lines.length <= maxBullets)
+        return lines;
+    return [...lines.slice(0, maxBullets - 1), `…and ${lines.length - (maxBullets - 1)} more change(s)`];
+}

package/dist/report.d.ts

@@ -1,4 +1,5 @@
 import { type PropChange } from './diff.js';
+export { describeChange, colorName, tokenIndex, toHex } from './describe.js';
 /**
  * Visual diff report: for every surface with findings, crop the before/after
  * full-page screenshots around the changed elements and write a markdown
@@ -6,9 +7,9 @@ import { type PropChange } from './diff.js';
  *
  * Cropping zooms out to the OUTERMOST changed element: changed paths that are
  * descendants of other changed paths are folded into their ancestor, nearby
- * regions are merged, and both sides are cropped at identical dimensions
- * (centered on each side's own coordinates) so the pair stays comparable
- * even when the change moved things around.
+ * regions are merged, and both sides are cropped at the SAME page rectangle (the
+ * union of where the change sits on each side) so the pair lines up exactly —
+ * the reviewer compares like-for-like instead of playing spot-the-difference.
  */
 export type ReportOptions = {
     beforeDir: string;
@@ -27,9 +28,9 @@ export type ReportOptions = {
     maxCrops?: number;
     /**
      * Row count at which a crop's property tables fold under a `<details>` toggle
-     * (default 0 = always fold; the essence line and screenshot stay visible). Set
-     * to e.g. 5 to keep small changes inline and fold only verbose ones, or
-     * `Infinity` to never fold.
+     * (default 0 = always fold; the plain-English bullets and screenshot stay
+     * visible). Set to e.g. 5 to keep small changes inline and fold only verbose
+     * ones, or `Infinity` to never fold.
      */
     foldDetailsAt?: number;
     /**

package/dist/report.js

@@ -3,6 +3,10 @@ import path from 'node:path';
 import { PNG } from 'pngjs';
 import { loadStyleMap } from './capture.js';
 import { diffStyleMapDirs } from './diff.js';
+import { describeChange, tokenIndex, toHex } from './describe.js';
+// Re-export the plain-English summariser so consumers (and tests) reach it
+// through the package's report module rather than a deep path.
+export { describeChange, colorName, tokenIndex, toHex } from './describe.js';
 // Hidden marker appended to a new-surface heading. Invisible in rendered
 // markdown; lets the PR-comment layer attach an OPTIONAL "approve" box to a new
 // surface (vs the required box on a real change), so new surfaces never gate.
@@ -20,6 +24,27 @@ const visible = (b) => !!b && b.w > 0 && b.h > 0;
 function outermost(paths) {
     return paths.filter((p) => !paths.some((q) => q !== p && p.startsWith(q + ' > ')));
 }
+/** Headline counts with the zeros dropped — `0 state-delta difference(s)` is noise. */
+function changeCountLabel(shown) {
+    const parts = [];
+    if (shown.dom)
+        parts.push(`${shown.dom} DOM change(s)`);
+    if (shown.style)
+        parts.push(`${shown.style} computed-style difference(s)`);
+    if (shown.state)
+        parts.push(`${shown.state} state-delta difference(s)`);
+    return parts.join(' · ');
+}
+/** Group findings by their element path (one group per changed element). */
+function groupByPath(findings) {
+    const byPath = new Map();
+    for (const f of findings) {
+        const arr = byPath.get(f.path) ?? [];
+        arr.push(f);
+        byPath.set(f.path, arr);
+    }
+    return [...byPath.values()];
+}
 function groupRegions(paths, a, b, padBy) {
     const groups = paths.map((p) => {
         const ra = a.elements[p]?.rect;
@@ -218,6 +243,13 @@ const CURRENTCOLOR_FOLLOWERS = [
     '-webkit-text-fill-color',
     '-webkit-text-stroke-color',
 ];
+// "No value here" markers: a forced-state delta that doesn't apply, an unset
+// longhand, or a capture artifact where a path didn't line up. A change BETWEEN
+// two of these (e.g. `— → (gone)`) is meaningless and must never read as a diff.
+const NON_VALUE = new Set(['(state does not change it)', '(state no longer changes it)', '(unset)', '(gone)']);
+const isNonValue = (v) => NON_VALUE.has(v);
+/** Combine longhands into a shorthand value; all-non-value sides collapse to one. */
+const combineValues = (vals) => (vals.every(isNonValue) ? '(unset)' : vals.join(' '));
 export function summarizeProps(props) {
     const map = new Map(props.map((p) => [p.prop, { ...p }]));
     for (const [logical, physical] of Object.entries(LOGICAL_TO_PHYSICAL)) {
@@ -273,13 +305,16 @@ export function summarizeProps(props) {
         map.delete('outline-color');
         map.set('outline', {
             prop: 'outline',
-            before: `${ow.before} ${os.before} ${oc.before}`,
-            after: `${ow.after} ${os.after} ${oc.after}`,
+            before: combineValues([ow.before, os.before, oc.before]),
+            after: combineValues([ow.after, os.after, oc.after]),
         });
     }
-    return [...map.values()]
+    return ([...map.values()]
         .map((p) => ({ prop: p.prop, before: cleanVal(p.before), after: cleanVal(p.after) }))
-        .sort((a, b) => orderIdx(a.prop) - orderIdx(b.prop) || a.prop.localeCompare(b.prop));
+        // Drop no-ops: a value that didn't actually change, or a change between two
+        // "no value here" markers (`— → (gone)`), which carries no information.
+        .filter((p) => p.before !== p.after && !(isNonValue(p.before) && isNonValue(p.after)))
+        .sort((a, b) => orderIdx(a.prop) - orderIdx(b.prop) || a.prop.localeCompare(b.prop)));
 }
 /** `div.who-grid`, `a.nav-cta`, `h3` — the semantic marker class, else the tag. */
 export function prettyLabel(p, cls) {
@@ -351,10 +386,9 @@ function regionHeading(regionPaths, findings) {
     const label = anchors.length > 1 ? `\`${head}\` + ${anchors.length - 1} more` : `\`${head}\``;
     return `${label} · ${groupTitle(findings)}`;
 }
-// A diff state row whose value is one of these placeholders means "this state
-// has no effect here" — meaningless to show, so render it as an em dash.
-const STATE_PLACEHOLDER = new Set(['(state does not change it)', '(state no longer changes it)', '(unset)']);
-const cell = (v) => (STATE_PLACEHOLDER.has(v) ? '—' : `\`${v}\``);
+// A "no value here" marker renders as an em dash; colours render as `#hex` so the
+// table cell shows GitHub's live swatch.
+const cell = (v) => (isNonValue(v) ? '—' : `\`${toHex(v)}\``);
 function beforeAfterTable(rows) {
     return [
         '| Property | Before | After |',
@@ -406,15 +440,9 @@ function renderOneElement(group) {
  * "before"); an existing element shows before → after.
  */
 function renderElements(findings, maxElements = 40) {
-    const byPath = new Map();
-    for (const f of findings) {
-        const arr = byPath.get(f.path) ?? [];
-        arr.push(f);
-        byPath.set(f.path, arr);
-    }
     const blocks = [];
     const bySig = new Map();
-    for (const group of byPath.values()) {
+    for (const group of groupByPath(findings)) {
         const el = renderOneElement(group);
         if (!el)
             continue;
@@ -439,25 +467,6 @@ function renderElements(findings, maxElements = 40) {
     }
     return out;
 }
-/**
- * A scannable one-liner of what a crop changed, shown ABOVE the folded tables so a
- * reviewer can judge without expanding: its top property deltas with values, the
- * rest as a count, and a flag when the change reaches into hover/focus/active — the
- * one kind of change a static before|after screenshot can't show.
- */
-function changeEssence(findings) {
-    const verbs = [];
-    for (const c of ['added', 'removed', 'retagged']) {
-        const k = findings.filter((f) => f.kind === 'dom' && f.change === c).length;
-        if (k)
-            verbs.push(`${k} ${c}`);
-    }
-    const rows = findings.flatMap((f) => (f.kind === 'dom' ? [] : summarizeProps(f.props)));
-    const top = rows.slice(0, 3).map((r) => `\`${r.prop}\` ${cell(r.before)} → ${cell(r.after)}`);
-    const more = rows.length > top.length ? `+${rows.length - top.length} more` : '';
-    const line = [...verbs, ...top, more].filter(Boolean).join(' · ') || '_see changes_';
-    return findings.some((f) => f.kind === 'state') ? `${line} _· incl. hover/focus/active_` : line;
-}
 /** Plain-text `<summary>` affordance — GitHub renders markdown inside `<summary>`
  *  literally, so no backticks or bold here. */
 function foldSummary(findings) {
@@ -466,31 +475,24 @@ function foldSummary(findings) {
         return 'Show details';
     return n === 1 ? 'Show the property change' : `Show all ${n} property changes`;
 }
-/** Render a crop's changes: the essence line, then the property tables — folded
- *  under a toggle once they would be a wall (the screenshot and approval checkbox
- *  above always stay visible). Blank lines around the table block are mandatory or
- *  GitHub prints the tables as literal text. `foldAt` is the row count at which the
- *  tables collapse; ≤ 0 folds always, Infinity never. */
-function renderCropChanges(findings, foldAt) {
+/** Render a crop's changes: plain-English bullets that tell the reviewer what to
+ *  look for, then the exact property tables — folded under a toggle once they would
+ *  be a wall (the screenshot and approval checkbox above always stay visible).
+ *  Blank lines around the table block are mandatory or GitHub prints the tables as
+ *  literal text. `foldAt` is the row count at which the tables collapse; ≤ 0 folds
+ *  always, Infinity never. */
+function renderCropChanges(findings, foldAt, ctx) {
     const tables = renderElements(findings);
     if (!tables.length)
         return [];
     const rows = findings.flatMap((f) => (f.kind === 'dom' ? [] : summarizeProps(f.props))).length;
-    // Small enough to read at a glance: the tables speak for themselves, no essence
-    // line (it would just echo a one- or two-row table).
+    // Small enough to read at a glance: the tables speak for themselves.
     if (rows < foldAt)
         return tables;
-    // Folded: the essence line is the visible stand-in for what the toggle hides.
-    return [
-        '',
-        changeEssence(findings),
-        '',
-        '<details>',
-        `<summary>${foldSummary(findings)}</summary>`,
-        ...tables,
-        '',
-        '</details>',
-    ];
+    // Folded: plain-English bullets are the visible stand-in for what the toggle hides.
+    const bullets = describeChange(buildElementChanges(findings), ctx);
+    const summary = bullets.length ? bullets.map((b) => `- ${b}`) : ['_see changes_'];
+    return ['', ...summary, '', '<details>', `<summary>${foldSummary(findings)}</summary>`, ...tables, '', '</details>'];
 }
 // Computed values that follow from an element's box size or position rather than
 // its styling. On any reflow they change all the way up the ancestor chain
@@ -519,20 +521,82 @@ const DERIVED_PROPS = new Set([
     'inset-inline-start',
     'inset-inline-end',
 ]);
-const hasRealChange = (f) => f.kind === 'dom' || f.props.some((p) => !DERIVED_PROPS.has(p.prop));
-const stripDerived = (f) => f.kind === 'dom' ? f : { ...f, props: f.props.filter((p) => !DERIVED_PROPS.has(p.prop)) };
+// Props stripped from forced :hover/:focus/:active deltas specifically. Layout
+// and grid-track values that shift when a state forces a relayout are capture
+// noise, not interaction feedback — a state finding is meant to catch a changed
+// hover/focus/active *style* (colour, outline, shadow), not a reflow.
+const STATE_STRIP = new Set([
+    ...DERIVED_PROPS,
+    'grid-template-columns',
+    'grid-template-rows',
+    'grid-template-areas',
+    'grid-auto-columns',
+    'grid-auto-rows',
+    'grid-auto-flow',
+]);
+/**
+ * Strip the noise the visual report shouldn't carry, cross-referencing each
+ * element's layers so the forced-state layer stops echoing the base:
+ *   - base/pseudo styles: drop size/position-derived longhands (reflow casualties);
+ *   - forced states: drop derived + grid-track props, drop a delta the BASE
+ *     already changed (a `:hover color` that just follows a recoloured base is an
+ *     echo, not a dropped variant), and drop non-value↔non-value rows;
+ *   - any finding left with no props is removed entirely.
+ */
+function cleanFindings(findings) {
+    const out = [];
+    for (const group of groupByPath(findings)) {
+        const base = group.find((f) => f.kind === 'style' && f.pseudo === null);
+        const baseChanged = new Set(base?.props.map((p) => p.prop) ?? []);
+        for (const f of group) {
+            if (f.kind === 'dom') {
+                out.push(f);
+                continue;
+            }
+            const props = f.kind === 'style'
+                ? f.props.filter((p) => !DERIVED_PROPS.has(p.prop))
+                : f.props.filter((p) => !STATE_STRIP.has(p.prop) && !baseChanged.has(p.prop) && !(isNonValue(p.before) && isNonValue(p.after)));
+            if (props.length)
+                out.push({ ...f, props });
+        }
+    }
+    return out;
+}
+/** Per-element view for the plain-English summariser: the base deltas (summarised)
+ *  plus which interactive states genuinely changed. */
+function buildElementChanges(findings) {
+    const els = [];
+    for (const group of groupByPath(findings)) {
+        const dom = group.find((f) => f.kind === 'dom');
+        const styleProps = group
+            .filter((f) => f.kind === 'style')
+            .flatMap((f) => f.props);
+        els.push({
+            label: prettyLabel(group[0].path, group[0].cls),
+            added: dom?.change === 'added',
+            removed: dom?.change === 'removed',
+            retagged: dom?.change === 'retagged',
+            props: summarizeProps(styleProps),
+            states: [
+                ...new Set(group.filter((f) => f.kind === 'state').map((f) => f.state)),
+            ],
+        });
+    }
+    return els;
+}
 export function generateStyleMapReport(opts) {
     const { beforeDir, afterDir, outDir, imageBaseUrl = '', pad: padBy = 24, minWidth = 320, minHeight = 180, maxHeight = 1600, maxCrops = 6, foldDetailsAt = 0, } = opts;
     const includeNoise = opts.includeLayoutNoise ?? false;
     const { surfaces, volatile: volatileCount } = diffStyleMapDirs(beforeDir, afterDir);
     fs.mkdirSync(path.join(outDir, 'crops'), { recursive: true });
-    // Focus each surface on styling intent: drop reflow-casualty elements (only
-    // size/position-derived changes) and strip those props from the rest, unless
-    // includeLayoutNoise is set. Surfaces left with no real change are dropped.
+    // Focus each surface on styling intent: drop reflow-casualty props, suppress
+    // forced-state echoes of base changes, and remove non-value noise (see
+    // cleanFindings), unless includeLayoutNoise is set. Surfaces left with no real
+    // change are dropped.
     const prepared = surfaces
         .map((sd) => ({
         sd,
-        findings: sd.missing || includeNoise ? sd.findings : sd.findings.filter(hasRealChange).map(stripDerived),
+        findings: sd.missing || includeNoise ? sd.findings : cleanFindings(sd.findings),
     }))
         .filter((p) => p.sd.missing || p.findings.length > 0);
     // Group surfaces that changed in the SAME way (the rects differ per width; the
@@ -580,8 +644,7 @@ export function generateStyleMapReport(opts) {
     }
     else {
         if (changeGroups.length > 0) {
-            md.push(`**${shown.dom} DOM change(s) · ${shown.style} computed-style difference(s) · ${shown.state} state-delta difference(s)** ` +
-                `across ${changeGroups.length} distinct change(s) in ${changedSurfaceCount} surface(s).`);
+            md.push(`**${changeCountLabel(shown)}** across ${changeGroups.length} distinct change(s) in ${changedSurfaceCount} surface(s).`);
         }
         if (missing.length > 0) {
             if (changeGroups.length > 0)
@@ -600,6 +663,8 @@ export function generateStyleMapReport(opts) {
         totalFindings += surfaceFindings.length;
         const mapA = loadStyleMap(findCapture(beforeDir, sd.surface));
         const mapB = loadStyleMap(findCapture(afterDir, sd.surface));
+        // Theme-token reverse-indexes so colour changes can name `red-200` per side.
+        const describeCtx = { tokensBefore: tokenIndex(mapA.tokens), tokensAfter: tokenIndex(mapB.tokens) };
         const pngA = readPng(path.join(beforeDir, `${sd.surface}.png`));
         const pngB = readPng(path.join(afterDir, `${sd.surface}.png`));
         const changedPaths = outermost([...new Set(surfaceFindings.map((f) => f.path))]);
@@ -634,21 +699,27 @@ export function generateStyleMapReport(opts) {
             const region = visible(g.after) ? g.after : g.before;
             let images = {};
             if (region && pngA && pngB) {
-                // Same crop dimensions on both sides so the pair reads as a pair.
-                const w = Math.max(minWidth, visible(g.before) ? g.before.w : 0, visible(g.after) ? g.after.w : 0);
-                const h = Math.min(maxHeight, Math.max(minHeight, visible(g.before) ? g.before.h : 0, visible(g.after) ? g.after.h : 0));
+                // Crop the SAME page rectangle from both sides — the union of where the
+                // change sits on each side — so the pair lines up exactly and the reviewer
+                // compares like-for-like instead of playing spot-the-difference. (Centring
+                // each side on its own moved box would shift the background between them.)
+                const cropBox = visible(g.before) && visible(g.after) ? union(g.before, g.after) : region;
+                const w = Math.max(minWidth, cropBox.w);
+                const h = Math.min(maxHeight, Math.max(minHeight, cropBox.h));
                 // Path-safe, report-unique stem: `hero@1280` → `hero-1280-3` so relative
                 // image links resolve cleanly and two crops never collide on one filename.
                 const stem = `crops/${sd.surface.replace(/[^a-z0-9-]/gi, '-')}-${cropSeq}`;
-                const before = cropPng(pngA, visible(g.before) ? g.before : region, w, h);
-                const after = cropPng(pngB, visible(g.after) ? g.after : region, w, h);
+                const before = cropPng(pngA, cropBox, w, h);
+                const after = cropPng(pngB, cropBox, w, h);
                 const composite = compositePair(before, after);
                 writePng(path.join(outDir, `${stem}-before.png`), before);
                 writePng(path.join(outDir, `${stem}-after.png`), after);
                 writePng(path.join(outDir, `${stem}-composite.png`), composite);
                 images = { before: `${stem}-before.png`, after: `${stem}-after.png`, composite: `${stem}-composite.png` };
-                // One side-by-side image per crop: clean inline render, single upload.
-                md.push('', `![before ◀ │ ▶ after](${img(images.composite)})`, '', `<sub>◀ before  ·  after ▶ — ${sd.surface}</sub>`);
+                // One side-by-side image per crop, left as a PLAIN image (not wrapped in a
+                // link) so GitHub's built-in lightbox opens it in a zoomable popup on click —
+                // a link wrapper would navigate to the file instead.
+                md.push('', `![before ◀ │ ▶ after](${img(images.composite)})`, '', `<sub>◀ before  ·  after ▶ — ${sd.surface} · click to zoom</sub>`);
             }
             else if (!region) {
                 md.push('', '_Changed element is not visible in this state (zero-size box) — see the property list._');
@@ -656,9 +727,9 @@ export function generateStyleMapReport(opts) {
             else {
                 md.push('', '_No screenshots in these capture sets (run captures with `screenshots: true` for side-by-side crops)._');
             }
-            // What this crop changed: a scannable essence line, then the property
-            // tables — folded under a toggle once they'd be a wall (foldDetailsAt).
-            md.push(...renderCropChanges(regionFindings, foldDetailsAt));
+            // What this crop changed: plain-English bullets, then the property tables —
+            // folded under a toggle once they'd be a wall (foldDetailsAt).
+            md.push(...renderCropChanges(regionFindings, foldDetailsAt, describeCtx));
             surfaceJson.regions.push({ paths: g.paths, before: g.before, after: g.after, images });
         }
         surfaceJson.findings = surfaceFindings;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",