An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): promote component:BottomSheet and component:BottomSheetSwitcher to current (#7822)
Xinzi Zhou3133fb04b9a2
diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.mdindex eca0274187..175e227be7 100644--- a/packages/core/src/BottomSheet/BottomSheet.spec.md+++ b/packages/core/src/BottomSheet/BottomSheet.spec.md@@ -3,11 +3,11 @@ schema_version: 3template_version: 3kind: componentid: component:BottomSheet-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: imdreamrunner+approved_at: 2026-10-21owners: [cixzhang]review_triggers: [theming, layout, public-api]verified_by:@@ -15,7 +15,6 @@ verified_by:packages/core/src/BottomSheet/BottomSheet.test.tsx,packages/core/src/BottomSheet/BottomSheetPanel.test.tsx,packages/core/src/BottomSheet/BottomSheetKeyboard.test.tsx,- packages/core/src/BottomSheet/__tests__/BottomSheetNativeModal.a11y.browser.spec.ts,packages/core/src/BottomSheet/__tests__/BottomSheetKeyboard.a11y.browser.spec.ts,apps/storybook/stories/BottomSheet.stories.tsx,scripts/check-knowledge.mjs,@@ -38,52 +37,24 @@ system_specs: [spec:AST-025]## IntentBottomSheet presents caller-provided content in a panel that rises from the-bottom edge. This draft records current consumer anatomy, keyboard-reachable-scrolling, theming reachability, and the Content area's container padding.+bottom edge. This record covers consumer anatomy, the native dialog every sheet+renders, keyboard-reachable scrolling, theming reachability, and the Content+area's container padding. Where the shipped sheet does not yet meet a+requirement, the row carries a present-tense implementation gap note.## Compatibility and migration-- Released default preserved: `no` — with no `padding` prop and no theme- padding, the Content area insets by `--spacing-4` on every logical edge-- Compatibility class: breaking default, scheduled for a minor release. Content- whose only child is a padded Section keeps its geometry because that Section- escapes the inset; content that supplies its own inset is padded twice until- it drops that inset or sets `padding={0}`+- Released default preserved: `yes`; with no `padding` prop and no theme+ padding, the Content area insets by `--spacing-4` on every logical edge, and+ `padding={0}` keeps an unpadded Content area+- Compatibility class: records the shipped anatomy, padded Content area, and+ native dialog; no public prop, default, or export changes- Controlled/uncontrolled behavior: unchanged-- Migration decision: `padding={0}` restores the released unpadded Content area+- Migration decision: none; the precedence rule under Transformation and+ precedence order is the whole contractConsumer migration instructions belong in consumer docs and release notes.-### DEP-0009 — Deprecate the unpadded default Content area of `BottomSheet`--| Field | Value |-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| id | `DEP-0009` |-| cleanup | `CLN-0018` |-| package | `@astryxdesign/core` |-| surface | Default inset of the `BottomSheet` Content area when no `padding` prop and no theme padding are set |-| old contract | The Content area has no padding |-| replacement | `padding={0}` keeps the unpadded Content area; `padding` and theme padding already resolve before the default |-| direct authority | `component:BottomSheet` Compatibility and migration. Owners: `cixzhang` |-| warning | Consumer docs and the release notes name `DEP-0009` and `padding={0}`. No runtime warning (`spec:AST-017` FR29) |-| migration | Mechanical: add `padding={0}` to a BottomSheet that sets no padding, unless its only child is a padded Section or a Layout |-| codemod | `astryx upgrade` adds `padding={0}` before any spread, skips sheets whose only child is a core Section or Layout, and marks a nested padding-less Layout for review |-| downstream | In-repo sheets that supply their own inset pass `padding={0}`; consumer examples rely on the default inset |-| transition | no prior transition |-| state | `proposed` |-| open decision | This record is draft and needs approval |-| target plan | `CLN-0018` in the next minor release |--### CLN-0018 — BottomSheet pads its Content area by default--| Field | Value |-| --------- | ------------------------------------------------------------------------------------------------------------------------------------ |-| id | `CLN-0018` |-| lifecycle | `DEP-0009` |-| delta | With no `padding` prop and no theme padding, the Content area insets by `--spacing-4` on every logical edge and publishes that inset |-| rollback | Restore the unpadded default from the final-patch baseline |-| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |-## Ownership boundary**Owns**@@ -95,7 +66,9 @@ Consumer migration instructions belong in consumer docs and release notes.`architecture:container-padding`.- Standalone sheet presentation, including its optional native-dialog Scrim.- The native dialog every sheet renders, standalone or switcher-managed- (`component:BottomSheetSwitcher` DEC-1's decided structure).+ (`component:BottomSheetSwitcher` DEC-1). Implementation gap: a+ switcher-managed sheet renders a panel inside the switcher's one shared+ dialog and owns no dialog of its own.**Does not own / non-goals**@@ -104,7 +77,7 @@ Consumer migration instructions belong in consumer docs and release notes.`main`.- The presentation lifecycle of its dialog and the flow's scrim ownership whenthe sheet participates in a BottomSheetSwitcher — owned by BottomSheetSwitcher- (`component:BottomSheetSwitcher` DEC-1's decided structure).+ (`component:BottomSheetSwitcher` DEC-1).- Shared layer hosting or dismissal policy.## Public concepts@@ -114,12 +87,12 @@ in `BottomSheet.doc.mjs`.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------------------- |-| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation. | Current source, docs, and tests | Verified current behavior; no new behavior decided |-| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target. | Current source, docs, and tests | Verified current behavior; no target change |-| FR3 | Content renders in one real observed content box. Effective overflow, containment, and keyboard access come from `useScrollableArea`; the named overflowing body delegates forward Tab entry to a safe first sequential native link/button. | `spec:AST-025`; issue #5207; tests | Focus-time prototype for owner review |-| FR4 | The Content area pads caller content by the sheet's container inset and publishes the applied inset to descendants as a container publisher. | `architecture:container-padding` | Admitted; implementation pending |+| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |+| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation. | Current source, docs, and tests |+| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target. | Current source, docs, and tests |+| FR3 | Content renders in one real observed content box. Effective overflow, containment, and keyboard access come from `useScrollableArea`; the named overflowing body delegates forward Tab entry to a safe first sequential native link/button. | `spec:AST-025`; tests |+| FR4 | The Content area pads caller content by the sheet's container inset and publishes the applied inset to descendants as a container publisher. | `architecture:container-padding` |### Allowed variation@@ -134,8 +107,8 @@ in `BottomSheet.doc.mjs`.without a Scrim.- A switcher-managed sheet renders the same panel anatomy in its own dialog whileBottomSheetSwitcher coordinates that dialog's lifecycle and the flow's one Scrim- (`component:BottomSheetSwitcher` DEC-1's decided structure, not shipped- anatomy).+ (`component:BottomSheetSwitcher` DEC-1). Implementation gap: the panel+ renders inside the switcher's one shared dialog.### Transformation and precedence orderdiff --git a/packages/core/src/BottomSheet/BottomSheetSwitcher.spec.md b/packages/core/src/BottomSheet/BottomSheetSwitcher.spec.mdindex ff4cbc6f2e..18c040a887 100644--- a/packages/core/src/BottomSheet/BottomSheetSwitcher.spec.md+++ b/packages/core/src/BottomSheet/BottomSheetSwitcher.spec.md@@ -3,17 +3,16 @@ schema_version: 3template_version: 4kind: componentid: component:BottomSheetSwitcher-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: imdreamrunner+approved_at: 2026-10-21owners: [cixzhang]review_triggers: [public-api, behavior, layout, theming, accessibility]verified_by:[packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx,- packages/core/src/BottomSheet/__tests__/BottomSheetNativeModal.a11y.browser.spec.ts,apps/storybook/stories/BottomSheetSwitcher.stories.tsx,scripts/check-knowledge.mjs,]@@ -35,13 +34,10 @@ system_specs: [spec:AST-002, spec:AST-027]## IntentBottomSheetSwitcher coordinates a mutually exclusive sequence of BottomSheet-children. This draft records verified shipped and remediated behavior, and the-hosting requirements its decision log decides — each child presented in its own-native dialog — without adding a prop, changing a default, or settling the-open modality, identifier, or theming decisions below. A row whose review state-is "Owner decision" is the decided requirement, not shipped behavior; the-representative states that name a sheet's own dialog, the retained dialog, or-the flow wrapper describe DEC-1's decided structure in the same way.+children, each presented in its own native dialog (DEC-1), without adding a+prop or changing a default. Where the shipped switcher does not yet meet a+requirement, the row carries a present-tense implementation gap note. The+modality, identifier, and theming questions below stay open.## Compatibility and migration@@ -61,6 +57,8 @@ Consumer migration instructions belong in consumer docs and release notes.- The presentation lifecycle of every directly nested BottomSheet child's nativedialog: which is presented, retained during a handoff, or closed.+ Implementation gap: the switcher renders one dialog of its own and hosts+ every child as a panel inside it; no child owns a dialog yet.- Which child sheet is active, retained during a handoff, or hidden.- Which sheet dialog hosts the flow (its ref, `id`, and dismissalregistration) and which paints the flow's one scrim, plus@@ -81,30 +79,27 @@ Consumer migration instructions belong in consumer docs and release notes.## Public concepts-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |-| ------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |-| Active sheet | `null` or one nested BottomSheet `sheetId` | Selects the only interactive child, or closes the flow | All presentations | `null` is closed; the prop is required | `component:BottomSheetSwitcher` | released | A non-matching or duplicate id is not given a safe public fallback by the current contract |-| Shared presentation | `true` / `false` through `hasScrim` | Selects the current modal scrim-backed host or non-modal no-scrim host | Entire flow | `true` | `component:BottomSheetSwitcher` | released | Boolean only |-| Child identity | Non-empty `sheetId` on each direct BottomSheet child | Associates controlled selection, labeling, purpose, and transition state with a child | Direct nested BottomSheet children | none | `component:BottomSheet` | released | Empty ids warn and stay hidden; duplicate-id behavior is not specified |-| Dismissal request | `onActiveSheetChange(null)` | Reports an allowed implicit close without taking control from the caller | Escape/platform close, scrim click, or swipe according to active child purpose | none | `component:BottomSheetSwitcher`; `family:overlay-dismissal` owns ordering | released | The caller may retain its controlled value |-| Dialog surface | inherited dialog props plus `ref` and `onCancel` | Dialog props and handlers, `onCancel` included, reach every sheet dialog; `ref`, `id`, and `data-testid` resolve to the host dialog, which is never null for an object ref while a sheet is mounted (owner decision, DEC-2) | Entire flow | none | `component:BottomSheetSwitcher` | released | Component-owned semantics and handlers retain precedence |+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| ------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |+| Active sheet | `null` or one nested BottomSheet `sheetId` | Selects the only interactive child, or closes the flow | All presentations | `null` is closed; the prop is required | `component:BottomSheetSwitcher` | released | A non-matching or duplicate id is not given a safe public fallback by the current contract |+| Shared presentation | `true` / `false` through `hasScrim` | Selects the current modal scrim-backed host or non-modal no-scrim host | Entire flow | `true` | `component:BottomSheetSwitcher` | released | Boolean only |+| Child identity | Non-empty `sheetId` on each direct BottomSheet child | Associates controlled selection, labeling, purpose, and transition state with a child | Direct nested BottomSheet children | none | `component:BottomSheet` | released | Empty ids warn and stay hidden; duplicate-id behavior is not specified |+| Dismissal request | `onActiveSheetChange(null)` | Reports an allowed implicit close without taking control from the caller | Escape/platform close, scrim click, or swipe according to active child purpose | none | `component:BottomSheetSwitcher`; `family:overlay-dismissal` owns ordering | released | The caller may retain its controlled value |+| Dialog surface | inherited dialog props plus `ref` and `onCancel` | Dialog props and handlers, `onCancel` included, reach every sheet dialog; `ref`, `id`, and `data-testid` resolve to the host dialog, which is never null for an object ref while a sheet is mounted (DEC-2). Implementation gap: every dialog prop, `ref`, `id`, and `data-testid` reaches the switcher's one shared dialog | Entire flow | none | `component:BottomSheetSwitcher` | released | Component-owned semantics and handlers retain precedence |## Behavioral and layout contract-Draft requirements identify their basis so observed code is not mistaken for an-intentional decision. This draft cannot clear the gaps it records.--| ID | Candidate invariant | Basis | Draft review state |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1 | Zero or one child sheet is interactive for each controlled `activeSheet` value; all other children are hidden or retained inert and `aria-hidden` during a transition. | Current source, docs, and tests | Verified shipped behavior |-| FR2 | Each child sheet owns one native dialog. Opening a sheet presents its dialog once; a handoff presents the entering sheet's dialog above the retained one and closes the retained dialog only after its panel has faded. Returning to a sheet whose dialog is still open beneath a newer one re-presents it so the interactive sheet is the topmost layer. | DEC-1 | Owner decision |-| FR3 | During a handoff, the entering sheet is above the retained sheet. A taller retained sheet aligns down to a shorter entering sheet, and the retained sheet fades only after required transform motion completes. | Current source and transition tests | Verified shipped behavior; exact visual treatment remains human-reviewed |-| FR4 | Closing retains the outgoing sheet through its exit, then closes the dialog. A modal flow restores focus to the element captured when that modal flow opened. | Current source and focus tests | Verified shipped behavior |-| FR5 | `hasScrim=true` uses `showModal()`, a native backdrop, and native focus containment, and locks page scroll: the page does not scroll while a modal flow is presented; the lock is held continuously across a handoff, never released and re-acquired between steps; it still holds beneath a `Dialog` opened from a step; it is released after the flow's exit (owner decision, DEC-1). `hasScrim=false` uses `show()` without a backdrop or scroll lock and leaves the page interactive (verified current behavior). In a non-modal flow the sheet dialogs order themselves with local values inside the switcher's isolated flow wrapper (owner decision, DEC-1); the page-level value that wrapper carries remains a `spec:AST-027` conformance gap. | DEC-1; `spec:AST-027` FR2, FR4, FR8 | Modal host and the wrapper's local ordering: owner decision. Non-modal `show()` host: verified current behavior. The wrapper's page-level value remains a `spec:AST-027` conformance gap |-| FR6 | The active child purpose governs implicit dismissal: `info` allows Escape, scrim click, and swipe; `form` allows Escape; `required` blocks all three and exposes `alertdialog`. | Current BottomSheet docs and switcher tests | Verified shipped behavior |-| FR7 | While visible, the switcher participates in `family:overlay-dismissal`; one Escape or platform close request reaches only the topmost present layer, and descendants receive a deeper logical layer scope. | `family:overlay-dismissal` and the audit regression test | Settled remediation in this audit |-| FR8 | One backdrop paints the flow's scrim at a time: the retained sheet's dialog keeps it through a handoff and the entering dialog takes it over without a fade when the retained dialog closes. A stale gesture from an outgoing sheet cannot change the flow's scrim, and unmounting a retained sheet cannot keep its dialog open or the flow's modal layer held. | DEC-1; current tests | Owner decision |-| FR9 | The switcher forwards neutral dialog attributes, styling inputs, and composed handlers, `onCancel` included, to every sheet dialog, so a handler fires for whichever sheet dialog raises the event; renders `id` and `data-testid` on the host dialog only, so each appears once in the document; attaches its ref to the host dialog; and preserves its owned ARIA and dismissal behavior. An object ref's `current` is never `null` while a sheet is mounted. A callback ref follows React's semantics on a handoff: a cleanup it returned runs when it detaches from the old host; a callback ref without a cleanup is called with `null` on detach, then with the new host. | DEC-1, DEC-2; `architecture:public-component-api` INV8 | Owner decision |+| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |+| FR1 | Zero or one child sheet is interactive for each controlled `activeSheet` value; all other children are hidden or retained inert and `aria-hidden` during a transition. | Current source, docs, and tests |+| FR2 | Each child sheet owns one native dialog. Opening a sheet presents its dialog once; a handoff presents the entering sheet's dialog above the retained one and closes the retained dialog only after its panel has faded. Returning to a sheet whose dialog is still open beneath a newer one re-presents it so the interactive sheet is the topmost layer. Implementation gap: the switcher presents one shared dialog once per flow and hosts every child as a panel inside it; a handoff swaps panels in that dialog, and no dialog is re-presented. | DEC-1 |+| FR3 | During a handoff, the entering sheet is above the retained sheet. A taller retained sheet aligns down to a shorter entering sheet, and the retained sheet fades only after required transform motion completes. | Current source and transition tests |+| FR4 | Closing retains the outgoing sheet through its exit, then closes the dialog. A modal flow restores focus to the element captured when that modal flow opened. | Current source and focus tests |+| FR5 | `hasScrim=true` uses `showModal()`, a native backdrop, and native focus containment, and locks page scroll: the page does not scroll while a modal flow is presented; the lock is held continuously across a handoff, never released and re-acquired between steps; it still holds beneath a `Dialog` opened from a step; it is released after the flow's exit (DEC-1). `hasScrim=false` uses `show()` without a backdrop or scroll lock and leaves the page interactive. In a non-modal flow the sheet dialogs order themselves with local values inside the switcher's isolated flow wrapper (DEC-1); the page-level value that wrapper carries remains a `spec:AST-027` conformance gap. Implementation gap: a script focus trap runs on top of the modal dialog's native containment; a non-modal flow is one shared dialog carrying the page-level value itself, with no flow wrapper. | DEC-1; `spec:AST-027` FR2, FR4, FR8 |+| FR6 | The active child purpose governs implicit dismissal: `info` allows Escape, scrim click, and swipe; `form` allows Escape; `required` blocks all three and exposes `alertdialog`. | Current BottomSheet docs and switcher tests |+| FR7 | While visible, the switcher participates in `family:overlay-dismissal`; one Escape or platform close request reaches only the topmost present layer, and descendants receive a deeper logical layer scope. | `family:overlay-dismissal` and the audit regression test |+| FR8 | One backdrop paints the flow's scrim at a time: the retained sheet's dialog keeps it through a handoff and the entering dialog takes it over without a fade when the retained dialog closes. A stale gesture from an outgoing sheet cannot change the flow's scrim, and unmounting a retained sheet cannot keep its dialog open or the flow's modal layer held. Implementation gap: the one backdrop is the shared dialog's, so no takeover between dialogs happens. | DEC-1; current tests |+| FR9 | The switcher forwards neutral dialog attributes, styling inputs, and composed handlers, `onCancel` included, to every sheet dialog, so a handler fires for whichever sheet dialog raises the event; renders `id` and `data-testid` on the host dialog only, so each appears once in the document; attaches its ref to the host dialog; and preserves its owned ARIA and dismissal behavior. An object ref's `current` is never `null` while a sheet is mounted. A callback ref follows React's semantics on a handoff: a cleanup it returned runs when it detaches from the old host; a callback ref without a cleanup is called with `null` on detach, then with the new host. Implementation gap: every forwarded input, `ref`, `id`, and `data-testid` reaches the one shared dialog, which never changes on a handoff. | DEC-1, DEC-2; `architecture:public-component-api` INV8 |### Allowed variation@@ -116,8 +111,9 @@ intentional decision. This draft cannot clear the gaps it records.### Representative states-The states below describe DEC-1's decided structure where they name a sheet's-own dialog, the retained dialog, or the flow wrapper.+Where a state names a sheet's own dialog, the retained dialog, or the flow+wrapper, the shipped switcher meets it with its one shared dialog instead; FR2+and FR5 record that implementation gap.| State | Required invariant | Allowed variation || ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |@@ -125,7 +121,7 @@ own dialog, the retained dialog, or the flow wrapper.| First open | Matching child is visible and interactive in its own dialog. | Child-owned height and content. || Handoff | Entering child is interactive in its own dialog; retained child's dialog stays open, inert, and hidden from accessibility APIs until it fades, and keeps painting the one scrim. | Alignment offset depends on measured panel geometry. || Closing | Outgoing child is retained inert while exit motion completes; modal focus and scroll ownership remain until close. | Theme-controlled duration. |-| Modal | Native modal host, backdrop, native focus containment, and the page scroll lock are active. | Active child's `purpose` controls implicit dismissal. |+| Modal | Native modal host, backdrop, native focus containment, and the page scroll lock are active. Implementation gap: a script focus trap runs on top of the native containment. | Active child's `purpose` controls implicit dismissal. || Non-modal | Native non-modal host has no backdrop or scroll lock and background content remains interactive. | The current clipping/stacking limitation is a conformance gap, not an allowed exception. |### Transformation and precedence order@@ -144,7 +140,8 @@ own dialog, the retained dialog, or the flow wrapper.Native modality holds across a modal flow's child handoffs because a sheetdialog is modal throughout, and the one page scroll lock is held for thewhole flow rather than per step. A non-modal flow paints no backdrop and- holds no lock.+ holds no lock. Implementation gap: one shared dialog is presented+ throughout, so a handoff has one dialog open, not two.- **PR2 — Stable child registration.** Parent rerenders and changing consumer refidentities do not unregister a mounted child or cancel an active handoff.@@ -160,11 +157,11 @@ own dialog, the retained dialog, or the flow wrapper.## Design relationships-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------- | ------------------ |-| Shared dialog | Transparent host for the flow's interaction and accessibility boundary; DEC-1 decides one such host per child sheet | Current source and public docs; DEC-1 for the per-sheet clause | Structural | FR2, FR5, AR1 |-| Sheet panels | Delegate visible panel, content, handle, and gesture presentation to BottomSheet | `component:BottomSheet` draft as observational context | Prominent | FR1, FR3 |-| Scrim | Optional native backdrop that dims and blocks the page in modal presentation; DEC-1 decides that one sheet dialog paints it at a time | Current source and public docs; DEC-1 for the one-painter clause | Supporting | FR5, FR8 |+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | -------------- | ------------------ |+| Shared dialog | Transparent host for the flow's interaction and accessibility boundary, one per child sheet (DEC-1). Implementation gap: one such host serves the whole flow | Current source and public docs; DEC-1 for the per-sheet clause | Structural | FR2, FR5, AR1 |+| Sheet panels | Delegate visible panel, content, handle, and gesture presentation to BottomSheet | `component:BottomSheet` as observational context | Prominent | FR1, FR3 |+| Scrim | Optional native backdrop that dims and blocks the page in modal presentation; one sheet dialog paints it at a time (DEC-1) | Current source and public docs; DEC-1 for the one-painter clause | Supporting | FR5, FR8 |### Theming anatomy@@ -198,16 +195,16 @@ own dialog, the retained dialog, or the flow wrapper.- `architecture:public-component-api` and `spec:AST-002` own the released prop,DOM, ref, and compatibility surface.- `spec:AST-027` identifies the non-modal `show()` plus page-level `z-index` path- as a migration gap; this draft does not treat it as an exception.+ as a migration gap, not an exception.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ---------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |-| FR1–FR4, FR8 | `BottomSheetSwitcher.test.tsx` | closed, first open, handoffs in either completion order, rapid replacement, unmount, close | A child becomes interactive at the wrong time, a retained child disappears early, a second backdrop paints, or a sheet dialog's lifecycle breaks. | `audit:BottomSheetSwitcher/behavior` |-| FR5–FR7, AR1–AR3 | `BottomSheetSwitcher.test.tsx`; `BottomSheetNativeModal.a11y.browser.spec.ts` | modal/non-modal, info/form/required, nested layer, IME, focus return, scroll lock in engines, non-modal local ordering | Modality, dismissal order, naming, inertness, scroll lock, or focus behavior diverges, or a sheet dialog takes a page-level z-index. | `audit:BottomSheetSwitcher/accessibility` |-| FR9 | `BottomSheetSwitcher.test.tsx`; export checks | ref across open/handoff/close/unmount, callback-ref cleanup, `id` once, DOM/ARIA/data/events, class, style, xstyle | A supported input is dropped or duplicated, an object ref is null while a sheet is mounted or skips a cleanup, or an input overrides component-owned semantics accidentally. | `audit:BottomSheetSwitcher/api` |-| Theming anatomy | `scripts/check-knowledge.mjs`; theming tests | dialog, delegated sheet panel, scrim | A non-painting host gains a target, a delegated panel loses its owner, or the scrim gap disappears without review. | `audit:BottomSheetSwitcher/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |+| FR1–FR4, FR8 | `BottomSheetSwitcher.test.tsx` | closed, first open, handoffs in either completion order, rapid replacement, unmount, close | A child becomes interactive at the wrong time, a retained child disappears early, a second backdrop paints, or a sheet dialog's lifecycle breaks. | `audit:BottomSheetSwitcher/behavior` |+| FR5–FR7, AR1–AR3 | `BottomSheetSwitcher.test.tsx`; `BottomSheetNativeModal.a11y.browser.spec.ts` (implementation gap: not yet in the tree) | modal/non-modal, info/form/required, nested layer, IME, focus return, scroll lock in engines, non-modal local ordering | Modality, dismissal order, naming, inertness, scroll lock, or focus behavior diverges, or a sheet dialog takes a page-level z-index. | `audit:BottomSheetSwitcher/accessibility` |+| FR9 | `BottomSheetSwitcher.test.tsx`; export checks | ref across open/handoff/close/unmount, callback-ref cleanup, `id` once, DOM/ARIA/data/events, class, style, xstyle | A supported input is dropped or duplicated, an object ref is null while a sheet is mounted or skips a cleanup, or an input overrides component-owned semantics accidentally. | `audit:BottomSheetSwitcher/api` |+| Theming anatomy | `scripts/check-knowledge.mjs`; theming tests | dialog, delegated sheet panel, scrim | A non-painting host gains a target, a delegated panel loses its owner, or the scrim gap disappears without review. | `audit:BottomSheetSwitcher/theming` |## Decision log