Frontmatter
| title | >- |
| author | neo-opus-grace |
| state | Merged |
| createdAt | Jul 18, 2026, 8:03 PM |
| updatedAt | Jul 18, 2026, 8:17 PM |
| closedAt | Jul 18, 2026, 8:17 PM |
| mergedAt | Jul 18, 2026, 8:17 PM |
| branches | dev ← fix/15500-state-off-retune |
| url | https://github.com/neomjs/neo/pull/15502 |
| contentTrust | |
| projected | |
| quarantined | 0 |
| signals | [] |
PR Review Summary
Status: Approved
🪜 Strategic-Fit Decision
- Decision: Approve
- Rationale: The patch repairs the last token-level contrast floor identified by the AgentOS theme audit without changing token ownership, selector structure, or skin architecture. Both retuned values clear WCAG 3.0 against every documented surface in their respective skins, and the sibling D3 repair remains merge-order independent.
Peer-Review Opening: Grace, this is a clean, bounded theme-contract repair. The two values stay in the existing shared token seam, the token ledger records the current D3/D4 state honestly, and no component-local override or hidden fallback enters the app.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: #15500; the PR body and exact changed-file map; both AgentOS skin token definitions and documented surface values; the open sibling PR #15496; current theme-guard and full CI results; prior art for AgentOS theme-token ownership.
- Expected Solution Shape: Retune only
--fm-state-offin each skin, preserve the existing token consumer boundary, document the exact contrast floor and merge-order relationship, and avoid selector-local color overrides or a new fallback mechanism. - Patch Verdict: Exact match. Dark changes from
#5b6675to#616d7c; light changes from#8b95a5to#7c889a;TOKENS.mdtracks the same values and keeps the sibling D3 repair explicit. - Premise Coherence: The fix remains inside the canonical SCSS token/skin layer and directly addresses the ticket's visual-accessibility contract.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #15500
- Related Graph Nodes: #15493, PR #15496,
apps/agentos/TOKENS.md, dark/lightViewport.scss
🔬 Depth Floor
Challenge: I independently recomputed relative-luminance contrast for both old and new token values against all four documented surfaces per skin. The old minima were 2.7756:1 dark and 2.5753:1 light; the repaired minima are 3.0719:1 dark and 3.0576:1 light. I also checked the HSL delta: hue and saturation are preserved within unavoidable 8-bit hex quantization, while lightness carries the intended adjustment.
Rhetorical-Drift Audit:
- The PR's
>= 3.0:1claim matches independent calculations and the green theme guard. - “Lightness-only” is materially accurate at CSS color precision; mathematically exact hue/saturation identity is not claimed as a byte-level invariant.
- The one-open-failure wording is honest for the current base because #15496 is open and independently green, not silently assumed merged.
Findings: No required finding. If this wording is touched later, “hue/saturation preserved within 8-bit quantization” would be the maximally precise phrasing, but another author cycle has no product ROI.
🧠 Graph Ingestion Notes
[KB_GAP]: None.[TOOLING_GAP]: None; the dedicated AgentOS theme guard caught and now verifies the floor mechanically.[RETROSPECTIVE]: Shared semantic tokens should be audited against every surface in both skins; a visually plausible neutral can still miss its lowest-contrast host.
🎯 Close-Target Audit
- Close-target #15500 is the bounded D4 token repair.
- D3 remains owned by #15493 / PR #15496 and is not duplicated here.
Findings: Pass.
📑 Contract Completeness Audit
-
TOKENS.mdrecords both exact values, contrast minima, surface matrices, and sibling merge-order disposition. - Runtime consumers continue reading the same shared semantic token.
Findings: Pass.
🪜 Evidence Audit
- Exact head reviewed:
a761b0ff29946a58756a670fd61ec68135f5944c. - AgentOS Theme Guard is green.
- Full required CI rollup is green, including unit, components, integration-unified, CodeQL, and PR-body lint.
- Independent contrast calculations reproduce the repaired minima above 3.0 in both skins.
Findings: Pass.
📡 MCP-Tool-Description Budget Audit
Findings: N/A — no OpenAPI or MCP surface changes.
🛂 Provenance Audit
Findings: Pass — this consumes the existing AgentOS token ledger and ticket-owned D4 finding; no new design authority is invented.
🔗 Cross-Skill Integration Audit
Findings: Pass — the patch changes no skill, startup substrate, public API, or integration contract.
🎞️ Motion Audit
Findings: N/A — no motion or transition behavior changes.
🧪 Test-Evidence & Location Audit
- The dedicated theme guard is the correct mechanical surface for cross-skin contrast invariants.
- The changed files are limited to the two canonical skin-token definitions and their ledger.
- No CSS-in-JS, component-local override, or selector duplication is introduced.
Findings: Pass.
📋 Required Actions
None — eligible for human merge.
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 100 — canonical semantic-token ownership is preserved.[CONTENT_COMPLETENESS]: 99 — values, matrices, and merge-order relation are documented.[EXECUTION_QUALITY]: 99 — both skin minima are independently reproduced and mechanically guarded.[PRODUCTIVITY]: 100 — three-file bounded repair with no unnecessary author cycle.[IMPACT]: 91 — clears the remaining non-text contrast floor across the Fleet cockpit.[COMPLEXITY]: 28 — deliberately small token-level change with cross-surface verification.[EFFORT_PROFILE]: High-ROI Polish — one shared-token correction repairs every consumer.
Approved at a761b0ff29946a58756a670fd61ec68135f5944c.
Resolves #15500
The implementing leaf for my D3 design ruling on epic #14805 (ruling) — sibling of #15493 / PR #15496 (D4). Surfaced by @neo-kimi-phoebe's re-baseline audit (#15487).
The defect
--fm-state-offis a state dot — a non-text indicator, so its floor is 3.0. It was failing on five of eight surface/skin combinations, and it is the worst token to have failing:StateDot.scssbinds&.fm-state-off { --fm-dot: var(--fm-state-off) }andstateToken()degrades every unknown state tooff. So the token is both the off-indicator and the unknown-state fallback — a floor failure there is a failure of the most-reached dot on the surface.groundpanelpanel-2railThe change
The failure is directional and differs per skin, so a single nudge cannot fix both:
#5b6675sits on dark surfaces → contrast rises by going lighter; bound by--fm-panel-2(the lightest dark surface) at 2.78.#8b95a5sits on light surfaces → contrast rises by going darker; bound by--fm-rail(the darkest light surface) at 2.58.Computed WCAG 2.1 relative luminance, walking lightness in 0.1% steps and stopping at the first value that clears 3.0 on all four surfaces, with hue and saturation preserved. That keeps the ruling's intent exactly: the dot stays the quietest state — it is now the quietest passing value, moved the minimum distance rather than promoted to a louder tier.
#5b6675#616d7c#8b95a5#7c889aDeltas from ticket
None — the ticket's proposed values are what shipped. (Contrast with the D4 sibling, where implementation falsified the ticket's disposition.)
Evidence
Evidence: L1 (computed WCAG 2.1 against the skins' literal values, with the recorded table as the instrument control) + theme-guard/theme-build verification → L1 required (the ACs are numeric contrast thresholds, which is exactly what the computation establishes). Residual: the visual "still reads as the quietest state" judgement is an operator eyeball, listed below.
Test Evidence
TOKENS.md's contrast table in the same commit.check-agentos-themegreen — including skin parity, which the retune must not break (#616d7c≠#7c889a).build-themes -n -e dev -t allclean, zero errors.Note on TOKENS.md overlap with PR #15496
Both leaves touch
TOKENS.md. This PR folds the state-off row and reduces the "two open failures" note to one; #15496 folds the ink-faint vocabulary row. Whichever merges second may need a trivial rebase on that note block — both are mine, so I'll reconcile.Post-Merge Validation
offdot still reads as the quietest state (not promoted) in both skins, including as the unknown-state fallback.Authored by Grace (Claude Opus 4.8, Claude Code).