Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): define local stacking and top-layer routing (#6067)

Cindy Zhanga9f6cf4a8ad8
diff --git a/docs/specs/AST-027/spec.md b/docs/specs/AST-027/spec.md
new file mode 100644
index 0000000000..57fbf89384
--- /dev/null
+++ b/docs/specs/AST-027/spec.md
@@ -0,0 +1,285 @@
+---
+schema_version: 1
+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
+
+## 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`](../../architecture/layer-runtime.md).
+
+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: isolate` on 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: isolate` for 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-index` value 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: isolate` owner 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-index` values
+ 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`](../../architecture/layer-runtime.md). A local
+ component MUST NOT recreate that system with positioned DOM and page-level
+ `z-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-runtime` and
+ [AST-003](../AST-003/spec.md). 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-index` in 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: isolate` defines local stacking in
+ every browser supported by Astryx. Floating-surface support follows the matrix
+ and reduced fallback in `architecture: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, BottomSheetSwitcher, and Lab Drawer 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, 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,
+BottomSheetSwitcher, and Drawer 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-runtime` plus 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.