@crystal-ui/core 2.1.0 → 2.2.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 (37) hide show
  1. package/assets/crystal-theme.css +15 -0
  2. package/assets/crystal.css +300 -5
  3. package/assets/crystal.js +10 -0
  4. package/assets/motion.js +17 -2
  5. package/assets/tokens.js +1 -1
  6. package/docs/accessibility.md +9 -2
  7. package/docs/adoption.md +3 -1
  8. package/docs/catalogue.md +462 -31
  9. package/docs/components.md +26 -9
  10. package/docs/materials.md +12 -4
  11. package/docs/motion-components.md +11 -6
  12. package/docs/motion.md +10 -2
  13. package/docs/tokens.md +1 -1
  14. package/engines.js +13 -2
  15. package/exports/crystal-tokens.kt +1 -1
  16. package/exports/crystal-tokens.swift +1 -1
  17. package/exports/crystal-tokens.ts +1 -1
  18. package/package.json +2 -1
  19. package/tokens/catalogue/01-layout.json +45 -0
  20. package/tokens/catalogue/02-navigation.json +88 -1
  21. package/tokens/catalogue/03-actions.json +41 -0
  22. package/tokens/catalogue/04-inputs.json +366 -5
  23. package/tokens/catalogue/05-data-display.json +187 -1
  24. package/tokens/catalogue/06-feedback.json +78 -6
  25. package/tokens/catalogue/07-overlays.json +50 -3
  26. package/tokens/catalogue/08-typography.json +54 -0
  27. package/tokens/catalogue/09-utility.json +79 -0
  28. package/tokens/catalogue/10-charts.json +89 -1
  29. package/tokens/catalogue/11-media.json +33 -0
  30. package/tokens/catalogue/12-commerce.json +134 -1
  31. package/tokens/catalogue/13-screens.json +77 -0
  32. package/tokens/catalogue/14-blocks.json +101 -0
  33. package/tokens/catalogue.json +1646 -19
  34. package/tokens/crystal.json +1 -1
  35. package/tokens/crystal.tokens.json +2 -2
  36. package/tokens/motion-recipes.json +124 -0
  37. package/tokens/surfaces.json +167 -0
@@ -17,19 +17,23 @@ The package contains working CSS primitives and a bounded interactive reference.
17
17
  | Quiet action | The same shell with **no** reading fill, so the label sits directly on the material | `.cr-button.quiet`; same semantics as any action |
18
18
  | Destructive action | Resin/Haze with independent danger boundary and explicit label | `.danger`; app supplies consequence-specific confirmation and recovery |
19
19
  | Text field | Visible label, state badge, glowing focus ring, validation, helper/error association | `.cr-input`; working native form example; app supplies validation rules |
20
- | Selection control | Explicit selected state plus text/mark | Native checkbox, radio and select, styled by `assets/crystal.css` as of 2.1.0; keyboard semantics must match the component |
20
+ | Selection control | Explicit selected state plus text/mark | Native checkbox, radio and select, styled by `assets/crystal.css` as of 2.1.0, and the native switch (`input[type=checkbox][role=switch]`) as of 2.2.0; keyboard semantics must match the component |
21
+ | Navigation entry | No material of its own; pill hit area; selection by label weight and `aria-current` | `.cr-nav-item`, `.stacked` for a rail. Routing and the current-page state are app-owned |
22
+ | Bare control | A control inside a coated surface: no fill, shadow, blur or pseudo-layers; target and focus ring kept | `.cr-bare`; the action itself is app-owned |
23
+ | Drag handle | Grip glyph, grab cursor, lift while held | `.cr-drag-handle` with `aria-grabbed` or `data-dragging`; pointer capture, keyboard drag and drop validation are app-owned |
24
+ | Resin panel | The Resin plane at the content radius | `.cr-resin.panel`; a floating window or wide control bar |
21
25
  | Range control | Visible label/value, keyboard adjustable range | Native `input[type=range]`, styled by `assets/crystal.css` as of 2.1.0, including its RTL track direction; product limits require domain validation |
22
26
  | Authored bubble | Haze, directional tight corner, optional author metadata | `.cr-bubble`, `.own`; app supplies content/Markdown semantics |
23
27
  | Composer surround | Frost frame and softened content well around protected input controls | CSS composition; no rich-text editor or delivery service is implemented |
24
28
  | Status badge | Independent ink/surface pair, symbol and visible label | `.cr-status` with `data-status`; 18px radius, 12px/18px padding, 36px floor, as the preview has always rendered it; dynamic announcements are app-owned |
25
29
  | Avatar | Circular image/initials, accessible identity when needed | Reference styling; app handles real identity, image failure and privacy |
26
30
  | Dialog | 80% feathered surface over Mirage; title, body and named actions | Working native HTML dialog example; Escape/focus return; app owns transactions |
27
- | Tooltip | Short supplemental text; never sole label | Working Resin/Haze tooltip in the motion suite; focus, hover and Escape |
28
- | Menu/popover | Supporting surface with keyboard navigation and dismissal | Working Resin/Haze local menu and popover in the motion suite; production adoption still requires testing |
31
+ | Tooltip | Short supplemental text; never sole label | Frost (`.cr-frost`, R15e); working tooltip in the motion suite with focus, hover and Escape |
32
+ | Menu/popover | Frost panel with Haze rows; keyboard navigation and dismissal | `.cr-frost` (R15e); working local menu and popover in the motion suite; production adoption still requires testing |
29
33
  | Drawer/sheet | Overlay support with label, close, focus management | Working modal inspector in the motion suite; app decides production modality |
30
34
  | Table/list | Soft content panel, clear header relationships, explicit sort/filter states | Native table in contrast report; production data controls not implemented |
31
35
  | Tabs | Labeled selected item with keyboard pattern matching actual semantics | Working ARIA tabs in the motion suite; scene navigation separately uses pressed buttons |
32
- | Notification/toast | Clear result plus useful next action | Manually dismissed Resin/Haze notification in the motion suite; production queue remains app-owned |
36
+ | Notification/toast | Clear result plus useful next action; Frost panel with Haze reading fill | `.cr-frost` (R15e); manually dismissed notification in the motion suite; production queue remains app-owned |
33
37
  | Loading | Preserve layout, communicate pending work, no false success | Specification only; user-triggered work needs real lifecycle state |
34
38
  | Empty/error/denied | Explain situation and a valid next step | Specification only; must reflect actual service/permission state |
35
39
  | Chart/data visualization | Direct labels, pattern/shape, accessible equivalent | Specification only; brand palettes are not prevalidated chart palettes |
@@ -40,7 +44,7 @@ Every production control needs default, hover where meaningful, pressed, focus-v
40
44
 
41
45
  Primary application buttons are at least 44px high. Compact documentation controls may be smaller but must meet applicable target-size/spacing criteria; do not infer that every clickable element is 44px from the button class. Validate touch use, not only a desktop screenshot.
42
46
 
43
- The selected preview destination has both a circular check badge and a pressed state. Palette selections have a visible check. Functional statuses have words and distinct symbols. These cues survive color changes.
47
+ The selected destination carries its state by `aria-pressed` and by label weight; palette swatches, which cannot carry a weight change, use an inset ring gap. Functional statuses have words and distinct symbols. These cues survive color changes, and none of them is a check mark — a check means validated, never selected.
44
48
 
45
49
  The preview product-name form performs a real local update with native validation; it does not save a brand to a remote service. Dialogs inspect actual specifications or exported tokens. The export buttons produce files from the current configuration. Fictional messages, avatars and library cards remain clearly labeled design content.
46
50
 
@@ -68,11 +72,24 @@ Buttons, action links, tabs, selectable controls and field shells use Resin as t
68
72
 
69
73
  **A quiet button has no reading fill.** It keeps the whole Resin shell — rim, float shadow, sheen — and drops the pad, which makes it the only variant that is glass all the way through. The cost is the pad's whole purpose: a quiet label reads against the Resin fill and therefore against whatever is behind the control. On Crystal's own foundation that is a wide margin — `--cr-text` over the Resin fill over canvas, surface, surface-alt and foundation measures 10.88 to 18.28 across all six palettes and both modes — but a quiet button placed over artwork has no protected ground, and that composition is the one to avoid. The recipe is in `assets/crystal.css`, in `@layer crystal.component`: a Resin fill with a rim and a float shadow, a `::before` carrying the inset Haze fill at the material's feather, and a `::after` carrying the optical sheen from `--cr-control-color` and `--cr-control-light`. Both pseudo-elements are dropped under reduced transparency and under forced colours.
70
74
 
71
- Until 2.1.0 this paragraph told you to load `assets/controls.css`, which is the documentation site's stylesheet and has never been in the package — so the surface this specification describes was one no consumer could obtain. `assets/controls.js` adds only a nonsemantic shell to native fields; labels, input values, validation and form submission remain native.
75
+ Until 2.1.0 this paragraph told you to load `assets/controls.css`, which is the documentation site's stylesheet and has never been in the package — so the surface this specification describes was one no consumer could obtain. The field shell is markup a product wraps around a native field — `<span class="cr-field-shell">` around the `<input>` — and adds no semantics of its own; labels, input values, validation and form submission remain native.
72
76
 
73
- Small display elements (tooltips, toasts, labels, tags and badges) and temporary menus (secondary menus, dropdowns, flyouts and popovers) use `.cr-resin-haze`. This is a reusable composition of existing materials, not a seventh material. Larger persistent components retain their structural material. Native OS popup internals are platform-owned; use an actual accessible custom component when full Crystal popup rendering is required.
77
+ Small display elements that sit *on* content — labels, tags, badges and keyboard caps — use `.cr-resin-haze`. This is a reusable composition of existing materials, not a seventh material. Transient overlays — tooltips, toasts, menus, dropdowns, flyouts and popovers — are **Frost** (`.cr-frost`), at Meridian's direction (R15e): a surface that opens over content is an intermediate panel, not a compact control, and its reading content sits on Haze inside it. Larger persistent components retain their structural material. Native OS popup internals are platform-owned; use an actual accessible custom component when full Crystal popup rendering is required.
74
78
 
75
- Selected controls retain circular symbol badges and correct ARIA state. Disabled controls retain legible content but cannot activate. Opaque and forced-color modes replace decorative optics while preserving control boundaries. Motion uses material deformation and changing light, with crisp foreground text.
79
+ Selected controls carry correct ARIA state and label weight; a circular badge marks activity or information, never selection. Disabled controls retain legible content but cannot activate. Opaque and forced-color modes replace decorative optics while preserving control boundaries. Motion uses material deformation and changing light, with crisp foreground text.
80
+
81
+ ### Every component names its surface
82
+
83
+ The catalogue gives every one of its components a **surface** — the material composition it is made of — from the closed vocabulary in `tokens/surfaces.json`, and each surface is one recipe in `assets/crystal.css`. The build refuses a component naming a surface with no recipe, so the catalogue cannot specify a material Crystal has not published. The vocabulary is listed, with counts, at the top of the [catalogue](catalogue.html#surfaces). Four of its entries arrived in 2.2.0 because a consumer had reached them and found nothing:
84
+
85
+ | Surface | Recipe | What it is |
86
+ |---|---|---|
87
+ | Navigation entry | `.cr-nav-item`, `.stacked` for a rail | Furniture on the panel beneath it: no material of its own, pill hit area, 44px target, selection by label weight (650 → 800) and `aria-current`. Lifted from this site's own side menu, which this page has always named as the reference implementation of selection. |
88
+ | Bare control | `.cr-bare` | A control inside a surface that already has a coat — a disclosure chevron, a chip's remove button, a sort header, a stepper's arrows, a dismiss button. Crystal paints every `<button>` by element in five layers; this removes all five and keeps the target and the focus ring. |
89
+ | Drag handle | `.cr-drag-handle` | A bare control with a grip and a lift while `aria-grabbed` or `data-dragging` is set. Pointer capture, the keyboard alternative and drop validation are the product's. |
90
+ | Resin panel | `.cr-resin.panel` | The Resin plane with the content radius instead of the pill, for a floating window or a wide control bar. |
91
+
92
+ A native switch is a checkbox with a track — `<input type="checkbox" role="switch">` — styled by element like the checkbox and radio: the track reads `--cr-switch-track-width` and `-height`, the thumb is the opaque surface, and the on state is the primary-soft pair.
76
93
 
77
94
  ### Interaction surface geometry
78
95
 
@@ -113,7 +130,7 @@ Focus uses an immediate 2px primary-color core at a 3px offset, surrounded by a
113
130
 
114
131
  The four feather colors are published as `--cr-focus-feather-1` through `-4` and the broad shadow as `--cr-focus-shadow`, so a product can retint the falloff without restating the recipe. The single token `--cr-focus-ring` composes all six layers so every focusable surface shares one recipe. The core remains defined for visibility; text and icons are never blurred. Keyboard focus applies to all interactive elements. Text entry lights its Resin shell through `:focus-within`. Motion must neither delay nor remove the focus cue. Forced colors substitute a system Highlight outline and remove decorative shadows.
115
132
 
116
- A `.cr-indicator` is a 20px circular Resin surface with a 3px-inset 80% Haze fill and a 1px feather on that fill. Field badges are 24px. Their foreground remains crisp and uses the tested body ink. They sit beside the content, never over text or a native select arrow. These are informational, non-interactive marks, not small click targets.
133
+ A `.cr-indicator` is a 20px circle painting an 80% Haze fill on an isolated layer with a 1px feather — Haze rather than Resin, for the reason given under [Indicators](#indicators). Field badges are 24px. Their foreground remains crisp and uses the tested body ink. They sit beside the content, never over text or a native select arrow. These are informational, non-interactive marks, not small click targets.
117
134
 
118
135
  <!-- generated:focus-recipe -->
119
136
 
package/docs/materials.md CHANGED
@@ -233,7 +233,7 @@ Inspect light/dark, every palette, strongest atmosphere, both Frost tint extreme
233
233
 
234
234
  Resin is the primary background for buttons and all interaction surfaces. Its body stays at 20% fill with the existing blur, saturation, illuminated rim and elevation. When contrast requires protection, put an 80% Haze reading fill inside that shell, with the existing 1.95px feather and an 8px visible Resin perimeter, exported as `--cr-haze-inset`. That inset is a token rather than a number each library retypes: the fill and its feather were always exported, the inset was not, and a library can carry every Haze token and still paint no fill at all. Keep text sufficiently inset from the feather. The adjustable preview always uses this protected construction.
235
235
 
236
- This same composition is required for small information displays—tooltips, toasts, labels, tags and badges—and temporary secondary menus, dropdowns, flyouts and popovers. It does not replace the structural Plastic → Frost → Resin hierarchy or turn every large component into Resin. Stone remains a named material with its own standalone specifications; compact UI labels now choose Resin/Haze instead of an isolated Stone slab.
236
+ This same composition is required for small information displays that sit on content — labels, tags, badges and keyboard caps. Transient overlays — tooltips, toasts, menus, dropdowns, flyouts and popovers — are **Frost** (R15e): they open over content, so they are intermediate panels rather than compact controls, and their reading content sits on Haze inside them. It does not replace the structural Plastic → Frost → Resin hierarchy or turn every large component into Resin. Stone remains a named material with its own standalone specifications; compact UI labels now choose Resin/Haze instead of an isolated Stone slab.
237
237
 
238
238
  Optical highlights remain below the Haze reading fill, including during animation. They can cross the exposed Resin perimeter without bleaching the protected label background. Contrast models check this actual ordering across all six palettes, both modes and RGB-corner backdrops.
239
239
 
@@ -282,9 +282,17 @@ from `rgba(39,24,68,.15)` to `rgba(107,40,112,.15)`: the same weight, carrying c
282
282
 
283
283
  ### Motion at rest
284
284
 
285
- These behaviours are the material's **rest state**, not a response to being used. A Crystal
286
- surface is alive before anyone touches it, and interaction *adds* energy rather than
287
- starting the effect: rest, faster on hover, faster still on press, decaying back.
285
+ **Deferred.** This subsection describes the ambient tier Crystal 2.0 specified, built,
286
+ measured and then withdrew at Meridian's direction (R22; §8 of the library contract). It is
287
+ kept as the record of what will return, not as a rule in force: **nothing in 2.x moves at
288
+ rest**, and the optical behaviours in the table above run only for the duration of a
289
+ motion a person started. Plastic's glow is a material property and stays; its drift was
290
+ ambient and does not.
291
+
292
+ What was specified, for when it returns: these behaviours are the material's **rest
293
+ state**, not a response to being used. A Crystal surface is alive before anyone touches it,
294
+ and interaction *adds* energy rather than starting the effect: rest, faster on hover,
295
+ faster still on press, decaying back.
288
296
 
289
297
  The single exception is text entry. A field being typed into is the one place where motion
290
298
  genuinely competes with the task, so ambient pauses there and nowhere else.
@@ -2,7 +2,7 @@
2
2
 
3
3
  [Open the live component studies](../motion.html#component-motion) · [Search all recipes](../motion.html#recipe-library) · [Run browser contracts](../motion-contracts.html)
4
4
 
5
- Crystal ships 57 executable component recipes in nine families, the six material signatures, Mirage withdrawal, a modal dismissal, and a measured-layout helper. This is the animation foundation for future component libraries. The demonstration includes real local component behavior, but is not an audited production React, Rust or native component library. No remote operation is represented as implemented.
5
+ Crystal ships 61 executable component recipes in nine families — three of them continuous indicators of pending work — the six material signatures, Mirage withdrawal, a modal dismissal, and a measured-layout helper. This is the animation foundation for future component libraries. The demonstration includes real local component behavior, but is not an audited production React, Rust or native component library. No remote operation is represented as implemented.
6
6
 
7
7
  ## Engine responsibilities
8
8
 
@@ -25,9 +25,9 @@ The engine bridge gives both libraries one cancellation contract: `finished` set
25
25
 
26
26
  ## Interaction and compact-surface materials
27
27
 
28
- All interaction surfaces use a 20% Resin body, visible illuminated rim and an inset 80% Haze reading fill where contrast needs protection. The preview uses the protected form consistently because its surroundings are adjustable. The reading fill is physically inset, so the Resin perimeter stays visible. Standalone actions keep a neutral Haze reading fill inside a broad Resin rim. Grouped actions share one Resin/Haze container: inactive items are transparent, and the selected item uses the tested primary/on-primary color pair as a raised indicator with a circular check badge. The group retains the surrounding material shell.
28
+ All interaction surfaces use a 20% Resin body, visible illuminated rim and an inset 80% Haze reading fill where contrast needs protection. The preview uses the protected form consistently because its surroundings are adjustable. The reading fill is physically inset, so the Resin perimeter stays visible. Standalone actions keep a neutral Haze reading fill inside a broad Resin rim. Grouped actions share one Resin/Haze container: inactive items are transparent, and the selected item uses the tested primary/on-primary color pair as a raised indicator, with its label at weight 800. Nothing is drawn beside the label — a check mark means validated, never selected. The group retains the surrounding material shell.
29
29
 
30
- The same formula applies to **tooltips, toasts, display labels, tags and badges**, and **secondary menus, dropdowns, flyouts and popovers**. Use `.cr-resin-haze` for these shells; `.cr-tag` adds compact label geometry. This does not change large persistent Frost panels, Plastic foundations, Haze reading areas, or the standalone Stone material. Plain prose and ordinary form-label text do not need their own material container. Native OS option popups and file choosers retain platform drawing; the in-app menu and select trigger use Crystal.
30
+ The same formula applies to **display labels, tags, badges and keyboard caps**. Use `.cr-resin-haze` for these shells; `.cr-tag` adds compact label geometry. **Tooltips, toasts, menus, dropdowns, flyouts and popovers are Frost** (`.cr-frost`), at Meridian's direction (R15e): they open over content, so they are intermediate panels, and their reading content sits on Haze inside them. This does not change large persistent Frost panels, Plastic foundations, Haze reading areas, or the standalone Stone material. Plain prose and ordinary form-label text do not need their own material container. Native OS option popups and file choosers retain platform drawing; the in-app menu and select trigger use Crystal.
31
31
 
32
32
  ## Component coverage and composition
33
33
 
@@ -51,8 +51,9 @@ The same formula applies to **tooltips, toasts, display labels, tags and badges*
51
51
  | Resizable panel / split view | `resize-settle`, `layout()` | Host owns resize handles and keyboard bounds |
52
52
  | Chat message / reaction / activity entry | `message-in`, `reaction`, `highlight` | Real local/remote data state; no forced scroll or replay on history |
53
53
  | Toast / snackbar / banner | `toast-in/out`, `attention` | Persistent readable status; manual dismissal in this preview |
54
- | Progress bar / transfer indicator | `progress-change`, `success` | Actual measured progress; never animate a fabricated success |
55
- | Busy indicator / skeleton | `busy`, `skeleton-resolve` | Real pending/ready state, no inference from animation completion |
54
+ | Progress bar / transfer indicator | `progress-change`, `success`; indeterminate: `activity-travel` (bar) or `activity-turn` (ring) | Actual measured progress; never animate a fabricated success. Indeterminate only while the work cannot be measured, and determinate the moment it can |
55
+ | Busy indicator / skeleton | `busy`, `skeleton-resolve`; while pending: `activity-turn` (loader), `skeleton-sweep` (skeleton) | Real pending/ready state, no inference from animation completion. The continuous recipe runs only while the work is pending and stops when it resolves |
56
+ | Chart mark — bar, series, segment | `mark-in`, staggered by index | Plays when the chart first appears, never when its data changes; critically damped, so no mark ever shows a value it does not have |
56
57
  | Empty state / no-results panel | `empty-in` | Actual empty collection or search result |
57
58
  | Image / video surface / lightbox | `media-in`, `caption-in`, Haze/Mirage if modal | Decode/readiness event, reserved layout space, media controls owned by host |
58
59
  | Carousel / gallery / thumbnail strip | `carousel-next/previous`, `selection` | Explicit navigation, item count, descriptive text; no autoplay |
@@ -126,11 +127,15 @@ Base times below are at 1×; the preview resolves the saved speed at playback. E
126
127
  | `haze-tide` | haze / feather | GSAP | 1800ms | Explicit material choreography for a large specimen; replay is a visual study, not an application action. |
127
128
  | `stone-contour` | stone / feather | GSAP | 1300ms | Explicit material choreography for a large specimen; replay is a visual study, not an application action. |
128
129
  | `check-off` | plastic / iris | Motion | 300ms | Checkbox and radio indicators returning to unchecked. Paired with `check`; the iris closes toward the same point it opened from. |
130
+ | `activity-turn` | stone / feather | Motion | 1200ms per cycle, while pending | 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. |
131
+ | `activity-travel` | stone / feather | Motion | 1200ms per cycle, while pending | Indeterminate linear progress while an operation is genuinely pending, stopping when it resolves or becomes measurable. |
132
+ | `skeleton-sweep` | haze / feather | Motion | 1200ms per cycle, while pending | A skeleton while its content is genuinely loading, on the Haze fill and never on the text that replaces it. Ends with skeleton-resolve. |
133
+ | `mark-in` | haze / feather | Motion | 500ms | 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. |
129
134
  <!-- /generated:component-recipes -->
130
135
 
131
136
  ## Runtime API
132
137
 
133
- `controls.js` adds Resin shells around native text fields and selects while preserving their labels, validation and keyboard behavior; the shells' appearance is in `crystal.css` as of 2.1.0, and no longer needs the preview's own `controls.css`. Load scripts in this order: theme CSS, primitive CSS, motion CSS, `assets/vendor/crystal-engines.js`, `assets/motion-catalog.js`, then `assets/motion.js`. Load `tokens.js` and `crystal.js` first if resolving user preferences dynamically. `motion-interactions.js` optionally installs delegated button feedback; omit it when your component library owns gesture handling to avoid duplicate effects.
138
+ The field shell's appearance is in `crystal.css` as of 2.1.0; the documentation site wraps its native fields with a script of its own, and a product wraps them in its own markup or component. Load the theme CSS, then `crystal.css`, then `motion.css`. The engines are the consumer's to bundle — `@crystal-ui/core` ships `engines.js` and declares gsap and motion as dependencies — and `assets/motion.js` is the adapter over them, reading the recipe catalogue from `window.CRYSTAL_MOTION_RECIPES` (the contents of `motion-recipes.json`). Load `tokens.js` and `crystal.js` first if resolving user preferences dynamically. The material presets a recipe id can also name — `plastic`, `frost`, `resin`, `haze`, `stone`, `mirage`, `mirage-out`, `dismiss` — are computed from tokens by `core/presets`, which a platform library imports directly. Delegated button feedback is the documentation site's; a component library binds motion to state in its own lifecycle.
134
139
 
135
140
  ```js
136
141
  // Apply real UI state before giving it visual feedback.
package/docs/motion.md CHANGED
@@ -43,7 +43,7 @@ Mirage uses an expanding elliptical mask with a broad feathered front rather tha
43
43
 
44
44
  ## Working examples
45
45
 
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 effects autoplay or loop.
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.
47
47
 
48
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.
49
49
 
@@ -230,7 +230,7 @@ including that reduced motion still applies the state instantly.
230
230
 
231
231
  <!-- generated:recipes -->
232
232
 
233
- All 57 recipes in 9 categories, generated from `core/tokens/motion-recipes.json`. **Damping ratio** and
233
+ All 61 recipes in 9 categories, generated from `core/tokens/motion-recipes.json`. **Damping ratio** and
234
234
  **overshoot** are derived from each recipe's spring by `core/assets/core/spring.js`, not
235
235
  authored — so a spring that was retuned cannot leave a stale number behind in this table.
236
236
 
@@ -299,6 +299,8 @@ correct is a material question, not a taste question — see the signature polic
299
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
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
301
  | `reaction` — Reaction response | 680ms | coalesce | resin | 0.620 | 8.4% | Toggle the real reaction state and count before the response. | Apply the semantic state immediately; omit decorative movement. |
302
+ | `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. |
303
+ | `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. |
302
304
 
303
305
  #### Feedback
304
306
 
@@ -312,6 +314,8 @@ correct is a material question, not a taste question — see the signature polic
312
314
  | `busy` — Finite busy cue | 680ms | feather | stone | 0.920 | none | One cycle for an actual pending operation; keep a static busy label if it lasts longer. | Apply the semantic state immediately; omit decorative movement. |
313
315
  | `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
316
  | `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. |
317
+ | `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. |
318
+ | `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. |
315
319
 
316
320
  #### Media
317
321
 
@@ -342,6 +346,10 @@ correct is a material question, not a taste question — see the signature polic
342
346
 
343
347
  **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.
344
348
 
349
+ **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.
350
+
351
+ **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.
352
+
345
353
  **Travel policy.** 5–30px ordinary, 50px guidance; justified large transitions may exceed it. Haze and Stone paint moves locally while text stays fixed.
346
354
 
347
355
  **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.
package/docs/tokens.md CHANGED
@@ -440,7 +440,7 @@ Values that belong to one component family and would be wrong to reuse elsewhere
440
440
  | Token | Type | Value | Meaning |
441
441
  | --- | --- | --- | --- |
442
442
  | `component.action.radius` | dimension | `999px` | Action controls are pill-shaped, independent of the content radius |
443
- | `component.action.minTarget` | dimension | `44px` | Minimum interactive target |
443
+ | `component.action.minTarget` | dimension | `48px` | Minimum interactive target. Above the 44px floor Crystal specifies, which this must never fall below. |
444
444
  | `component.action.paddingBlock` | dimension | `15px` | Action control block padding |
445
445
  | `component.action.paddingInline` | dimension | `24px` | Action control inline padding |
446
446
  | `component.action.gap` | dimension | `9px` | Gap between an action's icon and its label |
package/engines.js CHANGED
@@ -4,9 +4,18 @@ import { gsap } from 'gsap';
4
4
 
5
5
  const cssName = name => name.replace(/[A-Z]/g, letter => '-' + letter.toLowerCase());
6
6
  function easing(value){
7
+ /* A continuous recipe travels at constant speed. Anything that is not a named
8
+ curve used to fall through to the default ease, which made a loop surge and
9
+ slow once per cycle — a spinner that breathes. */
10
+ if(value==='linear')return t=>t;
7
11
  const match=/cubic-bezier\(([^)]+)\)/.exec(value||'');
8
12
  return match ? cubicBezier(...match[1].split(',').map(Number)) : cubicBezier(.22,.65,.22,1);
9
13
  }
14
+ /* Timing a recipe can ask for beyond its duration: a delay (a staggered mark) and
15
+ a repeat (a continuous indicator, which repeats until it is cancelled). Both are
16
+ in milliseconds here, like the duration; each engine is given its own unit. */
17
+ const delaySeconds=options=>Math.max(0,Number(options.delay)||0)/1000;
18
+ const repeats=options=>options.repeat===Infinity?Infinity:Math.max(0,Math.floor(Number(options.repeat)||0));
10
19
  function offsets(frames){
11
20
  const times=frames.map(frame=>frame.offset);times[0]??=0;times[times.length-1]??=1;
12
21
  let start=0;
@@ -28,7 +37,8 @@ export function frames(element,keyframes,options){
28
37
  // GSAP owns the clock; the native effect paints the real pseudo-element (no DOM copy).
29
38
  effect=element.animate(keyframes,{...options,easing:'linear',fill:'both'});effect.pause();effect.currentTime=0;
30
39
  const clock={time:0};
31
- control=gsap.timeline({onComplete:finish});
40
+ const repeat=repeats(options);
41
+ control=gsap.timeline({onComplete:finish,delay:delaySeconds(options),repeat:repeat===Infinity?-1:repeat});
32
42
  control.to(clock,{time:options.duration,duration:options.duration/1000,ease:easing(options.easing),onUpdate:()=>{effect.currentTime=clock.time;}});
33
43
  }else{
34
44
  const values=Object.fromEntries(props.map(p=>[p,keyframes.map(frame=>frame[p]??getComputedStyle(element)[p])]));
@@ -37,7 +47,8 @@ export function frames(element,keyframes,options){
37
47
  // Hybrid onComplete runs before its queued render, which could write opacity:0
38
48
  // back after dismiss cleanup and make the next dialog opening invisible.
39
49
  const bezier=/cubic-bezier\(([^)]+)\)/.exec(options.easing||'');
40
- control=animate(element,values,{duration:options.duration/1000,ease:bezier?bezier[1].split(',').map(Number):[.22,.65,.22,1],times:offsets(keyframes)});
50
+ const ease=options.easing==='linear'?'linear':bezier?bezier[1].split(',').map(Number):[.22,.65,.22,1];
51
+ control=animate(element,values,{duration:options.duration/1000,ease,times:offsets(keyframes),delay:delaySeconds(options),repeat:repeats(options)});
41
52
  control.finished.then(finish,error=>{if(!settled){cancel();}});
42
53
  }
43
54
  }catch(error){settled=true;control?.kill?.();effect?.cancel();restore();reject(error);}
@@ -117,7 +117,7 @@ object CrystalToken {
117
117
  const val defaultReduced = "false"
118
118
  const val defaultReduceMotion = "false"
119
119
  const val actionRadius = "999px"
120
- const val actionMinTarget = "44px"
120
+ const val actionMinTarget = "48px"
121
121
  const val actionPaddingBlock = "15px"
122
122
  const val actionPaddingInline = "24px"
123
123
  const val actionGap = "9px"
@@ -117,7 +117,7 @@ public enum CrystalToken {
117
117
  public static let defaultReduced = "false"
118
118
  public static let defaultReduceMotion = "false"
119
119
  public static let actionRadius = "999px"
120
- public static let actionMinTarget = "44px"
120
+ public static let actionMinTarget = "48px"
121
121
  public static let actionPaddingBlock = "15px"
122
122
  public static let actionPaddingInline = "24px"
123
123
  public static let actionGap = "9px"
@@ -117,7 +117,7 @@ export const crystalTokens = {
117
117
  "default.reduced": "false",
118
118
  "default.reduceMotion": "false",
119
119
  "action.radius": "999px",
120
- "action.minTarget": "44px",
120
+ "action.minTarget": "48px",
121
121
  "action.paddingBlock": "15px",
122
122
  "action.paddingInline": "24px",
123
123
  "action.gap": "9px",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crystal-ui/core",
3
- "version": "2.1.0",
3
+ "version": "2.2.0",
4
4
  "description": "Crystal design system: tokens, material primitives, headless core, icons and specifications.",
5
5
  "keywords": [],
6
6
  "type": "commonjs",
@@ -43,6 +43,7 @@
43
43
  "default": "./assets/core/presets.js"
44
44
  },
45
45
  "./catalogue": "./tokens/catalogue.json",
46
+ "./surfaces": "./tokens/surfaces.json",
46
47
  "./resolver": {
47
48
  "types": "./assets/crystal.d.ts",
48
49
  "default": "./assets/crystal.js"
@@ -13,6 +13,11 @@
13
13
  "narrow"
14
14
  ],
15
15
  "material": "Plastic foundation; Frost supporting panels; Resin destination plane",
16
+ "surface": [
17
+ "plastic",
18
+ "frost",
19
+ "dock"
20
+ ],
16
21
  "geometry": "Panel radius = content radius + 6px",
17
22
  "semantics": "Landmark roles: banner, navigation, main, contentinfo. One main per view.",
18
23
  "crystal": "Material assignment per region, elevation ordering, safe-area handling",
@@ -31,6 +36,9 @@
31
36
  "default"
32
37
  ],
33
38
  "material": "None; inherits the surface beneath",
39
+ "surface": [
40
+ "none"
41
+ ],
34
42
  "geometry": "Gutters follow the 4px rhythm: 18/26/44px by viewport",
35
43
  "semantics": "Presentational only; must not introduce a landmark",
36
44
  "crystal": "Width ceiling and gutter scale",
@@ -49,6 +57,9 @@
49
57
  "default"
50
58
  ],
51
59
  "material": "None",
60
+ "surface": [
61
+ "none"
62
+ ],
52
63
  "geometry": "Gutters from the 4px rhythm; 12-column reference",
53
64
  "semantics": "Presentational; reading order must match visual order",
54
65
  "crystal": "Gutter scale and breakpoint behaviour",
@@ -67,6 +78,9 @@
67
78
  "default"
68
79
  ],
69
80
  "material": "None",
81
+ "surface": [
82
+ "none"
83
+ ],
70
84
  "geometry": "Shared gutter with Grid",
71
85
  "semantics": "Presentational",
72
86
  "crystal": "Minimum cell width and gutter",
@@ -85,6 +99,9 @@
85
99
  "default"
86
100
  ],
87
101
  "material": "None",
102
+ "surface": [
103
+ "none"
104
+ ],
88
105
  "geometry": "Spacing from the 4px rhythm",
89
106
  "semantics": "Presentational",
90
107
  "crystal": "Spacing scale",
@@ -104,6 +121,9 @@
104
121
  "wrapped"
105
122
  ],
106
123
  "material": "None",
124
+ "surface": [
125
+ "none"
126
+ ],
107
127
  "geometry": "Spacing from the 4px rhythm",
108
128
  "semantics": "Presentational",
109
129
  "crystal": "Spacing scale and wrap behaviour",
@@ -124,6 +144,9 @@
124
144
  "vertical"
125
145
  ],
126
146
  "material": "Edge colour token; never a heavy rule",
147
+ "surface": [
148
+ "none"
149
+ ],
127
150
  "geometry": "1px, full-bleed within its container",
128
151
  "semantics": "role=separator with an accessible name when labelled; decorative dividers are aria-hidden",
129
152
  "crystal": "Rule colour and label treatment",
@@ -142,6 +165,9 @@
142
165
  "default"
143
166
  ],
144
167
  "material": "Inherits; commonly wraps Image or a media surface",
168
+ "surface": [
169
+ "none"
170
+ ],
145
171
  "geometry": "Content radius when clipping media",
146
172
  "semantics": "Presentational",
147
173
  "crystal": "Reserving space so loading media does not shift layout",
@@ -162,6 +188,9 @@
162
188
  "at-end"
163
189
  ],
164
190
  "material": "Inherits; edge fade uses the surrounding material",
191
+ "surface": [
192
+ "none"
193
+ ],
165
194
  "geometry": "Inherits container radius; fade depth 24px",
166
195
  "semantics": "Keyboard scrollable; must be focusable when it is the only way to reach content",
167
196
  "crystal": "Scrollbar appearance, edge fade, reduced-motion behaviour",
@@ -180,6 +209,9 @@
180
209
  "default"
181
210
  ],
182
211
  "material": "None",
212
+ "surface": [
213
+ "none"
214
+ ],
183
215
  "geometry": "None",
184
216
  "semantics": "Presentational",
185
217
  "crystal": "Nothing beyond layout",
@@ -198,6 +230,9 @@
198
230
  "default"
199
231
  ],
200
232
  "material": "None",
233
+ "surface": [
234
+ "none"
235
+ ],
201
236
  "geometry": "4px rhythm",
202
237
  "semantics": "Presentational; never used to convey grouping to assistive technology",
203
238
  "crystal": "Spacing scale",
@@ -218,6 +253,9 @@
218
253
  "condensed"
219
254
  ],
220
255
  "material": "Frost band over the Plastic foundation",
256
+ "surface": [
257
+ "frost"
258
+ ],
221
259
  "geometry": "Full-bleed; no radius on the outer edges; actions are pills.",
222
260
  "semantics": "role=\"banner\" unless nested; the title is the page heading or labels one.",
223
261
  "crystal": "Material, elevation on scroll, action geometry",
@@ -236,6 +274,9 @@
236
274
  "reflowing"
237
275
  ],
238
276
  "material": "None of its own; children carry material",
277
+ "surface": [
278
+ "none"
279
+ ],
239
280
  "geometry": "Gap follows the spacing scale; columns respond to container width.",
240
281
  "semantics": "A list when the items are a set; otherwise presentational.",
241
282
  "crystal": "Spacing, breakpoint behaviour, reduced-motion reflow",
@@ -255,6 +296,10 @@
255
296
  "menu-open"
256
297
  ],
257
298
  "material": "Children keep theirs; the overflow menu is Frost",
299
+ "surface": [
300
+ "none",
301
+ "frost"
302
+ ],
258
303
  "geometry": "Overflow trigger is a pill and reaches 44px.",
259
304
  "semantics": "The overflow trigger names how many items it holds; hidden items stay reachable.",
260
305
  "crystal": "Measurement, the trigger, the menu material",