An open source design system that's fully customizable and agent ready
TypeScript
docs(AST-105, AST-108): glides and tap-to-expand play the theme's motion tokens (#9964)
Cindy Zhanga0c48b8d7359
diff --git a/docs/specs/AST-105-animated-layout/spec.md b/docs/specs/AST-105-animated-layout/spec.mdindex cb4addf33b..25a05afe64 100644--- a/docs/specs/AST-105-animated-layout/spec.md+++ b/docs/specs/AST-105-animated-layout/spec.md@@ -32,8 +32,8 @@ affects_consumer_docs:## IntentWhen something inside an area changes size, the changed element and the-content after it animate together on one shared motion role instead of-jumping. An app opts in once per area; without it, nothing changes, except where a+content after it animate together on one shared motion instead of jumping,+on the theme's curve tokens, timed by its `character` and `tempo`. An app opts in once per area; without it, nothing changes, except where acomponent's record animates its own change (FR2).## Non-goals@@ -85,13 +85,17 @@ const animatedLayout = useAnimatedLayout({containerRef: scrollRef});of it opts in. Several changes in one area, nested or not, compose: eachelement moves once, by its total change. The area never scrolls because ofthe glide.-- **FR4 — One shared motion.** The changed element plays its own animation,- entering, exiting, or resizing, and the content after it moves with it.- Both read the same motion role, `springs.settle` (`spec:AST-094`- FR4), so the timing is governed centrally, never per component; both start- on the same frame, and Reduce Motion reaches both through that role, as- `design:reduced-motion` DR1–DR3 require: a cross-fade under a coarse- primary pointer, an immediate change otherwise.+- **FR4 — One shared motion on the theme's curve tokens.** The changed+ element plays its own animation, entering, exiting, or resizing, and the+ content after it moves with it. Both play the same motion, so the timing is+ governed centrally, never per component: the theme's move curve,+ `--ease-move`, over `--duration-medium-min`, which follow the theme's+ `character` and `tempo` (`spec:AST-108` FR1, FR2). The glide is curve+ tokens, never a spring, and no character or option plays a+ platform-measured curve for it (`spec:AST-094` FR45). Both start on the same+ frame, and Reduce Motion reaches both, as `design:reduced-motion` DR1–DR3+ require: a cross-fade under a coarse primary pointer, an immediate change+ otherwise.- **FR5 — Every pointer.** The glide applies under every pointer, a mouseincluded: it removes a layout jump that people using a fine pointer seetoo, so it is a named fine-pointer change under `spec:AST-017` FR59, and@@ -104,7 +108,8 @@ const animatedLayout = useAnimatedLayout({containerRef: scrollRef});- **FR7 — Documentation.** The hook's documentation reads: "Returns a handleto pass to a component whose size changes, such as TreeList or Collapsible.When that component changes size, it and the content after it inside- `containerRef` animate together on one shared motion role. Fixed and stuck+ `containerRef` animate together on one shared motion that follows the+ theme's motion tokens and tempo. Fixed and stucksticky elements stay put, the glide never scrolls the area, and ReduceMotion is respected."- **FR8 — Two elements can swap in place.** An area can swap one element for@@ -133,7 +138,7 @@ const animatedLayout = useAnimatedLayout({containerRef: scrollRef});so the content beside the edge glides with it and no gap opens. An optionaltwo-state form holds the element's old state as FR8's swap holds it, whilethe element rides the glide of the content beside its moving edge; a reversal- from the shown state springs from where it is. Under Reduce Motion it follows+ from the shown state starts from where it is. Under Reduce Motion it follows`design:reduced-motion` DR2 under a coarse primary pointer and DR3 otherwise.Every edge reveal in Core is this one:- Collapsible, TreeList and Table's row expansion keep its block-end form@@ -211,20 +216,24 @@ Out of coverage, each taking its final place at once:- `architecture:react-component-runtime` INV12 produces the glide.- `architecture:react-component-runtime` INV12 also gains the in-place swap(FR8); no component swaps yet.+- The glide, the in-place swap and the edge reveal play `springs.settle`+ today; FR4 moves them to `--ease-move` over `--duration-medium-min`. The+ SideNav rail and AppShell's content area, which share that motion+ (`component:SideNav` FR6, `component:AppShell` FR17), follow with them.- INV12 also produces the edge reveal (FR9). SideNav's rail clip and ride moveinto it from SideNav's own code, and a resizable LayoutPanel's collapse andopen, which today jump, adopt it; LayoutPanel's docs say a collapse slides.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| ------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| FR1, FR2 | Unit and browser tests with and without a handle | a handle on TreeList; no handle; a ScrollableArea ref | a handle with public members, behavior that changes without a handle, or ScrollableArea registering itself fails |-| FR3, Coverage | Real-browser tests, one per Coverage row | each Coverage row; mixed Astryx and plain content; two changes in one frame; an area scrolled mid-list | an element that behaves other than its row says, an element moved twice for one frame, content past the area that moves, or the area scrolling fails |-| FR4 | Real-browser frame capture under a coarse and a fine pointer, with and without Reduce Motion | a changed element and its visible followers | starting on different frames or reading different motion, a component-specific timing, or Reduce Motion applied to one and not the other fails |-| FR5 | Fine-pointer before-and-after evidence on each adopting pull request, from the component's Storybook story | a mouse on each adopting component | a glide missing under a mouse, or an adopting pull request without that evidence, fails |-| FR8 | Unit tests of the swap and real-browser proofs of its adopters | a fast load, a slow load, a forward and a back page change, Reduce Motion | an empty area during a swap, a placeholder flashed for a fast load, travel under Reduce Motion, a layer exit played by it, or a public export fails |-| FR9 | Unit tests of the reveal's measurement and real-browser frame capture of each adopter | Collapsible opening; the SideNav rail collapsing and expanding; a start and an end LayoutPanel collapsing and opening by toggle, Enter, the grow arrow, a controlled change and a drag past the threshold; a drag reopening a pane; a hook-only pane; focus inside a collapsing pane; Reduce Motion | a gap opening beside a moving edge, two motions for one rail collapse, a reveal during a drag that reopens a pane, a reveal on a hook-only pane, focus left inside a concealed pane, a concealed pane reachable by Tab, or a public export fails |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, FR2 | Unit and browser tests with and without a handle | a handle on TreeList; no handle; a ScrollableArea ref | a handle with public members, behavior that changes without a handle, or ScrollableArea registering itself fails |+| FR3, Coverage | Real-browser tests, one per Coverage row | each Coverage row; mixed Astryx and plain content; two changes in one frame; an area scrolled mid-list | an element that behaves other than its row says, an element moved twice for one frame, content past the area that moves, or the area scrolling fails |+| FR4 | Real-browser frame capture under a coarse and a fine pointer, with and without Reduce Motion | a changed element and its visible followers at each `character`, and at `tempo` 0.75 and 1.5 | starting on different frames or reading different motion, a component-specific timing, a glide that ignores the theme's `character` or `tempo`, a spring or a platform-measured curve played for the glide, or Reduce Motion applied to one and not the other fails |+| FR5 | Fine-pointer before-and-after evidence on each adopting pull request, from the component's Storybook story | a mouse on each adopting component | a glide missing under a mouse, or an adopting pull request without that evidence, fails |+| FR8 | Unit tests of the swap and real-browser proofs of its adopters | a fast load, a slow load, a forward and a back page change, Reduce Motion | an empty area during a swap, a placeholder flashed for a fast load, travel under Reduce Motion, a layer exit played by it, or a public export fails |+| FR9 | Unit tests of the reveal's measurement and real-browser frame capture of each adopter | Collapsible opening; the SideNav rail collapsing and expanding; a start and an end LayoutPanel collapsing and opening by toggle, Enter, the grow arrow, a controlled change and a drag past the threshold; a drag reopening a pane; a hook-only pane; focus inside a collapsing pane; Reduce Motion | a gap opening beside a moving edge, two motions for one rail collapse, a reveal during a drag that reopens a pane, a reveal on a hook-only pane, focus left inside a concealed pane, a concealed pane reachable by Tab, or a public export fails |## Decision log@@ -244,6 +253,19 @@ element, inside the area and only where it is visible.Rejected: wrapping following content in an element, and opting in eachfollowing element.+### DEC-2 — The glide plays the theme's curve tokens++**Reference:** `spec:AST-105/DEC-2`+**Decider:** `cixzhang`, `2026-11-04`++A glide is a move like any other, so it takes the theme's move curve and+duration, and a theme that sets `character` or `tempo` sees its glides change+with the rest of its motion, under every pointer. A tap that expands or+collapses content carries no velocity, so the glide that follows plays curve+tokens, never a spring (`spec:AST-094` FR45).++Rejected: the measured spring as the glide; a platform-measured opt-in, such as a separate character.+## Open questionsNone.diff --git a/docs/specs/AST-108-theme-motion/spec.md b/docs/specs/AST-108-theme-motion/spec.mdindex ad2cd5e658..cffa239ea7 100644--- a/docs/specs/AST-108-theme-motion/spec.md+++ b/docs/specs/AST-108-theme-motion/spec.md@@ -64,7 +64,11 @@ defineTheme({motion duration;- `character` is `'crisp'`, `'standard'` (default), or `'expressive'`; itpicks the entrance and move curves and the spring bounce. A continuous bounce- is not offered;+ is not offered. No character turns a curve into a spring or plays a+ platform-measured curve; which motion springs and which plays the curve+ tokens is `spec:AST-094` FR45's, and tap-started expand and collapse,+ including the animated-layout glide (`spec:AST-105` FR4), plays the curve+ tokens;- `reducedMotion` is `'system'` (default) or `'always'`; `'always'` applies`design:reduced-motion` DR1–DR3 for everyone, and `'system'` follows eachperson's setting. No value loosens Reduce Motion.diff --git a/docs/specs/components/AppShell/AppShell.spec.md b/docs/specs/components/AppShell/AppShell.spec.mdindex 00620f5e97..86f6c270a4 100644--- a/docs/specs/components/AppShell/AppShell.spec.md+++ b/docs/specs/components/AppShell/AppShell.spec.md@@ -185,7 +185,7 @@ the only component record in the AppShell root.| FR14 | Main content stays mounted across the breakpoint (`family:layout-regions` FR9); in addition, input values and focus inside `children` survive in both directions. | Current source and tests || FR15 | `className`, `style`, and `xstyle` merge onto the root after component styles. | Current source || FR16 | With `elevated`, a present `topNav`, and an inline side nav, the content area is a raised surface whose block-start, inline-start corner uses the page radius; otherwise the content wrapper creates no layout box. | Current source and stories |-| FR17 | While the side nav collapses or expands, the content area swaps its old wrap for its new one in place: the old wrap slides and fades out while the new wrap slides and fades in, on the side nav's one clock, `spec:AST-105` FR4's one shared motion (`springs.settle`; `component:SideNav` FR6). Before the side nav's first paint, a change it did not make with its own toggle lands at once, and the content area lands with it. So the initial state never animates. The old wrap is one transient copy, inert and hidden from assistive technology, removed when the swap ends (`architecture:component-style-authoring` INV7). When the old wrap is not copied, such as on a page too large to copy, no visible gap opens between the rail and the content during an expand. The content area never animates its width. Under reduced motion the swap follows `design:reduced-motion` DR2 under a coarse primary pointer and DR3 otherwise. | `spec:AST-105` FR8; `component:SideNav` FR6 |+| FR17 | While the side nav collapses or expands, the content area swaps its old wrap for its new one in place: the old wrap slides and fades out while the new wrap slides and fades in, on the side nav's one clock, `spec:AST-105` FR4's one shared motion, the theme's curve tokens, never a spring (`component:SideNav` FR6). Before the side nav's first paint, a change it did not make with its own toggle lands at once, and the content area lands with it. So the initial state never animates. The old wrap is one transient copy, inert and hidden from assistive technology, removed when the swap ends (`architecture:component-style-authoring` INV7). When the old wrap is not copied, such as on a page too large to copy, no visible gap opens between the rail and the content during an expand. The content area never animates its width. Under reduced motion the swap follows `design:reduced-motion` DR2 under a coarse primary pointer and DR3 otherwise. | `spec:AST-105` FR8; `component:SideNav` FR6 || FR18 | AppShell is a layout root: at its root it applies Layout's `layoutReset` (`component:Layout` FR8), resetting every layout value its ancestors pass down, so its header, side, and main regions lay out the same inside a padded card, inside a Layout, or at the page root. The published container padding (`--container-padding-inline-start`, `--container-padding-inline-end`, `--container-padding-block-start`, `--container-padding-block-end`) resets to zero, so AppShell's Layout escapes nothing (`component:Layout` FR2). The Layout inset and region values (`--layout-padding-outer-x`, `--layout-padding-outer-y`, `--layout-padding-own-outer-x`, `--layout-padding-own-outer-y`, `--layout-padding-inner-x`, `--layout-padding-inner-y`, `--layout-content-width`, `--layout-alignment-width`, `--_layout-flush-block-start`, `--_layout-flush-block-end`), Section padding propagation (`--_section-padding-propagated`), and the container height cap (`--container-max-height`) reset to unset, as at the page root. The Layout area, slot, and divider-default contexts (`LayoutAreaContext`, `LayoutSlotsContext`, `LayoutDividerContext`) reset to their defaults. These names are internal protocol, not theme API (`architecture:container-padding` INV1). A caller's own props and styles on AppShell (`height`, `variant`, `contentPadding`, `mobileNav`, `className`, `style`, `xstyle`) still apply after the reset (FR15). Theme tokens, color mode, writing direction, and translations keep inheriting. | DEC-1; `architecture:container-padding` INV6 (the same reset at overlay roots) |### Allowed variationdiff --git a/docs/specs/components/SideNav/SideNav.spec.md b/docs/specs/components/SideNav/SideNav.spec.mdindex f12993ec9b..38d27c73db 100644--- a/docs/specs/components/SideNav/SideNav.spec.md+++ b/docs/specs/components/SideNav/SideNav.spec.md@@ -113,14 +113,14 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis | Draft review state |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1 | SideNav renders its navigation children in a scrollable list, which may be grouped by SideNavSection. A SideNavItem with children renders them, after its own row, in a group labelled by the parent's label; unless `collapsible` is `false`, the group expands and collapses and is hidden from assistive technology and inert while collapsed. | Current source, docs, and tests | Current behavior |-| FR2 | In a collapsed rail, a SideNavItem without an icon is not rendered; a leaf item renders icon-only, named by a non-blank caller `aria-label` or else its label; an item with children renders an icon-only trigger that opens a flyout listing its children as the flyout's top level. | Current source, docs, and tests | Current behavior |-| FR3 | In an expanded rail, in a flyout, and in the mobile navigation drawer, every SideNavItem row MUST span the full inline size of its list at any depth. A row at depth `n` MUST start its content `n` × `--spacing-6` beyond the row's own inline-start padding for its size, inside the row; the nested group MUST add no inset. A flyout's top level is depth 0. | `component:SideNav/DEC-1` | Settled intent; implementation may be staged |-| FR4 | The indent area MUST be part of the row's target: a click there, including a modified or middle click on a link row, does what the same click on the row's primary element does. When the row also carries an independent expand toggle or `actions`, the indent belongs to the primary link or button, and the toggle and actions keep their own activation at the row's trailing edge. | `component:SideNav/DEC-1`; `family:navigation-destinations` | Settled intent; implementation may be staged |-| FR5 | An expanded nested group MUST NOT clip its rows once it has finished opening, so a nested row's focus ring paints in full. The group MAY clip while collapsed and while it opens or closes. | `component:SideNav/DEC-1` | Settled intent; implementation may be staged |-| FR6 | Collapsing or expanding the rail plays one motion on one clock, `spec:AST-105` FR4's one shared motion (`springs.settle`): layout snaps to the final rail width at once, with no width animation, and the rail reveals or covers its labels by a clip, its edge riding the main content's glide and its labels and collapsed icons fading on the same clock (`spec:AST-105` FR9's inline two-state form; the clip and the ride are the shared edge reveal's, and SideNav's own code keeps only the fades; the rail lends no pane to its resize controller, so a collapse plays once; implementation gap: the clip and the ride still run in SideNav's own rail motion code, not in the shared edge reveal): a collapse ends in the real collapsed state, icons only, and an expand ends in the real expanded state, with its labels. On a collapse or an expand the rail's old state is one transient copy, inert and hidden from assistive technology, removed when the motion ends. The main content moves on the same clock, as `component:AppShell` FR17 states. A change made before the rail first paints lands at once, unless the rail's own toggle made it, so the initial state never animates. Under reduced motion the rail follows `design:reduced-motion` DR2 under a coarse primary pointer and DR3 otherwise. Collapsing or expanding keeps the nav and its items mounted, a `resizable` rail included, so item state such as an open nested group, and focus, persist (AR3 governs focus on what the collapsed rail does not render). | `component:SideNav/DEC-2`; `component:AppShell` FR17; `spec:AST-105` FR8, FR9 | Verified by `SideNavRailMotion.test.tsx` and `SideNavRailMotion.interaction.browser.spec.ts`; the `reducedMotion: 'always'` theme case pending |+| ID | Invariant | Basis | Draft review state |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | SideNav renders its navigation children in a scrollable list, which may be grouped by SideNavSection. A SideNavItem with children renders them, after its own row, in a group labelled by the parent's label; unless `collapsible` is `false`, the group expands and collapses and is hidden from assistive technology and inert while collapsed. | Current source, docs, and tests | Current behavior |+| FR2 | In a collapsed rail, a SideNavItem without an icon is not rendered; a leaf item renders icon-only, named by a non-blank caller `aria-label` or else its label; an item with children renders an icon-only trigger that opens a flyout listing its children as the flyout's top level. | Current source, docs, and tests | Current behavior |+| FR3 | In an expanded rail, in a flyout, and in the mobile navigation drawer, every SideNavItem row MUST span the full inline size of its list at any depth. A row at depth `n` MUST start its content `n` × `--spacing-6` beyond the row's own inline-start padding for its size, inside the row; the nested group MUST add no inset. A flyout's top level is depth 0. | `component:SideNav/DEC-1` | Settled intent; implementation may be staged |+| FR4 | The indent area MUST be part of the row's target: a click there, including a modified or middle click on a link row, does what the same click on the row's primary element does. When the row also carries an independent expand toggle or `actions`, the indent belongs to the primary link or button, and the toggle and actions keep their own activation at the row's trailing edge. | `component:SideNav/DEC-1`; `family:navigation-destinations` | Settled intent; implementation may be staged |+| FR5 | An expanded nested group MUST NOT clip its rows once it has finished opening, so a nested row's focus ring paints in full. The group MAY clip while collapsed and while it opens or closes. | `component:SideNav/DEC-1` | Settled intent; implementation may be staged |+| FR6 | Collapsing or expanding the rail plays one motion on one clock, `spec:AST-105` FR4's one shared motion, the theme's curve tokens, never a spring: layout snaps to the final rail width at once, with no width animation, and the rail reveals or covers its labels by a clip, its edge riding the main content's glide and its labels and collapsed icons fading on the same clock (`spec:AST-105` FR9's inline two-state form; the clip and the ride are the shared edge reveal's, and SideNav's own code keeps only the fades; the rail lends no pane to its resize controller, so a collapse plays once; implementation gap: the clip and the ride still run in SideNav's own rail motion code, not in the shared edge reveal): a collapse ends in the real collapsed state, icons only, and an expand ends in the real expanded state, with its labels. On a collapse or an expand the rail's old state is one transient copy, inert and hidden from assistive technology, removed when the motion ends. The main content moves on the same clock, as `component:AppShell` FR17 states. A change made before the rail first paints lands at once, unless the rail's own toggle made it, so the initial state never animates. Under reduced motion the rail follows `design:reduced-motion` DR2 under a coarse primary pointer and DR3 otherwise. Collapsing or expanding keeps the nav and its items mounted, a `resizable` rail included, so item state such as an open nested group, and focus, persist (AR3 governs focus on what the collapsed rail does not render). | `component:SideNav/DEC-2`; `component:AppShell` FR17; `spec:AST-105` FR8, FR9 | Verified by `SideNavRailMotion.test.tsx` and `SideNavRailMotion.interaction.browser.spec.ts`; the `reducedMotion: 'always'` theme case pending |### Allowed variation