Skip to content

Phase 31 slice H: state checks - #252

Merged
vicmaster merged 4 commits into
masterfrom
phase-31-slice-h
Nov 17, 2026
Merged

vicmaster merged 4 commits into
masterfrom
phase-31-slice-h

Conversation

@vicmaster

Copy link
Copy Markdown
Owner

Slice H of Phase 31 (docs/specs/PHASE-31-SPEC.md, FR-H1 to FR-H4): the element states, checked without being drawn. The evaluator now computes, from the scene alone, what the renderer draws for every target's focus ring, active indicator, disabled look and boundary, and judges each against WCAG 1.4.11. The spec's "Slice H — contracts pinned before build" block (R1 to R11) records the contracts, and the "Slice H — as built" block (T1 to T4 and both rounds of fixes) records what changed during the build and verification.

What changes

  • desktop-app-focus-visible (error). A target's focus ring below 3:1 against the pixels it covers when the target is not focused: the backdrop behind it for the ring drawn outside the box, and a tab's own fill for the ring drawn inside it. Targets that share a ring and a backdrop make one error, with nodeIds and count. A target whose backdrop or ring the checker cannot read is listed in one info.
  • desktop-app-state-contrast (warning). An active nav-item's bar or an active line tab's underline below 3:1 against its active fill, at rest or with the hover layer over it.
  • desktop-app-boundary (warning). A text-input border, an unchecked checkbox or radio outline, or an unchecked toggle track below 3:1 against what is behind it. A border that draws nothing (transparent, a misspelt token) counts as invisible. A field whose own fill clears 3:1 passes, because the fill shows its edge.
  • desktop-app-disabled (info). When the state tokens make a disabled target look like its enabled self (within 1.1:1).
  • All four are desktop-app only and run in the color category, in each theme the canvas ships. They give the same answer in fast and detailed mode. A dark finding that only repeats the light one (literal colours, which no theme changes) is dropped. A finding on targets inside a component instance says the design system never reaches them.
  • On every type, text inside a disabled clickable primitive is exempt from the text-contrast error, as WCAG exempts it.
  • The colour helpers moved from evaluate.ts to a new src/color-math.ts, with the backdrop walk the text-contrast check and the state checks now share. parseAlpha now reads a percent alpha: rgba(0, 0, 0, 50%) is 0.5, where it was read as opaque. That is the only verdict change outside the new rules.
  • Agent surfaces updated: the server instructions, the element-states gotcha, the canvas_evaluate docstring, a new block in docs/GUIDELINES.md's desktop-app ruleset, four README rule rows and the color category row, and VISION.md.

Decisions worth a look

  1. The inset tab ring is measured against the tab's unfocused fill, not its focus layer. Measured against the focus layer, every dark generated system's tab ring failed (2.48 to 2.95), because $focus-ring is picked against the plain surfaces. This is the change-of-contrast reading of WCAG 2.4.13. A canvas that raises state.focus far above Material's 0.10 can hide a tab's ring under its own focus layer without a finding; that is recorded as accepted.
  2. The boundary rule measures a border that draws nothing instead of skipping it. The frozen contract skipped an unresolved or transparent boundary. Verification showed that left an invisible checkbox (a misspelt token) with no finding at all, so the contract was amended in place.
  3. A field whose own fill clears 3:1 passes the boundary rule. FR-H4 itself says a border needs 3:1 only when nothing else shows the field. A dark-filled input with a faint border was being flagged, and a faint field with no border was not.
  4. Two primitives draw no active indicator. tree-row and the contained tabs show their active state with a tint and a heavier weight only, so the indicator rule has nothing to measure on them. select is not in FR-H4, though its border is its only boundary too. Both are follow-ups in VISION.md.
  5. apply_preset after generate_design_system can leave $accent-tint and $border-strong out of step with the preset's surfaces. The warnings that then appear are true, and the slice D gate applies presets on their own, so it does not cover this case.

Testing

  • New test-state-checks.ts (fast, 226 checks) covers each FR-H acceptance with a twin that must fail, every rule's gate on its own, the exact 3.00 and 1.10 thresholds, every target type's colours, the overlay and item backdrops, instances, both themes, the web and mobile exclusions, and a gate. The gate generates every personality × three seeds in both themes, with every target on each bg-* and *-tint surface, and expects no finding. A twin breaks the tokens and finds each rule on the surface it was planted on.
  • New test-state-model-render.ts (Chrome) renders the targets unthemed and under a generated system in both themes, and compares 127 pixels with the model's colours within 2/255 per channel. The pixels cover rings and what they cover, indicators in rest and hover, every button variant's layers, an authored opacity, disabled tracks and containers, boundaries, a modal's close button and actions, and a translucent ink. A twin shows a model 0.05 off in layer opacity fails the same comparison.
  • The slice D desktop gate (fast and detailed) stays green with the four rules on.
  • Before the build, one agent tried to break the contracts on paper and found twelve problems. The most important was the inset-ring reference in decision 1, which would have failed every dark generated system. All twelve were folded in before freezing.
  • Verification, first round: six agents on ac2f203.
    • Spec conformance held R1 to R11 and every acceptance. It found a transparent boundary skipped silently, and a render test narrower than specified, which now covers every button variant, opacity, the disabled pairs and modal items.
    • Adversarial review found named colours drawn as transparent (a false 1.00:1 error), a crash on a non-string ring, and quadratic grouping.
    • Gate attack swept 65 seeds, every structure, overlays, states sheets and inherited systems, all clean. It found four holes: the fill-as-edge and invisible-border cases in decisions 2 and 3, advice that cannot fix a finding inside an instance, and a duplicated dark finding on literal colours.
    • Mutation testing ran 350 mutants: 162 killed, 12 equivalent, 176 survivors. About 80 new assertions target the survivors.
    • Docs steward proposed two edits; cold reader found seven gaps. All were applied.
    • Every fix was proved red on ac2f203 and green after.
  • Verification, second round (on the fixes, b094305): one agent found six low-severity issues and no wrong verdicts. They were an instance whose component root is the target missing its note, an info losing its own advice, and four wording gaps. They were fixed, proved red on b094305 and green on 3295307; no agent re-verified them.
  • npm run test:full: 136/136 on 3295307. Two runs during verification each had one test time out under machine load (load average 7 to 8); both passed when rerun alone.

@vicmaster
vicmaster merged commit 1b60930 into master Nov 17, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-31-slice-h branch November 17, 2026 19:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant