@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Banner/Banner.tsx

@@ -12,6 +12,7 @@
  * - Banner frame (themeProps 'banner-frame'): owns the resting elevation and,
  *   for elevated card banners, the outer radius that shapes that shadow
  * - Header area (themeProps 'banner'): colored status background with icon, title, description, actions, dismiss
+ * - End area restores the ordinary text context for consumer `endContent`; built-in controls opt back into the status foreground
  * - Content area (themeProps 'banner-content'): card background for additional content (children)
  * - Status icon (themeProps 'banner-icon'): the target rides on the default
  *   <Icon> itself — the element that paints — so 'status:X' overrides reach
@@ -208,10 +209,10 @@ const defaultIconNames: Partial<Record<BannerStatus, IconName>> = {
 };
 
 const statusIconColor: Partial<Record<BannerStatus, IconColor>> = {
-  info: 'accent',
-  warning: 'warning',
-  error: 'error',
-  success: 'success',
+  info: 'inherit',
+  warning: 'inherit',
+  error: 'inherit',
+  success: 'inherit',
 };
 
 // =============================================================================
@@ -295,6 +296,12 @@ const styles = stylex.create({
     color: colorVars['--color-text-secondary'],
     overflowWrap: 'anywhere',
   },
+  // Built-in status title, description, and icon inherit the header's on-muted
+  // color. Built-in controls receive the same context on their Button element
+  // only, so the sibling tooltip bubble keeps the theme's ordinary text color.
+  statusForeground: {
+    color: 'inherit',
+  },
   iconWrapper: {
     display: 'flex',
     alignItems: 'center',
@@ -307,6 +314,10 @@ const styles = stylex.create({
     justifyContent: 'flex-end',
     gap: spacingVars['--spacing-2'],
     flexShrink: 0,
+    // The status surface owns an inherited on-muted foreground, but consumer
+    // endContent does not. Reset the end area's ordinary text context, then let
+    // the built-in controls below opt back into the status foreground.
+    color: colorVars['--color-text-primary'],
     // Bounded so a group of actions wider than the row wraps within itself
     // rather than pushing the banner past the viewport (WCAG 1.4.10).
     maxWidth: '100%',
@@ -349,16 +360,73 @@ const styles = stylex.create({
 
 const statusStyles = stylex.create({
   info: {
-    backgroundColor: colorVars['--color-accent-muted'],
+    backgroundColor: colorVars['--color-info-muted'],
+    color: colorVars['--color-on-info-muted'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
   },
   warning: {
     backgroundColor: colorVars['--color-warning-muted'],
+    color: colorVars['--color-on-warning-muted'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
   },
   error: {
     backgroundColor: colorVars['--color-error-muted'],
+    color: colorVars['--color-on-error-muted'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
   },
   success: {
     backgroundColor: colorVars['--color-success-muted'],
+    color: colorVars['--color-on-success-muted'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
+  },
+});
+
+// Scope status text context to each built-in Button. Its tooltip is a sibling,
+// so it does not inherit these control-only variables.
+const statusControlStyles = stylex.create({
+  info: {
+    '--color-text-primary': colorVars['--color-on-info-muted'],
+  },
+  warning: {
+    '--color-text-primary': colorVars['--color-on-warning-muted'],
+  },
+  error: {
+    '--color-text-primary': colorVars['--color-on-error-muted'],
+  },
+  success: {
+    '--color-text-primary': colorVars['--color-on-success-muted'],
   },
 });
 
@@ -628,12 +696,21 @@ export function Banner({
             styles.headerContent,
             isRenderable(endContent) && styles.headerContentWithEndContent,
           )}>
-          <div {...stylex.props(styles.title)}>{title}</div>
+          <div
+            {...stylex.props(
+              styles.title,
+              hasStatusStyle(status) && styles.statusForeground,
+            )}>
+            {title}
+          </div>
           {isRenderable(description) && (
             <div
               {...mergeProps(
                 themeProps('banner-description'),
-                stylex.props(styles.description),
+                stylex.props(
+                  styles.description,
+                  hasStatusStyle(status) && styles.statusForeground,
+                ),
               )}>
               {description}
             </div>
@@ -672,6 +749,11 @@ export function Banner({
                   />
                 }
                 onClick={handleToggleExpand}
+                className={
+                  hasStatusStyle(status)
+                    ? stylex.props(statusControlStyles[status]).className
+                    : undefined
+                }
                 aria-expanded={isExpanded}
                 aria-controls={showContent ? contentId : undefined}
                 isIconOnly
@@ -685,6 +767,11 @@ export function Banner({
                 tooltip={dismissTooltip}
                 icon={<Icon icon="close" size="sm" color="inherit" />}
                 onClick={handleDismiss}
+                className={
+                  hasStatusStyle(status)
+                    ? stylex.props(statusControlStyles[status]).className
+                    : undefined
+                }
                 isIconOnly
               />
             )}

package/src/Blockquote/Blockquote.spec.md

@@ -0,0 +1,171 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Blockquote
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-26
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    .github/visual-baseline/manifest.json,
+    packages/core/src/Blockquote/Blockquote.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/Blockquote.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: [design:bidirectionality]
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-009]
+---
+
+# Blockquote component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                          |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | A semantic `blockquote` holding `children`, with an optional `cite` attribution.                                                  |
+| Behavior                | The quote has an inline-start rule and secondary text; a renderable `cite` follows the content in a bare `cite` element.          |
+| End-user impact         | Readers see quoted text set apart; screen-reader users get a native blockquote and no stray landmark from the attribution.        |
+| Builder impact          | None; the record describes shipped behavior.                                                                                      |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                        |
+| Review checks           | Reject a physical left rule, a `footer` around the attribution, or a non-`blockquote` root.                                       |
+| Governing rules         | `design:bidirectionality/DR3`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV2`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Blockquote sets quoted content apart from surrounding text with native quote
+semantics. It owns the rule, inset, and color of the quote and the placement of
+its optional attribution.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The `blockquote` root, its rule, inset, color, and zeroed margins.
+- The Attribution element and its placement after the quotation.
+
+**Does not own / non-goals**
+
+- The quoted content and attribution text — owned by the caller.
+- Quotation marks, if wanted — owned by the caller's content.
+- Markdown block quotes — owned by `component:Markdown`.
+
+## Public concepts
+
+| Concept     | Closed values or states | Meaning                                   | Availability by variant/orientation/state | Default | Owner                  | Stability | Invalid-value behavior                                         |
+| ----------- | ----------------------- | ----------------------------------------- | ----------------------------------------- | ------- | ---------------------- | --------- | -------------------------------------------------------------- |
+| Attribution | present; absent         | Renders the source of the quote after it. | Always                                    | absent  | `component:Blockquote` | Stable    | `false`, `true`, `null`, `undefined`, and `''` render nothing. |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                             | Basis                    |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The root is a `blockquote` carrying the `blockquote` target, with a solid `--spacing-0-5` rule in `--color-border-emphasized` on its inline-start edge, `--spacing-4` inline-start padding, secondary text color, word breaking for long words, and all margins zero. | Current source and tests |
+| FR2 | `children` render first inside the root. A renderable `cite` renders after them in a bare `cite` element — never wrapped in `footer` — displayed as a block with `--spacing-2` top margin, supporting type, and normal font style.                                    | Current source and tests |
+| FR3 | In a right-to-left region the rule and its padding sit on the right edge: the root uses logical inline-start border and padding, never physical left ones.                                                                                                            | Current source and docs  |
+| FR4 | `ref` reaches the `blockquote`. Supported DOM, ARIA, data, and event props reach it; `xstyle`, `className`, and `style` merge in that order after component styles. Blockquote renders on the server.                                                                 | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may restyle `blockquote`, including the rule,
+  without changing semantics or attribution placement.
+
+### Representative states
+
+| State            | Required invariant                                    | Allowed variation |
+| ---------------- | ----------------------------------------------------- | ----------------- |
+| Quote only       | `blockquote` with rule and secondary text; no `cite`. | Content.          |
+| With attribution | `cite` follows the content; no `footer` or landmark.  | Attribution.      |
+| Right-to-left    | Rule and padding on the right edge.                   | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Styling inputs.** Component class → component styles → `xstyle` →
+  `className` → `style` → remaining caller props.
+
+### Performance and resources
+
+- **PR1 — Static render.** Blockquote holds no state and uses no hooks.
+
+## Accessibility contract
+
+- **AR1 — Native quote.** The root is a native `blockquote`.
+- **AR2 — No stray landmark.** The attribution is a bare `cite`; it is never
+  wrapped in a `footer`, which inside a sectioning root would surface as a
+  content-information landmark.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                   | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Rule             | An emphasized line on the inline-start edge.         | Current source and docs  | Supporting     | FR1, FR3           |
+| Quotation        | The quoted content in secondary text.                | Current source and docs  | Prominent      | FR1, FR2           |
+| Attribution      | The source, in supporting type, below the quotation. | Current source and docs  | Supporting     | FR2, AR2           |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Rule": {"target": "blockquote"},
+  "Quotation": {"inherits": "blockquote"},
+  "Attribution": {"inherits": "blockquote"}
+}
+```
+
+The rule is a border of the root, so it shares the root's `blockquote` target.
+
+## Family and system relationships
+
+- `design:bidirectionality` DR3 owns inline-start and inline-end placement;
+  FR3 applies it to the rule.
+- `architecture:public-component-api` owns ref, passthrough, and styling-input
+  rules; FR4 applies them to the root.
+
+## Verification map
+
+| Contract            | Verification                                                            | Representative states               | Mutation or failure expectation                                                                                                                                                                                                                                                                                                      | Audit section               |
+| ------------------- | ----------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
+| FR1, FR4            | `Blockquote.test.tsx` render, class, ref, passthrough, and server tests | Quote only                          | A non-`blockquote` root, a lost target, ref, or caller prop, or a failed server render fails. The stable visual baseline `core-blockquote--default` (neutral, light and dark) returns a changed rule, padding, color, or margin for review. Gap: no unit test asserts those styles, word breaking, or the styling-input merge order. | `audit:Blockquote/behavior` |
+| FR2, AR2            | `Blockquote.test.tsx` cite tests                                        | With and without attribution        | A missing `cite` or a landmark wrapper fails. Gap: no test asserts that the attribution follows the content, and its block display, margin, type, and font style have no automated check, and the visual baseline renders no attribution.                                                                                            | `audit:Blockquote/a11y`     |
+| FR3                 | `@astryx/no-physical-properties` lint rule; `Blockquote.stories.tsx`    | Right-to-left                       | A physical left border or padding in Blockquote's styles fails lint. Gap: no rendered right-to-left check confirms the rule sits on the right edge.                                                                                                                                                                                  | `audit:Blockquote/i18n-rtl` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                           | Consumer anatomy and current target | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                        | `audit:Blockquote/theming`  |
+| AR1                 | `Blockquote.test.tsx` render test                                       | Quote only                          | A non-`blockquote` root fails.                                                                                                                                                                                                                                                                                                       | `audit:Blockquote/a11y`     |
+| PR1                 | `Blockquote.test.tsx` server-render test                                | Quote only                          | A failed server render fails. Gap: no test fails if Blockquote adds state or hooks.                                                                                                                                                                                                                                                  | `audit:Blockquote/behavior` |
+| AR1, AR2            | Accessibility-tree evidence (`spec:AST-009` FR3)                        | Quote with attribution              | Gap: no accessibility-tree check proves the blockquote role or the absence of a landmark; the unit tests query the DOM.                                                                                                                                                                                                              | `audit:Blockquote/a11y`     |
+
+## Decision log
+
+None recorded. The record describes shipped behavior.
+
+## 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.

package/src/BottomSheet/BottomSheet.doc.mjs

@@ -95,25 +95,25 @@ export const docs = {
     derived: [{property: 'padding', expand: 'container'}],
   },
   description:
-    "A mobile touch sheet that rises from the bottom edge, with animated entrance and exit, a grab handle, optional drag-to-resize snap points, and purpose-controlled dismissal. Like Dialog, it is a padded container: content starts at the theme's bottom-sheet padding (--spacing-4 by default), and a lone Section child or bleed children such as Table and Divider align against it. A sheet always owns a native <dialog>; inside BottomSheetSwitcher the switcher presents and closes that dialog as the flow moves between steps. In both modes, ref and shared DOM props target the visual panel <div>.",
+    "A mobile touch sheet that rises from the bottom edge, with animated entrance and exit, a grab handle, optional drag-to-resize snap points, and purpose-controlled dismissal. Like Dialog, it is a padded container: content starts at the theme's bottom-sheet padding (--spacing-4 by default), and a lone Section child or bleed children such as Table and Divider align against it. A sheet always owns a native <dialog>; inside the deprecated BottomSheetSwitcher the switcher presents and closes that dialog as the flow moves between steps. In both modes, ref and shared DOM props target the visual panel <div>. Sheets stack: a sheet opened while another is open sits on top of it, the covered sheet stays mounted and recedes, and one scrim covers the page. A sheet that closes as another opens in the same update is replaced by it, with the step-to-step handoff a multi-step flow needs.",
   props: [
     {
       name: 'isOpen',
       type: 'boolean',
       description:
-        'Whether a standalone sheet is open. Fully controlled; pair with onOpenChange. Omit inside BottomSheetSwitcher.',
+        'Whether a standalone sheet is open. Fully controlled; pair with onOpenChange. Omitted only inside the deprecated BottomSheetSwitcher, which drives its steps itself.',
     },
     {
       name: 'onOpenChange',
       type: '(isOpen: boolean) => void',
       description:
-        'For a standalone sheet, called when it requests an open-state change. Automatic calls follow purpose: info dismisses on Escape, scrim click, or swipe; form dismisses on Escape only; required never dismisses implicitly. Omit inside BottomSheetSwitcher.',
+        'For a standalone sheet, called when it requests an open-state change. Automatic calls follow purpose: info dismisses on Escape, scrim click, or swipe; form dismisses on Escape only; required never dismisses implicitly. Omitted only inside the deprecated BottomSheetSwitcher, which drives its steps itself.',
     },
     {
       name: 'finalFocusRef',
       type: 'RefObject<HTMLElement | null>',
       description:
-        'Optional explicit focus-return target for a standalone sheet. Use when the opener can remount or the active element is not a reliable trigger, such as an adaptive presentation switch. Omit inside BottomSheetSwitcher.',
+        'Optional explicit focus-return target for a standalone sheet. Use when the opener can remount or the active element is not a reliable trigger, such as an adaptive presentation switch. Always focused when the sheet closes on its own or last; when a modal sheet is still open beneath, focus returns into that sheet (to this element if it is inside it, else the revealed panel). Omitted only inside the deprecated BottomSheetSwitcher, which drives its steps itself.',
     },
     {
       name: 'purpose',
@@ -126,7 +126,7 @@ export const docs = {
       name: 'sheetId',
       type: 'string',
       description:
-        'Unique ID for this sheet inside BottomSheetSwitcher. The switcher opens it when activeSheet matches. Omit isOpen and onOpenChange when sheetId is used.',
+        'Deprecated with BottomSheetSwitcher: give each step its own standalone sheet with isOpen instead. Still works as released: the unique ID of this sheet inside a BottomSheetSwitcher, which opens it when activeSheet matches; omit isOpen and onOpenChange when sheetId is used.',
     },
     {
       name: 'label',
@@ -165,20 +165,25 @@ export const docs = {
       name: 'hasScrim',
       type: 'boolean',
       description:
-        "For a standalone BottomSheet, whether to render a scrim, the semi-transparent overlay that covers and blocks the background. true (default) uses showModal(): top layer, native focus containment, ::backdrop scrim, body scroll lock, and tap-scrim-to-dismiss when purpose='info', with the background inert. false uses show() with no scrim, leaving the page behind interactive and scrollable. For a multi-step flow, configure hasScrim on BottomSheetSwitcher instead; it applies to every child's dialog.",
+        "For a standalone BottomSheet, whether to render a scrim, the semi-transparent overlay that covers and blocks the background. true (default) uses showModal(): top layer, native focus containment, ::backdrop scrim, body scroll lock, and tap-scrim-to-dismiss when purpose='info', with the background inert. A scrim sheet also takes part in stacking (see Stacking below). false presents the sheet in the top layer as a manual popover (below the Popover API support floor, show() in page stacking order as a reduced fallback) with no scrim, no focus trap and no scroll lock, leaving the page behind interactive and scrollable; a no-scrim sheet neither stacks nor is stacked on, but no-scrim steps replace each other with the same handoff. A no-scrim sheet shown while a modal (a scrim sheet or a Dialog) that does not contain it is open is inert under that modal and stays beneath it (show(), no page-level z-index) until that modal has gone, then enters the top layer; a modal mid-exit counts as gone, and rendered inside the modal the sheet enters the top layer at once. In a multi-step flow, set hasScrim the same on every step.",
       default: 'true',
     },
   ],
   usage: {
     anatomy,
     description:
-      'A mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport; use BottomSheetSwitcher for multi-step flows.',
+      "A mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport. For a multi-step flow, give each step its own sheet and one state value that names the open step (see Replacing a sheet); open a second sheet over the first when a step should stay visible beneath it.\n\nStacking. Every sheet keeps its own isOpen. Open a sheet while another scrim sheet is open and it stacks on top: the sheet beneath stays mounted with its scroll position and inputs, recedes behind the new one (the nearest covered sheet shrinks to 0.96 and lifts 8px, deeper ones to 0.92 and 16px), and is blocked from pointer, keyboard, and assistive technology by the top sheet's modal dialog. The sheets can be siblings, live in separate components, sit inside another sheet's content, or sit inside a BottomSheetSwitcher step; a whole switcher is one level, and switching its step in place does not change its position. Nothing moves in the DOM: each sheet's dialog stays where it is written, and no wrapper component is needed.\n\nOrder is open order. The top sheet is the one presented most recently that is still open; a sheet that closes and reopens comes back on top. When several sheets open in one update (a deep link into a flow), there is no open order between them, so tree order decides: a sheet below the sheets rendered in its content, siblings in the order they are written. That order is right in the first painted frame.\n\nOne scrim. Only the bottom sheet's backdrop dims the page; the backdrops of the sheets above it are transparent, so a stack never darkens per level. The dim holds steady while sheets push and pop, and if the bottom sheet closes while sheets remain above it, the next sheet's backdrop takes over in the same frame.\n\nDismissal. Escape, a tap on the scrim, a downward swipe, and a platform close request (Android back, a close watcher) reach only the top sheet, through that sheet's own onOpenChange, and that sheet's purpose applies: required blocks all of them, form blocks the scrim and the swipe. Nothing closes a whole stack at once; set every sheet closed in one update when a flow is done and they leave together.\n\nClosing a covered sheet from code. Sheets rendered inside the closing sheet's content are part of it: they are presented only while it is open and leave with it. Their isOpen stays yours, as with a Dialog rendered in a closed Dialog: nothing is written to it, and a nested sheet that is still open when its host reopens is presented again, on top. Set it closed yourself when the flow is done. Sheets above the closing sheet that are not in its content stay open and keep their order; the closing sheet slides out from beneath them, and if it owned the scrim, the sheet above takes it over.\n\nReplacing a sheet. Close the top sheet and open another in the same update (one state value that names the open step does this) and the new sheet replaces it instead of stacking on it: the new sheet rises above the one it replaces; if the replaced sheet is taller it moves down to meet the new sheet's top edge at the same time; the replaced sheet fades only after both motions finish, and is inert and hidden from assistive technology from the start. The scrim holds steady throughout, with no dip; focus moves into the new sheet; and when the flow closes, focus returns to the element that opened its first sheet, whichever sheet closed last. This is the handoff the deprecated BottomSheetSwitcher ran between its steps; a multi-step flow needs no switcher: give each step its own BottomSheet and one state value. A replace happens only when exactly one sheet closes and one opens in the update, the closing sheet was the top sheet of its stack, and the move was made from inside it (the control last pressed, or with no recent press the focused element, was in the closing sheet, as a step's own Continue or Back button is); a covered sheet closing while a sheet opens, a close and an open in different updates, or a close and an open driven from a control outside the closing sheet (two unrelated owners acting at once) keep the ordinary push and pop motion and their own focus return. A replace over an open stack runs one level up and leaves the sheets beneath covered. Non-modal sheets (hasScrim={false}) replace each other the same way, with no scrim: they are hosted in the browser top layer as manual popovers, so the entering step orders above the retained one with no page-level z-index, and toasts raised before or while the sheet is open stay above it. Below the Popover API support floor (Tier 2 in the browser support guide) the sheet falls back to show() in page stacking order: usable, but with no promise over later page content. A non-modal sheet returns focus to its opener on close only while focus is still inside it; focus taken elsewhere on the live page stays there.\n\nFocus. Opening a sheet moves focus into it, wherever the engine's native dialog focusing steps land: the panel in Chromium, the first focusable control in Firefox (a data-autofocus field only when it comes first). A step entering as a replacement focuses a data-autofocus descendant first, so a flow that opens on a field keeps the keyboard on it. Closing the top sheet returns focus into the sheet it reveals: to the control that opened it when that control is still there, otherwise to the revealed sheet's panel. When the last sheet closes, the standalone rules apply: finalFocusRef, else the element that opened the sheet, with a focus ring only after keyboard input. When every sheet of a stack closes in one update, focus returns once, to the bottom sheet's finalFocusRef or opener, after the last dialog has closed.\n\nCaveats. A Dialog, AlertDialog, or Popover opened from a sheet paints above the sheet and does not make it recede; a sheet opened from inside that Dialog paints above the Dialog and stacks over the sheet beneath. Sheets with hasScrim={false} stay out of the stack entirely (they replace each other, but never stack, recede, or take the scrim). A sheet React hides (a suspended Suspense boundary, Activity mode=\"hidden\") leaves the stack and closes its dialog; when it is shown again it is presented again, on top. Only sheets rendered in the same document stack; a sheet inside an iframe is its own stack.",
     bestPractices: [
       {
         guidance: true,
         description:
           'Use for mobile-first surfaces (filters, share sheets, quick actions) where the content should rise from the bottom edge.',
       },
+      {
+        guidance: true,
+        description:
+          "For a drill-in, open the next sheet over the current one and keep each sheet's isOpen where its data lives; a detail sheet can sit inside the list sheet that opens it, right next to the row. Close every sheet in one update to close the whole flow.",
+      },
       {
         guidance: true,
         description:
@@ -192,7 +197,12 @@ export const docs = {
       {
         guidance: false,
         description:
-          "Don't make the sheet content overly long. Consider breaking it into steps and using Bottom Sheet Switcher.",
+          "Don't make the sheet content overly long. Break it into steps, each its own sheet, with one state value naming the open step; moving on replaces one with the next.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't stack more than two or three sheets: deeper sheets share the second recede step and the user has to pop them one at a time. Replace steps instead (close one, open the next in one update) when they do not need to stay visible.",
       },
     ],
   },
@@ -265,20 +275,87 @@ export const docs = {
 </BottomSheet>`,
     },
     {
-      label: 'Multi-step flow (one sheet at a time)',
-      code: `const [activeSheet, setActiveSheet] = useState(null);
+      label:
+        'Multi-step flow (one sheet at a time, each step replaces the last)',
+      code: `// One value names the open step. Moving on closes one sheet and opens the
+// next in the same update: the next step rises above the current one, which
+// fades once it has arrived. A dismissed step closes the flow.
+const [step, setStep] = useState(null);
+const stepProps = own => ({
+  isOpen: step === own,
+  onOpenChange: isOpen => !isOpen && setStep(current => (current === own ? null : current)),
+});
+<>
+  <Button label="Start" onClick={() => setStep('details')} />
+  <BottomSheet {...stepProps('details')} label="Details">
+    <Button label="Continue" onClick={() => setStep('confirm')} />
+  </BottomSheet>
+  <BottomSheet {...stepProps('confirm')} label="Confirm">
+    <Button label="Back" onClick={() => setStep('details')} />
+    <Button label="Done" onClick={() => setStep(null)} />
+  </BottomSheet>
+</>`,
+    },
+    {
+      label: 'Stacked sheets (drill-in: list, order, edit)',
+      code: `const [isListOpen, setIsListOpen] = useState(false);
+const [orderId, setOrderId] = useState(null);
+const [isEditing, setIsEditing] = useState(false);
+const closeAll = () => {
+  setIsListOpen(false);
+  setOrderId(null);
+  setIsEditing(false);
+};
 <>
-  <Button label="Start" onClick={() => setActiveSheet('details')} />
-  <BottomSheetSwitcher
-    activeSheet={activeSheet}
-    onActiveSheetChange={setActiveSheet}>
-    <BottomSheet sheetId="details" label="Details">
-      <Button label="Continue" onClick={() => setActiveSheet('confirm')} />
-    </BottomSheet>
-    <BottomSheet sheetId="confirm" label="Confirm">
-      <Button label="Back" onClick={() => setActiveSheet('details')} />
-    </BottomSheet>
-  </BottomSheetSwitcher>
+  <Button label="Orders" onClick={() => setIsListOpen(true)} />
+  <BottomSheet isOpen={isListOpen} onOpenChange={setIsListOpen} label="Orders">
+    {orders.map(order => (
+      <Button key={order.id} label={order.title} onClick={() => setOrderId(order.id)} />
+    ))}
+  </BottomSheet>
+  {/* Opens over the list; the list recedes and stays mounted. */}
+  <BottomSheet
+    isOpen={orderId != null}
+    onOpenChange={open => !open && setOrderId(null)}
+    label="Order">
+    <Button label="Edit" onClick={() => setIsEditing(true)} />
+    <Button label="Close all" onClick={closeAll} />
+  </BottomSheet>
+  <BottomSheet isOpen={isEditing} onOpenChange={setIsEditing} label="Edit order">
+    <Button label="Save" onClick={() => setIsEditing(false)} />
+  </BottomSheet>
+</>`,
+    },
+    {
+      label: 'Detail sheet inside the list sheet that opens it',
+      code: `function PlaceRow({place}) {
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <>
+      <Button label={place.name} onClick={() => setIsOpen(true)} />
+      {/* Rendered in the list sheet's content: stacks above it, leaves with it, and comes back with it while still open. */}
+      <BottomSheet isOpen={isOpen} onOpenChange={setIsOpen} label={place.name}>
+        <PlaceDetail place={place} />
+      </BottomSheet>
+    </>
+  );
+}
+
+<BottomSheet isOpen={isListOpen} onOpenChange={setIsListOpen} label="Places">
+  {places.map(place => <PlaceRow key={place.id} place={place} />)}
+</BottomSheet>`,
+    },
+    {
+      label: 'Deep link into a stack (several sheets open in one update)',
+      code: `// From a URL: list, order and editor open together. With no open order
+// between them, tree order decides: the list is at the bottom, the editor on top.
+const [isListOpen, setIsListOpen] = useState(() => route.list);
+const [orderId, setOrderId] = useState(() => route.orderId);
+const [isEditing, setIsEditing] = useState(() => route.edit);
+<>
+  <BottomSheet isOpen={isListOpen} onOpenChange={setIsListOpen} label="Orders">…</BottomSheet>
+  <BottomSheet isOpen={orderId != null} onOpenChange={open => !open && setOrderId(null)} label="Order">…</BottomSheet>
+  <BottomSheet isOpen={isEditing} onOpenChange={setIsEditing} label="Edit order">…</BottomSheet>
 </>`,
     },
     {
@@ -320,11 +397,11 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
-    'mobile touch sheet rising from the bottom edge (native <dialog>): grab handle, opt-in transform-based drag-to-resize snap points (snapPoints: viewport fraction, percent or px length), scrolling area resizes to the snapped visible height on release (a peek stop, a quarter of the sheet or less, keeps the full height and slides instead), Dialog-aligned dismissal purpose (info/form/required), purpose-gated swipe-to-dismiss, fully-expanded Tall visual-viewport mobile-keyboard handling, named height scale, Dialog-like container padding (padding prop, theme bottom-sheet padding, default --spacing-4), modal (default) or non-modal (hasScrim={false}) presentation',
+    'mobile touch sheet rising from the bottom edge (native <dialog>): grab handle, opt-in transform-based drag-to-resize snap points (snapPoints: viewport fraction, percent or px length), scrolling area resizes to the snapped visible height on release (a peek stop, a quarter of the sheet or less, keeps the full height and slides instead), Dialog-aligned dismissal purpose (info/form/required), purpose-gated swipe-to-dismiss, fully-expanded Tall visual-viewport mobile-keyboard handling, named height scale, Dialog-like container padding (padding prop, theme bottom-sheet padding, default --spacing-4), modal (default) or non-modal (hasScrim={false}) presentation; modal sheets stack in open order (covered sheet stays mounted, recedes 0.96/−8px then 0.92/−16px, blocked; one scrim; same-update opens ordered by tree; Escape/scrim/swipe pop the top sheet only; a sheet inside a closing sheet leaves with it and returns with it while still open)',
   usage: {
     anatomy,
     description:
-      'Mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport; use BottomSheetSwitcher for multi-step flows.',
+      "Mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport; for a multi-step flow give each step its own sheet and one state value naming the open step: a same-update close and open is a replace handoff (entering sheet above, retained sheet aligns then fades, one steady scrim, focus back to the flow's opener on close). Open a sheet over another to stack: each sheet keeps its own isOpen, the top sheet is the most recently opened one, the covered sheet recedes and is blocked, one scrim dims the page, and dismissal pops only the top sheet. Sheets rendered in a closing sheet's content leave with it (their isOpen stays yours; they return with the host while still open); siblings above it stay open.",
     bestPractices: [
       {
         guidance: true,
@@ -344,7 +421,12 @@ export const docsDense = {
       {
         guidance: false,
         description:
-          "Don't make the sheet content overly long. Consider breaking it into steps and using Bottom Sheet Switcher.",
+          "Don't make the sheet content overly long. Break it into steps, each its own sheet, with one state value naming the open step; moving on replaces one with the next.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't stack more than two or three sheets; replace steps (close one, open the next in one update) when they need not stay visible.",
       },
     ],
   },