Skip to content

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

TypeScript

docs(spec): admit BottomSheet as a container publisher (#6882)

Xinzi Zhouf4984589e75e
diff --git a/docs/architecture/container-padding.md b/docs/architecture/container-padding.md
index 32ed88f2ad..71cdcbfd72 100644
--- a/docs/architecture/container-padding.md
+++ b/docs/architecture/container-padding.md
@@ -6,8 +6,8 @@ id: architecture:container-padding
authority: current
archive_reason: null
superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-09-22
+approved_by: imdreamrunner
+approved_at: 2026-10-04
owners: [cixzhang, imdreamrunner]
applies_to:
[
@@ -37,6 +37,7 @@ verified_by:
packages/core/src/Layout/Layout.test.tsx,
packages/core/src/Layout/LayoutSlots.test.tsx,
packages/core/src/Layout/overlayPaddingReset.test.tsx,
+ packages/core/src/BottomSheet/BottomSheetPanel.test.tsx,
packages/core/src/Layout/__tests__/edgeCompensation.test.tsx,
packages/core/src/List/List.test.tsx,
packages/core/src/TabList/TabList.test.tsx,
@@ -77,9 +78,10 @@ The protocol has four layers:
public spacing scale. Theme component overrides may set supported padding
properties. `architecture:theme-authoring-contract` and
`architecture:component-theming-surface` own those public surfaces.
-2. **Container lowering.** `container()` resolves Card, Section, and Dialog
- padding into internal logical-edge variables. An explicit component padding
- prop may publish the same geometry through the maps in `padding.stylex.ts`.
+2. **Container lowering.** `container()` resolves Card, Section, Dialog, and
+ BottomSheet padding into internal logical-edge variables. An explicit
+ component padding prop may publish the same geometry through the maps in
+ `padding.stylex.ts`.
3. **Descendant geometry.** Four inherited `--container-padding-*` variables
carry the inset that bleed descendants subtract. Container publishers and
explicit region-padding paths couple those variables to their padding.
@@ -96,7 +98,7 @@ The protocol has four layers:
| Role | Participants | Contract responsibility |
| -------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Container publisher | Card, Section, Dialog, ScrollableArea | Resolve component padding or publish explicit content-box padding as logical-edge and Layout inset variables |
+| Container publisher | Card, Section, Dialog, BottomSheet, ScrollableArea | Resolve component padding or publish explicit content-box padding as logical-edge and Layout inset variables |
| Region publisher | LayoutHeader, LayoutContent, LayoutFooter, LayoutPanel | Publish baseline or explicit-padding geometry; automatic outer-edge publication has the conformance gap below |
| Bleed consumer | Section, ScrollableArea, Layout, Divider, Table | Subtract inherited inset on the edges each component is designed to escape; ScrollableArea does so only with `isFullBleed` |
| Edge-compensation consumer | TabList; List/ListItem rows (admitted) | Move visible content toward the container content line while retaining component-owned interaction padding; exact alignment depends on each component's bounded geometry |
@@ -111,6 +113,14 @@ compensation geometry, List is the admitted next consumer, and Toolbar consumes
alignment geometry. Participation here does not by itself make any of those
components a member of `family:layout-regions`.
+BottomSheet publishes the way Dialog does. Its Sheet panel is the overlay
+boundary owner, and its scrolling Content area is a container publisher that
+pads caller content and publishes the applied inset. The inset resolves from the
+`padding` prop on the public spacing scale, then the theme's `padding` properties
+on the `bottom-sheet` component. With neither, the Content area keeps its
+released default: no inset, and descendants see the boundary's reset values.
+This prop and theme property are BottomSheet's projection of container lowering.
+
Edge compensation is a two-sided geometry contract, not a token contract:
1. **Host side.** An eligible container or region state publishes the padding
@@ -283,12 +293,12 @@ evidence, not part of this documentation stack.
alias through its approved compatibility window, moves maintained examples to
the canonical name, and tests both paths before removal.
- Changing `container()` or the public-to-private padding lowering reviews Card,
- Section, Dialog, Layout regions, and overlay behavior together.
+ Section, Dialog, BottomSheet, Layout regions, and overlay behavior together.
- Changing overlay hosting or adding an overlay root verifies that stale page
geometry stops at the new boundary without suppressing public theme values.
-- A component that wants a new public full-bleed mode or padding prop follows
- its component/family API review; this architecture does not authorize that
- API. `component:List` owns List's first new projection, and
+- A component other than BottomSheet that wants a new public full-bleed mode or
+ padding prop follows its component/family API review; this architecture does
+ not authorize that API. `component:List` owns List's first new projection, and
`component:TabList` owns its existing behavior and migration. This record does
not authorize another component projection.
@@ -300,8 +310,8 @@ evidence, not part of this documentation stack.
logical-edge setters, Section propagation, and the overlay reset.
- `packages/core/src/Layout/edgeCompensation.stylex.ts` — owns the container-side
alignment adjustment for marked edge content.
-- Card, Section, Dialog, ScrollableArea, and Layout region implementations —
- publish their current geometry.
+- Card, Section, Dialog, BottomSheet, ScrollableArea, and Layout region
+ implementations — publish their current geometry.
- Section, ScrollableArea, Layout, Divider, Table, TabList, and Toolbar
implementations — consume the current geometry for bleed or alignment.
- TabList currently lowers its component-owned projection; List owns its admitted
@@ -329,6 +339,7 @@ evidence, not part of this documentation stack.
| INV2, INV5 | `Section.test.tsx` per-edge and nested-propagation tests | A per-edge prop leaves a stale geometry variable, or nested Sections lose the shipped propagation order |
| INV2, INV3, INV8 | `ScrollableArea.test.tsx` padding and full-bleed tests | The content box publishes inset different from its applied padding, or the viewport escapes inherited padding without explicit full bleed |
| INV4 | Layout source review plus `Layout.test.tsx` and `LayoutSlots.test.tsx` | Slot presence stops selecting the shipped applied outer/inner edge styles; exact republished geometry remains limited by the named conformance gap |
+| INV2 | `BottomSheetPanel.test.tsx` padding tests | The Content area publishes an inset that differs from its applied padding, or the `padding` prop or theme `padding` does not reach it |
| INV6 | `overlayPaddingReset.test.tsx` | An overlay inherits page inset, loses its theme's Section padding, or lets ancestor Section propagation cross the boundary |
| INV3, INV7 | `Layout/__tests__/edgeCompensation.test.tsx` plus component tests | An unmarked child is compensated, or marked edge content loses direct-child discoverability |
| INV9, INV10 | `List.test.tsx` plus real-browser geometry evidence | The header moves; a row reads the wrong logical edge, diverges from themed/density padding, applies the wrong bounded movement, or loses paint inset |
diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.md
index fa0f0dbd44..782be64cb0 100644
--- a/packages/core/src/BottomSheet/BottomSheet.spec.md
+++ b/packages/core/src/BottomSheet/BottomSheet.spec.md
@@ -9,7 +9,7 @@ superseded_by: null
approved_by: null
approved_at: null
owners: [cixzhang]
-review_triggers: [theming]
+review_triggers: [theming, layout, public-api]
verified_by:
[
packages/core/src/BottomSheet/BottomSheet.test.tsx,
@@ -23,7 +23,11 @@ modules: []
families: [family:overlay-dismissal]
design_specs: []
architecture:
- [architecture:component-theming-surface, architecture:layer-runtime]
+ [
+ architecture:component-theming-surface,
+ architecture:container-padding,
+ architecture:layer-runtime,
+ ]
contributing: []
system_specs: [spec:AST-025]
---
@@ -34,14 +38,14 @@ system_specs: [spec:AST-025]
BottomSheet presents caller-provided content in a panel that rises from the
bottom edge. This draft records current consumer anatomy, keyboard-reachable
-scrolling, and theming reachability without changing public API.
+scrolling, theming reachability, and the Content area's container padding.
## Compatibility and migration
-- Released default preserved: `yes`
-- Compatibility class: additive internal content box and shared scroll behavior;
- public props, defaults, targets, and caller child ordering inside the content box
- remain unchanged
+- Released default preserved: `yes` — with no `padding` prop and no theme
+ padding, the Content area has no inset
+- Compatibility class: additive `padding` prop. A theme's `padding` on
+ `bottom-sheet` now insets the Content area instead of the Sheet panel
- Controlled/uncontrolled behavior: unchanged
- Migration decision: none
@@ -54,6 +58,8 @@ Consumer migration instructions belong in consumer docs and release notes.
- The visual Sheet panel and its current `bottom-sheet` target.
- The scrolling Content area, its shared viewport/content-box integration, and
automatic keyboard-path selection.
+- The Content area's container padding, published per
+ `architecture:container-padding`.
- Standalone sheet presentation, including its optional native-dialog Scrim.
**Does not own / non-goals**
@@ -77,6 +83,7 @@ in `BottomSheet.doc.mjs`.
| 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, none by default, and publishes the applied inset to descendants as a container publisher. | `architecture:container-padding` | Admitted; implementation pending |
### Allowed variation
@@ -94,7 +101,9 @@ in `BottomSheet.doc.mjs`.
### Transformation and precedence order
-- No new height, gesture, motion, or styling precedence rule is introduced.
+- Content area inset: the `padding` prop, then the theme's `padding` properties
+ on `bottom-sheet`, then no inset.
+- No new height, gesture, or motion precedence rule is introduced.
### Performance and resources
@@ -116,7 +125,7 @@ in `BottomSheet.doc.mjs`.
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
| ---------------- | ------------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
| Sheet panel | Presents the painted bottom-edge surface and owns panel geometry and motion. | Current source and public docs | Prominent | FR1, FR2 |
-| Content area | Provides the scrolling area for caller-provided sheet content. | Current source and tests | Prominent | FR1, FR2 |
+| Content area | Provides the scrolling, inset area for caller-provided sheet content. | Current source and tests | Prominent | FR1, FR2, FR4 |
| Handle | Presents the decorative grab affordance and owns the panel's drag interaction region. | Current source and tests | Supporting | FR1, FR2 |
| Scrim | Dims and blocks the page in a scrim-backed host. | Current source and public docs | Supporting | FR1, FR2 |
@@ -153,6 +162,8 @@ a decision that they must remain unthemeable.
- `architecture:component-theming-surface` owns anatomy qualification, target
mapping, and factual `none` dispositions.
+- `architecture:container-padding` owns the shared container inset protocol and
+ admits the Content area as a container publisher.
- `architecture:layer-runtime` owns the current native-dialog host distinction
and records that sheets retain local scrim and swipe behavior.
- `spec:AST-025` owns effective scroll measurement, overflow and containment,
@@ -168,6 +179,7 @@ a decision that they must remain unthemeable.
| FR1 | `BottomSheet.test.tsx` render, content, Handle, and scrim behavior suites | Modal, non-modal, and switcher presentations | Removing a documented part fails existing content, structure, or dismissal assertions. | `audit:BottomSheet/anatomy` |
| FR2 | Panel target assertion, source inspection, and theming target inventories | Sheet panel, Content area, Handle, and Scrim | Removing the panel target or documenting an unshipped child target fails evidence or inventory. | `audit:BottomSheet/theming` |
| FR3, AR1–AR2 | `BottomSheetKeyboard.test.tsx`; `BottomSheetKeyboard.a11y.browser.spec.ts`; open Storybook stories | fitting/overflow, plain text, usable/unusable/dynamic descendants, focus | Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails. | `audit:BottomSheet/accessibility` | | Layout evidence | `BottomSheetPanel.test.tsx` | Floating Handle and scrolling Content area | Reordering or merging the stable parts fails existing panel structure and style assertions. | `audit:BottomSheet/anatomy` |
+| FR4 | `BottomSheetPanel.test.tsx` container padding tests; `derivedVarRegistry.test.ts` | default, `padding` prop, theme `padding`, lone padded Section child | The published inset differs from the applied padding, or the default sheet changes geometry. | `audit:BottomSheet/anatomy` |
| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:BottomSheet/theming` |
Existing tests directly assert the Sheet panel target, Content area placement,