Harness Inspector visual contract migration

Traceability

• Spec ID: 2026-08-19-inspector-visual-contract-migration
• Status: Implemented

Intent

DESIGN.md declares itself the visual source of truth for packages/harness-studio and for interactive Better Harness reports without a narrower approved contract. Harness Inspector has no such narrower contract, so the root contract governs it.

The three commits that flattened the evidence workbench (refactor(inspector): flatten the evidence workbench, refactor(inspector): redesign date calendar and session detail, feat(inspector): list selected-day sessions in date mode) moved the structure toward the contract but left two gaps and introduced one regression:

• The stylesheet still rendered meaningful text at 7–11px, which DESIGN.md forbids twice: Do not render meaningful text below metadata (12/16) and Do not use 7–9px prototype text. The date calendar and session navigator added in the last two commits shipped new 9/10/11px rules.
• Colour and radius were split between the declared token block and roughly 68 one-off hex literals plus off-scale radii, so Do not introduce one-off colors, font sizes, radii was unenforced in practice.
• Nothing observed the rendered result. The first commit checked 390px and 1440px only; the last two recorded node --check and no browser verification at all, so the contract had no executable gate.

Close the gaps without changing evidence semantics, and add a check that measures the rendered report so the next change cannot silently reintroduce sub-floor type or unreachable text.

Acceptance Scenarios

• AC-1 (typography floor holds in the rendered page): every element with visible text in the Capability, Date, Session Trace, and Session Replay surfaces resolves a computed font-size of at least 12px. Measured after the cascade, not asserted against stylesheet source, because inherited rules such as .date-weekdays span carry no declaration of their own.
• AC-2 (single colour and radius source): the stylesheet declares every colour and radius through a custom property. The tool-family palette, which the semantic roles do not cover, is declared in :root as categorical evidence identity and read by the chart through var() instead of a script literal.
• AC-3 (no unreachable text): no element clips text horizontally while offering neither ellipsis truncation nor a scroll affordance. Ellipsis truncation and bounded scroll regions remain allowed.
• AC-4 (no document-level horizontal overflow): documentElement.scrollWidth does not exceed clientWidth at wide, compact, or narrow layout modes.
• AC-5 (three layout modes verified): the check runs at 1440×900, 1024×768, and 390×844, and reports console and page errors per surface.
• AC-6 (dead rules removed, not migrated): stylesheet blocks whose markup no longer exists are deleted rather than brought up to the contract.
• AC-7 (categorical identity is not state): tool family and replay event kind are categorical dimensions and draw from the categorical scale that DESIGN.md declares. No categorical value equals an interaction or state token, every value clears 3:1 against the surface it is drawn on, and no two categories in one legend share a colour.

Non-goals

• Changing evidence semantics, correlation strength, privacy bounds, or any report data model.
• Migrating packages/harness-studio surfaces. The unbundled Inter reference and the 11px rule in packages/harness-studio/src/app/index.html and StudioDiff.tsx remain open under the Studio visual system spec, whose Status stays Draft.
• Adding a browser dependency to the root npm test run.
• Claiming WCAG conformance.

Plan and Tasks

1. Raise every sub-12px rule in scripts/harness-inspector/ui/workbench.css to the 12px floor, growing the affected control boxes where a larger glyph no longer fits.
2. Delete the dead .session-notebook-context and .session-context-grid blocks, including their media-query overrides. This removes the max-height:34px prose clip at its root rather than tuning it.
3. Replace off-scale radii with --radius-* and all one-off hex literals with the matching semantic token.
4. Declare the tool-family palette in :root and have workbench.js emit var(--family-*) and var(--color-danger) instead of hex literals.
5. Relax the compact commit row from a rigid five-column grid to a wrapping flex row, since hash, subject, stats, and evidence label no longer fit one line at the readable floor in a narrow delivery lane.
6. Add scripts/harness-inspector/visual-contract-check.mjs and the inspector:visual-check npm script.
7. Repair background:var(--color-surface)df9 on .session-event.intermediate. The malformed value predates this change and silently dropped the intermediate tint; it is replaced with var(--color-surface-subtle) rather than reinventing the warm one-off.

Test and Review Evidence

• AC-1/AC-3/AC-4/AC-5: npm run inspector:visual-check renders the bundled demo report and measures it in Chromium. 12 checks pass (3 layout modes × Capability, Date, Session Trace, Session Replay) with belowFloor=0, clipped=0, overflow=0px, errors=0.
• Negative control: reintroducing font-size:9px on .date-weekdays makes the check fail with belowFloor=7, naming the seven inherited weekday spans. A source-level check on .date-weekdays would have reported one rule; a source-level check on the spans would have reported nothing, since they declare no font size. This is why the gate measures computed style.
• AC-2/AC-6: verified by rendering — the family bars, chart marks, and state colours still paint at every layout mode with no console errors, which a stylesheet with an unresolvable var() or a deleted live rule could not do.
• Regression scope: npm test passes at 96 files / 1330 tests, including the 27 files under test/reporting/.
• Screenshots: wide, compact, and narrow captures for all four surfaces, reviewed for the primary decision remaining obvious. Compact and narrow now show full commit file paths that the previous 9px monospace truncated.
• Risk: raising the type floor reduces density. Mitigation applied — the family label column and the narrow filter summary were widened, and the compact commit row wraps, so no text became unreachable; the check enforces this.
• Risk: a broad token substitution can shift a colour's meaning. Mitigation — each literal was mapped to the nearest declared role, and colour-carrying states (success, warning, danger, candidate, primary, family identity) were reviewed in the screenshots rather than only diffed.
• Risk: the check is not in npm test, so it can be skipped. Accepted for now: the root suite runs in a Node environment and adding a browser dependency there is out of scope. The npm script keeps it one command.

Review Findings Addressed

A code review of this change found three defects, all fixed before completion:

• Token self-reference (introduced here): the bulk substitution of #667085 also rewrote the :root declaration into --color-text-subtle:var(--color-text-subtle). A self-referencing custom property never resolves, so every var(--color-text-subtle) consumer fell back to inherited colour and lost the subtle tier. The rendered check did not catch this, because an unresolvable colour still paints and still measures at 12px. Lesson: a global literal substitution must exclude the token declaration block that defines the literal.
• Screen reader-only false positive (introduced here): .visually-hidden clips a 224px accessible name into a 1px box, which the clipping rule counted as unreachable text. It went unnoticed because the only such element is hidden in the demo report, so it measured zero. Left unfixed, the gate would have failed the first time a multi-workbench scope revealed the jump control, and the cheapest way to make it pass would have been deleting the accessible name. The rule now skips clip-path-hidden 1px boxes and aria-hidden subtrees.
• Malformed declaration (pre-existing): .session-event.intermediate carried background:var(--color-surface)df9, an invalid value left by an earlier token migration in refactor(inspector): flatten the evidence workbench. It was silently ignored by every browser.

Correction: categorical colour versus state colour

The first pass of this migration mapped the tool-family palette onto the nearest semantic token, which made five of seven families byte-identical to --color-primary, --color-success, --color-warning, --color-text-muted, and --color-text-subtle. That traded one violation for a worse one: DESIGN.md reserves green, amber, and red as state colours, and the palette it replaced had deliberately kept the family hues offset from them. Chasing token purity removed a real semantic separation.

The fix is a declared categorical-1 … categorical-7 scale in DESIGN.md, with a Color rule stating that categorical identity carries no judgement, never equals an interaction or state token, and is always redundant with a lane, label, or legend. Inspector maps --family-* and the replay rail onto that scale; only failure keeps --color-danger, drawn as a ring so the kind stays readable underneath.

This also fixed a pre-existing defect: .replay-rail-mark.response and .replay-rail-mark.commit both painted --color-success, so the rail rendered as one colour what its own legend listed as two kinds.

Scale properties verified numerically before adoption: minimum contrast 4.47:1 against white (≥3:1 for non-text graphics), minimum perceptual distance 32 to any interaction or state token, and 79 between any two categorical values.