An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:Overlay authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-22 owners: [cixzhang] review_triggers: [public-api, layout, accessibility] verified_by: [ packages/core/src/Overlay/Overlay.test.tsx, apps/storybook/stories/Overlay.stories.tsx, apps/storybook/rtl-audit/targets.json, ] modules: [] families: [] design_specs: [design:bidirectionality] architecture: [ architecture:public-component-api, architecture:component-theming-surface, architecture:internationalization, ] contributing: []
system_specs: [spec:AST-002/DEC-1, spec:AST-017/FR5, spec:AST-027/FR2]
Overlay component contract
This record governs how several pieces of content are placed over an Overlay's
surface, each at a preset spot or at fractional coordinates, including the
stacking of a container that holds such content. Overlay's scrim, reveal modes,
own position values, and alignment remain described by its source, tests, and
Overlay.doc.mjs until a record claims them.
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | New OverlayRegion component, exported beside Overlay: position (required) is a preset ('fill' | 'top' | 'bottom' | 'center' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end') or open placement {x, y, width?, height?} in 0–1 fractions; plus children, ref, xstyle, className, style. |
| Behavior | Inside a fill Overlay, a preset region sits at that spot (corners follow the writing direction) and open placement sits at fractions of the media measured from its top-left corner, never mirrored. A sized open region stays inside the media. Regions scale with the media. |
| End-user impact | Several captions, tags, badges, or hotspots over one image or video each stay on their spot of the media at every size, in either text direction. |
| Builder impact | None by default. A builder places content with OverlayRegion instead of hand-written absolute positioning; moving a region stays the builder's code. |
| Compatibility/readiness | Additive: a new component and export; an Overlay without a region renders and stacks exactly as before. This record is current authority; OverlayRegion, its consumer docs, region tests, and region stories have not shipped yet. |
| Review checks | Reject open placement that mirrors in right-to-left, corner presets that do not, JavaScript measurement or observers, drag or resize behavior inside Overlay, a role or focus stop on the region, a theme target on it, or a region placed inside a strip. |
| Governing rules | FR1–FR11 below; design:bidirectionality/DR3, DR5, DR6; architecture:component-theming-surface/INV4; spec:AST-017/FR5; spec:AST-027/FR2. |
This table is a review projection; the body below is authoritative.
Intent
Overlay layers content over a bounded surface, usually media, and places that content as one block: the whole surface or a band at the top or bottom. Some surfaces carry several pieces of content, each belonging to its own spot: two captions drawn into an image, a badge in a corner beside a caption, a tag on a face. A spot is either one of Overlay's familiar places or a point on the media described as fractions of its width and height, because the media is shown at many sizes and the spot must stay on the same pixels of it. Overlay owns that placement because Overlay owns the surface it is measured against.
Compatibility and migration
- Released default preserved:
yes; an Overlay without a region renders and stacks exactly as before. Only a container that holds a region isolates its stacking (FR10). - Compatibility class: additive component and export.
- Controlled/uncontrolled behavior: not applicable; a region holds no state.
- Migration decision: none required (
spec:AST-017/FR5).
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
OverlayRegion: itspositionvalues, their geometry, clamping, scaling, and reference box.- The rule that open placement is measured in the media's own physical space.
- The rule that regions are placed only in fill overlays, and the fallback everywhere else.
- The stacking isolation of a container that holds a region.
Does not own / non-goals
- Moving, dragging, or resizing a region, including pointer capture, keyboard
steps, snapping, and when a new position is reported — owned by the product
callsite (
component:Overlay/DEC-3). - What a region paints: borders, fills, handles, and text — owned by the region's content.
- Making the base content fill the surface — owned by the caller, as for every Overlay; fractions are measured against the surface, so media that does not fill it does not line up with them.
- Overlay's own
positionandalign— unchanged; a region does not read or alter them beyond FR2. - Placement relative to a trigger or outside the surface — owned by the layer runtime (Popover, Tooltip, HoverCard).
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Preset | fill, top, bottom, center, top-start, top-end, bottom-start, bottom-end |
fill, top, and bottom are the places Overlay's own position names: the whole surface, or a full-width band at that edge. center and the corners hold content-sized boxes at that spot. |
Fill overlays (FR2) | None; required prop | component:Overlay |
stable | Other strings are rejected by the public type |
| Open placement | {x, y, width?, height?}; each a number from 0 to 1 |
x, y: the region's top-left corner as fractions of its reference box, measured from that box's top-left corner. width, height: the region's size as fractions, extending right and down; omitted means it fits its content. |
Fill overlays (FR2) | None; required prop | component:Overlay |
stable | Values clamped into 0–1; a non-finite coordinate is treated as 0 and a non-finite size as omitted (FR6) |
Behavioral and layout contract
| ID | Invariant | Basis | Draft review state |
|---|---|---|---|
| FR1 | OverlayRegion rendered directly in the content of an Overlay or useOverlay host with position="fill", the default, MUST position against that host's scrim box, which is the whole base surface: 0 and 1 are the media's edges, and the box matches the Overlay's ref. Any element between the region and the scrim that establishes a containing block for absolutely positioned descendants becomes its reference box instead. In this record, the surface means the region's reference box. |
component:Overlay/DEC-1 |
settled |
| FR2 | Regions are placed only in fill hosts. A region rendered anywhere else MUST NOT be placed: in the content of an Overlay or useOverlay host whose position is "top" or "bottom", in an Overlay's children, or with no Overlay or useOverlay host at all, it renders its content as ordinary in-flow content where it stands (in a strip, that content reveals and slides with the strip) and MUST emit one development warning per mount naming the fill-only rule. |
component:Overlay/DEC-4 |
settled |
| FR3 | A preset region MUST sit at its spot inside Overlay's content inset: fill covers the inset box; top and bottom span its full width at that edge with content height; center is content-sized at its center; each corner is content-sized at that corner. Content larger than the inset box is clipped by the container, not shifted. |
component:Overlay/DEC-2 |
settled |
| FR4 | Corner presets MUST resolve start and end against the writing direction of the region's own context: top-start is the top-left corner in left-to-right and the top-right corner in right-to-left. fill, top, bottom, and center are symmetric and do not change with direction. |
design:bidirectionality/DR3 |
settled |
| FR5 | Open placement MUST measure x from the surface's left edge and y from its top edge in every writing direction, and MUST NOT mirror in right-to-left. The region's own content follows the ambient direction. |
design:bidirectionality/DR5 |
settled |
| FR6 | Open coordinates and sizes MUST be clamped into 0–1 before placement. A non-finite coordinate MUST resolve to 0, and a non-finite size MUST resolve to omitted. | Invalid-value behavior | settled |
| FR7 | Open placement puts the region's top-left corner at (x, y) (component:Overlay/DEC-6). On an axis with a size, the region MUST be exactly that fraction of the surface, extending right or down, and MUST sit wholly inside it: its start is clamped between 0 and one minus the size. On an axis without a size, the region MUST fit its content starting at the coordinate, and any overhang past the container's edge is clipped, not shifted inward. |
component:Overlay/DEC-5 |
settled |
| FR8 | When the surface changes size, every region MUST keep its spot: presets by their insets, open placement by its fractional position and size, without a re-render. | component:Overlay/DEC-1 |
settled |
| FR9 | A region MUST appear, hide, and become inert with the overlay content that contains it, following Overlay's showOn and isOpen, and MUST inherit the scrim's media theme. It adds no visibility rule of its own. |
Overlay's existing reveal behavior | settled |
| FR10 | A placed region MUST paint above the fill surface's in-flow overlay content, including positioned in-flow content written after it, and a later placed region MUST paint above an earlier one. A placed region inside a wrapper that forms a stacking context is ordered only among that wrapper's content. An Overlay or useOverlay container with a placed region anywhere inside it MUST own an isolated stacking context; a container with no region inside it keeps its stacking unchanged. A placed region MUST NOT take part in the scrim's flow layout. |
Absolute positioning within the surface; spec:AST-027/FR2 |
settled |
| FR11 | Overlay and OverlayRegion MUST NOT move, drag, or resize a region, and MUST NOT attach pointer, keyboard, or gesture handlers to it. A region moves only when its caller passes a new position. |
component:Overlay/DEC-3 |
settled |
Allowed variation
- AV1 — Content. Any content may sit in a region; on an open region each axis is sized or content-sized independently (FR7).
- AV2 — Surface size and shape. The surface may be any size or aspect ratio, and may change size at any time (FR8).
- AV3 — Mixed content. In-flow overlay content, preset regions, and open regions may share one surface (FR10).
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
Two captions, top and bottom presets |
Each spans the inset width at its edge, like Overlay's own strips. | Caption text. |
top-start badge, left-to-right and right-to-left |
Top-left corner in left-to-right; top-right corner in right-to-left. | Badge content. |
| Open sized caption near the right edge | Box is the given fraction of the image and stays wholly inside, flush with that edge. | Which edge. |
| Open content-sized pin | Pin starts at its point and extends right and down; overhang past the container is clipped. | Pin content. |
| Open region, right-to-left page | Same spot on the media as left-to-right; the region's text reads right-to-left. | Writing direction. |
| Surface resized from 640px to 320px wide | Every region keeps its spot, with no re-render. | Any surface size. |
Region in an Overlay's children or outside any Overlay |
Is not placed: its content flows where it stands, and it warns once in development. | Location. |
Region in a position="bottom" Overlay |
Is not placed: its content flows in the strip like other strip content, and it warns once in development. | Strip content. |
showOn="hover" overlay at rest |
Regions are hidden with the rest of the overlay content. | Reveal mode. |
Transformation and precedence order
- ORD1 — Placement. Resolve the reference box (FR1, FR2) → for a preset,
place it in the content inset and resolve start/end against direction (FR3,
FR4); for open placement, clamp values (FR6) and resolve each axis as sized or
content-sized in physical space (FR5, FR7) → express the result as insets and
fractions of the box (FR8). Styling inputs compose after placement in the order
architecture:public-component-api/INV6gives; a caller who overrides inset or size properties owns the result.
Performance and resources
- PR1 — CSS geometry only. Placement, clamping, and scaling MUST be achieved with arithmetic on the given values and CSS: no measurement, observer, listener, state, Effect, or extra render pass. The fill-only check adds no measurement, state, or extra render pass.
Accessibility contract
- AR1 — Presentation only.
OverlayRegionMUST add no role, accessible name, description, focus stop, or text. Its content keeps its own semantics. - AR2 — Source order is reading order. Assistive technology and keyboard focus follow the regions' source order, not their position on the surface. A caller renders regions in the order a reader should meet them.
- AR3 — Movement offers non-drag paths. Overlay's documented move pattern
for open regions pairs pointer dragging with a single-pointer path that needs
no drag, where activating a spot on the media moves the region there, and a
keyboard path that moves a region whose content has focus by a fixed step per
arrow key, with arrow directions matching the visual axes
(
design:bidirectionality/DR6).
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Preset region | Reads as Overlay's own places, with Overlay's content inset. | Owner direction | Supporting | FR3 |
| Corner preset in RTL | Leading and trailing corners follow reading order. | design:bidirectionality/DR3 |
Supporting | FR4 |
| Open region | Stays on the same spot of the media at every size. | Owner direction | Supporting | FR7, FR8 |
| Open region in RTL | Media is physical content and does not mirror. | design:bidirectionality/DR5 |
Supporting | FR5 |
Family and system relationships
design:bidirectionalityowns direction behavior: FR4 applies DR3 to corner presets, FR5 applies DR5 to open placement, and AR3 applies DR6 to movement.architecture:component-theming-surface/INV4keeps a non-painting box out of the theme surface: the region is a geometry-only box that paints nothing, so it has no theme target and its content owns its paint.architecture:public-component-apiowns prop admission and styling-input order; ORD1 applies INV6.spec:AST-027/FR2puts the isolation boundary on the surface; FR10 makes the Overlay oruseOverlaycontainer that holds a region that owner.spec:AST-017/FR5classifies this as nonbreaking: it adds a new component, changes no default, and a caller who never renders a region sees no change.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR2, FR6, FR11 | Overlay.test.tsx region suite |
Region in Overlay and useOverlay content; in a bottom Overlay; outside any Overlay; out-of-range and non-finite input; pointer and key events |
Unclamped values, a region outside the scrim, a placed region in a strip or a missing warning, or a region that moves on its own fails. | audit:Overlay/api |
| FR3, FR4, FR5, FR7, FR8, FR10 | Real-Chromium assertions in the Overlay region story's play function | Every preset; open sized, edge-clamped, and content-sized; resized surface; RTL; a region before a positioned control | A region off its spot by more than 0.5px, a corner that does not flip or an open region that does, the in-flow control hit at a region's center, or wrong isolation, fails. | audit:Overlay/layout |
| FR9 | Overlay.test.tsx reveal case with a region |
isOpen={false} |
A region outside the scrim, or a closed scrim that is not inert, fails. | audit:Overlay/api |
| AR1, AR2 | Overlay.test.tsx DOM check of the region element |
Text content | Any attribute other than class and style on the region element, or text it adds, fails. |
audit:Overlay/a11y |
| AR3 | Region move story's play function | Arrow key and single activation on the media, LTR and RTL | ArrowRight moving a region left, or an activation that does not move the region to the activated spot, fails. | audit:Overlay/a11y |
| PR1 | Source review of OverlayRegion |
All inputs | A ref read, observer, listener, or Effect added for placement fails review. | audit:Overlay/layout |
| RTL relation | RTL audit curated D4 target (apps/storybook/rtl-audit/targets.json) on Overlay / Bottom strip |
Start-aligned scrim content; LTR and RTL | Start-aligned content that does not move to the mirrored side of its container in RTL fails D4. | audit:Overlay/i18n-rtl |
Decision log
DEC-1 — Several placed items are Overlay regions with one position prop
Reference: component:Overlay/DEC-1
Decider: cixzhang, 2026-10-22
Overlay places one content block, so a surface with several spots needs a child
that places itself. OverlayRegion inside Overlay's content inherits Overlay's
surface, reveal, and media theme with no new Overlay prop, and one position
prop covers both kinds of spot: a named place or open placement. Sizes live
inside the open placement object, so a region never carries width or height
props whose numbers mean fractions while the same names mean pixels on Card,
Button, and Grid.
Rejected: an object form of Overlay's own position, because it still places
only one block.
DEC-2 — Presets reuse Overlay's places and add the center and corners
Reference: component:Overlay/DEC-2
Decider: cixzhang, 2026-10-22
fill, top, and bottom mean on a region what they mean on Overlay, so a
builder reads one vocabulary. Static badges and labels need the center and the
corners, which Overlay's single block cannot hold beside other content. Corners
use start and end because a leading badge leads in either direction.
DEC-3 — Moving a region stays at the callsite
Reference: component:Overlay/DEC-3
Decider: cixzhang, 2026-10-22
What moving a region means differs by product: whether the position commits on release or live, the keyboard step, snapping, which regions move, and what happens while a new rendering of the media loads. Overlay therefore never moves a region; the caller converts pointer and keyboard input into new fractions measured against the region's reference box and passes them back.
Rejected: a drag hook on Overlay, because a shared drag primitive needs its own record and more than one caller's needs.
DEC-4 — Regions belong to fill overlays
Reference: component:Overlay/DEC-4
Decider: cixzhang, 2026-10-22
A spot on the media is meaningless inside a strip whose height follows its own
content and which slides in and out. A strip is also the containing block of
everything inside it, so CSS cannot place a region against the media from
there. In a strip overlay a region therefore renders its content as ordinary
strip content and warns in development, so the content stays visible. The
public type cannot enforce the rule, because regions arrive through content.
The same fallback applies outside any fill host, where there is no surface to
measure against and nothing to isolate a region's paint order.
Rejected: placing a strip's regions against the container, because escaping the strip needs a second rendering layer that duplicates Overlay's reveal.
DEC-5 — Open sized axes are clamped inside; content-sized axes are not
Reference: component:Overlay/DEC-5
Decider: cixzhang, 2026-10-22
A sized region can be kept inside the surface with arithmetic on the given fractions, so it never spills off the media however far it is moved. Keeping a content-sized region inside would require measuring it, which PR1 forbids, so the container clips any overhang.
DEC-6 — Open placement names the region's top-left corner
Reference: component:Overlay/DEC-6
Decider: cixzhang, 2026-10-22
x and y are the region's top-left corner, and width and height extend
right and down. That matches how servers and editors report boxes (left, top,
width, height) and how CSS insets read, so a reported box passes through with no
conversion and is clamped with plain arithmetic.
Rejected: the region's center, because every reported box would need converting.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.