Skip to content

Phase 31 slice E: overlays in one layer above the content - #249

Merged
vicmaster merged 4 commits into
masterfrom
phase-31-slice-e
Nov 15, 2026
Merged

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

Conversation

@vicmaster

Copy link
Copy Markdown
Owner

Slice E of Phase 31 (docs/specs/PHASE-31-SPEC.md, FR-E1 to FR-E3): overlays. Six overlay node types draw screen states (an open menu, a comment popover, a confirm dialog, a toast) and always render above the content, whatever their parent. The spec's "Slice E — contracts pinned before build" block (K1 to K8) records the contracts; the "Slice E — as built" block records the decisions the contracts left open and every fix from verification.

What changes

  • Six overlay types: tooltip, popover, menu, modal, toast and drawer.
    • tooltip is an inverted hint that wraps at 240px and never renders children.
    • popover is a panel 192 / 320 / 480 / 640 wide, for a comment box or a filter form.
    • menu holds menu-rows and dividers and is at least 192 wide.
    • modal is 480 / 640 / 960 wide over its own scrim. Its header has a close button named "Close" (closeLabel renames it). Its actions sit right-aligned with the filled one (primary or destructive) rightmost; an action with no variant renders secondary.
    • toast sits bottom-centre with a tone glyph and an optional action. danger renders role="alert".
    • drawer is pinned to the right edge at full height, with an optional scrim.
    • New props: text, anchor, closeLabel, actions, tone, action, scrim.
  • One overlay layer. The renderer lifts every overlay out of the tree and renders it in a layer after the root. A menu inside a sticky toolbar or a scrolling pane is never clipped and never covered by a fixed bar.
    • Stacking is fixed by kind, with no z-index property: popover and menu 400, scrim 500, modal and drawer 510, toast 600, tooltip 800.
    • x / y are offsets from the root's top-left, not from the parent.
    • A canvas without overlays renders byte-identical HTML.
  • Colours from tokens. Overlays take $bg-surface, $border, $text-primary, $text-secondary and their depth from $elevation.overlay, with neutral fallbacks when unthemed.
  • snapshot_layout places overlays as the root's last children, and a modal (or a drawer with a scrim) carries a new scrim rect.
  • Rules that waited for overlays:
    • A modal and a drawer are panes for desktop-app-current and desktop-app-primary-count.
    • A modal's primary actions count as primaries in the modal's own pane.
    • A modal's close button and actions and a toast's action join the 24px pointer census.
    • desktop-app-artboard warns on an undeclared canvas holding an overlay. Web and mobile canvases may hold overlays, including a menu with its rows.
    • The detailed overlap check never counts an overlay as overlapping its siblings.
  • Phones. On a root with a declared safeArea or a pinned tab bar, a centred modal, a default toast and a drawer keep clear of the insets and the tab bar, and the safe-area rules skip them only then.
  • Screen states are variants. canvas_add_variant recommends menu-open, comment-open, confirm-delete and toast. Coverage lists them and never demands them.
  • Agent surfaces updated: the server instructions, a new gotcha, the batch_design, snapshot_layout, canvas_add_variant and canvas_evaluate docstrings, a new "Overlays (screen states)" section in docs/GUIDELINES.md, an Overlays section in the README, and VISION.md.

Decisions worth a look

  1. The halo tell no longer flags dark shadows, on every type. The generated $elevation.overlay shadow is a deep blue-black ink with a 25px blur, and the gradient-glow tell read it as a coloured glow, so every overlay on a generated design system was blocked from presenting. A coloured glow now also needs a lightness above 0.2. Indigo, violet, crimson and white glows still fire. A very dark saturated glow (such as #0B1B4F at a 40px blur on a near-black surface) is no longer flagged.
  2. A menu inside a modal renders under the modal. The ladder puts menus at 400 and modals at 510, as the spec fixes it. The docs say so. The overlay rules in slice F may want to flag it.
  3. A fullPage capture keeps the overlay layer at the artboard. The page grows, but a scrim dims only the first screen. The docs say so.
  4. A modal's box is never a neighbour in the 24px circle test. Its buttons render under its own id, so its whole box stood in for them and any small target near a modal failed. Everything outside a modal is under its scrim, so it is left out. A toast keeps its box.
  5. Follow-up, recorded in VISION.md: a modal's 32px controls and a toast's 24px action are not in the mobile 44px touch census. Meeting 44px needs a size option on the overlay, since render never depends on type. The docs send phone dialogs to sheet until then.

Testing

  • New test-overlays.ts (fast) covers:
    • the layer: lifting, nesting, instances, the ladder, root coordinates, and no layer without overlays
    • anatomy, sizes, roles and colour defaults, themed and unthemed
    • the rule clauses: FR-C9 by declaration, panes, modal primaries, census targets
    • stress text props and the confirm-delete variant in coverage
    • twins that must fail for each passing assertion
  • New test-overlays-render.ts (Chrome) covers:
    • stacking by elementFromPoint: a menu in a sticky bar in a scrolling pane above a fixed sibling and unclipped, and the full ladder in reverse tree order
    • a 640px centred modal with a full scrim
    • the walker from the root and from an overlay, a narrower root, and a full-page capture
    • the overlap check, stress, the 24px neighbour rule, and phones with and without a safe area
  • Verification, first round: five agents on the first build.
    • Spec conformance refuted nothing. It flagged the modal's box as a circle-test neighbour.
    • Mutation testing killed 63 of 86 mutants. Every real survivor now has an assertion.
    • Regression and input attack found the halo tell on generated shadows, false safe-area findings inside a scrolling modal body on a phone, overlays ignoring the phone insets and tab bar, and a menu on web or mobile tripping FR-C9 through its rows.
    • Docs steward and cold reader found stale rule descriptions, a broken README example, an over-claimed anchor, and missing sizes and positions in the guideline.
    • Each fix that loosens a verdict was proved against the first build with its nearest keep-cases unchanged.
  • Verification, second round (on the fixes): one agent confirmed the loosenings hold their keep-cases and that desktop renders are unchanged apart from the modal's centring CSS. It found one regression: on a phone root with no declared safe area, the safe-area rule skipped overlays the render does not keep clear. That fix was proved red on the previous snapshot and green on the fix; no agent re-verified it.
  • npm run test:full: 130/130 on 042ce73.

@vicmaster
vicmaster merged commit 04d38fd into master Nov 15, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-31-slice-e branch November 15, 2026 20:08
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