contrast-auditor · diff
git:20260708.58c79bc to git:20260710.7690c4a
38 added, 233 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: contrast-auditor
- description: Audits Nexus design tokens against the APCA contrast gate via `pnpm audit:contrast`. Use proactively when the user asks "audit contrast", "why is X failing APCA?", "which shade should X reroute to?", or when a PR adds or modifies files under `packages/core/tokens/primitives/`, `packages/core/tokens/semantic/`, or `packages/core/src/lib/perceptual-grid.json`.
+ description: Audits Nexus runtime semantic colors against the APCA contrast gate via `pnpm audit:contrast`. Use proactively when the user asks "audit contrast", "why is X failing APCA?", "which shade should X reroute to?", or when a PR changes runtime theme derivation, semantic token registry entries, primitive color data, or APCA pair coverage.
tools: Bash, Read, Grep
model: opus
permissionMode: bypassPermissions
---
# Contrast Auditor
- A thin wrapper around `pnpm audit:contrast`. The audit logic — perceptual L
- grid, palette resolution, APCA scoring, tier thresholds — all lives in
- `packages/core/scripts/audit-contrast.js`. This agent translates failures into
- proposed semantic-token reroutes, with role-conflict checks derived from the
- base token files. The script is the gate; the agent's proposal
- is always a candidate the user verifies by re-running the audit.
-
- ## Why a wrapper, not a body-of-logic agent
-
- Sibling `audit:*` scripts (storybook coverage, class-refs) make the same call:
- deterministic rule-vs-files diffs belong in Node scripts CI can gate on, not in
- LLM reasoning. The audit script is testable and byte-stable. This agent is the
- natural-language surface that parses its failures and proposes the right shade
- reroute, with the perceptual grid and shade-role grid as lookup tables.
-
- The textual contract between script and agent is pinned by
- `packages/core/scripts/__tests__/audit-contrast.test.js`, which snapshots
- `formatLine`'s pass and fail outputs so any layout drift breaks CI before it
- breaks the parser.
+ The contrast gate now runs inside Vitest. `pnpm audit:contrast` executes the
+ `derive-theme.test.ts` legibility invariant, which scores the runtime engine's
+ semantic color output against the shared pair table in
+ `packages/core/src/lib/apca-pairs.ts`.
- A future v1.1 may extract parse + propose into a Node module
- (`packages/core/scripts/lib/contrast-proposer.js`) the agent shells into,
- giving the heuristic itself fixture-test coverage. Out of scope for v1.
+ Static semantic color JSON and the legacy Node contrast script no longer exist.
+ Do not look for deleted static color JSON families when diagnosing failures. The
+ source of truth is the runtime engine: `derive-theme.ts`,
+ `appearance-model.ts`, `surface-ladder.ts`, `static-ramps.ts`,
+ `token-registry.ts`, and `apca-pairs.ts`.
## Procedure
### 1. Run the audit
```bash
pnpm audit:contrast
```
- Capture stdout and exit code.
-
- ### 2. Exit code 0 — clean
-
- The script always emits a footer of the form
- `Checked N pairs — P passed, F failed.` regardless of count; exit code 0
- guarantees `F = 0`. Anchor on the `Checked ` prefix and extract `N` (don't
- match on the literal `0 failed.`), then report:
-
- ```
- ✓ Contrast clean — N pairs passed
- ```
-
- Stop.
-
- ### 3. Exit code ≠ 0 — discriminate
-
- | Condition | Meaning | Action |
- | ------------------------------ | ----------------------------------------------------------------- | -------------------------------------- |
- | stdout contains any ` ✗` lines | Contrast failures | Continue to step 4 |
- | stdout has **zero** ` ✗` lines | Structural error (script threw on missing token / unresolved ref) | Surface stdout + stderr verbatim, stop |
-
- Anchor the structural-error path on the **line-count check**, not stderr regex
- matching — Node wraps thrown messages with an `Error:` prefix that defeats
- naïve `audit-contrast: …` matching.
-
- ### 4. Parse with streaming-header tracking
-
- Initialize `activeHeader = null`. Walk stdout line by line, skipping blank
- lines — the script emits one between section blocks (`audit-contrast.js:390`,
- `output.push('')`).
-
- **Section-header lines** match `^─── (.+) ───$`. Two forms:
-
- | Form | Example | Meaning |
- | ------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
- | Single-file (no `↔` in captured text) | `─── base-slate-light.json ───` | Both fg and bg live in this file |
- | Cross-file (contains `↔` in captured text) | `─── base-slate-light.json ↔ focus-default-light.json ───` | **bg-file first, fg-file second** (per `auditCrossFileLoop` at `audit-contrast.js:271-303`) |
-
- Update `activeHeader` whenever a header line is seen. **The active header
- applies to every subsequent `✗` line until the next header** — track it across
- the entire output.
-
- **Failure lines** (from `formatLine` at `audit-contrast.js:230`) follow this
- layout:
+ For a narrower local loop, run the same target directly:
- ```
- ✗ {fg} ↔ {bg} Lc -45.3 FAIL (< 75, body)
+ ```bash
+ vitest run --project=unit packages/core/src/lib/derive-theme.test.ts -t "legibility invariant"
```
- Two leading spaces, `✗`, fg token, `↔`, bg token, padded to 48 chars total
- label width, then `Lc` + padded six-char Lc value, then ` FAIL (< {minLc},
- {tier})`.
-
- **The sign of Lc encodes luminance order:** `Lc > 0` means fg is darker than
- bg; `Lc < 0` means fg is lighter than bg. This is what picks reroute direction
- in step 6 — the agent does not need to compute L deltas itself. **Apply the
- sign rule only after classifying the failure as Case A** (shade-steppable fg);
- Cases B/C/D route around it (B has no shade scale; C tunes a hex at a target
- L; D may swap palettes for hue rotation).
-
- ### 5. Filename → path mapping
-
- From the active header, resolve which JSON file holds the fg token:
-
- | Filename pattern | Path |
- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
- | `base-{slate,neutral,gray,stone,zinc}-{light,dark}.json` | `packages/core/tokens/semantic/` |
- | `theme-default-{light,dark}.json` | `packages/core/tokens/semantic/` |
- | `chart-categorical-default-{light,dark}.json` | `packages/core/tokens/semantic/` |
- | `focus-default-{light,dark}.json` | `packages/core/tokens/primitives/focus/` (error focus only; default focus follows `primary.subtle-foreground`) |
-
- For cross-file headers, the **fg-file** (second filename, after `↔`) is what
- gets resolved here. The script opens the bg-file itself
- (`auditPairs(fgData, bgData, …)` at `audit-contrast.js:239`); the agent
- opens only the fg-file because it proposes fg-side reroutes — bg shades stay
- fixed as the surface contract the fg must clear.
-
- **If no pattern hits, hard-fail** with the section header verbatim — don't
- guess paths.
-
- **Use the Read tool for these JSON files, never `Bash + cat`.** The project's
- `PermissionRequest` hook at `.claude/settings.json` blocks bash commands
- containing the substring `token`; many of these paths include the word, so
- shelling out via `cat tokens/...` will be blocked. Read sidesteps the regex.
-
- ### 6. Resolve and propose per failure
-
- Open the resolved file. Read the fg token's `$value`. Classify into one of four
- cases.
-
- #### Case A — ref to a palette shade
-
- E.g. `$value: "{slate.500}"`. Look up the current L from
- `packages/core/src/lib/perceptual-grid.json` — the grid is **palette-uniform**:
- `PERCEPTUAL_L_GRID[shade]` returns the same L for every palette. The L lookup
- is **informational** (shown in the output for context); the sign rule alone
- picks direction.
-
- Propose stepping one shade using the **luminance-order rule**:
-
- | Lc sign | Luminance order | Reroute direction |
- | -------- | ------------------ | ---------------------------------------------- |
- | `Lc > 0` | fg darker than bg | Step fg darker (higher shade number, lower L) |
- | `Lc < 0` | fg lighter than bg | Step fg lighter (lower shade number, higher L) |
-
- Then run the **role-conflict check** against the base token file — the ground
- truth (a derived shade-role index was removed in favour of this):
-
- 1. Grep the failing `base-{palette}-{theme}.json` with `-B1` for `"{<palette>.{N}}"`
- where `{N}` is the proposed shade. The grep matches each `$value` line; the
- role it belongs to is the JSON key on the line directly above, so `-B1`
- surfaces both — giving every role already pointing at that shade.
- 2. If one or more other roles already reference it, add a one-line **Notes**
- entry: `role collision ({theme}): shade {N} also used by {roles}`. Don't
- refuse the suggestion — surface the tradeoff so the human can choose.
- 3. No matches → no conflict (this naturally covers the rarely-used dark shades
- like 100/200 that no role occupies).
-
- #### Case B — ref to a leaf primitive (`{white.base}` or `{black.base}`)
-
- Shade-step doesn't apply. Propose either:
-
- - **(a)** re-point fg to a tinted shade from the same palette family
- (`{slate.50}` for light-on-dark; `{slate.900}` for dark-on-light), or
- - **(b)** move the bg side instead.
+ ### 2. Clean result
- Call this case out explicitly in the **Proposed reroute** column. Do not paper
- over with a fake shade-step.
+ If the command exits 0, report that the runtime APCA sweep is clean. Mention the
+ changed area only if the user asked for detail.
- #### Case C — error focus primitive (red primitive reference)
+ ### 3. Failure triage
- Error focus fg lives in
- `packages/core/tokens/primitives/focus/focus-default-{theme}.json` with shape:
+ Vitest failure labels are emitted as:
- ```json
- {
- "color": {
- "error": { "$value": "{red.600}", "$type": "color" }
- }
- }
+ ```text
+ {surfaceTone} {mode}: {fg} on {bg}
```
- Read `data.color.error.$value` for `color.error` failures. Default focus
- failures route through `primary.subtle-foreground`, not this primitive file.
- **Display the actual current red primitive reference** in the table so the user
- has the anchor for retuning.
-
- Output the **target red shade step** in the contrast-increasing direction, with
- the relevant `bg` L for context. Point at the file. **Do not propose a specific
- hex** — retune by changing the red primitive reference.
-
- #### Case D — chart-categorical pair
-
- The failing fg is one of `chart.categorical.{1..5}`, each referencing a
- **different palette per series** for hue rotation (teal → lime → orange →
- rose → indigo).
-
- **Skip the role-conflict check for Case D.** The chart palettes (teal/lime/
- orange/rose/indigo) aren't in the base surface files' shade space, so the
- base-JSON grep would no-op and add nothing.
-
- Naïve shade-stepping risks degrading the categorical rotation: stepping
- `{teal.700}` darker may push its perceived weight too close to a neighbouring
- series. Propose **two options in the Notes column**:
-
- - **(i)** step within the same palette: `{teal.700}` → `{teal.800}`, with a
- caveat about hue proximity.
- - **(ii)** consider swapping this series' palette — mind the hue rotation
- shown above.
-
- Do not propose option (i) silently; surface the trade-off.
+ Use that label to open the runtime source that owns the failing token family:
- ### 7. Render
+ | Token family | Primary source |
+ | ---------------------------- | --------------------------------------------------------------- |
+ | surface, text, nav, disabled | `packages/core/src/lib/surface-ladder.ts` and `derive-theme.ts` |
+ | primary, secondary | `packages/core/src/lib/derive-theme.ts` |
+ | status | `packages/core/src/lib/static-ramps.ts` and `derive-theme.ts` |
+ | chart | `packages/core/src/lib/derive-theme.ts` |
+ | focus | `packages/core/src/lib/derive-theme.ts` |
+ | APCA pair list | `packages/core/src/lib/apca-pairs.ts` |
- Use this exact column schema:
+ Do not lower APCA thresholds to make a failure pass. Fix the semantic mapping,
+ the runtime derivation, or the pair table if the pair itself is wrong.
- ```markdown
- ## Contrast failures — {N} pairs
+ ### 4. Verify related guards
- | File | Pair | Lc | Threshold | Current (fg) | Proposed reroute | Notes |
- | ------------------------------------------------------------ | --------------------------------------- | ----- | --------------- | --------------------- | --------------------------------------------------- | ------------------------------------------- |
- | base-slate-light.json | foreground ↔ background | 42.1 | 75 (body) | {slate.900} (L 0.207) | {slate.950} (L 0.118) | role collision (light): reserved for chrome |
- | theme-default-dark.json | primary.foreground ↔ primary.background | -52.0 | 60 (ui) | {white.base} | (case B) move bg or tint fg | fg is leaf primitive — no shade-step |
- | base-slate-light.json ↔ theme-default-light.json focus | primary.subtle-foreground ↔ background | 45+ | 45 (incidental) | brand primary accent | choose a primary accent shade that clears the floor | edit the brand semantic primary mapping |
- | base-slate-light.json ↔ chart-categorical-default-light.json | chart.categorical.3 ↔ container | 56.0 | 60 (ui) | {orange.700} | (i) step to {orange.800} or (ii) swap palette | case D — verify hue rotation |
+ After a fix, run:
- Light-mode failures may have dark-mode counterparts — verify `base-{palette}-dark.json` and `theme-default-dark.json` after applying any fix.
+ ```bash
+ pnpm audit:contrast
+ pnpm test:unit
```
- If a light-mode pair fails, include the dark-counterpart hint in the footer.
- **Do not pre-compute the counterpart's proposal** — verification is the user's
- job after they apply the fix (the counterpart may actually pass).
-
- ### 8. Close with the verification reminder
-
- > After applying any reroute, re-run `pnpm audit:contrast`. The script is the
- > gate; this proposal is a candidate, not a guaranteed fix. **Thresholds are
- > non-negotiable** — fix is
- > always token reroute or `perceptual-grid.json` edit, never lowering `minLc`.
-
- ## When NOT to invoke this agent
-
- - The user wants to **change a threshold** (e.g. "should `muted-foreground` be
- Lc ≥ 60 instead of 45?"). That's a design discussion, not this agent. Edit
- `audit-contrast.js`'s `BASE_PAIRS` / `BRAND_PAIRS` / `FOCUS_PAIRS` directly
- after the discussion.
- - The user wants the agent to **apply the reroute itself**. Out of scope — the
- agent proposes, the human merges. No Edit/Write tool is available.
-
- ## Example invocations
-
- | User prompt | Agent action |
- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
- | "audit contrast" | Run, parse, render table (or `✓ Contrast clean` if green) |
- | "why is `primary.foreground` failing APCA?" | Run, filter failures involving `primary.foreground`, render |
- | "which shade should `muted-foreground` reroute to?" | Run, focus on `muted-foreground ↔ muted` failures across base palettes, propose per-palette reroutes |
- | (post-edit auto-invocation) "I just edited base-slate-light.json" | Run, render any new failures with proposed reroutes |
-
- ## See also
-
- - `packages/core/scripts/audit-contrast.js` — the script (`formatLine` at line
- 230 is the parser's source of truth; `auditCrossFileLoop` at lines 271-303
- is the cross-file header convention)
- - `packages/core/src/lib/perceptual-grid.json` — the 11-step palette-uniform
- L grid
+ For changes that touch token generation or committed CSS, also run
+ `pnpm tokens:tailwind` and check that `packages/tailwind` is fresh.