An open source design system that's fully customizable and agent ready
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
{
"paths": ["packages/core/src/theme/**", "packages/core/src/motion/**"]
}
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-motionDR1–DR4 for a person who asked for it. - A public resolver for a theme's motion values (OQ1).
Public contract
defineTheme({
name: 'Brand',
motion: {tempo: 1, character: 'standard', reducedMotion: 'system'},
});
Requirements
- FR1 — Three motion knobs.
defineTheme'smotiontakes{tempo, character, reducedMotion}:tempois a number, default1, clamped to 0.75–1.5; it scales every motion duration;characteris'crisp','standard'(default), or'expressive'; it picks the entrance and move curves and the spring bounce. A continuous bounce 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 isspec:AST-094FR45's, and tap-started expand and collapse, including the animated-layout glide (spec:AST-105FR4), plays the curve tokens;reducedMotionis'system'(default) or'always';'always'appliesdesign:reduced-motionDR1–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 timestempo.charactersets only the job-named--ease-entranceand--ease-movetokens, declared intokens.stylex.ts.--ease-standard, which the existing exits read, and--ease-exit, whose default iscubic-bezier(0.3, 0, 0.6, 0.6), are the same at every character, so exits stay quiet. Withtempo1 andcharacter'standard', the tokens keep their released values:--duration-*130, 175, 230, 310, 410, 550, 730, 975 and 1300 ms, and--ease-standardcubic-bezier(0.24, 1, 0.4, 1);--ease-entranceand--ease-moveequal--ease-standardat'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-094FR4, derive from the theme'stempoandcharacterat their source: a spring's duration scales bytempo, andcharacteroffsets 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. Withtempo1 andcharacter'standard', every role plays its measured value exactly. A spring keeps its measured physics, scaled bytempoand shaped bycharacter; 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.
tempoandcharacterdo not move finger-following and drag motion, scroll momentum and decay, the rubber band, the on-screen keyboard's motion (spec:AST-099FR8), the press model's clocks (its onset delay, cancel distance, and tap flash), hover-intent delays, gesture thresholds (spec:AST-002FR3), the loop periods of busy indicators such as Spinner and Skeleton, which read the duration their theme sets beforetemposcales it, so aMotionScaleConfigstill times them, or the 200 ms Reduce Motion cap;tempomay shorten a Reduce Motion cross-fade but never lengthens it. - FR5 — Existing motion configuration keeps working.
defineTheme'smotionalso accepts the existingMotionScaleConfig, andexpandMotionScaleand theMotionScale*types are unchanged. AMotionScaleConfigkeeps 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 setstempoitself, so an existing theme renders exactly as before, springs included. ExplicitMotionScaleConfigfields and explicittokenswin overtempoandcharacter, and an extending theme inherits field by field: aMotionScaleConfigfield or a knob the child leaves unset keeps its base's value. An adaptation rule may settempoandcharacterlike any othermotionvalue (spec:AST-012FR4);reducedMotionis 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 onprefers-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 onprefers-reduced-motionalso keys it on that mark; the animator, every script reader ofprefers-reduced-motion(amatchMediaoruseMediaQuerycheck), and every adaptation rule keyed onwhen: {motion}(spec:AST-012FR2) 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 loosensdesign:reduced-motionDR1–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-contractdescribe the three knobs, the fixed list, and the precedence before the implementation lands.
Current-state impact
defineTheme'smotionwidens to accept the three knobs beside the existingMotionScaleConfig; existing themes render exactly as before.- Until
reducedMotion: 'always'ships, the publicmotiontype has noreducedMotionfield and every theme follows each person's setting, as'system'does (the known gap inarchitecture:theme-authoring-contract). - Core gains
--ease-entrance,--ease-move, and--ease-exit, and a theme-root mark forreducedMotion: 'always'that every component style keying reduced motion onprefers-reduced-motionalso 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 onwhen: {motion}(spec:AST-012). design:reduced-motiongains DR2a: a theme may reduce motion for everyone.- Spinner and Skeleton read their loop durations before
temposcales them (FR4), so their timing is unchanged under every existing theme;component:SpinnerFR3 andcomponent:SkeletonFR4 say so. - BottomSheet's sheet and scrim share
--duration-medium; when the sheet settles onsprings.settle, its scrim's fade takes the spring's settle time (FR4a). spec:AST-094FR1, FR4, and DEC-15,design:reduced-motionDR2a,spec:AST-012FR4 (reducedMotionstays root-owned),architecture:theme-applicationINV1 ('always'reaches nested providers),architecture:theme-authoring-contract(the internal motion resolver),component:ButtonFR15 (its release fade followstempothrough--duration-exit, which references a tempo-scaled duration), the draftdesign:motionDR3, andspec:AST-090are 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.resolveThemeMotionis internal.