@crystal-ui/core 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +82 -23
  2. package/assets/core/preferences.d.ts +4 -4
  3. package/assets/core/preferences.js +4 -4
  4. package/assets/core/presets.d.ts +4 -3
  5. package/assets/core/presets.js +24 -18
  6. package/assets/core/spring.js +9 -10
  7. package/assets/core/state.js +7 -7
  8. package/assets/crystal.css +784 -284
  9. package/assets/crystal.d.ts +3 -3
  10. package/assets/crystal.js +100 -123
  11. package/assets/icons/heading-2.svg +1 -0
  12. package/assets/icons/heading-3.svg +1 -0
  13. package/assets/icons/heading-4.svg +1 -0
  14. package/assets/icons/link.svg +1 -0
  15. package/assets/icons/list-ordered.svg +1 -0
  16. package/assets/icons/list.svg +1 -0
  17. package/assets/icons/manifest.json +81 -2
  18. package/assets/icons/quote.svg +1 -0
  19. package/assets/icons/redo.svg +1 -0
  20. package/assets/icons/subscript.svg +1 -0
  21. package/assets/icons/undo.svg +1 -0
  22. package/assets/icons/unlink.svg +1 -0
  23. package/assets/motion.js +13 -12
  24. package/docs/accessibility.md +50 -54
  25. package/docs/adoption.md +33 -19
  26. package/docs/catalogue.md +113 -108
  27. package/docs/colors.md +67 -73
  28. package/docs/components.md +142 -66
  29. package/docs/icons.md +9 -3
  30. package/docs/materials.md +129 -117
  31. package/docs/motion-components.md +15 -15
  32. package/docs/motion.md +156 -158
  33. package/docs/principles.md +12 -12
  34. package/docs/tokens.md +129 -130
  35. package/engines.js +3 -3
  36. package/package.json +11 -3
  37. package/tokens/catalogue/01-layout.json +1 -1
  38. package/tokens/catalogue/02-navigation.json +4 -4
  39. package/tokens/catalogue/03-actions.json +2 -1
  40. package/tokens/catalogue/04-inputs.json +30 -22
  41. package/tokens/catalogue/05-data-display.json +9 -14
  42. package/tokens/catalogue/06-feedback.json +8 -6
  43. package/tokens/catalogue/07-overlays.json +4 -4
  44. package/tokens/catalogue/08-typography.json +12 -8
  45. package/tokens/catalogue/09-utility.json +1 -1
  46. package/tokens/catalogue/10-charts.json +7 -7
  47. package/tokens/catalogue/11-media.json +33 -20
  48. package/tokens/catalogue/12-commerce.json +4 -4
  49. package/tokens/catalogue/13-screens.json +2 -3
  50. package/tokens/catalogue/14-blocks.json +3 -3
  51. package/tokens/catalogue.json +176 -116
  52. package/tokens/crystal.tokens.json +6 -6
  53. package/tokens/motion-recipes.json +6 -6
  54. package/tokens/surface-recipes.json +3452 -0
  55. package/tokens/surfaces.json +48 -17
package/docs/motion.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Motion: material in movement
2
2
 
3
- Crystal’s motion makes its materials recognizable: Plastic levitates, Frost emerges toward the viewer, Resin flows and catches light, Haze and Stone carry moving feathered edges, and Mirage washes across the scene. [Open the interactive motion studies](../motion.html).
3
+ Crystal's motion makes its materials recognisable: Plastic levitates, Frost emerges toward the viewer, Resin flows and catches light, Haze and Stone carry moving feathered edges, and Mirage washes across the scene. [Open the interactive motion studies](../motion.html).
4
4
 
5
5
  ## Timing and easing
6
6
 
7
- The earlier 25% speed reduction is retained for small interaction tokens. The larger material journeys have their own longer timings so bounded travel and layered detail have time to resolve smoothly. The preview’s **1×** setting uses the defaults below.
7
+ Small interaction tokens keep the earlier 25% speed reduction. The larger material journeys have their own longer timings, so that bounded travel and layered detail have time to resolve smoothly. The preview's 1× setting uses the defaults below.
8
8
 
9
9
  | Token | Default | Use |
10
10
  |---|---|---|
@@ -20,11 +20,11 @@ The earlier 25% speed reduction is retained for small interaction tokens. The la
20
20
  | `--cr-ease-settle` | `cubic-bezier(0.2, 0, 0.2, 1)` | Small control response |
21
21
  | `--cr-ease-exit` | `cubic-bezier(0.4, 0, 0.6, 1)` | Smooth acceleration and departure |
22
22
 
23
- Ordinary travel stays within **5–30px**, with **50px as the compact-motion guideline**, not a universal ceiling. Larger or longer spatial transitions may exceed it when the movement requires it: full-width sheets, view changes, measured reordering, gallery turns and large material compositions. Each authored exception records its purpose in `travelException`; do not apply large composition motion to a small button.
23
+ Ordinary travel stays within 5px to 30px. 50px is the guideline for compact motion. Larger or longer spatial transitions may exceed it when the movement requires it: full-width sheets, view changes, measured reordering, gallery turns and large material compositions. Each authored exception records its purpose in `travelException`. Do not apply large composition motion to a small button.
24
24
 
25
- Haze and Stone retain **zero component translation** for their material signatures: their feathered paint shifts and changes contour while text stays fixed. Optical light can travel across an entire surface without moving its content. Small controls use liquid compression and surface tension rather than a generic upward lift.
25
+ Haze and Stone retain zero component translation for their material signatures: their feathered paint shifts and changes contour while text stays fixed. Optical light can travel across an entire surface without moving its content. Small controls use liquid compression and surface tension rather than a generic upward lift.
26
26
 
27
- The legacy `maxTravel: 50` token continues to bound the six compact material presets. Larger recipes explicitly define their travel and bypass that compact clamp. `layout()` uses the actual measured displacement up to the viewport diagonal, with `{extended:false}` available for a compact crossfade. Motion still respects the user speed factor, five-second duration ceiling, cancellation and reduced motion.
27
+ The legacy `maxTravel: 50` token bounds the six compact material presets. Larger recipes define their own travel and bypass that compact clamp. `layout()` uses the measured displacement up to the viewport diagonal, and `{extended:false}` is available for a compact crossfade. Motion still respects the user speed factor, five-second duration ceiling, cancellation and reduced motion.
28
28
 
29
29
  ## Material signatures
30
30
 
@@ -37,15 +37,17 @@ The legacy `maxTravel: 50` token continues to bound the six compact material pre
37
37
  | Stone | Fixed component and label; movement stays within the surface | Feathered background ripples around its fixed center; label retains its own crisp paint | Label backing study; ordinary button presses still use the short press token |
38
38
  | Mirage | Curved reveal spreads from left, right, top or bottom; withdrawal contracts toward an edge | Actual underlying colors continue to blend through its chromatic blur; no fabricated wallpaper or hue sweep | Entrance and exit specimens, native dialog backdrop |
39
39
 
40
- Resin light is a temporary optical overlay, not a change to the 20% fill recipe. Haze and Stone start and end at rest; neither slides in, scales its content nor changes label opacity during replay. Their feathered backgrounds make one quiet outward-and-return cycle. They move the already feathered `::before` layer; their blur radius stays at 1.95px and their resting opacity stays unchanged. Foreground labels are not blurred. Component transforms move their children together; Resin’s small scale/skew deformation also affects its compact label. Avoid applying that preset to long-form text.
40
+ Resin light is a temporary optical overlay, and the 20% fill recipe does not change. Haze and Stone start and end at rest. Neither slides in, scales its content or changes label opacity during replay. Their feathered backgrounds make one subdued outward-and-return cycle. The cycle moves the already feathered `::before` layer. The blur radius stays at 1.95px and the resting opacity is unchanged. Foreground labels are not blurred. Component transforms move their children together, so Resin's small scale/skew deformation also affects its compact label. Avoid applying that preset to long-form text.
41
41
 
42
- Mirage uses an expanding elliptical mask with a broad feathered front rather than physically simulated fluid. Registered CSS properties animate the reveal radius; engines without registration support use a curved clip-path fallback. The native dialog’s entrance begins at the chosen edge and its exit contracts toward the opposite edge. **Cycle directions** advances left → bottom → right → top; explicit direction choices make a study repeatable. Its fixed 28px chromatic filter continues to sample the real scene beneath the reveal.
42
+ Mirage uses an expanding elliptical mask with a broad feathered front. It does not simulate a fluid physically. Registered CSS properties animate the reveal radius, and engines without registration support use a curved clip-path fallback. The native dialog's entrance begins at the chosen edge and its exit contracts toward the opposite edge. **Cycle directions** advances through left, bottom, right and top, in that order. An explicit direction choice makes a study repeatable. Mirage's fixed 28px chromatic filter continues to sample the real scene beneath the reveal.
43
+
44
+ **In 2.x the material presets are studies (D-31).** The catalogue assigns `mirage`, `mirage-out` and `dismiss`, to the dialog and its scrim. It assigns none of `plastic`, `frost`, `resin`, `haze` and `stone`, and none of the five material compositions (`resin-confluence`, `frost-unfold`, `plastic-settle`, `haze-tide`, `stone-contour`), so a platform library is not expected to play them as entrances. The preview uses them as the table above says, as specimens and in its own scenes. Which preset a surface enters with when a person opens it (Frost for a side sheet, Resin for a floating transport) is decided per surface in 3.0, against the approved baseline.
43
45
 
44
46
  ## Working examples
45
47
 
46
- Each Replay button runs a finite animation. **Replay Mirage exit** withdraws and hides the specimen; **Replay Mirage** brings it back. Animation speed ranges from 0.25× to 2× and applies to specimens, scene transitions, button feedback and modal/backdrop timings. It is saved as `motionSpeed` alongside appearance and included in CSS/JSON exports. Labels show the resolved duration. Each resolved duration is `min(5000ms, baseDuration / motionSpeed)`; reduced motion resolves it to zero. Default sequences should stay within 0–2 seconds. Five seconds is a hard ceiling, including any extra API replay-rate adjustment. At 0.25×, Resin would take 5.6 seconds and is capped at 5 seconds; other effects retain their own scaled timings. Interactions, data and focus respond immediately even during a long visual transition. Appearance and reduced-motion preferences are shared with the main playground. No effect autoplays, and nothing loops, with one exception: a **continuous indicator** — `activity-turn`, `activity-travel`, `skeleton-sweep` — repeats while the work it reports is genuinely pending and stops when that work resolves. It is not ambient motion, which is what a surface does at rest; a continuous indicator has no rest state, only a pending one. All three share one period, `motion.flow`, and reduced motion replaces each with its whole track or fill, static. The rule is enforced by `tools/validate-motion.cjs`, which refuses a loop by any other name.
48
+ Each Replay button runs a finite animation. **Replay Mirage exit** withdraws and hides the specimen, and **Replay Mirage** brings it back. Animation speed ranges from 0.25× to 2× and applies to specimens, scene transitions, button feedback and modal/backdrop timings. It is saved as `motionSpeed` alongside appearance and included in CSS/JSON exports. Labels show the resolved duration. Each resolved duration is `min(5000ms, baseDuration / motionSpeed)`; reduced motion resolves it to zero. Default sequences should stay within 0 to 2 seconds. Five seconds is a hard ceiling, including any extra API replay-rate adjustment. At 0.25×, Resin would take 5.6 seconds and is capped at 5 seconds; other effects retain their own scaled timings. Interactions, data and focus respond immediately even during a long visual transition. Appearance and reduced-motion preferences are shared with the main playground. No effect autoplays, and nothing loops, with one exception. A **continuous indicator** (`activity-turn`, `activity-travel` or `skeleton-sweep`) repeats while the work it reports is genuinely pending and stops when that work resolves. Ambient motion is what a surface does at rest. A continuous indicator has no rest state, only a pending one, so it is not ambient motion. All three share one period, `motion.flow`, and reduced motion replaces each with its whole track or fill, static. `tools/validate-motion.cjs` enforces the rule and refuses any other loop.
47
49
 
48
- The native modal opens with Haze’s in-place edge motion, matching its content material, while Mirage reveals the backdrop. Its content stays fixed on entrance; dismissal fades it in place while its edge settles. Focus and modality take effect immediately. The 650ms default exit (scaled by the speed preference, capped at five seconds) finishes before the dialog closes and focus returns. Escape uses that same path; repeated dismissal requests do not stack.
50
+ The native modal opens with Haze's in-place edge motion, matching its content material, while Mirage reveals the backdrop. Its content stays fixed on entrance; dismissal fades it in place while its edge settles. Focus and modality take effect immediately. The 650ms default exit (scaled by the speed preference, capped at five seconds) finishes before the dialog closes and focus returns. Escape uses that same path; repeated dismissal requests do not stack.
49
51
 
50
52
  ## Interruption, accessibility and rendering
51
53
 
@@ -72,16 +74,16 @@ CrystalMotion.stopAll();
72
74
  CrystalMotion.direction(dialog, 'bottom');
73
75
  ```
74
76
 
75
- Presets: `plastic`, `frost`, `resin`, `haze`, `stone`, `mirage`, `mirage-out`, `dismiss`. The optional `direction` accepts `left`, `right`, `top`, `bottom`; omission or `cycle` chooses the next direction. The adapter does not hide or remove targets; callers own exit completion. The playground implements the specimen’s hidden state explicitly.
77
+ Presets: `plastic`, `frost`, `resin`, `haze`, `stone`, `mirage`, `mirage-out`, `dismiss`. The optional `direction` accepts `left`, `right`, `top`, `bottom`; omission or `cycle` chooses the next direction. The adapter does not hide or remove targets; callers own exit completion. The playground implements the specimen's hidden state explicitly.
76
78
 
77
- GSAP controls paint-layer motion through Web Animations pseudo-element targeting on `::before` and `::after`. Engines without that support retain supported component movement and may omit the optional optical effects. Haze and Stone stay still in that fallback rather than substituting a sliding animation. Invalid targets or unknown presets produce errors; unavailable animation APIs return `instant`. Material selectors must supply the actual pseudo-element paints. Use Haze motion for Haze dialogs rather than reusing Resin’s deforming rim on them.
79
+ GSAP controls paint-layer motion through Web Animations pseudo-element targeting on `::before` and `::after`. Engines without that support retain supported component movement and may omit the optional optical effects. In that fallback Haze and Stone stay still. No sliding animation is substituted for them. Invalid targets or unknown presets produce errors; unavailable animation APIs return `instant`. Material selectors must supply the actual pseudo-element paints. Use Haze motion for Haze dialogs. Do not reuse Resin's deforming rim on them.
78
80
 
79
- The canonical motion definitions live in `tokens/crystal.json`; CSS and JSON exports include both compact and expressive durations and travel values. Always include `motion.css` for native dialog backdrop choreography and accessibility overrides. The reference provides real visual behavior, not a native compositor or a physics simulation.
81
+ The canonical motion definitions live in `tokens/crystal.json`; CSS and JSON exports include both compact and expressive durations and travel values. Always include `motion.css` for native dialog backdrop choreography and accessibility overrides. The reference provides real visual behaviour. It does not provide a native compositor or a physics simulation.
80
82
 
81
83
 
82
84
  ## Installed animation engines
83
85
 
84
- Both engines are now installed, bundled locally and used by the runtime. [Motion’s animate API](https://motion.dev/docs/animate) drives element keyframes. [GSAP timelines](https://gsap.com/docs/v3/GSAP/Timeline/) control material paint-layer clocks and selected component sequences. Native Web Animations effects paint actual pseudo-elements under those GSAP clocks; CSS supplies the native dialog backdrop fallback.
86
+ Both engines are installed, bundled locally and used by the runtime. [Motion's animate API](https://motion.dev/docs/animate) drives element keyframes. [GSAP timelines](https://gsap.com/docs/v3/GSAP/Timeline/) control material paint-layer clocks and selected component sequences. Native Web Animations effects paint actual pseudo-elements under those GSAP clocks; CSS supplies the native dialog backdrop fallback.
85
87
 
86
88
  See the [component motion suite](motion-components.html) for all 59 recipes, engine assignments, API contracts, live component behavior, test instructions and future component-library/Storybook coverage. [License notices](../reference/ASSET-NOTICES.md) accompany the local bundle.
87
89
 
@@ -89,20 +91,20 @@ The compact CSS timing tokens remain available for small state changes. The mate
89
91
 
90
92
  ## Springs are the portable primitive
91
93
 
92
- Every recipe carries a spring — `{stiffness, damping, mass}` — fitted so that its derived
94
+ Every recipe carries a spring, `{stiffness, damping, mass}`, fitted so that its derived
93
95
  settle time matches the authored duration within 15%. The authored duration remains the
94
- authority; the spring is what makes the recipe portable, because a duration and a cubic
95
- bezier do not survive being moved to SwiftUI or Compose, and a spring does.
96
+ authority. The spring makes the recipe portable: a duration and a cubic bezier do not
97
+ survive being moved to SwiftUI or Compose, and a spring does.
96
98
 
97
99
  `assets/core/spring.js` derives everything else from those three numbers, with no DOM and
98
100
  no dependencies: damping ratio, sampled displacement, settle time, whether the recipe
99
101
  overshoots and by how much. The generated table below is computed from it at build time,
100
- which is why the numbers there cannot go stale.
102
+ so its numbers cannot go stale.
101
103
 
102
104
  ### The three regimes
103
105
 
104
- The damping ratio **ζ = c / (2√(km))** decides which closed form applies, and they are
105
- genuinely different equations rather than one equation with a parameter:
106
+ The damping ratio ζ = c / (2√(km)) decides which closed form applies. The three closed
107
+ forms are separate equations, not one equation with a parameter:
106
108
 
107
109
  | ζ | Regime | Behaviour |
108
110
  | --- | --- | --- |
@@ -115,73 +117,70 @@ damped frequency of zero. `sampleSpring` branches on the regime explicitly.
115
117
 
116
118
  ### Damping is chosen by signature, not by taste
117
119
 
118
- Whether a movement overshoots is a claim about what the material *is*:
120
+ Whether a movement overshoots says what the material is:
119
121
 
120
- - **`inertia`** and **`coalesce`** overshoot, most of all — momentum is their entire claim.
121
- Mass that stops dead was never moving.
122
- - **`feather`** and **`caustic`** do not overshoot. A soft edge that bounces is wrong: the
123
- signature is diffusion, and diffusion has no momentum to carry.
122
+ - `inertia` and `coalesce` overshoot the most, because their signature is momentum.
123
+ - `feather` and `caustic` do not overshoot. Their signature is diffusion, and diffusion
124
+ has no momentum to carry, so a soft edge that bounces is wrong.
124
125
  - Everything between is scaled accordingly.
125
126
 
126
127
  The generated table shows measured peak overshoot per recipe. `feather` comes out at 0.1%
127
- and `inertia` at 12.6% — the fitting produces the policy rather than being asserted
128
- alongside it.
128
+ and `inertia` at 12.6%. Both figures come from the fitted springs, so the fitting produces
129
+ the policy and the policy is not asserted separately.
129
130
 
130
131
  ## Deformation is incompressible
131
132
 
132
- Any `scale(sx, sy)` in a recipe must satisfy **sx · sy = 1** within 0.005. A surface that
133
- squashes without spreading is a surface losing volume, and it reads as cheap because
134
- nothing physical behaves that way.
133
+ Any `scale(sx, sy)` in a recipe must satisfy sx · sy = 1 within 0.005. A surface that
134
+ squashes without spreading loses volume, which nothing physical does, and it reads as
135
+ cheap.
135
136
 
136
- Corrections divide **both** axes by the square root of the area. Keeping the dominant axis
137
+ Corrections divide both axes by the square root of the area. Keeping the dominant axis
137
138
  and deriving the other also conserves volume, but it changes the deformation's aspect
138
- ratio — which alters the designed look rather than only the physics. Normalising by √area
139
- conserves volume *and* preserves aspect ratio exactly, so the correction removes the
140
- compressibility error and nothing else. `tools/validate-motion.cjs` asserts both.
139
+ ratio, which alters the designed look. Normalising by √area conserves volume and preserves
140
+ aspect ratio exactly, so the correction removes only the compressibility error.
141
+ `tools/validate-motion.cjs` asserts both.
141
142
 
142
143
  ## Why Resin is not animated with ripples
143
144
 
144
- An early model animated Resin as a surface wave — a ripple spreading from the contact
145
- point. It was rejected, and the reasoning is recorded here because the rejected model is
146
- the one people reach for first.
145
+ The model people reach for first animates Resin as a surface wave: a ripple spreading from
146
+ the contact point. Crystal rejects that model.
147
147
 
148
- A ripple is a *surface* phenomenon: it says the material has a skin, that the skin was
149
- disturbed, and that the disturbance is travelling across it. That is water in a dish. Resin
150
- is not a skin; it is a solid, transparent body with optical depth. Its response to contact
151
- is not a wave — it is a change in how it bends light.
148
+ A ripple is a surface phenomenon: it says the material has a skin, that the skin was
149
+ disturbed, and that the disturbance is travelling across it, like water in a dish. Resin
150
+ has no skin: it is a solid, transparent body with optical depth. Its response to contact
151
+ is a change in how it bends light.
152
152
 
153
- What contemporary glass interfaces actually do, and what Crystal now does:
153
+ Crystal does what contemporary glass interfaces do:
154
154
 
155
155
  - **Edge lensing.** Refraction concentrates in a band just inside the boundary and falls
156
156
  off steeply, leaving the centre optically clear. The interior is shrunk and the edges
157
157
  stretched outward.
158
- - **Specular tracking.** The highlight band moves with the interaction rather than
159
- spreading from it. Contact changes where the light is, not what the surface shape is.
158
+ - **Specular tracking.** The highlight band moves with the interaction and does not spread
159
+ from it. Contact changes where the light is and does not change the shape of the surface.
160
160
  - **Morphing.** The boundary itself changes shape. The lens follows the boundary, because
161
- the lens *is* the boundary.
161
+ the lens is the boundary.
162
162
 
163
- The practical difference: a ripple animates the middle of a surface, where the user is
164
- reading. Edge lensing animates the rim, where nothing is. The optical model is stated in
163
+ A ripple animates the middle of a surface, where the user is reading. Edge lensing
164
+ animates the rim, where nothing is. The optical model is stated in
165
165
  `assets/shaders/manifest.json` under `opticalModel`, including the rejected approach, so
166
- that a platform port inherits the reasoning and not just the result.
166
+ that a platform port inherits the reasoning as well as the result.
167
167
 
168
168
  ## The shader layer is an enhancement, never a requirement
169
169
 
170
170
  WebGL2 shaders are attached only when WebGL2 is available, `prefers-reduced-motion` is not
171
- set, and the surface is visible. The CSS approximation is the floor, and it is what the
172
- committed visual baselines are captured against — with WebGL2 unavailable, every page must
173
- render exactly those baselines. That is the gate that keeps the shader optional rather
174
- than load-bearing.
171
+ set, and the surface is visible. The CSS approximation is the floor, and the committed
172
+ visual baselines are captured against it. With WebGL2 unavailable, every page must render
173
+ exactly those baselines. That gate keeps the shader optional.
175
174
 
176
- Two implementation notes that cost real time to find:
175
+ Two implementation notes:
177
176
 
178
- **Blend mode.** `screen` and `overlay` are both no-ops on a white backdrop — `overlay`
177
+ **Blend mode.** `screen` and `overlay` are both no-ops on a white backdrop: `overlay`
179
178
  resolves to `1 − 2(1−b)(1−s)`, which is 1 whenever b = 1. Only `hard-light` produces
180
179
  visible output on both white and dark backdrops.
181
180
 
182
181
  **Stacking.** The shader canvas sits at `z-index:-1` inside an `isolation:isolate`
183
- container, so it paints behind the content rather than over it. Verified by proving label
184
- glyphs are pixel-identical with the shader on and off.
182
+ container, so it paints behind the content. This is verified by label glyphs that are
183
+ pixel-identical with the shader on and off.
185
184
 
186
185
 
187
186
  ## Ambient motion
@@ -189,18 +188,17 @@ glyphs are pixel-identical with the shader on and off.
189
188
  **Deferred to a later version of Crystal.** Nothing in 2.0 moves at rest, and a surface
190
189
  that animates on its own is not Crystal until a later version specifies how.
191
190
 
192
- It was built and withdrawn rather than never attempted, and the reasoning is in the
193
- request log rather than lost. Two findings will apply whenever it returns: a rest state
194
- can fail by being too strong *or* too weak, so it needs a measured floor as well as a
195
- ceiling; and its cost on the reference preview did not follow resolution, blend mode,
196
- nesting or shader complexity, which means it was structural rather than a tuning problem.
191
+ Ambient motion was built and then withdrawn, and the reasoning is in the request log. Two
192
+ findings apply whenever it returns. A rest state can fail by being too strong or too weak,
193
+ so it needs a measured floor as well as a ceiling. Its cost on the reference preview did
194
+ not follow resolution, blend mode, nesting or shader complexity, so the cost was
195
+ structural and not a tuning problem.
197
196
 
198
197
  Motion a person starts is unaffected, and so is the optical layer that runs during it.
199
198
 
200
199
  ## What triggers a recipe
201
200
 
202
- A recipe that nothing triggers is a specification, not a behaviour. Crystal binds motion
203
- to **state, not to clicks**:
201
+ Crystal binds motion to state, not to clicks:
204
202
 
205
203
  | State change | Recipe |
206
204
  | --- | --- |
@@ -213,13 +211,13 @@ to **state, not to clicks**:
213
211
  | A `<details>` opens or closes | `accordion-in` / `accordion-out` |
214
212
  | A button is pressed or hovered | `press` / `hover` |
215
213
 
216
- Binding to `pointerdown` instead of to the state would give a mouse user motion that a
217
- keyboard user and a screen reader user never see. Binding to the state means every input
218
- method produces the same motion, and a programmatic change produces it too.
214
+ A recipe bound to `pointerdown` gives a mouse user motion that a keyboard user and a
215
+ screen reader user never see. With a recipe bound to the state, every input method
216
+ produces the same motion, and a programmatic change produces it too.
219
217
 
220
- Two guards matter in practice. A recipe never restarts itself while that same recipe is
221
- already running on that element — restarting mid-flight is what makes a continuous control
222
- feel choppy. And a page that drives a component itself marks that subtree
218
+ There are two guards. A recipe never restarts itself while that same recipe is already
219
+ running on that element, because restarting mid-flight makes a continuous control feel
220
+ choppy. A page that drives a component itself marks that subtree
223
221
  `data-cr-motion="manual"`, so the delegated wiring does not fire the same recipe twice.
224
222
 
225
223
  `npm run verify:interactions` asserts all of this in a real browser against plain controls,
@@ -230,125 +228,125 @@ including that reduced motion still applies the state instantly.
230
228
 
231
229
  <!-- generated:recipes -->
232
230
 
233
- All 59 recipes in 9 categories, generated from `core/tokens/motion-recipes.json`. **Damping ratio** and
234
- **overshoot** are derived from each recipe's spring by `core/assets/core/spring.js`, not
235
- authored — so a spring that was retuned cannot leave a stale number behind in this table.
231
+ All 59 recipes in 9 categories, generated from `core/tokens/motion-recipes.json`. Damping ratio and
232
+ overshoot are derived from each recipe's spring by `core/assets/core/spring.js`, so a
233
+ retuned spring cannot leave a stale number in this table.
236
234
 
237
235
  A damping ratio below 1 overshoots and settles back; exactly 1 is the fastest approach
238
236
  with no overshoot; above 1 crawls in without ever passing the target. Which one is
239
- correct is a material question, not a taste question — see the signature policy below.
237
+ correct is a material question; see the signature policy below.
240
238
 
241
239
  #### Controls
242
240
 
243
241
  | Recipe | Duration | Signature | Material | Damping ζ | Overshoot | Use | Reduced motion |
244
242
  | --- | --- | --- | --- | --- | --- | --- | --- |
245
- | `press` — Press and release | 320ms | pressure | resin | 0.660 | 6.3% | Buttons, icon buttons and segmented controls. Disabled controls never animate. | Apply the semantic state immediately; omit decorative movement. |
246
- | `hover` — Light follows the surface | 700ms | caustic | resin | 0.900 | 0.2% | Fine-pointer affordance only; keyboard focus is immediate. | Apply the semantic state immediately; omit decorative movement. |
247
- | `selection` — Selection settle | 420ms | meniscus | resin | 0.700 | 4.6% | Selected chips, radios, toggles and navigation; set selected semantics first. | Apply the semantic state immediately; omit decorative movement. |
248
- | `switch-on` — Switch on | 460ms | coalesce | resin | 0.620 | 8.4% | Animate the thumb after its checked state is applied. | Apply the semantic state immediately; omit decorative movement. |
249
- | `switch-off` — Switch off | 460ms | coalesce | resin | 0.620 | 8.4% | Animate the thumb after its unchecked state is applied. | Apply the semantic state immediately; omit decorative movement. |
250
- | `check` — Checkmark confirmation | 340ms | iris | resin | 0.800 | 1.5% | Checkbox and radio indicators; retain a visible non-color state. | Apply the semantic state immediately; omit decorative movement. |
251
- | `slider-step` — Value response | 400ms | feather | stone | 0.920 | none | Range outputs, steppers and scrubber labels; value updates immediately. | Apply the semantic state immediately; omit decorative movement. |
252
- | `icon-turn` — Disclosure icon | 440ms | torsion | resin | 0.660 | 6.3% | Disclosure chevrons; parent expanded state is authoritative. | Apply the semantic state immediately; omit decorative movement. |
253
- | `copy-confirm` — Copy confirmation | 540ms | coalesce | resin | 0.620 | 8.4% | Only after clipboard write succeeds; retain textual confirmation. | Apply the semantic state immediately; omit decorative movement. |
254
- | `check-off` — Uncheck | 300ms | iris | plastic | 0.800 | 1.5% | Checkbox and radio indicators returning to unchecked. Paired with `check`; the iris closes toward the same point it opened from. | Apply the unchecked state immediately; omit the iris. |
243
+ | `press`: Press and release | 320ms | pressure | resin | 0.660 | 6.3% | Buttons, icon buttons and segmented controls. Disabled controls never animate. | Apply the semantic state immediately; omit decorative movement. |
244
+ | `hover`: Light follows the surface | 700ms | caustic | resin | 0.900 | 0.2% | Fine-pointer affordance only; keyboard focus is immediate. | Apply the semantic state immediately; omit decorative movement. |
245
+ | `selection`: Selection settle | 420ms | meniscus | resin | 0.700 | 4.6% | Selected chips, radios, toggles and navigation; set selected semantics first. | Apply the semantic state immediately; omit decorative movement. |
246
+ | `switch-on`: Switch on | 460ms | coalesce | resin | 0.620 | 8.4% | Animate the thumb after its checked state is applied. | Apply the semantic state immediately; omit decorative movement. |
247
+ | `switch-off`: Switch off | 460ms | coalesce | resin | 0.620 | 8.4% | Animate the thumb after its unchecked state is applied. | Apply the semantic state immediately; omit decorative movement. |
248
+ | `check`: Checkmark confirmation | 340ms | iris | resin | 0.800 | 1.5% | Checkbox and radio indicators; retain a visible non-color state. | Apply the semantic state immediately; omit decorative movement. |
249
+ | `slider-step`: Value response | 400ms | feather | stone | 0.920 | none | Range outputs, steppers and scrubber labels; value updates immediately. | Apply the semantic state immediately; omit decorative movement. |
250
+ | `icon-turn`: Disclosure icon | 440ms | torsion | resin | 0.660 | 6.3% | Disclosure chevrons; parent expanded state is authoritative. | Apply the semantic state immediately; omit decorative movement. |
251
+ | `copy-confirm`: Copy confirmation | 540ms | coalesce | resin | 0.620 | 8.4% | Only after clipboard write succeeds; retain textual confirmation. | Apply the semantic state immediately; omit decorative movement. |
252
+ | `check-off`: Uncheck | 300ms | iris | plastic | 0.800 | 1.5% | Checkbox and radio indicators returning to unchecked. Paired with `check`; the iris closes toward the same point it opened from. | Apply the unchecked state immediately; omit the iris. |
255
253
 
256
254
  #### Forms
257
255
 
258
256
  | Recipe | Duration | Signature | Material | Damping ζ | Overshoot | Use | Reduced motion |
259
257
  | --- | --- | --- | --- | --- | --- | --- | --- |
260
- | `field-focus` — Field focus response | 600ms | caustic | resin | 0.900 | 0.2% | Supplementary focus response; never animate or delay the actual focus ring. | Apply the semantic state immediately; omit decorative movement. |
261
- | `field-invalid` — Invalid field | 480ms | tension | resin | 0.700 | 4.6% | Single low-amplitude cue with persistent error text; never repeated shaking. | Apply the semantic state immediately; omit decorative movement. |
262
- | `field-valid` — Valid field | 550ms | meniscus | resin | 0.700 | 4.6% | After real local validation; never imply a remote operation succeeded. | Apply the semantic state immediately; omit decorative movement. |
263
- | `hint-in` — Help text reveal | 500ms | coalesce | resin | 0.620 | 8.4% | Inline help, character guidance and validation details. | Apply the semantic state immediately; omit decorative movement. |
264
- | `hint-out` — Help text departure | 500ms | meniscus | resin | 0.700 | 4.6% | Hide the help only after completion; do not remove focused content. | Apply the semantic state immediately; omit decorative movement. |
258
+ | `field-focus`: Field focus response | 600ms | caustic | resin | 0.900 | 0.2% | Supplementary focus response; never animate or delay the actual focus ring. | Apply the semantic state immediately; omit decorative movement. |
259
+ | `field-invalid`: Invalid field | 480ms | tension | resin | 0.700 | 4.6% | Single low-amplitude cue with persistent error text; never repeated shaking. | Apply the semantic state immediately; omit decorative movement. |
260
+ | `field-valid`: Valid field | 550ms | meniscus | resin | 0.700 | 4.6% | After real local validation; never imply a remote operation succeeded. | Apply the semantic state immediately; omit decorative movement. |
261
+ | `hint-in`: Help text reveal | 500ms | coalesce | resin | 0.620 | 8.4% | Inline help, character guidance and validation details. | Apply the semantic state immediately; omit decorative movement. |
262
+ | `hint-out`: Help text departure | 500ms | meniscus | resin | 0.700 | 4.6% | Hide the help only after completion; do not remove focused content. | Apply the semantic state immediately; omit decorative movement. |
265
263
 
266
264
  #### Navigation
267
265
 
268
266
  | Recipe | Duration | Signature | Material | Damping ζ | Overshoot | Use | Reduced motion |
269
267
  | --- | --- | --- | --- | --- | --- | --- | --- |
270
- | `tab-in` — Tab content arrival | 650ms | refraction | frost | 0.850 | 0.6% | Selected tab panels; apply aria-selected and hidden state synchronously. | Apply the semantic state immediately; omit decorative movement. |
271
- | `page-in` — View arrival | 1050ms | inertia | plastic | 0.550 | 12.6% | New local view after routing is committed; preserve focus and history. | Apply the semantic state immediately; omit decorative movement. |
272
- | `page-out` — View departure | 760ms | inertia | plastic | 0.550 | 12.6% | Departing view only; never postpone route authorization or loading. | Apply the semantic state immediately; omit decorative movement. |
273
- | `view-push-in` — Pushed view arrival | 700ms | inertia | plastic | 0.550 | 12.6% | A view pushed onto a stack. It arrives from the inline-end edge, along the reading direction, so the movement says the stack went forward. Mirror it for a pop, and again for right-to-left. | Apply the semantic state immediately; omit decorative movement. |
274
- | `view-push-out` — Pushed view departure | 700ms | inertia | plastic | 0.550 | 12.6% | The view a push covered. It travels a fraction of the incoming view's distance and stays behind it, so the two read as one stack rather than two independent slides; it is still there, which is what makes the back gesture legible. | Apply the semantic state immediately; omit decorative movement. |
275
- | `breadcrumb` — Location update | 500ms | coalesce | resin | 0.620 | 8.4% | New breadcrumb item; current-page semantics stay explicit. | Apply the semantic state immediately; omit decorative movement. |
268
+ | `tab-in`: Tab content arrival | 650ms | refraction | frost | 0.850 | 0.6% | Selected tab panels; apply aria-selected and hidden state synchronously. | Apply the semantic state immediately; omit decorative movement. |
269
+ | `page-in`: View arrival | 1050ms | inertia | plastic | 0.550 | 12.6% | New local view after routing is committed; preserve focus and history. | Apply the semantic state immediately; omit decorative movement. |
270
+ | `page-out`: View departure | 760ms | inertia | plastic | 0.550 | 12.6% | Departing view only; never postpone route authorization or loading. | Apply the semantic state immediately; omit decorative movement. |
271
+ | `view-push-in`: Pushed view arrival | 700ms | inertia | plastic | 0.550 | 12.6% | A view pushed onto a stack. It arrives from the inline-end edge, along the reading direction, so the movement says the stack went forward. Mirror it for a pop, and again for right-to-left. | Apply the semantic state immediately; omit decorative movement. |
272
+ | `view-push-out`: Pushed view departure | 700ms | inertia | plastic | 0.550 | 12.6% | The view a push covered. It travels a fraction of the incoming view's distance and stays behind it, so the two read as one stack rather than two independent slides; it is still there, which is what makes the back gesture legible. | Apply the semantic state immediately; omit decorative movement. |
273
+ | `breadcrumb`: Location update | 500ms | coalesce | resin | 0.620 | 8.4% | New breadcrumb item; current-page semantics stay explicit. | Apply the semantic state immediately; omit decorative movement. |
276
274
 
277
275
  #### Overlays
278
276
 
279
277
  | Recipe | Duration | Signature | Material | Damping ζ | Overshoot | Use | Reduced motion |
280
278
  | --- | --- | --- | --- | --- | --- | --- | --- |
281
- | `drawer-in` — Drawer arrival | 1000ms | refraction | frost | 0.850 | 0.6% | Side sheets and inspector panels; establish modality first. | Apply the semantic state immediately; omit decorative movement. |
282
- | `drawer-out` — Drawer departure | 650ms | refraction | frost | 0.850 | 0.6% | Keep modal focus contained until dismissal completes. | Apply the semantic state immediately; omit decorative movement. |
283
- | `menu-in` — Menu reveal | 620ms | coalesce | resin | 0.620 | 8.4% | Dropdowns, selects and command menus; keyboard behavior belongs to the component. | Apply the semantic state immediately; omit decorative movement. |
284
- | `menu-out` — Menu dismissal | 380ms | meniscus | resin | 0.700 | 4.6% | Close menus and restore trigger focus when appropriate. | Apply the semantic state immediately; omit decorative movement. |
285
- | `tooltip-in` — Tooltip arrival | 420ms | meniscus | resin | 0.700 | 4.6% | Noninteractive descriptions on focus or hover; Escape dismisses. | Apply the semantic state immediately; omit decorative movement. |
286
- | `tooltip-out` — Tooltip departure | 420ms | meniscus | resin | 0.700 | 4.6% | Pointer and focus must both leave before hiding. | Apply the semantic state immediately; omit decorative movement. |
287
- | `popover-in` — Popover arrival | 620ms | coalesce | resin | 0.620 | 8.4% | Nonmodal details with outside-click, Escape and focus handling. | Apply the semantic state immediately; omit decorative movement. |
288
- | `popover-out` — Popover departure | 380ms | meniscus | resin | 0.700 | 4.6% | Dismiss nonmodal details without trapping focus. | Apply the semantic state immediately; omit decorative movement. |
279
+ | `drawer-in`: Drawer arrival | 1000ms | refraction | frost | 0.850 | 0.6% | Side sheets and inspector panels; establish modality first. | Apply the semantic state immediately; omit decorative movement. |
280
+ | `drawer-out`: Drawer departure | 650ms | refraction | frost | 0.850 | 0.6% | Keep modal focus contained until dismissal completes. | Apply the semantic state immediately; omit decorative movement. |
281
+ | `menu-in`: Menu reveal | 620ms | coalesce | resin | 0.620 | 8.4% | Dropdowns, selects and command menus; keyboard behavior belongs to the component. | Apply the semantic state immediately; omit decorative movement. |
282
+ | `menu-out`: Menu dismissal | 380ms | meniscus | resin | 0.700 | 4.6% | Close menus and restore trigger focus when appropriate. | Apply the semantic state immediately; omit decorative movement. |
283
+ | `tooltip-in`: Tooltip arrival | 420ms | meniscus | resin | 0.700 | 4.6% | Noninteractive descriptions on focus or hover; Escape dismisses. | Apply the semantic state immediately; omit decorative movement. |
284
+ | `tooltip-out`: Tooltip departure | 420ms | meniscus | resin | 0.700 | 4.6% | Pointer and focus must both leave before hiding. | Apply the semantic state immediately; omit decorative movement. |
285
+ | `popover-in`: Popover arrival | 620ms | coalesce | resin | 0.620 | 8.4% | Nonmodal details with outside-click, Escape and focus handling. | Apply the semantic state immediately; omit decorative movement. |
286
+ | `popover-out`: Popover departure | 380ms | meniscus | resin | 0.700 | 4.6% | Dismiss nonmodal details without trapping focus. | Apply the semantic state immediately; omit decorative movement. |
289
287
 
290
288
  #### Content
291
289
 
292
290
  | Recipe | Duration | Signature | Material | Damping ζ | Overshoot | Use | Reduced motion |
293
291
  | --- | --- | --- | --- | --- | --- | --- | --- |
294
- | `accordion-in` — Disclosure reveal | 650ms | feather | haze | 0.920 | none | Animate visible content after expanding; no scripted height measurement needed. | Apply the semantic state immediately; omit decorative movement. |
295
- | `accordion-out` — Disclosure close | 650ms | feather | haze | 0.920 | none | Hide content after completion; return focus first if a child has focus. | Apply the semantic state immediately; omit decorative movement. |
296
- | `list-in` — Item insertion | 650ms | feather | haze | 0.920 | none | Real added messages, table rows, cards and collection items. | Apply the semantic state immediately; omit decorative movement. |
297
- | `list-out` — Item removal | 440ms | feather | haze | 0.920 | none | Remove after completion; announce the actual change and keep focus valid. | Apply the semantic state immediately; omit decorative movement. |
298
- | `reorder` — Reorder settle | 500ms | inertia | plastic | 0.550 | 12.6% | Supplement DOM reordering; use layout() for measured bounded displacement. | Apply the semantic state immediately; omit decorative movement. |
299
- | `highlight` — Updated content | 500ms | feather | haze | 0.920 | none | A brief update cue paired with actual content or announcement. | Apply the semantic state immediately; omit decorative movement. |
300
- | `message-in` — Message arrival | 650ms | feather | haze | 0.920 | none | Only on a new message; do not replay on virtualized history or steal scroll. | Apply the semantic state immediately; omit decorative movement. |
301
- | `skeleton-sweep` — Luminance sweep | 1200ms | feather | haze | linear loop | — | A skeleton while its content is genuinely loading, on the Haze fill and never on the text that replaces it. Ends with skeleton-resolve. | Static Haze fill. |
302
- | `mark-in` — Mark arriving | 500ms | feather | haze | 1.000 | none | A data mark — a bar, a series, a segment — growing from its baseline when a chart first appears, and not when its data later changes. transform-origin is the baseline. Staggered by index up to 24 marks; past that every mark arrives together, because a sequence nobody can count is decoration. Staggered 24ms per mark, up to 24. | Marks appear in place at their values. |
292
+ | `accordion-in`: Disclosure reveal | 650ms | feather | haze | 0.920 | none | Animate visible content after expanding; no scripted height measurement needed. | Apply the semantic state immediately; omit decorative movement. |
293
+ | `accordion-out`: Disclosure close | 650ms | feather | haze | 0.920 | none | Hide content after completion; return focus first if a child has focus. | Apply the semantic state immediately; omit decorative movement. |
294
+ | `list-in`: Item insertion | 650ms | feather | haze | 0.920 | none | Real added messages, table rows, cards and collection items. | Apply the semantic state immediately; omit decorative movement. |
295
+ | `list-out`: Item removal | 440ms | feather | haze | 0.920 | none | Remove after completion; announce the actual change and keep focus valid. | Apply the semantic state immediately; omit decorative movement. |
296
+ | `reorder`: Reorder settle | 500ms | inertia | plastic | 0.550 | 12.6% | Supplement DOM reordering; use layout() for measured bounded displacement. | Apply the semantic state immediately; omit decorative movement. |
297
+ | `highlight`: Updated content | 500ms | feather | haze | 0.920 | none | A brief update cue paired with actual content or announcement. | Apply the semantic state immediately; omit decorative movement. |
298
+ | `message-in`: Message arrival | 650ms | feather | haze | 0.920 | none | Only on a new message; do not replay on virtualized history or steal scroll. | Apply the semantic state immediately; omit decorative movement. |
299
+ | `skeleton-sweep`: Luminance sweep | 1200ms | feather | haze | linear loop | None | A skeleton while its content is genuinely loading, on the Haze fill and never on the text that replaces it. Ends with skeleton-resolve. | Static Haze fill. |
300
+ | `mark-in`: Mark arriving | 500ms | feather | haze | 1.000 | none | A data mark (a bar, a series, a segment) growing from its baseline when a chart first appears, and not when its data later changes. transform-origin is the baseline. Staggered by index up to 24 marks; past that every mark arrives together, because a sequence nobody can count is decoration. Staggered 24ms per mark, up to 24. | Marks appear in place at their values. |
303
301
 
304
302
  #### Feedback
305
303
 
306
304
  | Recipe | Duration | Signature | Material | Damping ζ | Overshoot | Use | Reduced motion |
307
305
  | --- | --- | --- | --- | --- | --- | --- | --- |
308
- | `toast-in` — Notification arrival | 650ms | coalesce | resin | 0.620 | 8.4% | Live status text with a persistent dismiss button. | Apply the semantic state immediately; omit decorative movement. |
309
- | `toast-out` — Notification departure | 440ms | meniscus | resin | 0.700 | 4.6% | No timer required; manual dismissal preserves reading time. | Apply the semantic state immediately; omit decorative movement. |
310
- | `success` — Success acknowledgement | 600ms | feather | stone | 0.920 | none | Use after a successful operation with text and a recognizable mark. | Apply the semantic state immediately; omit decorative movement. |
311
- | `attention` — Attention cue | 500ms | feather | stone | 0.920 | none | Single finite cue for important text; never flash or loop. | Apply the semantic state immediately; omit decorative movement. |
312
- | `progress-change` — Progress settle | 500ms | feather | stone | 0.920 | none | Actual progress is set first; this animation does not fabricate completion. | Apply the semantic state immediately; omit decorative movement. |
313
- | `skeleton-resolve` — Loading content resolve | 650ms | feather | haze | 0.920 | none | Replace a skeleton only when real data arrives; no endless shimmer. | Apply the semantic state immediately; omit decorative movement. |
314
- | `empty-in` — Empty-state reveal | 500ms | coalesce | resin | 0.620 | 8.4% | Shown only when the collection is actually empty. | Apply the semantic state immediately; omit decorative movement. |
315
- | `activity-turn` — Indeterminate arc | 1200ms | feather | stone | linear loop | — | A loader, or an indeterminate progress ring, while an operation is genuinely pending — and only then. Starts when the work starts and stops when it resolves. One period for every continuous indicator, so two in one view never tick against each other. | Static: the whole track visible and nothing turning. Never a partial arc, which reports a measurement nobody took. |
316
- | `activity-travel` — Indeterminate bar | 1200ms | feather | stone | linear loop | — | Indeterminate linear progress while an operation is genuinely pending, stopping when it resolves or becomes measurable. | Static: the whole track visible. A segment frozen part of the way along reports a measurement nobody took. |
306
+ | `toast-in`: Notification arrival | 650ms | coalesce | resin | 0.620 | 8.4% | Live status text with a persistent dismiss button. | Apply the semantic state immediately; omit decorative movement. |
307
+ | `toast-out`: Notification departure | 440ms | meniscus | resin | 0.700 | 4.6% | No timer required; manual dismissal preserves reading time. | Apply the semantic state immediately; omit decorative movement. |
308
+ | `success`: Success acknowledgement | 600ms | feather | stone | 0.920 | none | Use after a successful operation with text and a recognizable mark. | Apply the semantic state immediately; omit decorative movement. |
309
+ | `attention`: Attention cue | 500ms | feather | stone | 0.920 | none | Single finite cue for important text; never flash or loop. | Apply the semantic state immediately; omit decorative movement. |
310
+ | `progress-change`: Progress settle | 500ms | feather | stone | 0.920 | none | Actual progress is set first; this animation does not fabricate completion. | Apply the semantic state immediately; omit decorative movement. |
311
+ | `skeleton-resolve`: Loading content resolve | 650ms | feather | haze | 0.920 | none | Replace a skeleton only when real data arrives; no endless shimmer. | Apply the semantic state immediately; omit decorative movement. |
312
+ | `empty-in`: Empty-state reveal | 500ms | coalesce | resin | 0.620 | 8.4% | Shown only when the collection is actually empty. | Apply the semantic state immediately; omit decorative movement. |
313
+ | `activity-turn`: Indeterminate arc | 1200ms | feather | stone | linear loop | None | A loader, or an indeterminate progress ring, only while an operation is genuinely pending. Starts when the work starts and stops when it resolves. One period for every continuous indicator, so two in one view never tick against each other. | Static: the whole track visible and nothing turning. Never a partial arc, which reports a measurement nobody took. |
314
+ | `activity-travel`: Indeterminate bar | 1200ms | feather | stone | linear loop | None | Indeterminate linear progress while an operation is genuinely pending, stopping when it resolves or becomes measurable. | Static: the whole track visible. A segment frozen part of the way along reports a measurement nobody took. |
317
315
 
318
316
  #### Media
319
317
 
320
318
  | Recipe | Duration | Signature | Material | Damping ζ | Overshoot | Use | Reduced motion |
321
319
  | --- | --- | --- | --- | --- | --- | --- | --- |
322
- | `media-in` — Media arrival | 900ms | refraction | frost | 0.850 | 0.6% | After an image decodes or media becomes ready; reserve layout space. | Apply the semantic state immediately; omit decorative movement. |
323
- | `caption-in` — Caption reveal | 500ms | coalesce | resin | 0.620 | 8.4% | Optional descriptive caption; text remains accessible in reduced motion. | Apply the semantic state immediately; omit decorative movement. |
324
- | `carousel-next` — Next item | 920ms | refraction | frost | 0.850 | 0.6% | Explicit next/previous navigation; never autoplay. | Apply the semantic state immediately; omit decorative movement. |
325
- | `carousel-previous` — Previous item | 920ms | refraction | frost | 0.850 | 0.6% | Maintain item count and keyboard navigation. | Apply the semantic state immediately; omit decorative movement. |
320
+ | `media-in`: Media arrival | 900ms | refraction | frost | 0.850 | 0.6% | After an image decodes or media becomes ready; reserve layout space. | Apply the semantic state immediately; omit decorative movement. |
321
+ | `caption-in`: Caption reveal | 500ms | coalesce | resin | 0.620 | 8.4% | Optional descriptive caption; text remains accessible in reduced motion. | Apply the semantic state immediately; omit decorative movement. |
322
+ | `carousel-next`: Next item | 920ms | refraction | frost | 0.850 | 0.6% | Explicit next/previous navigation; never autoplay. | Apply the semantic state immediately; omit decorative movement. |
323
+ | `carousel-previous`: Previous item | 920ms | refraction | frost | 0.850 | 0.6% | Maintain item count and keyboard navigation. | Apply the semantic state immediately; omit decorative movement. |
326
324
 
327
325
  #### Manipulation
328
326
 
329
327
  | Recipe | Duration | Signature | Material | Damping ζ | Overshoot | Use | Reduced motion |
330
328
  | --- | --- | --- | --- | --- | --- | --- | --- |
331
- | `drag-pickup` — Lift to move | 500ms | tension | resin | 0.700 | 4.6% | Visual lift for a selected movable item; keyboard alternative required. | Apply the semantic state immediately; omit decorative movement. |
332
- | `drag-settle` — Drop settle | 640ms | coalesce | resin | 0.620 | 8.4% | After a valid local move, with undo where data changes. | Apply the semantic state immediately; omit decorative movement. |
333
- | `resize-settle` — Resize settle | 600ms | refraction | frost | 0.850 | 0.6% | After measured layout size changes; never animate focus or hide handles. | Apply the semantic state immediately; omit decorative movement. |
329
+ | `drag-pickup`: Lift to move | 500ms | tension | resin | 0.700 | 4.6% | Visual lift for a selected movable item; keyboard alternative required. | Apply the semantic state immediately; omit decorative movement. |
330
+ | `drag-settle`: Drop settle | 640ms | coalesce | resin | 0.620 | 8.4% | After a valid local move, with undo where data changes. | Apply the semantic state immediately; omit decorative movement. |
331
+ | `resize-settle`: Resize settle | 600ms | refraction | frost | 0.850 | 0.6% | After measured layout size changes; never animate focus or hide handles. | Apply the semantic state immediately; omit decorative movement. |
334
332
 
335
333
  #### Material compositions
336
334
 
337
335
  | Recipe | Duration | Signature | Material | Damping ζ | Overshoot | Use | Reduced motion |
338
336
  | --- | --- | --- | --- | --- | --- | --- | --- |
339
- | `resin-confluence` — Resin confluence | 1600ms | coalesce | resin | 0.620 | 8.4% | Explicit material choreography for a large specimen; replay is a visual study, not an application action. | Keep the resting material visible; omit choreography. |
340
- | `frost-unfold` — Frost unfolds into depth | 1900ms | refraction | frost | 0.850 | 0.6% | Explicit material choreography for a large specimen; replay is a visual study, not an application action. | Keep the resting material visible; omit choreography. |
341
- | `plastic-settle` — Plastic settles into place | 1700ms | inertia | plastic | 0.550 | 12.6% | Explicit material choreography for a large specimen; replay is a visual study, not an application action. | Keep the resting material visible; omit choreography. |
342
- | `haze-tide` — Haze perimeter tide | 1800ms | feather | haze | 0.920 | none | Explicit material choreography for a large specimen; replay is a visual study, not an application action. | Keep the resting material visible; omit choreography. |
343
- | `stone-contour` — Stone contour ripple | 1300ms | feather | stone | 0.920 | none | Explicit material choreography for a large specimen; replay is a visual study, not an application action. | Keep the resting material visible; omit choreography. |
337
+ | `resin-confluence`: Resin confluence | 1600ms | coalesce | resin | 0.620 | 8.4% | Explicit material choreography for a large specimen; replay is a visual study, not an application action. | Keep the resting material visible; omit choreography. |
338
+ | `frost-unfold`: Frost unfolds into depth | 1900ms | refraction | frost | 0.850 | 0.6% | Explicit material choreography for a large specimen; replay is a visual study, not an application action. | Keep the resting material visible; omit choreography. |
339
+ | `plastic-settle`: Plastic settles into place | 1700ms | inertia | plastic | 0.550 | 12.6% | Explicit material choreography for a large specimen; replay is a visual study, not an application action. | Keep the resting material visible; omit choreography. |
340
+ | `haze-tide`: Haze perimeter tide | 1800ms | feather | haze | 0.920 | none | Explicit material choreography for a large specimen; replay is a visual study, not an application action. | Keep the resting material visible; omit choreography. |
341
+ | `stone-contour`: Stone contour ripple | 1300ms | feather | stone | 0.920 | none | Explicit material choreography for a large specimen; replay is a visual study, not an application action. | Keep the resting material visible; omit choreography. |
344
342
 
345
343
  **Spring policy.** Every recipe carries a spring fitted to its authored duration, which remains the authority. Damping ratio is chosen by signature: inertia and coalesce overshoot because momentum is their material claim, feather and caustic do not because a soft edge that bounces is wrong. Disabling springs must reproduce the keyframes exactly.
346
344
 
347
- **Continuous policy.** A continuous recipe is the one kind of motion that repeats, and it is not ambient: it reports work that is genuinely pending, runs only while that work is pending, and stops when it resolves. Nothing loops at rest. Every continuous recipe travels linearly at one period, motion.flow, so no two indicators in a view tick against each other, and none carries a spring, because a loop has no rest position to settle to. Reduced motion removes it and leaves the whole track or fill in place — never a partial segment, which would report a measurement nobody took.
345
+ **Continuous policy.** A continuous recipe is the one kind of motion that repeats, and it is not ambient: it reports work that is genuinely pending, runs only while that work is pending, and stops when it resolves. Nothing loops at rest. Every continuous recipe travels linearly at one period, motion.flow, so no two indicators in a view tick against each other, and none carries a spring, because a loop has no rest position to settle to. Reduced motion removes it and leaves the whole track or fill in place, never a partial segment, which would report a measurement nobody took.
348
346
 
349
- **Stagger policy.** A recipe that animates many marks at once may declare a stagger: a step between consecutive marks and a ceiling on how many are staggered. Past the ceiling every mark arrives together. The whole staggered sequence stays within the recipe's duration ceiling, and a recipe that shows data declares overshoot never and is critically damped — a mark that overshoots its value has shown a number that is not true.
347
+ **Stagger policy.** A recipe that animates many marks at once may declare a stagger: a step between consecutive marks and a ceiling on how many are staggered. Past the ceiling every mark arrives together. The whole staggered sequence stays within the recipe's duration ceiling, and a recipe that shows data declares overshoot never and is critically damped. A mark that overshoots its value has shown a number that is not true.
350
348
 
351
- **Travel policy.** 5–30px ordinary, 50px guidance; justified large transitions may exceed it. Haze and Stone paint moves locally while text stays fixed.
349
+ **Travel policy.** 5 to 30px ordinary, 50px guidance; justified large transitions may exceed it. Haze and Stone paint moves locally while text stays fixed.
352
350
 
353
351
  **Incompressibility.** Deformations conserve volume: every scale(sx, sy) satisfies sx*sy = 1 within 0.005. Corrected by dividing both axes by the square root of the area, which preserves each deformation's aspect ratio exactly and removes only the compressibility error. Enforced by tools/validate-motion.cjs.
354
352
 
@@ -380,59 +378,59 @@ GLSL, Metal or AGSL. The `.frag` files in this repository are one implementation
380
378
 
381
379
  #### `resin-refraction`
382
380
 
383
- - **Material** — resin
384
- - **Signatures** — refraction, meniscus, tension
385
- - **Blend mode** — `hard-light`
386
- - **Degrades to** — The existing CSS travelling-light sweep.
381
+ - **Material**: resin
382
+ - **Signatures**: refraction, meniscus, tension
383
+ - **Blend mode**: `hard-light`
384
+ - **Degrades to**: The existing CSS travelling-light sweep.
387
385
 
388
386
  Resin bends and disperses light at its rim. A signed-distance field gives the lens profile; the lighting response is a specular band that tracks the direction of travel, a defined bright edge, and chromatic separation where the lens is steepest. The interior stays clear so content remains readable through the material.
389
387
 
390
388
  #### `resin-caustics`
391
389
 
392
- - **Material** — resin
393
- - **Signatures** — caustic
394
- - **Blend mode** — `screen`
395
- - **Degrades to** — A static highlight at the resting opacity.
390
+ - **Material**: resin
391
+ - **Signatures**: caustic
392
+ - **Blend mode**: `screen`
393
+ - **Degrades to**: A static highlight at the resting opacity.
396
394
 
397
395
  Light focused by a curved surface concentrates into bright curves. The curvature here is at the rim, so the caustics fall as sparse arcs along the boundary. Read from the same height field as the refraction shader, so the two agree by construction rather than by tuning.
398
396
 
399
397
  #### `frost-displacement`
400
398
 
401
- - **Material** — frost
402
- - **Signatures** — feather, refraction
403
- - **Blend mode** — `hard-light`
404
- - **Degrades to** — The existing backdrop-filter blur and grain, unchanged.
399
+ - **Material**: frost
400
+ - **Signatures**: feather, refraction
401
+ - **Blend mode**: `hard-light`
402
+ - **Degrades to**: The existing backdrop-filter blur and grain, unchanged.
405
403
 
406
404
  Frost refracts colour, not shape. At 40px of diffusion nothing sharp survives the material, so the three channels sample the same field at slightly separated points and resolve into a slow warm-to-cool wander across the surface rather than a visible fringe. Resin, at 20px, keeps detail and disperses sharply at its rim instead: the diffusion radius decides which behaviour is correct, not taste. Turning Resin down does not produce Frost, it produces weak Resin.
407
405
 
408
406
  #### `mirage-flow`
409
407
 
410
- - **Material** — mirage
411
- - **Signatures** — iris
412
- - **Blend mode** — `screen`
413
- - **Degrades to** — The existing clip-path ellipse reveal.
408
+ - **Material**: mirage
409
+ - **Signatures**: iris
410
+ - **Blend mode**: `screen`
411
+ - **Degrades to**: The existing clip-path ellipse reveal.
414
412
 
415
413
  Mirage washes across a scene as a curved front. A flow field advects the front so its edge is organic rather than a geometric ellipse.
416
414
 
417
415
  ### Compositing
418
416
 
419
- **element** — A transparent canvas positioned over the surface, never in the content flow.
417
+ **element**: A transparent canvas positioned over the surface, never in the content flow.
420
418
 
421
- **blend** — mix-blend-mode as declared per shader; the canvas carries no opaque pixels.
419
+ **blend**: mix-blend-mode as declared per shader; the canvas carries no opaque pixels.
422
420
 
423
- **note** — A web shader cannot sample the page behind it, so refraction is rendered as the lighting response to a computed surface normal rather than by displacing a backdrop. The eye reads normals and specular as refraction, and the technique degrades to nothing rather than to something wrong.
421
+ **note**: A web shader cannot sample the page behind it, so refraction is rendered as the lighting response to a computed surface normal rather than by displacing a backdrop. The eye reads normals and specular as refraction, and the technique degrades to nothing rather than to something wrong.
424
422
 
425
423
  ### The optical model
426
424
 
427
- **basis** — Edge lensing, not surface waves.
425
+ **basis**: Edge lensing, not surface waves.
428
426
 
429
- **rationale** — Refraction is concentrated in a band just inside the boundary and falls off steeply, leaving the centre of a surface optically clear. This follows how contemporary glass interfaces behave: the interior is shrunk and the edges stretched outward, which is a displacement concentrated at the rim rather than a wave crossing the surface. A defined, light-catching edge is what separates glass from frosted plastic.
427
+ **rationale**: Refraction is concentrated in a band just inside the boundary and falls off steeply, leaving the centre of a surface optically clear. This follows how contemporary glass interfaces behave: the interior is shrunk and the edges stretched outward, which is a displacement concentrated at the rim rather than a wave crossing the surface. A defined, light-catching edge is what separates glass from frosted plastic.
430
428
 
431
- **rejected** — An earlier implementation radiated concentric ripples from the contact point. That is what water does when something is dropped into it, and it read as a pond rather than as a solid transparent material. Meridian rejected it on sight and they were right: glass does not oscillate, it bends light where it curves.
429
+ **rejected**: An earlier implementation radiated concentric ripples from the contact point. That is what water does when something is dropped into it, and it read as a pond rather than as a solid transparent material. Meridian rejected it on sight and they were right: glass does not oscillate, it bends light where it curves.
432
430
 
433
- **specular** — The highlight tracks the direction of travel rather than sitting still. On a handset the reference for this is the gyroscope; on the web it is the motion's own direction, taken from the contact point. A highlight that does not move with the object reads as a painted-on gradient.
431
+ **specular**: The highlight tracks the direction of travel rather than sitting still. On a handset the reference for this is the gyroscope; on the web it is the motion's own direction, taken from the contact point. A highlight that does not move with the object reads as a painted-on gradient.
434
432
 
435
- **morphing** — Shape-shifting between states is geometry, not optics, and is carried by the spring recipes: the coalesce and meniscus signatures describe surfaces merging and separating. The optical layer lights whatever shape the geometry produces.
433
+ **morphing**: Shape-shifting between states is geometry, not optics, and is carried by the spring recipes: the coalesce and meniscus signatures describe surfaces merging and separating. The optical layer lights whatever shape the geometry produces.
436
434
 
437
435
  ### Platform mapping
438
436