@crystal-ui/core 2.0.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.
- package/assets/crystal-theme.css +126 -3
- package/assets/crystal.css +1192 -5
- package/assets/crystal.js +106 -11
- package/assets/motion.js +17 -2
- package/assets/tokens.js +1 -1
- package/docs/accessibility.md +9 -2
- package/docs/adoption.md +29 -48
- package/docs/catalogue.md +465 -33
- package/docs/colors.md +84 -0
- package/docs/components.md +55 -25
- package/docs/materials.md +12 -4
- package/docs/motion-components.md +16 -12
- package/docs/motion.md +12 -2
- package/docs/tokens.md +31 -3
- package/engines.js +13 -2
- package/exports/crystal-tokens.kt +19 -1
- package/exports/crystal-tokens.swift +19 -1
- package/exports/crystal-tokens.ts +19 -1
- package/package.json +2 -1
- package/tokens/catalogue/01-layout.json +45 -0
- package/tokens/catalogue/02-navigation.json +89 -2
- package/tokens/catalogue/03-actions.json +42 -1
- package/tokens/catalogue/04-inputs.json +366 -5
- package/tokens/catalogue/05-data-display.json +187 -1
- package/tokens/catalogue/06-feedback.json +78 -6
- package/tokens/catalogue/07-overlays.json +50 -3
- package/tokens/catalogue/08-typography.json +54 -0
- package/tokens/catalogue/09-utility.json +79 -0
- package/tokens/catalogue/10-charts.json +89 -1
- package/tokens/catalogue/11-media.json +33 -0
- package/tokens/catalogue/12-commerce.json +134 -1
- package/tokens/catalogue/13-screens.json +81 -0
- package/tokens/catalogue/14-blocks.json +101 -0
- package/tokens/catalogue.json +1652 -21
- package/tokens/crystal.json +253 -13
- package/tokens/crystal.tokens.json +98 -2
- package/tokens/motion-recipes.json +216 -0
- package/tokens/surfaces.json +167 -0
package/docs/colors.md
CHANGED
|
@@ -33,6 +33,90 @@ The seed is not automatically a text color. The canonical [token JSON](../tokens
|
|
|
33
33
|
| Functional | `success`, `attention`, `danger`, `info` ink/surface pairs | Independent of brand palette and mode-aware |
|
|
34
34
|
| Component/material | Resin fill, Stone backing, edge, shadows, radii | Derived from the chosen palette and settings |
|
|
35
35
|
|
|
36
|
+
### There is no secondary colour, and that is a decision
|
|
37
|
+
|
|
38
|
+
Crystal defines **one action pair per palette** — `primary` with `onPrimary`, and
|
|
39
|
+
`primarySoft` with `onPrimarySoft` for the container form. There is no
|
|
40
|
+
`secondary`, and nothing in the token set, the exported theme or the component
|
|
41
|
+
vocabulary names one.
|
|
42
|
+
|
|
43
|
+
A palette is not one hue: each carries a seed, a **companion** and a **glow**, and
|
|
44
|
+
all three ship as `--cr-decorative`, `--cr-companion` and `--cr-glow`. What they
|
|
45
|
+
do not carry is an ink. They sit in the Expressive layer above precisely because
|
|
46
|
+
they have never been given a tested foreground, and the resolver consumes them in
|
|
47
|
+
four places, all of them paint rather than ground: the three atmosphere stops and
|
|
48
|
+
the focus shadow.
|
|
49
|
+
|
|
50
|
+
Promoting the companion is not a matter of renaming it. As a solid reading fill it
|
|
51
|
+
fails the 4.5 floor with **both** candidate inks in a third of the matrix — Prism
|
|
52
|
+
dark 3.27 against white and 3.00 against the text ink, Amethyst dark 4.02 / 3.68,
|
|
53
|
+
Harbor 4.16 / 3.07 in light and 4.16 / 3.32 in dark. The other eight
|
|
54
|
+
palette-and-mode combinations clear it between 4.54 and 6.60, and a role that
|
|
55
|
+
works in eight of twelve is not a role. A secondary action colour would need its
|
|
56
|
+
own tuned tones and its own tested ink authored per palette per mode, which is
|
|
57
|
+
work nobody has done and not an omission anybody can close by promotion.
|
|
58
|
+
|
|
59
|
+
The consequence for components is that **no variant may be named after it**. A
|
|
60
|
+
`.secondary` button existed until 22 September 2026 and was withdrawn for exactly
|
|
61
|
+
this reason: a variant named after a colour the system does not define is a
|
|
62
|
+
promise it cannot keep. Emphasis is carried by `.primary` being opt-in, by label
|
|
63
|
+
weight, and by placement.
|
|
64
|
+
|
|
65
|
+
### The chart series scale, which is not that
|
|
66
|
+
|
|
67
|
+
Charts need several colours at once and a palette gives one. Crystal 2.1.0
|
|
68
|
+
therefore publishes a **series scale**: six categorical colours per palette per
|
|
69
|
+
mode, as `--cr-chart-series-1` through `--cr-chart-series-6`, alongside
|
|
70
|
+
`--cr-chart-axis` and `--cr-chart-grid`.
|
|
71
|
+
|
|
72
|
+
This is not the secondary colour arriving by another door, and the distinction is
|
|
73
|
+
worth being exact about. A series colour is **for data marks only** — a bar, a
|
|
74
|
+
line, a segment, a cell. It is never ink, never an action fill, never a surface
|
|
75
|
+
and never a state. It has no tested foreground, because nothing is ever set on
|
|
76
|
+
top of it; that is precisely the property the companion lacks and cannot be given
|
|
77
|
+
by renaming.
|
|
78
|
+
|
|
79
|
+
They are derived rather than picked, in `tools/build-tokens.cjs`, because the
|
|
80
|
+
thing that has to be true of seventy-two colours is a measurement and not a
|
|
81
|
+
preference. Take the palette's seed hue, turn half a step off it, step six times
|
|
82
|
+
around the hue circle, and draw all six at one OKLab lightness (0.55 light, 0.72
|
|
83
|
+
dark) and one chroma (0.18). Then:
|
|
84
|
+
|
|
85
|
+
- **Every one clears 3:1 against both the surface and the canvas of its mode.** A
|
|
86
|
+
data mark is a graphical object carrying information, so WCAG 1.4.11 applies.
|
|
87
|
+
Where a hue cannot reach the floor at the stated lightness its lightness moves
|
|
88
|
+
until it does — the floor is a promise, the family resemblance is a preference.
|
|
89
|
+
- **No two in a scale are closer than 0.10 in OKLab.** Segments and stacked bars
|
|
90
|
+
are adjacent to each other, not only to the ground.
|
|
91
|
+
- **One lightness for all six**, deliberately: a categorical scale must not imply
|
|
92
|
+
an order, and a ramp does.
|
|
93
|
+
- **The ring is centred on the palette hue rather than started from it.** A slot
|
|
94
|
+
on the seed hue at these lightnesses is the palette's action colour, and a data
|
|
95
|
+
mark the colour of every button on the page is one people try to press.
|
|
96
|
+
|
|
97
|
+
All four are asserted in `tests/core-contracts.cjs` for all twelve
|
|
98
|
+
palette-and-mode combinations.
|
|
99
|
+
|
|
100
|
+
Beside the series scale, and on the same principle from the other direction,
|
|
101
|
+
Crystal 2.1.0 publishes an **intensity ramp**: `--cr-chart-heat-1` through
|
|
102
|
+
`--cr-chart-heat-5`, for a heatmap cell or a calendar day, each with its own ink
|
|
103
|
+
as `--cr-chart-on-heat-N`. A cell is a *ground* rather than a mark — the value is
|
|
104
|
+
written on it — so the floor that applies is the text one, 4.5:1, and it applies
|
|
105
|
+
to every step. The ink changes partway along the ramp in some palettes, which is
|
|
106
|
+
what a ramp spanning light to dark has to do; what the construction guarantees is
|
|
107
|
+
that no step falls in the gap where neither of a mode's inks reaches the floor.
|
|
108
|
+
Harbor is why that is a search and not a constant: its body ink is a soft grey
|
|
109
|
+
rather than a near-black, and a ramp built for the other five would be unreadable
|
|
110
|
+
in exactly the palette that chose to be quiet.
|
|
111
|
+
|
|
112
|
+
Six is where hue separation runs out, not where charts do. **A seventh series
|
|
113
|
+
repeats the first colour and must differ by another channel** — a dash pattern, a
|
|
114
|
+
fill pattern, a marker shape. That rule is not a fallback for the seventh series
|
|
115
|
+
only: colour is never the sole carrier of a series at any count, because six hues
|
|
116
|
+
at sixty degrees do not survive dichromatic vision, and the scale is not built to
|
|
117
|
+
pretend otherwise. Two of the six also sit near the danger and success hues; they
|
|
118
|
+
carry no such meaning, and a chart that needs to say "bad" says it in words.
|
|
119
|
+
|
|
36
120
|
CSS variables use the `--cr-` namespace and kebab-case names. Source JSON uses camelCase keys and the explicit `Crystal token schema v1`; it is not advertised as a Design Tokens Community Group interchange schema.
|
|
37
121
|
|
|
38
122
|
## Functional meanings
|
package/docs/components.md
CHANGED
|
@@ -9,26 +9,31 @@ The package contains working CSS primitives and a bounded interactive reference.
|
|
|
9
9
|
| Foundation | Opaque canvas and contextual gradients; light/dark | `.cr-plastic`; product chooses composition |
|
|
10
10
|
| Haze content card | 80% fill, 1.95px feathered perimeter, radius, content depth | `.cr-haze`; use semantic article or button according to behavior |
|
|
11
11
|
| Frost panel | Frosted surround, grain, Haze reading wells | `.cr-frost`; app supplies menu/sheet behavior and focus |
|
|
12
|
-
| Resin toolbar | Single floating plane, protected label group, selected destination | `.cr-resin`, `.cr-dock
|
|
12
|
+
| Resin toolbar | Single floating plane, protected label group, selected destination | `.cr-resin`, `.cr-dock` (a Resin pill, 9px padding, Haze perimeter, 7px when narrow), `.cr-dock-inner`; local preview switches actual scenes; app supplies routing |
|
|
13
13
|
| Stone label backing | 55% light / 60% dark, 1.95px feather, crisp text | `.cr-stone`; `.cr-dock-inner` shares the recipe |
|
|
14
14
|
| Mirage modal scrim | Dark tint with chromatic diffusion of the scene behind the active modal | `.cr-mirage` and dialog `::backdrop`; standalone paint requires real application modal behavior |
|
|
15
|
-
|
|
|
16
|
-
|
|
|
15
|
+
| Action | Resin shell with the neutral Haze reading fill, optical pressure and light; hover/pressed/focus/disabled | `.cr-button`. Real action and progress/error handling are app-owned |
|
|
16
|
+
| Primary action | The same control with its Haze reading fill **in the primary colour** and the tested ink on it | `.cr-button.primary`; `--cr-primary` on the fill, `--cr-on-primary` as the ink. Opt-in, so a button is emphatic only where somebody said so |
|
|
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 |
|
|
17
18
|
| Destructive action | Resin/Haze with independent danger boundary and explicit label | `.danger`; app supplies consequence-specific confirmation and recovery |
|
|
18
19
|
| Text field | Visible label, state badge, glowing focus ring, validation, helper/error association | `.cr-input`; working native form example; app supplies validation rules |
|
|
19
|
-
| Selection control | Explicit selected state plus text/mark | Native checkbox
|
|
20
|
-
|
|
|
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 |
|
|
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 |
|
|
21
26
|
| Authored bubble | Haze, directional tight corner, optional author metadata | `.cr-bubble`, `.own`; app supplies content/Markdown semantics |
|
|
22
27
|
| Composer surround | Frost frame and softened content well around protected input controls | CSS composition; no rich-text editor or delivery service is implemented |
|
|
23
|
-
| Status badge | Independent ink/surface pair, symbol and visible label | `.cr-status` with `data-status`; dynamic announcements are app-owned |
|
|
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 |
|
|
24
29
|
| Avatar | Circular image/initials, accessible identity when needed | Reference styling; app handles real identity, image failure and privacy |
|
|
25
30
|
| Dialog | 80% feathered surface over Mirage; title, body and named actions | Working native HTML dialog example; Escape/focus return; app owns transactions |
|
|
26
|
-
| Tooltip | Short supplemental text; never sole label |
|
|
27
|
-
| Menu/popover |
|
|
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 |
|
|
28
33
|
| Drawer/sheet | Overlay support with label, close, focus management | Working modal inspector in the motion suite; app decides production modality |
|
|
29
34
|
| Table/list | Soft content panel, clear header relationships, explicit sort/filter states | Native table in contrast report; production data controls not implemented |
|
|
30
35
|
| Tabs | Labeled selected item with keyboard pattern matching actual semantics | Working ARIA tabs in the motion suite; scene navigation separately uses pressed buttons |
|
|
31
|
-
| Notification/toast | Clear result plus useful next action |
|
|
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 |
|
|
32
37
|
| Loading | Preserve layout, communicate pending work, no false success | Specification only; user-triggered work needs real lifecycle state |
|
|
33
38
|
| Empty/error/denied | Explain situation and a valid next step | Specification only; must reflect actual service/permission state |
|
|
34
39
|
| Chart/data visualization | Direct labels, pattern/shape, accessible equivalent | Specification only; brand palettes are not prevalidated chart palettes |
|
|
@@ -39,7 +44,7 @@ Every production control needs default, hover where meaningful, pressed, focus-v
|
|
|
39
44
|
|
|
40
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.
|
|
41
46
|
|
|
42
|
-
The selected
|
|
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.
|
|
43
48
|
|
|
44
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.
|
|
45
50
|
|
|
@@ -63,11 +68,28 @@ Maintain a production Storybook or equivalent gallery for actual components with
|
|
|
63
68
|
|
|
64
69
|
## Resin interaction and information surfaces
|
|
65
70
|
|
|
66
|
-
|
|
71
|
+
Buttons, action links, tabs, selectable controls and field shells use Resin as their interaction surface, with Haze reading protection inside a visible Resin perimeter. **On the primary action that reading fill is the primary colour, and the perimeter is the ordinary glass rim** — `--cr-primary` on the fill, `--cr-on-primary` as the ink, which is the palette's own tested pair and measures 4.74 to 10.31 against the rendered composite across all six palettes and both modes. The fill is opaque there where the neutral one is 80%, and that is the single deliberate deviation in this recipe. An 80% fill transmits a fifth of what is behind it: white over a light page is still white, so the neutral pad loses nothing, but a mid-tone primary at 80% over the Resin shell composites to a washed-out lilac sitting at the luminance where neither a white nor a near-black label clears 4.5 — 3.37 to 4.55 with `onPrimary`, 2.95 to 5.06 with `text`, failing in every light palette. A reading ground whose job is to make the label independent of the backdrop cannot be the one thing that depends on it.
|
|
67
72
|
|
|
68
|
-
|
|
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.
|
|
69
74
|
|
|
70
|
-
|
|
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.
|
|
76
|
+
|
|
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.
|
|
78
|
+
|
|
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.
|
|
71
93
|
|
|
72
94
|
### Interaction surface geometry
|
|
73
95
|
|
|
@@ -100,27 +122,35 @@ Icons next to text are decorative and hidden from assistive technology. Icon-onl
|
|
|
100
122
|
|
|
101
123
|
## Focus light and circular state badges
|
|
102
124
|
|
|
103
|
-
Focus uses an immediate 2px primary-color core at a 3px offset, surrounded by a broadly feathered halo. The halo is four graded layers of the primary color — 46% at 6px
|
|
125
|
+
Focus uses an immediate 2px primary-color core at a 3px offset, surrounded by a broadly feathered halo. The halo is four graded layers of the primary color — 46% at 6px / 1px, 30% at 16px / 3px, 17% at 30px / 6px and 8% at 54px / 11px (blur / spread) — so the light falls off smoothly instead of ending on a hard edge. The spreads were halved from 2/6/12/22 at Meridian's request; the blur radii were deliberately left alone, so the ring thins without the falloff flattening.
|
|
126
|
+
|
|
127
|
+
**A focused control also lifts.** Beneath the halo sit two elevation layers: a directional 8px / 18px (offset / blur) at 30% of the primary color, and a broad 22px / 40px at 27% of the *decorative* color. The directional layer reuses the halo's second feather so the lift reads as the same light source; the broad one is decorative rather than primary so the shadow under a focused control carries the palette's own shadow hue instead of tinting the page purple. Focus changes the elevation shadow's hue without blurring any foreground.
|
|
128
|
+
|
|
129
|
+
**In dark mode the feather alphas lift**, to 56 / 38 / 22 / 11 against light's 46 / 30 / 17 / 8. A deep canvas swallows the falloff at the lighter values, so the ring reads as a hard edge with nothing around it. Blur, spread and the elevation layers are identical in both modes.
|
|
130
|
+
|
|
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.
|
|
104
132
|
|
|
105
|
-
A `.cr-indicator` is a 20px
|
|
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.
|
|
106
134
|
|
|
107
135
|
<!-- generated:focus-recipe -->
|
|
108
136
|
|
|
109
137
|
| Layer | Blur | Spread | Role |
|
|
110
138
|
|---|---|---|---|
|
|
111
139
|
| `outline: 2px solid var(--cr-focus-core)` at `outline-offset: 3px` | — | — | The crisp core. Never feathered, and the only part that survives forced colours. |
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
|
|
|
115
|
-
|
|
|
116
|
-
|
|
|
117
|
-
|
|
|
140
|
+
| Halo 1 | 6px | 1px | 46% of the primary colour |
|
|
141
|
+
| Halo 2 | 16px | 3px | 30% of the primary colour |
|
|
142
|
+
| Halo 3 | 30px | 6px | 17% of the primary colour |
|
|
143
|
+
| Halo 4 | 54px | 11px | 8% of the primary colour |
|
|
144
|
+
| Elevation 1 | 18px | — | 30% of the primary colour, offset 8px — the directional lift |
|
|
145
|
+
| Elevation 2 | 40px | — | 27% of the decorative colour, offset 22px — the broad lift |
|
|
118
146
|
<!-- /generated:focus-recipe -->
|
|
119
147
|
|
|
120
|
-
|
|
121
|
-
cannot disagree with what ships.
|
|
122
|
-
|
|
123
|
-
|
|
148
|
+
Every layer is read from `--cr-focus-ring` in the library's own exported theme, so this
|
|
149
|
+
table cannot disagree with what ships. It used to be read from the preview site's
|
|
150
|
+
`assets/controls.css` — a stylesheet the package does not contain — which is how Crystal
|
|
151
|
+
came to document a halo it did not export and a lift no consumer received. The core is
|
|
152
|
+
never feathered and the offset is never zero: a ring drawn *on* the border is hard to
|
|
153
|
+
tell from a hover state, and on a pill it reads as a thicker stroke rather than as focus.
|
|
124
154
|
|
|
125
155
|
A check mark is reserved for validation and information display — the status badges in `.cr-status` and a checkbox's own `:checked` indicator. It never marks a selected, pressed or focused control. Selection instead uses a heavier label weight, which changes no metric that would reflow the group. Round specimen swatches, which cannot carry a weight change, use an inset ring gap. Ordinary prose links retain their link styling. Badges are `aria-hidden`: the real control supplies its accessible name, required/invalid/selected/busy state and error association. The visual symbol never gets appended to the control's text content. Native checkbox/radio indicators and functional labels remain intact. Small controls retain full-sized hit targets. Badges have solid, unblurred alternatives under reduced transparency and forced colors.
|
|
126
156
|
|
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—
|
|
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
|
-
|
|
286
|
-
|
|
287
|
-
|
|
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
|
|
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
|
|
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 **
|
|
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 |
|
|
@@ -86,6 +87,8 @@ Base times below are at 1×; the preview resolves the saved speed at playback. E
|
|
|
86
87
|
| `tab-in` | frost / refraction | Motion | 650ms | Selected tab panels; apply aria-selected and hidden state synchronously. |
|
|
87
88
|
| `page-in` | plastic / inertia | Motion | 1050ms | New local view after routing is committed; preserve focus and history. |
|
|
88
89
|
| `page-out` | plastic / inertia | Motion | 760ms | Departing view only; never postpone route authorization or loading. |
|
|
90
|
+
| `view-push-in` | plastic / inertia | GSAP | 700ms | 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. |
|
|
91
|
+
| `view-push-out` | plastic / inertia | GSAP | 700ms | 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. |
|
|
89
92
|
| `breadcrumb` | resin / coalesce | Motion | 500ms | New breadcrumb item; current-page semantics stay explicit. |
|
|
90
93
|
| `drawer-in` | frost / refraction | GSAP | 1000ms | Side sheets and inspector panels; establish modality first. |
|
|
91
94
|
| `drawer-out` | frost / refraction | GSAP | 650ms | Keep modal focus contained until dismissal completes. |
|
|
@@ -124,11 +127,15 @@ Base times below are at 1×; the preview resolves the saved speed at playback. E
|
|
|
124
127
|
| `haze-tide` | haze / feather | GSAP | 1800ms | Explicit material choreography for a large specimen; replay is a visual study, not an application action. |
|
|
125
128
|
| `stone-contour` | stone / feather | GSAP | 1300ms | Explicit material choreography for a large specimen; replay is a visual study, not an application action. |
|
|
126
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. |
|
|
127
134
|
<!-- /generated:component-recipes -->
|
|
128
135
|
|
|
129
136
|
## Runtime API
|
|
130
137
|
|
|
131
|
-
|
|
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.
|
|
132
139
|
|
|
133
140
|
```js
|
|
134
141
|
// Apply real UI state before giving it visual feedback.
|
|
@@ -164,16 +171,13 @@ The catalog replays visual recipes on isolated specimens; a menu recipe replay i
|
|
|
164
171
|
|
|
165
172
|
```sh
|
|
166
173
|
npm ci
|
|
167
|
-
npm run build
|
|
174
|
+
npm run build
|
|
168
175
|
npm test
|
|
169
|
-
python3 tools/build.py
|
|
170
|
-
python3 tools/validate.py
|
|
171
|
-
python3 tools/package.py
|
|
172
176
|
```
|
|
173
177
|
|
|
174
|
-
|
|
178
|
+
`npm run build` regenerates the token data, the exported theme and the reference sections in `docs/`. `npm test` runs that build and then checks token contracts and contrast, recipe uniqueness, duration and travel bounds, engine declarations against the lockfile, documentation drift, and what the published package may contain. It needs Node and nothing else — the library has no Python tooling.
|
|
175
179
|
|
|
176
|
-
|
|
180
|
+
The motion engines are bundled for a browser by the documentation website, not here: `@crystal-ui/core` ships `engines.js` and declares gsap and motion as dependencies, and a consumer bundles them as it prefers. The browser contract page that exercises the real engines — recipe completion, cancellation, supersession, property restoration, reduced motion, duration limits, stationary foregrounds and every material signature — lives in `crystal-preview` and runs against the published package. Its results are evidence for the exercised browser, not a full WCAG, native-renderer or cross-browser certification.
|
|
177
181
|
|
|
178
182
|
### Storybook and future component packages
|
|
179
183
|
|
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
|
|
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
|
|
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
|
|
|
@@ -270,6 +270,8 @@ correct is a material question, not a taste question — see the signature polic
|
|
|
270
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
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
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. |
|
|
273
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. |
|
|
274
276
|
|
|
275
277
|
#### Overlays
|
|
@@ -297,6 +299,8 @@ correct is a material question, not a taste question — see the signature polic
|
|
|
297
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. |
|
|
298
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. |
|
|
299
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. |
|
|
300
304
|
|
|
301
305
|
#### Feedback
|
|
302
306
|
|
|
@@ -310,6 +314,8 @@ correct is a material question, not a taste question — see the signature polic
|
|
|
310
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. |
|
|
311
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. |
|
|
312
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. |
|
|
313
319
|
|
|
314
320
|
#### Media
|
|
315
321
|
|
|
@@ -340,6 +346,10 @@ correct is a material question, not a taste question — see the signature polic
|
|
|
340
346
|
|
|
341
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.
|
|
342
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
|
+
|
|
343
353
|
**Travel policy.** 5–30px ordinary, 50px guidance; justified large transitions may exceed it. Haze and Stone paint moves locally while text stays fixed.
|
|
344
354
|
|
|
345
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
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
Every value Crystal ships, generated from `core/tokens/crystal.tokens.json` — the W3C
|
|
4
4
|
Design Tokens (DTCG) source of truth. This page is written by
|
|
5
5
|
`tools/build-reference.cjs`; editing it by hand is pointless, because the next build
|
|
6
|
-
overwrites it. Edit the token file and run `
|
|
6
|
+
overwrites it. Edit the token file and run `npm run build`.
|
|
7
7
|
|
|
8
8
|
## How the three tiers work
|
|
9
9
|
|
|
@@ -433,14 +433,14 @@ What a value *means*: the surface a card sits on, the duration a control settles
|
|
|
433
433
|
|
|
434
434
|
Values that belong to one component family and would be wrong to reuse elsewhere. This tier exists so a component can be specific without inventing a private constant.
|
|
435
435
|
|
|
436
|
-
|
|
436
|
+
58 tokens.
|
|
437
437
|
|
|
438
438
|
### Component · action
|
|
439
439
|
|
|
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 | `
|
|
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 |
|
|
@@ -565,6 +565,34 @@ Values that belong to one component family and would be wrong to reuse elsewhere
|
|
|
565
565
|
| --- | --- | --- | --- |
|
|
566
566
|
| `component.haze.inset` | dimension | `8px` | How far a Resin surface holds its Haze content fill back from its own rim, so the glass edge still reads while the label sits on a stable ground. The fill is feathered and therefore lives on an isolated layer behind the content; feathering an element that contains text blurs the text. A Resin strip uses the same inset and its pills carry no material of their own. |
|
|
567
567
|
|
|
568
|
+
### Component · chart
|
|
569
|
+
|
|
570
|
+
| Token | Type | Value | Meaning |
|
|
571
|
+
| --- | --- | --- | --- |
|
|
572
|
+
| `component.chart.seriesCount` | number | `6` | How many categorical series the palette can tell apart by colour. A seventh series repeats the first colour and must differ by another channel — a dash pattern, a fill pattern or a marker shape — because six hues is where perceptual separation runs out, not where charts do. |
|
|
573
|
+
| `component.chart.seriesLightness.light` | number | `0.55` | OKLab lightness every light-mode series colour is drawn at. One lightness for all six is what makes them read as one family rather than a ramp: a categorical scale must not imply an order it does not have. |
|
|
574
|
+
| `component.chart.seriesLightness.dark` | number | `0.72` | The same, for dark mode. Higher than light, because the ground is dark and a mark must be lighter than it — but not as high as the ground allows. At 0.80 sRGB can no longer hold the chroma at the violet and blue hues, the colours there go pale, and the first series of a violet palette lands on the same colour as the palette's own action colour, which is a data mark that reads as a button. |
|
|
575
|
+
| `component.chart.seriesChroma` | number | `0.18` | OKLab chroma asked for at each series hue, reduced per hue only where sRGB cannot hold it. Asking for one chroma and clipping is what keeps the six equally saturated to the eye. |
|
|
576
|
+
| `component.chart.seriesHueOffset` | number | `30` | Degrees the ring of series hues is turned from the palette's own seed hue. Half a step, so the palette hue falls exactly between the first and last series rather than on the first. The ring is centred on the palette rather than started from it for one reason: a series colour sitting on the seed hue at the lightness these are drawn at is the palette's action colour, and a data mark that is the colour of every button on the page is a data mark people try to press. |
|
|
577
|
+
| `component.chart.seriesContrast` | number | `3` | The floor every series colour clears against both the surface and the canvas of its mode. A data mark is a graphical object carrying information, so WCAG 1.4.11 applies to it and 3:1 is the bar. Where a hue cannot reach the floor at the stated lightness, its lightness moves until it does — the floor is not negotiable and the family resemblance is. |
|
|
578
|
+
| `component.chart.stroke` | dimension | `2px` | Line and edge weight for a data mark: a chart line, a polygon edge, a candle wick. |
|
|
579
|
+
| `component.chart.hairline` | dimension | `1px` | The separation a chart draws in the surface colour rather than in ink — between pie segments, heatmap cells, treemap rectangles and map regions. It is a gap, not a border: it shows the ground through. |
|
|
580
|
+
| `component.chart.pointMin` | dimension | `6px` | Smallest drawn point diameter. Points are sized on a scale between this and pointMax; the hit area is the action minimum regardless, so a 6px point is still a 44px target. |
|
|
581
|
+
| `component.chart.pointMax` | dimension | `18px` | Largest drawn point diameter. |
|
|
582
|
+
| `component.chart.barRadius` | dimension | `4px` | Radius on the value end of a bar only. The base end stays square because it sits on the axis, and rounding it would lift the bar off the line it is measured from. |
|
|
583
|
+
| `component.chart.cellGap` | dimension | `2px` | Gap between the square cells of a heatmap or calendar heatmap. |
|
|
584
|
+
| `component.chart.ringThickness` | number | `0.32` | A donut's ring thickness as a proportion of its outer radius. Declared rather than chosen per chart so a donut is recognisably the same object at every size. |
|
|
585
|
+
| `component.chart.fillOpacity` | number | `0.25` | Opacity of a fill whose job is to show extent without hiding what is behind it — the region under a line, the inside of a radar polygon. Low enough that two overlapping series are still two, and that the gridlines a reader measures against are still legible through both. |
|
|
586
|
+
| `component.chart.linkOpacity` | number | `0.45` | Opacity of a flow between two nodes. Higher than a fill because a link is the mark rather than its backing, and low enough that a crossing reads as two links rather than as a third shape. |
|
|
587
|
+
| `component.chart.intensitySteps` | number | `5` | How many buckets an intensity scale has — a heatmap cell, a calendar day. Five, because a reader comparing cells is matching them to a key rather than reading a gradient, and a key with more entries than a hand has fingers is a key nobody uses. |
|
|
588
|
+
| `component.chart.gaugeSweep` | number | `270` | Degrees an arc gauge sweeps, centred on the bottom. Not a full circle, because a full circle has no ends and a gauge is a value between two of them; not a half, because three quarters gives the same travel half the diameter would and leaves the centre square for the value. |
|
|
589
|
+
|
|
590
|
+
### Component · progress
|
|
591
|
+
|
|
592
|
+
| Token | Type | Value | Meaning |
|
|
593
|
+
| --- | --- | --- | --- |
|
|
594
|
+
| `component.progress.ringStroke` | dimension | `8px` | Stroke of a circular progress ring, and of the gauge arc that the catalogue says matches it. One value so the two cannot drift: a gauge is a progress ring that has been told what it is measuring. |
|
|
595
|
+
|
|
568
596
|
## Deprecations
|
|
569
597
|
|
|
570
598
|
A deprecated token still resolves. It is listed here so adopters can migrate before
|
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
|
-
|
|
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
|
-
|
|
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 = "
|
|
120
|
+
const val actionMinTarget = "48px"
|
|
121
121
|
const val actionPaddingBlock = "15px"
|
|
122
122
|
const val actionPaddingInline = "24px"
|
|
123
123
|
const val actionGap = "9px"
|
|
@@ -156,4 +156,22 @@ object CrystalToken {
|
|
|
156
156
|
const val anchorUnderlineOffset = "4px"
|
|
157
157
|
const val treeIndentStep = "20px"
|
|
158
158
|
const val hazeInset = "8px"
|
|
159
|
+
const val chartSeriesCount = "6"
|
|
160
|
+
const val chartSeriesLightnessLight = "0.55"
|
|
161
|
+
const val chartSeriesLightnessDark = "0.72"
|
|
162
|
+
const val chartSeriesChroma = "0.18"
|
|
163
|
+
const val chartSeriesHueOffset = "30"
|
|
164
|
+
const val chartSeriesContrast = "3"
|
|
165
|
+
const val chartStroke = "2px"
|
|
166
|
+
const val chartHairline = "1px"
|
|
167
|
+
const val chartPointMin = "6px"
|
|
168
|
+
const val chartPointMax = "18px"
|
|
169
|
+
const val chartBarRadius = "4px"
|
|
170
|
+
const val chartCellGap = "2px"
|
|
171
|
+
const val chartRingThickness = "0.32"
|
|
172
|
+
const val chartFillOpacity = "0.25"
|
|
173
|
+
const val chartLinkOpacity = "0.45"
|
|
174
|
+
const val chartIntensitySteps = "5"
|
|
175
|
+
const val chartGaugeSweep = "270"
|
|
176
|
+
const val progressRingStroke = "8px"
|
|
159
177
|
}
|