An open source design system that's fully customizable and agent ready
schema_version: 4 template_version: 1 kind: system-spec id: spec:AST-027 authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-09-04 phase: accepted owners: [cixzhang, imdreamrunner] affects_architecture: [architecture:layer-runtime] affects_families: [family:input-fields, family:layout-regions, family:overlay-dismissal] affects_contributing: [] affects_consumer_docs: []
Local stacking and browser top-layer routing system spec
{
"scope": "global",
"triggers": {
"layering": ["DEC-1", "DEC-2", "DEC-3", "DEC-4", "FR11"]
}
}
Intent
An Astryx component should be able to order its own painted parts without
changing how unrelated components, page content, or application chrome stack.
Menus, dialogs, and other floating interaction surfaces should escape ordinary
document stacking through Astryx's Layer system and the browser top layer, not
through larger z-index values.
This spec separates two mechanisms:
- local stacking orders parts inside one component-owned surface; and
- top-layer routing hosts floating interaction surfaces through
architecture:layer-runtime.
A local number never becomes a claim on the whole page.
Non-goals
- Define shadows, borders, or perceived elevation. Those remain visual-design concerns.
- Create a global numeric z-index scale or semantic page-wide z-index tokens.
- Change which interaction dismisses a menu, dialog, popover, or other overlay.
- Require
isolation: isolateon components that have no local paint-order relationship. - Treat a React portal as equivalent to browser top-layer promotion.
Terms
- Local layer: a positioned or stacking-context descendant whose paint order is meaningful only inside one component-owned surface.
- Isolation owner: the component-owned element that establishes
isolation: isolatefor one local stacking relationship. - Surface owner: the element that paints or directly owns the component surface whose parts are being ordered, including its background, border, clipping, or elevation boundary.
- Floating interaction surface: a menu, dialog, popover, tooltip, hover card, sheet, command surface, or similar UI that must escape ordinary content or clipping to perform its interaction role.
- Browser top layer: the platform stacking plane entered through native
mechanisms such as the Popover API or modal
<dialog>.
Requirements
Local stacking
- FR1 — z-index is local only. A
z-indexvalue in Astryx MUST order parts within one component-owned stacking relationship. It MUST NOT establish an ordering contract against unrelated components, application content, AppShell chrome, or another page region. - FR2 — The surface owns the isolation boundary. Every local stacking
relationship MUST have an
isolation: isolateowner on the component surface that contains the relationship. The isolation boundary MUST live on the surface owner rather than an arbitrary page wrapper or distant ancestor. - FR3 — The isolation owner does not escalate itself. The outer isolation
owner MUST remain at its normal parent paint level. Local
z-indexvalues belong to descendants inside that owner. If a nested surface must be ordered inside a larger component, that larger component supplies another local isolation owner. - FR4 — Local values have no system-wide rank. Values such as
-1,0,1,2, or a dynamic local depth MAY express a relationship inside an isolation owner. The same value MAY mean something different in another component. Astryx MUST NOT document or depend on page-wide bands such as “inputs at 1,” “sticky content at 10,” or “overlays at 1000.” - FR5 — Fix the leaking owner, not the unrelated neighbor. When a component part paints above unrelated UI, the fix MUST contain that part at its component-owned surface. Raising the unrelated header, shell, or neighbor to a larger value is not a conforming fix.
- FR6 — Every local state stays contained. Hover, focus, validation, drag, sticky, selected, resized, animated, and negative-layer states MUST remain inside the same isolation boundary. A state change MUST NOT promote the component surface into a page-level stacking competitor.
Floating interaction surfaces
- FR7 — Floating interactions use the Layer system. Menus, dialogs,
popovers, tooltips, hover cards, sheets, command surfaces, and equivalent
floating interactions MUST use the hosting and promotion mechanisms owned by
architecture:layer-runtime. A local component MUST NOT recreate that system with positioned DOM and page-levelz-index. - FR8 — Browser promotion owns cross-surface order. A floating interaction that must escape ordinary content or clipping MUST enter the browser top layer through the applicable Layer/native host. A body portal, a fixed position, or a larger number is not a substitute.
- FR9 — Numeric values inside a top-layer host remain local. A promoted surface MAY use locally isolated z-index values to order its own backdrop, panel, arrow, controls, or animation plates. Those values MUST NOT be treated as the reason the surface appears above page content or another native host.
- FR10 — Existing Layer support boundaries remain authoritative. Native
Popover and modal-dialog behavior, corrective portals, anchored positioning,
reduced browser fallback, and global-host admission continue to follow
architecture:layer-runtimeand AST-003. This spec does not authorize a component to bypass those contracts when native support is unavailable. - FR11 — In-flow UI remains in flow. A label, status message, banner, sticky page region, focus ring, or other in-flow presentation does not become a floating interaction merely because it needs local paint ordering. It follows FR1–FR6 unless its owning contract explicitly assigns it to Layer.
Implementation requirements
- IR1 — Every shipped z-index is classified. Before this spec ships,
every production
z-indexin published package source and CLI-emitted template source MUST be classified as a contained local relationship, a local relationship inside a Layer/native top-layer host, or a migration gap. Unclassified values fail the migration. - IR2 — New leaks fail mechanically. Repository checks MUST reject a new local z-index relationship that has no component-owned isolation surface. The check MAY use source metadata or a narrow allowlist for relationships whose owner cannot be derived statically, but an allowlist entry MUST name its owner and verification.
- IR3 — Layer bypasses fail mechanically. Repository checks MUST reject a new menu, dialog, popover, tooltip, hover card, sheet, command surface, or equivalent overlay that uses page-level z-index instead of the shared Layer or native top-layer path.
- IR4 — Migrations remove obsolete bands. When a surface is contained or moved into the top layer, obsolete page-wide z-index comments, constants, tokens, tests, and compensating neighbor values MUST be removed in the same change.
Platform support
- Supported feature/engine floor:
isolation: isolatedefines local stacking in every browser supported by Astryx. Floating-surface support follows the matrix and reduced fallback inarchitecture:layer-runtime. - Unsupported behavior: a browser below the native Layer feature floor receives the documented reduced fallback. It MUST NOT receive an undocumented global z-index ladder as an attempted top-layer polyfill.
- Browser evidence: local containment requires real-browser paint and hit-test
evidence. Popover, modal-dialog, focus/inertness, and top-layer ordering require
the real-browser matrix named by
architecture:layer-runtime; Playwright WebKit does not substitute for Safari-specific evidence.
Current-state impact
The repository already contains good examples of the intended local pattern:
Thumbnail, Calendar, ChatComposer, ChatLayout, CodeBlock, CheckboxInput,
RadioList, Switch, Slider, Field's attached-status wrapper, and the touch
DateInput panel place internal z-index relationships beneath a local
isolation: isolate owner. They are migration references, not blanket proof
that every descendant is correct.
The source audit covered published package source and CLI-emitted template source:
packages/{core,lab,charts,richtext}/src and
packages/cli/assets/templates, excluding tests and stories. It found 56
production declarations across 40 files and these current gaps:
| Surface | Current mechanism | Impact under this spec | Required migration or proof |
|---|---|---|---|
| Shared Field input wrappers, including TextInput, FileInput, TextArea, NumberInput, and RichTextEditor | inputWrapperStyles.base places the painted input surface itself at z-index: 1; only the attached-status composition adds an isolated wrapper; RichTextEditor also places its status icon at local 1 inside the unisolated surface |
Confirmed leak. Detached and tooltip Field compositions compete directly with AppShell and later page content | Put isolation on the Field-owned surface for every variant, keep wrapper and status-icon layers beneath it, and remove the painted input surface's external rank |
| Production docsite component pages | A live Chromium probe on /components/TextInput found a rendered input and the sticky AppShell header both at z-index: 1 with isolation: auto; after the input was scrolled into the header, it won browser hit-testing |
Confirmed user-facing leak. A real component example covers navigation on the production route | Preserve that route and overlapping-control relationship as a Chromium regression fixture; prove the contained field passes below unrelated sticky chrome |
| AppShell header and skip link | The sticky header uses 1, the focused skip link uses 9999, and the shell root is not isolated; only transparent content establishes a local isolation boundary |
Confirmed page-level coupling. AppShell exposes numeric bands for ordinary shell parts | Isolate the AppShell-owned surface and use only local depths inside it; the skip link remains local AppShell content rather than a reusable global band |
| ChatComposerDrawer and ChatDictationButton | The separately exported drawer root and dictation bars use z-index: 1 without owning isolation; placement inside ChatComposer is only a consumer convention |
Confirmed implicit-containment gaps. Either export can be composed outside ChatComposer's isolated root | Give each exported part a component-owned isolation surface and keep its internal ordering local; do not rely on a consumer ancestor |
| InputGroup focus ordering | A focused connected child uses z-index: 1; InputGroup composes Field through the detached path |
Confirmed leak. Focus ordering can escape the group | Isolate the complete painted group owner and verify connected-border focus ordering against neighboring components |
| SideNav sticky content | The sticky top region uses z-index: 1; the SideNav root is not isolated |
Confirmed leak. Sticky navigation internals can compete with siblings | Add isolation to the SideNav surface; collapsed menus continue to use Popover/Layer |
| Outline active indicator | The positioned indicator uses z-index: 1 beneath an unisolated root |
Confirmed leak. The visual indicator can compete outside Outline | Isolate the Outline root and keep the indicator relationship local |
| Table sticky columns and resize handle | Sticky header/body cells use 3 and 1, the row overlay uses -1, and the resize handle uses 1; TableScrollWrapper is not isolated |
Confirmed leak. Table internals can meet unrelated shell content | Isolate TableScrollWrapper; retain header/body/overlay/resize ordering beneath it and verify sticky states under shell chrome |
| Resizable handles and local overlays | Overlay root, hit area, and pill use 1 and 2; no resized surface owner is isolated |
Confirmed leak. Resize affordances can escape their region | Isolate each resized panel or region owner, not only the handle descendant; verify drag and focus states against adjacent content |
| Lab Schedule and ChartZoom overlays | Schedule uses 1, dynamic event levels, and 20; ChartZoom uses 1; neither painted root is isolated |
Confirmed leaks. Visualization internals create page-level ranks | Isolate the Schedule and Chart painted roots; Chart also establishes the containing block required by its absolute toolbar |
| ChartTooltip | The published Charts package renders the tooltip with position: fixed and z-index: 9999 instead of Layer |
Confirmed Layer bypass and page-level leak. It uses exactly the substitute prohibited by FR7–FR8 | Route ChartTooltip through Layer's fixed mode and the browser top layer; keep tooltip-internal ordering inside its surface |
| Lab ListInput and TransferList reorder indicators | Shared reorder styles use z-index: 2; ListInput's detached Field path is unisolated, while TransferList relies incidentally on container-type |
Confirmed gap for ListInput; implicit containment for TransferList is not the explicit contract | Add explicit isolation to both painted owners and verify reorder hit-testing in Chromium |
| CLI-emitted page templates | Dashboard alert rail and Settings dialog use local 1; Table filter uses reorder 2; Kanban renders a fixed drag clone at 1000 |
Generated leaks. New consumer apps inherit implicit local boundaries and, for Kanban, a page-level floating band | Add explicit surface isolation to local template relationships; route the Kanban drag clone through a visual-only Layer/top-layer host |
| Popover, Lightbox, and modal panel internals | Small values order arrows, controls, handles, panels, and tints inside native Popover or dialog hosts | Correct cross-page mechanism; local ownership still requires proof. The browser host, not the number, places the surface above page content | Preserve top-layer hosting and add or identify an explicit isolation owner for each internal relationship |
| ToastViewport | The viewport enters popover="manual" but also carries z-index: 500 |
Redundant page-band value plus the AST-003 hosting gap. Native promotion, not 500, owns page-content order; current Toast can still sit behind a later modal |
Complete AST-003's global host first or in the same change, then remove 500 and keep any internal ordering beneath an isolated viewport surface |
| BottomSheet and BottomSheetSwitcher non-modal paths | Non-modal dialog.show() paths use static or dynamic values beginning at 1000 |
Confirmed global leaks. A page band cannot provide dialog-layer semantics | Route non-modal hosting through Layer/native top-layer infrastructure; keep panel, handle, tint, action, and stack ordering locally isolated inside the host |
Current source already routes Tooltip, HoverCard, Popover, DropdownMenu and its
submenus, ContextMenu, CommandPalette, modal Dialog, Drawer, Lightbox,
MobileNav, Tour, Date-input layers, and RadialTooltip through Layer, native
Popover, or showModal(). Their cross-page mechanism is directionally
conforming. The confirmed exceptions are ChartTooltip and the non-modal
BottomSheet and BottomSheetSwitcher paths. Toast is promoted but still has the
global-host limitation already owned by AST-003.
This table is an impact inventory, not an implementation approval. Each row still requires its named browser evidence before migration lands. The exhaustive IR1 audit may add rows; a row may be cleared only with named ownership and evidence.
Verification
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1–FR6 | Source classification plus real Chromium paint/hit-test matrix | positive, zero, negative, sticky, focused, dragged, selected, and animated local layers | Removing the isolation owner lets a descendant cover an unrelated sibling; changing a local value never changes page-level order |
| FR2, FR3 | DOM ownership and computed-style assertions | painted surface root, nested local surface, transparent surface, consumer wrapper | Isolation appears on a distant page ancestor, or the isolation owner itself competes through a page-level z-index |
| FR5 | Before/after regression fixtures | docsite Field under sticky AppShell header; Table under shell chrome | A neighbor must be raised to make the fixture pass, or the leaking surface still wins hit-testing |
| FR7–FR10 | Layer unit tests and real browser top-layer matrix | menu, submenu, dialog, popover, tooltip, hover card, sheet, CommandPalette, Toast | Positioned DOM or a body portal replaces Layer, or a numeric band determines cross-surface order |
| FR11 | Component and browser tests | label/status overlap, sticky region, focus ring, banner | In-flow UI is unnecessarily promoted, or its local paint state escapes its surface |
| IR1 | Generated shipped z-index inventory checked in CI | every published package and emitted template declaration | A declaration is missing, duplicated, or has no owner/classification |
| IR2, IR3 | Static-rule fixtures with valid and invalid examples | isolated local component, leaking field, hand-built menu, native Layer surface | A leak or Layer bypass passes, or a valid isolated relationship is rejected |
| IR4 | Changed-file and source scans | migrated Field, AppShell, Table, Toast, BottomSheet, Drawer | Obsolete bands, comments, tests, or compensating values remain after migration |
Completion criteria
This spec moves to shipped only when:
- every z-index in published package source and CLI-emitted template source has an owner and classification;
- every ordinary local relationship is contained by its component-owned painted surface;
- the real docsite Field/AppShell failure is reproduced before the fix and passes through local containment afterward;
- menus, dialogs, popovers, tooltips, hover cards, sheets, command surfaces, and equivalent overlays use the Layer/native top-layer path;
- numeric bands no longer determine cross-component, page-shell, or overlay order;
- mechanical checks reject a representative local leak and Layer bypass;
- the browser matrices for local containment and Layer hosting pass; and
architecture:layer-runtimeplus affected family/component records describe the shipped ownership without relying on this impact inventory.
Decision log
DEC-1 — z-index expresses local relationships only
Reference: spec:AST-027/DEC-1
Decider: cixzhang, 2026-09-04
A z-index value belongs to one component-owned stacking relationship. Reusing a number elsewhere creates no relationship between the components.
Rejected: a global scale that ranks inputs, sticky navigation, page chrome, and overlays against one another. That scale turns every local change into a page-wide compatibility problem.
DEC-2 — Isolation lives on the component surface
Reference: spec:AST-027/DEC-2
Decider: cixzhang, 2026-09-04
The element that owns the painted surface also establishes isolation: isolate.
Descendant z-index values can then order that surface's parts without escaping to
unrelated content.
Rejected: placing isolation on an arbitrary page wrapper or raising the surface root itself. Both preserve hidden coupling between the component and its caller.
DEC-3 — Floating interactions use the browser top layer through Layer
Reference: spec:AST-027/DEC-3
Decider: cixzhang, 2026-09-04
Menus, dialogs, and equivalent floating interactions route through Astryx's Layer system and applicable native top-layer host. Their cross-surface order comes from the browser host and Layer contract, not a number.
Rejected: fixed positioning, a body portal, or a large z-index as a substitute for Layer. These mechanisms do not provide native top-layer, modal, association, positioning, or dismissal behavior.
DEC-4 — Leaks are repaired at their owner
Reference: spec:AST-027/DEC-4
Decider: cixzhang, 2026-09-04
When a Field or another component covers unrelated shell chrome, contain the component at its own surface. Do not raise AppShell or add another global band.
Rejected: escalating the AppShell header to a larger page-level value. It can pass a known comparison only by outranking today's values and leaves the next larger value to recreate the same defect.
Open questions
None.