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.mdindex 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 twiceoutside 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 thatone 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.mdindex 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 acurrent theme target or documented anatomy names stays. A component exceeds abudget 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 questionsNone.diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.mdindex 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,