An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-108): theme motion is three knobs — tempo, character, reducedMotion (#8613)
Cindy Zhangab0db1f73565
diff --git a/docs/architecture/theme-application.md b/docs/architecture/theme-application.mdindex b9e978fdf3..d7c38f99d5 100644--- a/docs/architecture/theme-application.md+++ b/docs/architecture/theme-application.md@@ -25,7 +25,7 @@ verified_by:packages/core/src/theme/themeRegistry.test.ts,packages/core/src/AppShell/AppShell.test.tsx,]-deciding_specs: [spec:AST-012/DEC-1, spec:AST-087/DEC-2]+deciding_specs: [spec:AST-012/DEC-1, spec:AST-087/DEC-2, spec:AST-108/DEC-1]---# Theme application@@ -95,7 +95,8 @@ standard width map.## Boundaries and invariants- **INV1 — The nearest provider wins.** Children read the closest Theme context- and CSS scope.+ and CSS scope. One exception: a theme's `reducedMotion: 'always'` also reaches+ every nested provider (`spec:AST-108` FR6).- **INV2 — Only the root provider changes `<html>`.** Nested providers stay localand cannot change browser chrome or portal-wide theme identity.- **INV3 — Detached consumers share one root-theme store.** A separate React@@ -159,6 +160,8 @@ which component parts are public theme targets.- `spec:AST-012/DEC-1` owns the fixed width-point vocabulary AppShell consumes.- `spec:AST-087/DEC-2` makes theme icon entries functions, so a theme holdingthem reaches `Theme` from client code.+- `spec:AST-108/DEC-1` lets a theme's `reducedMotion: 'always'` reach nested+ providers (INV1).## Verificationdiff --git a/docs/architecture/theme-authoring-contract.md b/docs/architecture/theme-authoring-contract.mdindex a439149242..f02be19784 100644--- a/docs/architecture/theme-authoring-contract.md+++ b/docs/architecture/theme-authoring-contract.md@@ -285,6 +285,12 @@ classify local references. Until the implementation lands, INV8's prefix-indepenclauses are current authority but not enforcement. Existing explicit enrollment,owner, lineage, collision, cycle, and legacy-unenrolled behavior remains shipped.+The motion resolver is accepted but unshipped: an internal, pure+`resolveThemeMotion(theme)` returns a theme's motion knobs, durations, easings,+and role tables for the animator and for server code, touching no DOM and with+no import-time side effects (`spec:AST-108` FR6). Until it lands, FR6's+resolution is current authority but not enforcement.+## Verification| Invariant | Evidence | Failure signal |diff --git a/docs/design/motion.md b/docs/design/motion.mdindex 4b0971cd69..6018bc9cbc 100644--- a/docs/design/motion.md+++ b/docs/design/motion.md@@ -32,7 +32,9 @@ when motion is reduced.- **DR2 — Weight determines timing.** Small local feedback SHOULD feel fasterthan large entrances, exits, or continuous movement.- **DR3 — Movement settles naturally.** Easing SHOULD communicate controlled- deceleration rather than ornamental bounce or elasticity.+ deceleration rather than ornamental bounce or elasticity; a theme's+ expressive character may overshoot on entrances and moves only+ (`spec:AST-108`).- **DR4 — Stable content stays stable.** Motion SHOULD avoid unnecessary layoutdisruption and preserve reading and interaction context.- **DR5 — Reduced motion preserves meaning.** Every animated transition MUST havediff --git a/docs/design/reduced-motion.md b/docs/design/reduced-motion.mdindex 00f3edeaaa..31995ac895 100644--- a/docs/design/reduced-motion.md+++ b/docs/design/reduced-motion.md@@ -54,11 +54,12 @@ trackpad, or keyboard the change is immediate.## State representation-| State | Required representation | Allowed variation |-| --------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------- |-| reduced motion, coarse pointer | Opacity-only cross-fade of 200 ms or less (DR2); an in-place value change applies at once (DR2) | A shorter cross-fade |-| reduced motion, any other pointer | Immediate change (DR3), except a touch drag's release (DR2) | None |-| no reduced-motion preference | Outside this record | Component and theme motion |+| State | Required representation | Allowed variation |+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------- |+| reduced motion, coarse pointer | Opacity-only cross-fade of 200 ms or less (DR2); an in-place value change applies at once (DR2) | A shorter cross-fade |+| reduced motion, any other pointer | Immediate change (DR3), except a touch drag's release (DR2) | None |+| no reduced-motion preference, theme on `'system'` | Outside this record | Component and theme motion |+| a theme on `'always'` (DR2a) | As reduced motion, whatever the person's setting | DR1–DR3 |## Responsive and input behavior@@ -75,6 +76,10 @@ trackpad, or keyboard the change is immediate.under Reduce Motion. An in-place value change, such as a progress fill's length oranother continuous value, does not cross-fade: under reduced motion itapplies at once on any pointer, with no added element (DEC-3).+- **DR2a — A theme may reduce motion for everyone.** A theme's+ `reducedMotion: 'always'` applies DR1–DR3 for every person, whatever their+ setting; `'system'` follows each person's setting (`spec:AST-108`). No theme+ option loosens DR1–DR4.- **DR3 — Fine-pointer presentations change at once.** Under reduced motion,every other DR1 transition, when the primary pointer is not coarse, MUST completeimmediately, with no animated property.diff --git a/docs/specs/AST-012/spec.md b/docs/specs/AST-012/spec.mdindex a841f8e5b2..88ca925050 100644--- a/docs/specs/AST-012/spec.md+++ b/docs/specs/AST-012/spec.md@@ -118,7 +118,8 @@ A breakpoint map alone emits no CSS. Only rules with adaptation values do.`localTokens` or an enrolled exact base declares names. A rule may replace onlyan exact name already enrolled in the effective lineage and uses AST-006's`TokenValue` normalization and validation. Identity, inheritance, syntax, icons,- indicators, media-surface fields, and adaptations remain root-owned. Within one+ indicators, media-surface fields, adaptations, and `motion.reducedMotion`+ (`spec:AST-108` FR5) remain root-owned. Within onerule, values use the root expansion, deep-merge, and kind precedence. Agenerative axis expands against the root axis metadata, and every produced leafcounts as a write by that rule except invariant type-scale component defaultsdiff --git a/docs/specs/AST-090-exit-motion/spec.md b/docs/specs/AST-090-exit-motion/spec.mdindex dcf138257c..0fc309ed77 100644--- a/docs/specs/AST-090-exit-motion/spec.md+++ b/docs/specs/AST-090-exit-motion/spec.md@@ -101,7 +101,10 @@ FR1–FR13 govern dialog and layer surfaces in a pointer presentation. FR14governs them in a touch presentation.- **FR1 — Exits are off by default.** `--duration-exit-dialog` and- `--duration-exit-layer` default to `0ms`. A surface whose kind's exit+ `--duration-exit-layer` default to `0ms`. An exit duration a theme sets as a+ reference to a tempo-scaled token, such as FR12's `var(--duration-exit)`,+ follows the theme's tempo; one set as a literal plays as written+ (`spec:AST-108` FR5). A surface whose kind's exitduration is zero closes at once: it is hidden in the update that closes it,and focus, callbacks, and dismissal behave as they do for a surface with noexit.diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.mdindex 2bdaf010ca..5e0e66f3ec 100644--- a/docs/specs/AST-094-touch-presentations/spec.md+++ b/docs/specs/AST-094-touch-presentations/spec.md@@ -65,8 +65,8 @@ a measured, sourced difference exists.deceleration rate, rubber-band coefficient, gesture threshold and hapticmoment a touch presentation uses MUST default to the measured native valuefor that use (FR2), and every component that plays the same motion or- gesture MUST use the same value; once the roles are public, a theme MAY- override a motion role (FR4).+ gesture MUST use the same value; a theme reaches the roles only+ through its motion knobs (FR4, DEC-15).No component uses a value of its own where a measured value exists. The samevalues apply on every touch platform; a platform gets a value of its own onlywhere a measured, sourced difference exists (FR2).@@ -107,18 +107,24 @@ a measured, sourced difference exists.touch presentation plays MUST be a motion role named for its use(`architecture:theme-tokens` INV3). The roles this record names are listed below with their defaults andsources; further roles a component's own record measures join through the- generated motion role table (DEC-5). The role's value is its- measured value (FR1, FR2). The roles are internal until the public- motion-token set is decided, so a theme cannot override them yet (DEC-11). A component MUST read touch motion through these roles- and MUST NOT play a literal. Once a role is public, a theme value MUST reach the motion at its+ generated motion role table (DEC-5). With tempo 1 and character+ standard, every role plays its measured value exactly (FR1, FR2); a theme's+ tempo scales durations and its character offsets bounce through fixed+ per-role weights (`spec:AST-108` FR3), and roles on the fixed list ignore+ both: the on-screen keyboard (`spec:AST-099` FR8); gesture thresholds, the+ content-touch delay, and momentum (`spec:AST-002` FR3); finger tracking, the+ rubber band, the press model's onset delay, cancel distance, and tap flash+ (`spec:AST-108` FR4), and busy loops; and the 200 ms Reduce Motion cap.+ The per-role tables stay internal (DEC-15). A component MUST read touch motion through these roles+ and MUST NOT play a literal. A theme's knob values MUST reach the motion at itsstart, without changing how the motion runs (FR5, FR6). Motion thatmust stay in step with the on-screen keyboard is not a theme role: it ridesthe keyboard's own motion (`spec:AST-099` FR8,`architecture:react-component-runtime` INV11). Gesture thresholds, the timings that decide who gets a touch (thecontent-touch delay, the scroll brake, momentum memory) and haptics are not- motion: they stay internal measured values and are not public concepts (`spec:AST-002` FR3). When the public set is decided, its roles join the motion configuration of- `architecture:theme-authoring-contract` and `architecture:theme-tokens`,- whose rules are unchanged until then. It departs from the draft `design:motion` DR3+ motion: they stay internal measured values and are not public concepts (`spec:AST-002` FR3). The three knobs join the motion configuration of+ `architecture:theme-authoring-contract` and `architecture:theme-tokens`+ (`spec:AST-108`). It departs from the draft `design:motion` DR3wherever the native motion settles with an overshoot or stretches with arubber band.@@ -546,8 +552,8 @@ outside a menu closes it.## Current-state impact- `architecture:theme-tokens` and `architecture:theme-authoring-contract`:- unchanged until the public motion-token set is decided; then its roles join- the motion configuration (FR4, DEC-11).+ the three motion knobs join the motion configuration (FR4, DEC-15,+ `spec:AST-108`).- `architecture:interaction-modality`: the touch-presentation conditions(FR13) sit beside the shared modality state; its invariants are unchanged.- `architecture:react-component-runtime`: FR24 states the caller-visible@@ -613,7 +619,7 @@ outside a menu closes it.| --------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || FR1, FR2 | Value check over every measured value and its uses | every value; a guess and its measurement task; a platform-specific value; two components playing the same motion | an unsourced value, an unknown source kind, a guess without a listed measurement, an unsourced platform split, or two values for one use fails || FR3 | Unit tests of the spring, decay, rubber band and projection math against an independent integration and values read from UIKit | under-, critically and overdamped springs; release velocities; both rates; overscroll depths | changing a formula or a constant breaks the agreement with UIKit's values |-| FR4 | Role unit tests over every touch motion | each role at its table value; a theme that writes `motion` | a literal played in place of a role, a value that differs from the table, or a theme that changes a role before the public set is decided fails |+| FR4 | Role unit tests over every touch motion | each role at its table value; a theme that writes `motion` | a literal played in place of a role, a value that differs from the table at `tempo` 1 and `'standard'`, or a theme that changes a role other than through its motion knobs fails || FR5 | Browser proof: an animation keeps advancing frame by frame through a 1 s main-thread block, with no layout or paint per frame | Chromium phone emulation; WebKit | a script-driven or layout-animating implementation freezes or lays out || FR6 | Unit and browser tests catching an animation mid-flight and retargeting it | catch at peak velocity; retarget with a new spring | a layout read, a jump, or a lost velocity fails || FR7, FR8 | Component browser tests and storyboards with and without Reduce Motion | entrance, exit, move; a drag and its lift under Reduce Motion | a missing exit, any travel, scale or spring under Reduce Motion other than a coast after a throw and its settle at an edge (`design:reduced-motion` DR2), or an opacity fade over 200 ms fails |@@ -650,8 +656,8 @@ remembered: a number enters the table only with a citable source, and Androidtouch devices get the same values until a measured, sourced difference isrecorded.-The table supplies the defaults and a theme may retune any motion role (FR4):-a product can soften a spring without forking a component, and the measured+The table supplies the defaults and a theme tunes them through its motion+knobs (FR4, DEC-15): a product can soften motion without forking a component, and the measuredvalues stay the ones it starts from. Platform-matched look and feel is not partof this decision.@@ -673,8 +679,8 @@ release runs as a compositor animation of the measured curve (FR5, FR9).**Decider:** `cixzhang`, `2026-10-24`A product tunes motion as it tunes color and type, so every touch spring,-duration and curve is a theme motion role whose default is the measured value-(FR4). Thresholds decide who gets a touch, not how anything looks, so they stay+duration and curve is a motion role whose default is the measured value and+which a theme reaches through its motion knobs (FR4, DEC-15). Thresholds decide who gets a touch, not how anything looks, so they stayinternal (`spec:AST-002` FR3).### DEC-4 — A finger opens a menu on press@@ -787,6 +793,18 @@ iOS 26.2 simulator measures it.Rejected: the 150 ms delay on every menu row.+### DEC-15 — The public motion set is three theme knobs; per-role tables stay internal++**Reference:** `spec:AST-094/DEC-15`+**Decider:** `cixzhang`, `2026-10-26`++A theme reaches touch motion only through `spec:AST-108`'s three knobs, tempo,+character, and reduced motion, which transform the measured roles; the+per-role tables and weights stay internal. This supersedes DEC-11's "all+internal" for exactly these three knobs, and DEC-1's and DEC-3's per-role+retuning, which a theme does through the knobs; DEC-11's rejected alternative, public+per-component roles, stays rejected.+### DEC-21 — Gestures work on the web, not only under a finger**Reference:** `spec:AST-094/DEC-21`diff --git a/docs/specs/AST-108-theme-motion/spec.md b/docs/specs/AST-108-theme-motion/spec.mdnew file mode 100644index 0000000000..1a6adbeb91--- /dev/null+++ b/docs/specs/AST-108-theme-motion/spec.md@@ -0,0 +1,202 @@+---+schema_version: 4+template_version: 2+kind: system-spec+id: spec:AST-108+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-10-26+phase: accepted+owners: [cixzhang]+affects_architecture:+ [+ architecture:theme-tokens,+ architecture:theme-authoring-contract,+ architecture:theme-application,+ ]+affects_families: []+affects_contributing: []+affects_consumer_docs: [motion, tokens, theme]+---++# Theme motion system spec++<!-- path-applicability:v1 -->++```json+{+ "paths": ["packages/core/src/theme/**", "packages/core/src/motion/**"]+}+```++<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->++## Intent++A theme sets how fast and how lively its motion feels, and whether motion is+reduced for everyone, with three knobs. The same knobs drive the CSS motion+tokens and the animator's springs and curves, and animations that run together+start and land together. Every per-use motion value stays internal.++## Non-goals++- Per-role or per-component motion settings for themes.+- Loosening Reduce Motion: no option turns off `design:reduced-motion`+ DR1–DR4 for a person who asked for it.+- A public resolver for a theme's motion values (OQ1).++## Public contract++```ts+defineTheme({+ name: 'Brand',+ motion: {tempo: 1, character: 'standard', reducedMotion: 'system'},+});+```++## Requirements++- **FR1 — Three motion knobs.** `defineTheme`'s `motion` takes+ `{tempo, character, reducedMotion}`:+ - `tempo` is a number, default `1`, clamped to 0.75–1.5; it scales every+ motion duration;+ - `character` is `'crisp'`, `'standard'` (default), or `'expressive'`; it+ picks the entrance and move curves and the spring bounce. A continuous bounce+ is not offered;+ - `reducedMotion` is `'system'` (default) or `'always'`; `'always'` applies+ `design:reduced-motion` DR1–DR3 for everyone, and `'system'` follows each+ person's setting. No value loosens Reduce Motion.+- **FR2 — The knobs generate the CSS motion tokens.** The theme's+ `--duration-*` tokens are their base values times `tempo`. `character` sets+ only the job-named `--ease-entrance` and `--ease-move` tokens, declared in+ `tokens.stylex.ts`. `--ease-standard`, which the existing exits read, and+ `--ease-exit`, whose default is `cubic-bezier(0.3, 0, 0.6, 0.6)`, are the same at every character, so exits stay+ quiet. With `tempo` 1 and `character`+ `'standard'`, the tokens keep their released values: `--duration-*` 130, 175, 230, 310, 410,+ 550, 730, 975 and 1300 ms, and `--ease-standard`+ `cubic-bezier(0.24, 1, 0.4, 1)`; `--ease-entrance` and `--ease-move` equal+ `--ease-standard` at `'standard'`. The curves at `'crisp'` and+ `'expressive'` are a decelerate-only curve and a curve with a slight+ overshoot.+- **FR3 — The animator's tables derive from the same knobs.** The animator's+ base tables, every role in `spec:AST-094` FR4, derive from the theme's+ `tempo` and `character` at their source: a spring's duration scales by+ `tempo`, and `character` offsets the role's measured bounce by an amount+ times the role's fixed weight: `'standard'` adds nothing, and `'crisp'` and+ `'expressive'` shift it down and up, so a role whose weight is zero, such as+ an exit, a fade, or a full-screen move, keeps its measured bounce at every+ character. With+ `tempo` 1 and `character` `'standard'`, every role plays its measured value+ exactly. A spring keeps its measured physics, scaled by `tempo` and shaped+ by `character`; it does not follow a CSS duration or easing twin. The roles+ and their weights stay internal.+- **FR4a — Coordinated animations share one clock.** Animations that run+ together start and land together: they play the same motion role, or the CSS+ part is timed from the spring's computed settle time, and never as two+ independently timed curves. This covers an element and the siblings that+ glide around it (`spec:AST-105`'s one shared timing), an element's+ entrance and its exit, a sheet and its scrim, a menu's grow and its content, and a CSS fade+ paired with a JavaScript spring, such as MobileNav's close timed from its+ computed duration and BottomSheet's scrim, whose fade lasts the sheet's+ computed settle time.+- **FR4 — Some motion is fixed on purpose.** `tempo` and `character` do not+ move+ finger-following and drag motion, scroll momentum and decay, the rubber+ band, the on-screen keyboard's motion (`spec:AST-099` FR8), the press+ model's clocks (its onset delay, cancel distance, and tap flash), hover-intent+ delays, gesture thresholds (`spec:AST-002` FR3), the loop periods of busy+ indicators such as Spinner and Skeleton, which read the duration their theme+ sets before `tempo` scales it, so a `MotionScaleConfig` still times them,+ or the 200 ms Reduce Motion cap; `tempo` may shorten a+ Reduce Motion cross-fade but never lengthens it.+- **FR5 — Existing motion configuration keeps working.** `defineTheme`'s+ `motion` also accepts the existing `MotionScaleConfig`, and+ `expandMotionScale` and the `MotionScale*` types are unchanged. A+ `MotionScaleConfig` keeps generating its CSS duration tokens, and the tempo+ it implies drives those durations only: the animator's tables stay at tempo 1+ unless the theme sets `tempo` itself, so an existing theme renders exactly as+ before, springs included. Explicit+ `MotionScaleConfig` fields and explicit `tokens` win over `tempo` and+ `character`, and an extending theme inherits field by field: a `MotionScaleConfig` field+ or a knob the child leaves unset keeps its base's value. An adaptation rule may set `tempo` and `character` like+ any other `motion` value (`spec:AST-012` FR4); `reducedMotion` is set on the+ theme itself, since its root mark has no conditional form.+- **FR6 — Server rendering gets the same values.** A theme is plain data, and+ the theme utilities run on the server. `'system'` adds no theme CSS:+ component styles already key reduced motion on `prefers-reduced-motion`, so+ the server never guesses and nothing flashes at hydration. `'always'` marks+ the theme's root, and every component style that keys reduced motion on+ `prefers-reduced-motion` also keys it on that mark; the animator, every script reader of+ `prefers-reduced-motion` (a `matchMedia` or `useMediaQuery` check), and every+ adaptation rule keyed on `when: {motion}` (`spec:AST-012` FR2) treat the+ preference as set. The mark only adds: an ancestor's `'always'` reaches+ inside every nested theme, and a nested theme can add `'always'` but never+ removes an ancestor's, since nothing loosens `design:reduced-motion` DR1–DR3+ (DR2a). The server and the client resolve the same+ motion values from a theme, and importing the theme and motion modules+ touches no DOM (`architecture:theme-authoring-contract`). The animator reads a person's Reduce Motion+ setting only when an animation starts, on the client.+- **FR7 — Docs ship with it.** The motion, duration-token, and easing-token+ docs, the theme template, the theme-authoring guide, and+ `architecture:theme-authoring-contract` describe the three knobs, the fixed+ list, and the precedence before the implementation lands.++## Current-state impact++- `defineTheme`'s `motion` widens to accept the three knobs beside the existing+ `MotionScaleConfig`; existing themes render exactly as before.+- Core gains `--ease-entrance`, `--ease-move`, and `--ease-exit`, and a+ theme-root mark for `reducedMotion: 'always'` that every component style+ keying reduced motion on `prefers-reduced-motion` also keys on; Carousel's+ paging, BottomSheet's panel and sheet gestures, Item's swipe release,+ MobileNav, AppShell, Chat, Markdown's streaming reveal, BottomSheet's+ keyboard scroll, and the animated-layout glide, which read the preference in+ script, also honour it, as do adaptation rules keyed on `when: {motion}`+ (`spec:AST-012`).+- `design:reduced-motion` gains DR2a: a theme may reduce motion for everyone.+- Spinner and Skeleton read their loop durations before `tempo` scales them+ (FR4), so their timing is unchanged under every existing theme;+ `component:Spinner` FR3 and `component:Skeleton` FR4 say so.+- BottomSheet's sheet and scrim share `--duration-medium`; when the+ sheet settles on `springs.settle`, its scrim's fade takes the spring's settle+ time (FR4a).+- `spec:AST-094` FR1, FR4, and DEC-15, `design:reduced-motion` DR2a,+ `spec:AST-012` FR4 (`reducedMotion` stays root-owned),+ `architecture:theme-application` INV1 (`'always'` reaches nested+ providers), `architecture:theme-authoring-contract` (the internal motion resolver),+ `component:Button` FR15 (its release fade follows `tempo`), the draft `design:motion` DR3, and `spec:AST-090` are amended to+ match.++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, FR2 | Theme unit tests over generated CSS | each `tempo` bound and 1; each `character`; `reducedMotion` both values; no `motion` | a token off its formula, the released tokens changed at the defaults, an exit curve that changes, or a value outside a clamp fails |+| FR3 | Tests that the CSS tokens and the animator's tables derive from the same knob values | each role at the defaults and at each knob value; an adaptation rule that sets `tempo` or `character` | a role off its measured value at the defaults, a role that ignores a knob it follows, or a weight-0 role whose bounce changes with `character` fails |+| FR4a | Browser tests of each paired animation at each knob value | an element and gliding siblings, an element's entrance and exit, a sheet and its scrim, a menu's grow and content, a CSS fade with a spring | paired animations that end more than one frame apart fail |+| FR4 | Unit tests of each fixed item | finger tracking, momentum, rubber band, keyboard, press and hover clocks, loops, Reduce Motion cap; Spinner and Skeleton loops at each tempo | a fixed item that moves with `tempo` or `character`, or a cross-fade longer than 200 ms, fails |+| FR5 | Theme tests with the released configurations | a `MotionScaleConfig` theme, explicit tokens, an extending theme; an adaptation rule that sets `tempo` or `character` | changed output for an existing theme, or a knob that beats an explicit field, fails |+| FR6 | Server-render tests and import checks | a server render with each `reducedMotion`; importing the theme and motion modules; `'always'` with the person's setting off, across components that key on `prefers-reduced-motion`; a nested theme under an `'always'` theme | a DOM access at import or on the server, theme CSS emitted for `'system'`, a hydration change, or a component style, script reader, or `when: {motion}` rule that ignores the root mark under `'always'`, or a nested theme that restores motion under an ancestor's `'always'`, fails |+| FR7 | Docs review | each listed doc | a doc without the knobs, the fixed list, or the precedence fails |++## Decision log++### DEC-1 — A theme's motion is three knobs; per-role tables stay internal++**Reference:** `spec:AST-108/DEC-1`+**Decider:** `cixzhang`, `2026-10-26`++Theme authors set how fast and how lively motion feels and whether it is+reduced for everyone; few want per-use values. Three character steps, not a continuous bounce,+are the recommendation adopted with the knobs. Three knobs drive CSS tokens and JavaScript springs from the same values, and the measured+per-role values stay internal. This supersedes `spec:AST-094` DEC-11's "all+internal" for exactly these three knobs.++Rejected: a public token per motion group.++## Open questions++- **OQ1 — Whether a theme's motion values get a public resolver.**+ (`human-design`) Open. `resolveThemeMotion` is internal.diff --git a/packages/core/src/Button/Button.spec.md b/packages/core/src/Button/Button.spec.mdindex c3bc2b625d..f915b54b42 100644--- a/packages/core/src/Button/Button.spec.md+++ b/packages/core/src/Button/Button.spec.md@@ -131,7 +131,7 @@ Consumer migration instructions belong in consumer docs and release notes.| FR12 | With `tooltip`, the tooltip attaches to the Button element itself (no wrapper element), opens above it, and its content is added to `aria-describedby` after any caller value. | Current source; real-browser accessibility test || FR13 | A standalone Button paints the shadow token for its `elevation`. Inside a ButtonGroup it paints no shadow and reflects `data-elevation="none"`, whatever `elevation` says. | `family:buttons` FR8–FR10; current source and tests || FR14 | The root carries `astryx-button` and reflects the effective `data-variant`, `data-size`, and `data-elevation`. | `family:buttons` FR10; `architecture:component-theming-surface`; tests |-| FR15 | Hover paints the shared interaction overlay on hover-capable pointers, and a press paints the shared pressed overlay through the press controller: at once under a mouse or a pen (`spec:AST-094` FR11's fine-pointer profile) and on FR11's control profile under a finger, fading out over 200 ms on release. Without a reduced-motion preference, a standalone Button also scales to 0.98 on a mouse press, or while the touch press reads on; under reduced motion it MUST NOT scale (`design:reduced-motion` DR1). All of this paint follows the element's exposed disabled state: a Button that is natively disabled or exposes `aria-disabled="true"` (busy-only, disabled with a tooltip, or a caller's own `aria-disabled`) shows no overlay and no press scale, even when it stays operable. Inside a ButtonGroup the press scale does not apply. Button's hover and press transitions are fast, and instant under reduced motion. Implementation gap: the 0.98 press scale also applies under reduced motion; only its transition becomes instant. | Current source and tests; `spec:AST-094` FR11 and DEC-21 for the mouse and pen press |+| FR15 | Hover paints the shared interaction overlay on hover-capable pointers, and a press paints the shared pressed overlay through the press controller: at once under a mouse or a pen (`spec:AST-094` FR11's fine-pointer profile) and on FR11's control profile under a finger, fading out over 200 ms on release at `tempo` 1, scaled by the theme's `tempo` (`spec:AST-108` FR4). Without a reduced-motion preference, a standalone Button also scales to 0.98 on a mouse press, or while the touch press reads on; under reduced motion it MUST NOT scale (`design:reduced-motion` DR1). All of this paint follows the element's exposed disabled state: a Button that is natively disabled or exposes `aria-disabled="true"` (busy-only, disabled with a tooltip, or a caller's own `aria-disabled`) shows no overlay and no press scale, even when it stays operable. Inside a ButtonGroup the press scale does not apply. Button's hover and press transitions are fast, and instant under reduced motion. Implementation gap: the 0.98 press scale also applies under reduced motion; only its transition becomes instant. | Current source and tests; `spec:AST-094` FR11 and DEC-21 for the mouse and pen press || FR16 | The ghost variant carries the edge-compensation marker so an enclosing container can align it flush with its edge; other variants do not. | Current source; edge-compensation tests || FR17 | `ref`, `className`, `style`, `xstyle`, and other DOM props reach the root element. A caller's own `aria-busy` and `aria-disabled` are kept beside Button's own (either one sets the attribute); a caller `aria-disabled` changes exposure and paint only and does not make the Button inert. The tooltip trigger shares the caller's `ref`, which stays attached across rerenders. | Current source and tests |diff --git a/packages/core/src/Skeleton/Skeleton.spec.md b/packages/core/src/Skeleton/Skeleton.spec.mdindex 141bd3e665..18ffaccadd 100644--- a/packages/core/src/Skeleton/Skeleton.spec.md+++ b/packages/core/src/Skeleton/Skeleton.spec.md@@ -84,13 +84,13 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | Skeleton renders one childless `div` carrying the `skeleton` target, sized by `width` and `height` (numbers in pixels, strings as CSS), default `100%` each. | Current source and tests |-| FR2 | `radius` maps `none` to no radius, `0` to `--radius-none`, `1` to `--radius-inner`, `2` to `--radius-element`, `3` and `4` to `--radius-container`, and `rounded` to `--radius-full`; the default is `3`. | Current source |-| FR3 | The block paints `--color-skeleton` at opacity 0.25. Under `prefers-contrast: more` it paints that color mixed 30% toward primary text. Under `forced-colors: active` it paints `GrayText`, which wins over the contrast rule, at full opacity while no pulse runs; with motion allowed the FR4 pulse still varies its opacity. | Current source and tests |-| FR4 | The block pulses its opacity from 0.25 to 0.925 in ten equal held steps and back, alternating indefinitely, each climb and each fall taking `--duration-medium-max`, with a linear timing function and no `steps()`. The pulse starts after 1000 ms plus 100 ms times `index`. Under `prefers-reduced-motion: reduce` there is no pulse. | Current source and tests |-| FR5 | `ref` reaches the block. Supported DOM, ARIA, data, and event props, including `data-testid`, reach the block after the default `aria-hidden`; `xstyle`, `className`, and `style` merge in that order after component styles. | Current source and tests |+| ID | Invariant | Basis |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | Skeleton renders one childless `div` carrying the `skeleton` target, sized by `width` and `height` (numbers in pixels, strings as CSS), default `100%` each. | Current source and tests |+| FR2 | `radius` maps `none` to no radius, `0` to `--radius-none`, `1` to `--radius-inner`, `2` to `--radius-element`, `3` and `4` to `--radius-container`, and `rounded` to `--radius-full`; the default is `3`. | Current source |+| FR3 | The block paints `--color-skeleton` at opacity 0.25. Under `prefers-contrast: more` it paints that color mixed 30% toward primary text. Under `forced-colors: active` it paints `GrayText`, which wins over the contrast rule, at full opacity while no pulse runs; with motion allowed the FR4 pulse still varies its opacity. | Current source and tests |+| FR4 | The block pulses its opacity from 0.25 to 0.925 in ten equal held steps and back, alternating indefinitely, each climb and each fall taking `--duration-medium-max` as the theme sets it before `tempo` scales it (`spec:AST-108` FR4), with a linear timing function and no `steps()`. The pulse starts after 1000 ms plus 100 ms times `index`. Under `prefers-reduced-motion: reduce` there is no pulse. | Current source and tests |+| FR5 | `ref` reaches the block. Supported DOM, ARIA, data, and event props, including `data-testid`, reach the block after the default `aria-hidden`; `xstyle`, `className`, and `style` merge in that order after component styles. | Current source and tests |### Allowed variationdiff --git a/packages/core/src/Spinner/Spinner.spec.md b/packages/core/src/Spinner/Spinner.spec.mdindex 9c7bbfe668..a997f449c6 100644--- a/packages/core/src/Spinner/Spinner.spec.md+++ b/packages/core/src/Spinner/Spinner.spec.md@@ -108,16 +108,16 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | Without a label, Spinner renders one inline-grid `span` status element that carries the `spinner` target, ref, `data-testid`, and passthrough props. With a label, a column `div` wrapper with `--spacing-2` gap carries the target, ref, `data-testid`, passthrough props, and styling inputs; the status `span` and then the label render inside it. | Current source and tests |-| FR2 | The status element's box is the ring diameter plus one stroke width on each side, set inline after the caller's `style`, so a caller `width` or `height` never resizes it while other caller styles still apply. The box does not shrink in a flex host. With no stylesheet, the box and ring draw at the size's default geometry. | Current source and tests |-| FR3 | The ring is an `aria-hidden` SVG of two concentric circles: a full track and an arc covering `--spinner-arc-fraction` of the circumference (0.375 by default), starting at twelve o'clock with round caps. The arc's dash moves around the stationary circle at `--duration-slow-min` per cycle, linear, indefinitely; under `prefers-reduced-motion: reduce` the cycle slows to 3 seconds and does not stop. | Current source and tests |-| FR4 | All mounted rings turn in the same phase, whenever each mounted. Where the browser cannot report running animations, Spinner does no phase work. | Current source and tests |-| FR5 | `default` paints `--color-accent` on `--color-track`; `subtle` paints `--color-text-secondary` on `--color-track`; `onMedia` paints `--color-on-dark` on itself at track opacity 77/255; `inherit` paints `currentColor` on itself at track opacity 0.3. | Current source and tests |-| FR6 | The five public variables are declared only on the element carrying the `spinner` target, per `size` and `shade`, so a theme rule on that target and its `size:` or `shade:` variants overrides them; the inner status element inherits them when a label moves the target to the wrapper. | Current source and tests |-| FR7 | A string label renders as bold body Text; a rich-node label renders as supplied. | Current source and tests |-| FR8 | `xstyle` and `className` reach the element carrying the target and merge after component styles; `style` merges after them except for the status box's `width` and `height` (FR2). | Current source and tests |+| ID | Invariant | Basis |+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | Without a label, Spinner renders one inline-grid `span` status element that carries the `spinner` target, ref, `data-testid`, and passthrough props. With a label, a column `div` wrapper with `--spacing-2` gap carries the target, ref, `data-testid`, passthrough props, and styling inputs; the status `span` and then the label render inside it. | Current source and tests |+| FR2 | The status element's box is the ring diameter plus one stroke width on each side, set inline after the caller's `style`, so a caller `width` or `height` never resizes it while other caller styles still apply. The box does not shrink in a flex host. With no stylesheet, the box and ring draw at the size's default geometry. | Current source and tests |+| FR3 | The ring is an `aria-hidden` SVG of two concentric circles: a full track and an arc covering `--spinner-arc-fraction` of the circumference (0.375 by default), starting at twelve o'clock with round caps. The arc's dash moves around the stationary circle at `--duration-slow-min` per cycle, as the theme sets it before `tempo` scales it (`spec:AST-108` FR4), linear, indefinitely; under `prefers-reduced-motion: reduce` the cycle slows to 3 seconds and does not stop. | Current source and tests |+| FR4 | All mounted rings turn in the same phase, whenever each mounted. Where the browser cannot report running animations, Spinner does no phase work. | Current source and tests |+| FR5 | `default` paints `--color-accent` on `--color-track`; `subtle` paints `--color-text-secondary` on `--color-track`; `onMedia` paints `--color-on-dark` on itself at track opacity 77/255; `inherit` paints `currentColor` on itself at track opacity 0.3. | Current source and tests |+| FR6 | The five public variables are declared only on the element carrying the `spinner` target, per `size` and `shade`, so a theme rule on that target and its `size:` or `shade:` variants overrides them; the inner status element inherits them when a label moves the target to the wrapper. | Current source and tests |+| FR7 | A string label renders as bold body Text; a rich-node label renders as supplied. | Current source and tests |+| FR8 | `xstyle` and `className` reach the element carrying the target and merge after component styles; `style` merges after them except for the status box's `width` and `height` (FR2). | Current source and tests |### Allowed variation