styleproof 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ 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

package/README.md

@@ -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 (a plain-English bullet first, then the exact table 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_
 
-- **`a.btn-solid`** — background cyan → amber
+- **`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

@@ -20,9 +20,19 @@ export type ElementChange = {
 };
 /** 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[], maxBullets?: number): string[];
+export declare function describeChange(els: ElementChange[], ctx?: DescribeCtx, maxBullets?: number): string[];

package/dist/describe.js

@@ -51,10 +51,69 @@ export function colorName(v) {
     const qual = chromatic ? (lum > 200 ? 'light ' : lum < 70 ? 'dark ' : '') : '';
     return `${qual}${best}`;
 }
-const shift = (before, after) => {
-    const cb = colorName(before);
-    const ca = colorName(after);
-    return cb && ca ? `${cb} → ${ca}` : `${before} → ${after}`;
+/** 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. */
@@ -98,18 +157,23 @@ const gridRule = (m, mark) => {
             continue;
         mark(prop);
         const [b, a] = [trackCount(g.before), trackCount(g.after)];
-        if (b !== a && (b > 0 || a > 0))
+        // 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 = /^0/.test(bw.before);
-    const isZero = /^0/.test(bw.after);
+    const wasZero = noBorder(bw.before);
+    const isZero = noBorder(bw.after);
     if (wasZero && !isZero)
         return [`gains a ${bw.after} border`];
     if (!wasZero && isZero)
@@ -127,12 +191,13 @@ const borderRadiusRule = (m, mark) => {
         return ['corners fully rounded'];
     return [`corner radius ${r.before} → ${r.after}`];
 };
-const colorRule = (m, mark) => {
+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 [];
@@ -140,8 +205,8 @@ const colorRule = (m, mark) => {
     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 ${shift(first[0].before, first[0].after)}`];
-    return present.map(([c, w]) => `${w} ${shift(c.before, c.after)}`);
+        return [`recoloured ${sh(first[0])}`];
+    return present.map(([c, w]) => `${w} ${sh(c)}`);
 };
 const fillRule = (m, mark) => {
     const bgi = m.get('background-image');
@@ -197,17 +262,38 @@ const RULES = [
     typographyRule,
     spacingRule,
 ];
-/** Build the English phrases for ONE element's property deltas. */
-function phrasesFor(props) {
+// 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 out = RULES.flatMap((rule) => rule(m, mark));
-    // Anything no rule named: a quiet tail so nothing is silently lost.
-    const rest = [...m.keys()].filter((p) => !used.has(p));
-    if (rest.length)
-        out.push(`+${rest.length} more (${rest.slice(0, 3).join(', ')}${rest.length > 3 ? '…' : ''})`);
-    return out;
+    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) {
@@ -219,27 +305,48 @@ function domVerbLines(els) {
     }
     return Object.entries(verbs).map(([verb, n]) => `**${n}** element${n === 1 ? '' : 's'} ${verb}`);
 }
-/** Restyle phrases per element, deduped: a phrase on ONE element is labelled with
- *  it; the same phrase across many collapses to `×N` (naming one of fourteen would
- *  mislead). */
-function restyleLines(els) {
-    const byLine = new Map();
-    const order = [];
+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
-        const line = phrasesFor(el.props).join(', ');
-        if (!line)
+        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, label: el.label });
+            byLine.set(line, { count: 0, labels: new Set() });
             order.push(line);
         }
-        byLine.get(line).count++;
+        const e = byLine.get(line);
+        e.count += group.length;
+        e.labels.add(label);
     }
     return order.map((line) => {
-        const { count, label } = byLine.get(line);
-        return count > 1 ? `${line} _(×${count})_` : `**\`${label}\`** — ${line}`;
+        const { count, labels } = byLine.get(line);
+        if (labels.size > 1)
+            return `${line} _(×${count})_`;
+        const label = [...labels][0];
+        return `**\`${label}\`**${count > 1 ? ` ×${count}` : ''} — ${line}`;
     });
 }
 /**
@@ -247,8 +354,8 @@ function restyleLines(els) {
  * 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, maxBullets = 6) {
-    const lines = [...domVerbLines(els), ...restyleLines(els)];
+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(', ')}`);

package/dist/report.d.ts

@@ -1,5 +1,5 @@
 import { type PropChange } from './diff.js';
-export { describeChange, colorName } from './describe.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

package/dist/report.js

@@ -3,10 +3,10 @@ import path from 'node:path';
 import { PNG } from 'pngjs';
 import { loadStyleMap } from './capture.js';
 import { diffStyleMapDirs } from './diff.js';
-import { describeChange } from './describe.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 } from './describe.js';
+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.
@@ -24,6 +24,17 @@ 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();
@@ -375,8 +386,9 @@ function regionHeading(regionPaths, findings) {
     const label = anchors.length > 1 ? `\`${head}\` + ${anchors.length - 1} more` : `\`${head}\``;
     return `${label} · ${groupTitle(findings)}`;
 }
-// A "no value here" marker renders as an em dash rather than its literal text.
-const cell = (v) => (isNonValue(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 |',
@@ -469,7 +481,7 @@ function foldSummary(findings) {
  *  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) {
+function renderCropChanges(findings, foldAt, ctx) {
     const tables = renderElements(findings);
     if (!tables.length)
         return [];
@@ -478,7 +490,7 @@ function renderCropChanges(findings, foldAt) {
     if (rows < foldAt)
         return tables;
     // Folded: plain-English bullets are the visible stand-in for what the toggle hides.
-    const bullets = describeChange(buildElementChanges(findings));
+    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>'];
 }
@@ -632,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)
@@ -652,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))]);
@@ -703,8 +716,10 @@ export function generateStyleMapReport(opts) {
                 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._');
@@ -714,7 +729,7 @@ export function generateStyleMapReport(opts) {
             }
             // 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));
+            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.6.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",