Skip to content

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

TypeScript

spec: an open layer may render up to 5 more elements under touch, with no new anatomy (#8439)

Cindy Zhang67dc45f66d3c
diff --git a/docs/architecture/component-style-authoring.md b/docs/architecture/component-style-authoring.md
index 400d5627c6..6b16ed7859 100644
--- a/docs/architecture/component-style-authoring.md
+++ b/docs/architecture/component-style-authoring.md
@@ -17,7 +17,7 @@ verified_by:
internal/eslint-plugin-astryx/no-stylex-null-override.test.mjs,
internal/eslint-plugin-astryx/no-style-only-wrapper.test.mjs,
]
-deciding_specs: [spec:AST-080/DEC-4, spec:AST-017/DEC-26]
+deciding_specs: [spec:AST-080/DEC-4, spec:AST-017/DEC-26, spec:AST-017/DEC-29]
---
# Component style authoring architecture
@@ -146,7 +146,8 @@ not evidence of conformance or violation.
- **Layers while open** — Popover, BottomSheet, DropdownMenu, ContextMenu,
Lightbox, and Dialog: one presentation mounted, no content mounted twice
outside the transient copy above, and the open layer under a coarse
- pointer has at most as many elements as under a fine pointer.
+ pointer has at most as many elements as under a fine pointer (beyond that,
+ only by the open-layer allowance `spec:AST-017` FR60 and DEC-29 set).
Good: when a segmented control's selected label gets heavier, CSS on that
one label element keeps the segment's width; Popover mounts its surface once
@@ -281,13 +282,13 @@ RSC owners retain the delegated decisions above.
## Verification
-| Invariant | Evidence | Failure signal |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| INV1 | StyleX capability scan plus component-source mutation | Shipped component styling bypasses the maintained lowering path without another named owner, including component-local raw CSS where that path supports the same result |
-| INV2 | Equivalent CSS/JS mutation fixtures and real-browser presentation | JavaScript recreates CSS-resolvable presentation, flashes intermediate state, or disagrees with CSS conditions |
-| INV3 | StyleX compile fixtures and independent consumer-property override mutations | Input lowers to invalid CSS or changing one supported property cannot compose without removing another |
-| INV4 | Nested unrelated-owner browser fixture across hover, focus-within, active, and disabled states | Outer component state activates an inner component's visual treatment |
-| INV5 | Wrapper mutations in default and host-composed render paths | Removing a wrapper changes no semantic, behavior/ref, formatting-context, outside-border-spacing, or required style-bearing DOM boundary |
-| INV6 | Pull-request size report against base, with value-table import fixtures | A changed component with no base-against-head gzip JavaScript or CSS figure; a touch-only feature over 2 KB gzip JavaScript or 1 KB gzip CSS per component that is not flagged; importing a component pulls in value-table rows only other components read |
-| INV7 | Story element counts (`document.body.querySelectorAll('*').length`) at rest and open under a fine and a coarse pointer, base against head, plus render inspection for duplicated content | An element beyond the component's roles, themable parts, and INV5 wrappers, or a duplicated or hidden twin of content; a state or variant rendered as an extra element; a pseudo-element repeating content; a layer with two presentations mounted outside the transient copy, content mounted twice, more elements under a coarse pointer than a fine one, a transient copy made by a component itself, or one left past 1 second; an added element with no measured counts, or a budget exceeded with no recorded owner exception |
-| Capability registry | Registry generation against the installed StyleX package | Recorded and installed StyleX versions differ, so capability-dependent cases are untestable |
+| Invariant | Evidence | Failure signal |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| INV1 | StyleX capability scan plus component-source mutation | Shipped component styling bypasses the maintained lowering path without another named owner, including component-local raw CSS where that path supports the same result |
+| INV2 | Equivalent CSS/JS mutation fixtures and real-browser presentation | JavaScript recreates CSS-resolvable presentation, flashes intermediate state, or disagrees with CSS conditions |
+| INV3 | StyleX compile fixtures and independent consumer-property override mutations | Input lowers to invalid CSS or changing one supported property cannot compose without removing another |
+| INV4 | Nested unrelated-owner browser fixture across hover, focus-within, active, and disabled states | Outer component state activates an inner component's visual treatment |
+| INV5 | Wrapper mutations in default and host-composed render paths | Removing a wrapper changes no semantic, behavior/ref, formatting-context, outside-border-spacing, or required style-bearing DOM boundary |
+| INV6 | Pull-request size report against base, with value-table import fixtures | A changed component with no base-against-head gzip JavaScript or CSS figure; a touch-only feature over 2 KB gzip JavaScript or 1 KB gzip CSS per component that is not flagged; importing a component pulls in value-table rows only other components read |
+| INV7 | Story element counts (`document.body.querySelectorAll('*').length`) at rest and open under a fine and a coarse pointer, base against head, plus render inspection for duplicated content | An element beyond the component's roles, themable parts, and INV5 wrappers, or a duplicated or hidden twin of content; a state or variant rendered as an extra element; a pseudo-element repeating content; a layer with two presentations mounted outside the transient copy, content mounted twice, more elements under a coarse pointer than a fine one beyond the allowance of `spec:AST-017` FR60, a transient copy made by a component itself, or one left past 1 second; an added element with no measured counts, or a budget exceeded with no recorded owner exception |
+| Capability registry | Registry generation against the installed StyleX package | Recorded and installed StyleX versions differ, so capability-dependent cases are untestable |
diff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.md
index 6f97412124..0014be414a 100644
--- a/docs/specs/AST-017/spec.md
+++ b/docs/specs/AST-017/spec.md
@@ -762,6 +762,18 @@ one removal merged ahead of the decision to allow it.
or merging undocumented elements to meet it is compatible (FR3); an element a
current theme target or documented anatomy names stays. A component exceeds a
budget only through an owner exception recorded with its element counts.
+ Under touch, a component renders no more elements than under a fine pointer,
+ except that a layer, a surface mounted only while open (a sheet, popover,
+ menu, context menu, dialog, toast, or lightbox), may render up to 5 more
+ elements while open, and fewer is preferred (DEC-29). Each added element is
+ an internal node with a job its component's record names; the allowance
+ adds no anatomy part and no theme target. Decoration, such as a pill, an
+ edge tint, a shadow, or a tint, SHOULD be drawn by a pseudo-element or an
+ existing element. While closed, a layer and its trigger render no more
+ elements than under a fine pointer. Repeated components, such as rows, list
+ items, and controls like Button, Switch, and CheckboxInput, keep the strict
+ budget, at rest and pressed. Anything beyond this needs an owner exception
+ with before and after counts.
### Platform support
@@ -914,7 +926,7 @@ lands, maintainers apply its requirement in review and release approval.
| FR53 | Changeset classification review against the governing component record's accessibility evidence | a fix that replaces documented keyboard or focus behavior to meet an adopted APG pattern's required parts; a fix that changes a role, state, or accessible name to meet WCAG 2.2 A/AA; a fix that adds an optional prop | An accessibility fix is held for a minor, given a coexistence path, or classified `[breaking]`; or a change that needs an app-layer code edit, or that removes, renames, or narrows public surface, ships as an accessibility `[fix]` |
| FR54 | Changeset classification review against the surface's current record, then the same tier admission every Changeset receives | a CLI correction the CLI record classifies as `[fix]`; a CLI change the CLI record leaves undecided; a CLI change the CLI record classifies as `[breaking]` on a patch plan; a component change | A non-component change is classified by a rule this record restates instead of its surface record, a surface rule turns on risk or adoption, a surface-classified `[breaking]` change ships in a patch or a surface rule makes it patch-eligible, or a component change is classified by a surface record |
| FR59 | Pull request review of fine-pointer before-and-after evidence | a touch change that also fixes a defect fine-pointer users hit; a deliberate cross-device consistency change; a touch-only change; a new fine-pointer look proposed with touch work | A touch change alters fine-pointer behavior or appearance with neither reason, shows no fine-pointer before-and-after evidence, or ships a new fine-pointer look without its own owner decision |
-| FR60 | Element counts per story at rest and open, fine and coarse pointer, against architecture INV7 | a surface component at rest; an open layer; a DOM reduction; a recorded exception | An element beyond INV7's budgets with no recorded owner exception, a hidden twin or second presentation, or a DOM reduction that removes a theme target or documented anatomy, or that is classified as breaking |
+| FR60 | Element counts per story at rest and open, fine and coarse pointer, against architecture INV7 | a surface component at rest; an open layer; a DOM reduction; a recorded exception; an open layer under touch with extra elements | An element beyond INV7's budgets with no recorded owner exception, a hidden twin or second presentation, or a DOM reduction that removes a theme target or documented anatomy, or that is classified as breaking; an open layer more than 5 elements over its fine-pointer count, an added element that is themeable, a new anatomy part, or without a job in its record, or a closed layer, trigger, or repeated component above its fine-pointer count |
## Decision log
@@ -1420,6 +1432,20 @@ DEC-27 requires.
Rejected: an `experimental_` name prefix.
+### DEC-29 — An open layer may render up to 5 more elements under touch
+
+**Reference:** `spec:AST-017/DEC-29`
+**Decider:** `cixzhang`, `2026-10-25`
+
+Pages render few layers at once, so an open layer can afford a small, fixed
+allowance that rows and controls, repeated across a page, cannot. The
+allowance covers internal elements with named jobs and never adds anatomy or
+theme targets, so themes and docs see the same parts on every pointer.
+Decoration belongs on pseudo-elements and existing elements, and each
+implementation tries to use fewer than the allowance.
+
+Rejected: strict parity for layers, with an owner exception for every sheet frame.
+
## Open questions
None.
diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.md
index bfe8299218..2337776fbf 100644
--- a/packages/core/src/BottomSheet/BottomSheet.spec.md
+++ b/packages/core/src/BottomSheet/BottomSheet.spec.md
@@ -116,7 +116,22 @@ in `BottomSheet.doc.mjs`.
### Performance and resources
-- No new performance or resource rule is introduced.
+- Element jobs (`architecture:component-style-authoring` INV7; the
+ open-layer allowance of `spec:AST-017` FR60, DEC-29). An open sheet's frame
+ has these elements, each with one job:
+ - the dialog carries the sheet's dialog role, and modality and the top
+ layer when the sheet is modal;
+ - the positioner holds the panel at the block end;
+ - the panel paints the `bottom-sheet` target;
+ - the grabber bar is the drag handle, and its pill draws the handle;
+ - the body is the scroll area;
+ - the content box carries the padding and is the observed content box (FR3);
+ - the edge tint gives iOS Safari's toolbar the sheet's color.
+- Fewer is preferred: the pill and the edge tint are decoration that should
+ move to pseudo-elements, and the positioner should merge into the panel;
+ each is an open gap.
+- Elements a presenting component adds beyond this frame are its own to
+ justify.
## Accessibility contract
@@ -191,6 +206,7 @@ a decision that they must remain unthemeable.
| 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 a lone padded Section changes geometry. | `audit:BottomSheet/anatomy` |
+| Element jobs | Open-sheet element count test against the named job list | modal and non-modal sheet, scrim and no scrim | An element in the open sheet's frame with no named job, or a named job with no element |
| 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,