Skip to content

Phase 31 slice G: element states - #251

Merged
vicmaster merged 5 commits into
masterfrom
phase-31-slice-g
Nov 17, 2026
Merged

vicmaster merged 5 commits into
masterfrom
phase-31-slice-g

Conversation

@vicmaster

Copy link
Copy Markdown
Owner

Slice G of Phase 31 (docs/specs/PHASE-31-SPEC.md, FR-G1): element states. A state property draws hover, focus, pressed and disabled from the design system's state tokens, so a states sheet or a screenshot can show them. The spec's "Slice G — contracts pinned before build" block (S9, P1 to P9) records the contracts. The "Slice G — as built" block (S10, Q1 to Q8) records the decisions made while building and every fix from verification.

What changes

  • state: "rest" | "hover" | "focus" | "pressed" | "disabled" on button, link, text-input, nav-item, tree-row, menu-row, list-row and the four controls. Primitives that draw several targets take it on the item: each tabs and tab-bar item, a nav-bar's actions, each modal action and a toast action. Every other node type ignores it.
  • Hover, focus and pressed lay the target's label colour over its fill at the state tokens' opacities (Material 3's 8, 10 and 10 percent when unset). A target with no fill tints what is behind it, and a link also underlines.
  • Focus draws a 2px $focus-ring outline at a 2px gap (spec change S9). The ring therefore touches only the backdrop and never a brand fill. A tab and a tab-bar item draw it inside their box, because the tablist and a floating bar clip. The live viewer's keyboard focus now uses the same ring colour.
  • Disabled renders in $text-primary when the state tokens set a disabled opacity (spec change S10):
    • content at disabledContent (38%)
    • a drawn fill or border at disabledContainer (12%)
    • a check mark, knob or badge numeral in $bg-surface
  • Disabled without those tokens renders as before: 0.5 opacity in the target's own colours.
  • state: "disabled" counts as disabled everywhere disabled: true does. It takes the target out of the tab order, out of the 24px census and out of the primary count. The phone's 44px census still measures disabled targets, as it always has.
  • Nothing else moves. A canvas with no state and no disabled node renders the same as before, except the live-focus ring colour, which never reaches a capture.
  • Agent surfaces updated: the server instructions, a new gotcha, the batch_design property list and every primitive line, a new "Element states" paragraph, the set_variables state description, a new "Element states" section in docs/GUIDELINES.md with an example, the README primitive tables and a new paragraph, VISION.md, and a discoverability check.

Decisions worth a look

  1. Spec change S9, approved before the build. FR-G1 asked for a 1px inner ring "in the fill color" on filled primitives, which draws nothing visible. The ring now sits at a 2px gap instead, which does the same job and matches today's live focus. Slice H's focus check compares the ring with the backdrop, and that model is now exact.
  2. Spec change S10, approved during the build. The frozen contract drew a disabled target in its own colours at 38% and 12%. A rendered states sheet showed a disabled primary's white label nearly vanishing on a light page. Disabled now uses Material's on-surface colour, the source of those two numbers, so it reads as a grey version of the control in both themes.
  3. Disabled buttons and controls now leave the tab order (tabindex="-1", aria-disabled), as the slice B primitives already did. This changes HTML only, not pixels (Q2).
  4. A disabled tabs node now dims its tabs (Q4). Before this slice its opacity was set but never drawn, so it rendered as enabled.
  5. Truthiness. The renderer treats any truthy disabled as disabled, as it did before. The census and primary count still read disabled === true, as before. disabled is typed boolean, so the two only disagree on out-of-contract values.
  6. Accepted as found:
    • A disabled control inside a component instance is not dimmed. Instances render after variable resolution, and that was already true for disabled: true. It is a follow-up in VISION.md.
    • A focused row flush against a clipping pane edge has its ring cut, because only tabs and tab-bar items draw the ring inside.
    • A disabled toggle shows on and off by knob position only, as Material does.

Testing

  • New test-element-states.ts (fast, 277 checks) covers:
    • each stateful node and item at each state, with exact inks, ring and percentages
    • a twin for every presence: rest, a node type that ignores state, an unknown value, disabled: true beating state: "hover"
    • token fallbacks, disabled arithmetic, authored opacity and clear fills
    • the census, overlay targets and primary count readers
    • the mobile census exception
  • New test-element-states-render.ts (Chrome) renders four button variants at five states in both themes. Each state renders the same pixels twice, and every pair of states differs.
  • No-change check. 337 scenes were rendered before and after: every structure on every type, themed and unthemed, both themes, and every stateful type enabled and disabled. They differ only in the live-ring colour, Q2's tab-order attributes and the intended disabled-tab token render (Q1).
  • Verification, first round: five agents on 5fbbbf3.
    • Spec conformance held P1 to P8 and found two defects. Overlays lost their disabled dimming on token canvases, and a disabled field's error message became unreadable.
    • Adversarial review found four more:
      • white marks vanished on dark disabled controls
      • a non-boolean disabled stopped dimming
      • clear fills spelled none or with a zero alpha got painted
      • state lowered the token-adoption score
    • Mutation testing ran 294 mutants and left 76 survivors, about 22 of them equivalent. They were concentrated in the disabled paths of every type but the button. Every one now has a test that kills it, and a representative 16 were re-run and killed.
    • Docs steward proposed nine edits, all applied.
    • Cold reader flagged five gaps, all closed, including an example.
    • Each fix was proved red on 5fbbbf3 and green after. The disabled-truthiness fix was also checked against the pre-slice commit.
  • Verification, second round (on the fixes, 6896c88): one agent ran a 4,140-render matrix and an 864-case census matrix against the pre-slice commit. It found a real bug: the clear-colour test read the last channel of an opaque rgb(255, 165, 0) as an alpha. It also found three wording over-claims. That fix was proved red on 6896c88 and green on ddada5e; no agent re-verified it.
  • npm run test:full: 134/134 on ddada5e and on the final commit, which only tidies two comments.

@vicmaster
vicmaster merged commit c127161 into master Nov 17, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-31-slice-g branch November 17, 2026 17:11
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