overlays· chapter 31 · 10 primitives · 3 anchors · 3 dismissals
ten overlays · one grammar · no ad-hoc backdrops
every floating surface in the brand system declares one of three anchors and one of three dismissal modes. tooltip, popover, dropdown, dialog, and toast came first; the audit's eighth gap was the missing five — sheet, drawer, accordion, context menu, and alert-dialog. they ship together so the covenant detector can grep one set of data-dismissal attributes and every consumer reaches the same chrome by typing.
as of
board · live
five overlay primitives reachable from one stage · tooltip · popover · sheet · drawer · dialog · toast. dial each anchor and watch the floating-ui math respond. the receipt below traces the contract: anchor · dismissal · decision-node kind.
toasts mount in the global ToastProvider · prefer-reduced-motion is respected
trade receipt
- last overlay
- idle
- last action
- no overlay opened yet
- at
- —
- tooltip
- placement top
- popover
- placement bottom-start
- sheet
- edge bottom
- drawer
- edge right · modal
as of
01 · vocabularyten overlays · five existing · five newthe ten-overlay vocabulary
| # | primitive | anchor | dismissal | SSR-clean | use case |
|---|---|---|---|---|---|
| 17 | Tooltip | anchor | casual | no | label-on-hover · keyboard-revealable |
| 18 | Popover | anchor | casual | no | click-anchored panel · arbitrary content |
| 19 | Dropdown | anchor | casual | no | select-style menu · keyboard nav · typeahead |
| 20 | Dialog | viewport | casual | no | modal panel · backdrop · scroll-lock |
| 21 | ToastProvider | edge | manual | no | live region · auto-dismiss by timer |
| 67 | Sheet | edge (top/bottom) | casual | no | mobile bottom-sheet · settings · file detail |
| 68 | Drawer | edge (left/right) | casual or manual (persistent) | no | desktop side-rail · contextual operator detail |
| 69 | Accordion | inline | n/a | yes | sibling-grouped collapsible · settings · FAQ |
| 70 | ContextMenu | anchor (cursor) | casual | no | right-click verbs · chart cell · row actions |
| 71 | AlertDialog | viewport | committed | no | destructive confirm · refuse posture · forced choice |
why ten, not five or twenty
five was incomplete (no mobile sheet, no desktop drawer, no collapsible group, no right-click verbs, no committed confirm). twenty would duplicate (every component library that ships twenty overlays has three flavours of "modal" and four flavours of "menu"). ten covers every consumer surface in cockpit · league · coliseum · studio · the future getzero.dev, and every primitive maps cleanly to one of three anchors and one of three dismissals.as of
02 · the five newSheet · Drawer · Accordion · ContextMenu · AlertDialogthe five primitives ADR-025 lands
tone
every overlay carries the dark-only substrate, the amber focus ring, and the bone-on-ink hierarchy. nothing inverts when an overlay opens; the user's eye does not re-acclimate.
palette
amber stays under the 7% surface ceiling even with an overlay open. AlertDialog tone='refuse'is the only overlay that paints with amber as a hairline, and even there it's a one-pixel border, not a fill.
cadence
slide-in animations resolve in 220 ms via the four-clock organism's --ease-step. the refuse variant uses --ease-refuse — a slight backstep on entry that earns its own visual weight without flashbang attention.
| primitive | num | cls | headline tokens | states |
|---|---|---|---|---|
Sheet | 67 | .zero-sheet | --ink-1 · --bone-1 · --hair-3 · --radius · --ease-step | closed · opening · open · closing |
Drawer | 68 | .zero-drawer | --ink-1 · --bone-1 · --hair-3 · --shadow-4 · --ease-step | closed · opening · open · closing · persistent |
Accordion | 69 | .zero-accordion | --ink-1 · --bone-1 · --hair-2 · --s-3 · --s-5 | idle · open · disabled |
ContextMenu | 70 | .zero-context-menu | --ink-1 · --bone-1 · --bone-3 · --hair-2 · --amber | closed · open · item-hover · item-active · item-refuse |
AlertDialog | 71 | .zero-alert-dialog | --ink-1 · --ink-2 · --amber · --shadow-4 · --ease-refuse | closed · open · tone-normal · tone-refuse |
as of
03 · anchoring grammarviewport · edge · anchorthree ways an overlay attaches to the surface
| anchor | position | backdrop | example |
|---|---|---|---|
viewport | centered · full screen reach | full · scroll-locked | Dialog · AlertDialog |
edge | pinned to one of top | bottom | left | right | full (default) · or none (persistent: true) | Sheet · Drawer · Toast |
anchor | relative to a trigger element or cursor | none · click-outside dismisses | Tooltip · Popover · Dropdown · ContextMenu |
why three anchors, not five
we considered portal-fixed (toast-style, but configurable) and inline-popover (popover that flows in document order). both collapsed cleanly into the three above. fewer anchors means fewer permutations the covenant detector has to grep, and one consistent positioning model across the catalog.as of
04 · dismissal grammarcasual · committed · manualthree ways an overlay closes
| mode | escape dismisses | outside-press dismisses | used by |
|---|---|---|---|
casual | yes | yes | Tooltip · Popover · Dropdown · Dialog · Sheet · Drawer · ContextMenu |
committed | no | no | AlertDialog (forces explicit confirm/cancel) |
manual | no | no | Toast (timer-driven) · Drawer (persistent: true) |
committed dismissal is brand-grade
when you want the user to confirm a destructive action, you must reach for AlertDialog, not Dialog. the typing guides you: Dialog has no tone='refuse'; AlertDialog has no dismissal='casual'. the system will not let you ship an outside-press-dismissable demolition confirm.as of
05 · refuse postureAlertDialog tone='refuse'the brand-verb overlay
| aspect | tone='normal' | tone='refuse' |
|---|---|---|
| background | --ink-1 | --ink-2 (one step deeper) |
| bottom edge | 1 px --hair-3 | 1 px --amber (the only amber paint) |
| confirm label default | confirm | refuse (the brand verb · article I) |
| slide-in easing | --ease-step | --ease-refuse (slight backstep on entry) |
| covenant rule | — | #14 · brand verb consistency · enforced by ci:rewrite |
why the refuse variant exists
article I of the constitution says we refuse loudly, deterministically, and on cue. the primitive shape now matches the verb shape. when an external coding agent assembles a demolition flow from @zero/ui, it inherits the refuse posture by typing — not by reading prose. the brand system does the work once; every consumer gets it for free.