@crystal-ui/core 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +82 -23
  2. package/assets/core/preferences.d.ts +4 -4
  3. package/assets/core/preferences.js +4 -4
  4. package/assets/core/presets.d.ts +4 -3
  5. package/assets/core/presets.js +24 -18
  6. package/assets/core/spring.js +9 -10
  7. package/assets/core/state.js +7 -7
  8. package/assets/crystal.css +784 -284
  9. package/assets/crystal.d.ts +3 -3
  10. package/assets/crystal.js +100 -123
  11. package/assets/icons/heading-2.svg +1 -0
  12. package/assets/icons/heading-3.svg +1 -0
  13. package/assets/icons/heading-4.svg +1 -0
  14. package/assets/icons/link.svg +1 -0
  15. package/assets/icons/list-ordered.svg +1 -0
  16. package/assets/icons/list.svg +1 -0
  17. package/assets/icons/manifest.json +81 -2
  18. package/assets/icons/quote.svg +1 -0
  19. package/assets/icons/redo.svg +1 -0
  20. package/assets/icons/subscript.svg +1 -0
  21. package/assets/icons/undo.svg +1 -0
  22. package/assets/icons/unlink.svg +1 -0
  23. package/assets/motion.js +13 -12
  24. package/docs/accessibility.md +50 -54
  25. package/docs/adoption.md +33 -19
  26. package/docs/catalogue.md +113 -108
  27. package/docs/colors.md +67 -73
  28. package/docs/components.md +142 -66
  29. package/docs/icons.md +9 -3
  30. package/docs/materials.md +129 -117
  31. package/docs/motion-components.md +15 -15
  32. package/docs/motion.md +156 -158
  33. package/docs/principles.md +12 -12
  34. package/docs/tokens.md +129 -130
  35. package/engines.js +3 -3
  36. package/package.json +11 -3
  37. package/tokens/catalogue/01-layout.json +1 -1
  38. package/tokens/catalogue/02-navigation.json +4 -4
  39. package/tokens/catalogue/03-actions.json +2 -1
  40. package/tokens/catalogue/04-inputs.json +30 -22
  41. package/tokens/catalogue/05-data-display.json +9 -14
  42. package/tokens/catalogue/06-feedback.json +8 -6
  43. package/tokens/catalogue/07-overlays.json +4 -4
  44. package/tokens/catalogue/08-typography.json +12 -8
  45. package/tokens/catalogue/09-utility.json +1 -1
  46. package/tokens/catalogue/10-charts.json +7 -7
  47. package/tokens/catalogue/11-media.json +33 -20
  48. package/tokens/catalogue/12-commerce.json +4 -4
  49. package/tokens/catalogue/13-screens.json +2 -3
  50. package/tokens/catalogue/14-blocks.json +3 -3
  51. package/tokens/catalogue.json +176 -116
  52. package/tokens/crystal.tokens.json +6 -6
  53. package/tokens/motion-recipes.json +6 -6
  54. package/tokens/surface-recipes.json +3452 -0
  55. package/tokens/surfaces.json +48 -17
@@ -1,10 +1,10 @@
1
1
  # Accessibility contract and validation
2
2
 
3
- Crystal preserves the original project's strict accessibility intent. WCAG 2.2 is the current Recommendation verified from the W3C source on September 17, 2026; recheck the latest finalized standard at adoption and release. AA is this reusable system’s engineering baseline, not a claim that the entire package or a consuming application has been certified. [WCAG 2.2](https://www.w3.org/TR/WCAG22/).
3
+ Crystal preserves the original project's strict accessibility intent. WCAG 2.2 is the current Recommendation verified from the W3C source on September 17, 2026; recheck the latest finalized standard at adoption and release. AA is this reusable system's engineering baseline. It does not certify the package or a consuming application. [WCAG 2.2](https://www.w3.org/TR/WCAG22/).
4
4
 
5
5
  ## Color and material requirements
6
6
 
7
- Normal reading/control text must meet at least 4.5:1 against its actual background; applicable large text and essential non-text identification have 3:1 requirements. Use the standard's definitions and exceptions, not a blanket assumption that a decorative border must pass or that every large label qualifies.
7
+ Normal reading/control text must meet at least 4.5:1 against its actual background; applicable large text and essential non-text identification have 3:1 requirements. Use the standard's definitions and exceptions. Do not assume that a decorative border must pass or that every large label qualifies.
8
8
 
9
9
  No essential meaning depends solely on hue. Use visible words, circular symbol badges or other shapes alongside programmatic state. Screen-reader labels alone do not address a sighted user who cannot distinguish colors. Functional colors remain independent of the product theme. [W3C use-of-color explanation](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html).
10
10
 
@@ -32,7 +32,7 @@ The live table checks ten defined solid color pairs per palette/mode. It does no
32
32
  | States | Focus, pressed, selected, disabled, pending, empty, invalid, denied, offline |
33
33
  | Platform | Actual supported browser engines and native adapters, not just one screenshot |
34
34
 
35
- Use automated scans as one part of review. Screen-reader journeys, focus recovery, content clarity, high zoom, mobile behavior and native accessibility APIs require direct testing. Runtime contrast exports are evidence about token pairs, not a complete conformance claim.
35
+ Use automated scans as one part of review. Screen-reader journeys, focus recovery, content clarity, high zoom, mobile behavior and native accessibility APIs require direct testing. Runtime contrast exports are evidence about token pairs only and do not establish conformance.
36
36
 
37
37
  ## What this delivery verifies
38
38
 
@@ -40,23 +40,20 @@ See the [verification report](../verification/report.html) for checks actually r
40
40
 
41
41
  ## Forced colours
42
42
 
43
- Windows High Contrast — `forced-colors: active` in CSS — replaces the page's palette with
43
+ Windows High Contrast (`forced-colors: active` in CSS) replaces the page's palette with
44
44
  a small set of system colours the user has chosen: `Canvas`, `CanvasText`, `Highlight`,
45
- `HighlightText`, `ButtonFace`, `ButtonText`, `LinkText`. Crystal honours that choice
46
- rather than opting out of it.
45
+ `HighlightText`, `ButtonFace`, `ButtonText`, `LinkText`. Crystal honours that choice.
47
46
 
48
47
  ### Selection is a ring, never a fill
49
48
 
50
- This is the rule, and it comes from a real defect found in this system.
51
-
52
49
  Chromium paints an opaque **text backplate** behind text runs in forced-colors mode: a
53
- rectangle of `Canvas` drawn *above* the element's own background, so that text is
50
+ rectangle of `Canvas` drawn above the element's own background, so that text is
54
51
  guaranteed to sit on the user's background colour. A selected control styled as a filled
55
- row therefore renders as: your fill, then an opaque `Canvas` rectangle over it, then the
56
- label. In the dark high-contrast palette `HighlightText` and `Canvas` are both black — so
52
+ row therefore renders as your fill, then an opaque `Canvas` rectangle over it, then the
53
+ label. In the dark high-contrast palette `HighlightText` and `Canvas` are both black, so
57
54
  the label disappears into the backplate and the control becomes a solid black block.
58
55
 
59
- The fix is to stop filling and start ringing:
56
+ Selection is therefore drawn as an outline:
60
57
 
61
58
  ```css
62
59
  @media (forced-colors: active){
@@ -73,32 +70,32 @@ An outline is not covered by the backplate, because the backplate only spans the
73
70
  negative offset draws the ring just inside the control's boundary so it reads as "this one"
74
71
  rather than as a focus ring.
75
72
 
76
- **`forced-color-adjust: none` is not the fix.** It works, and it does so by discarding the
77
- palette the user deliberately chose — which is the entire point of the mode. It is
78
- reserved for content whose meaning *is* its colour, such as a palette swatch.
73
+ **Do not use `forced-color-adjust: none` here.** It works by discarding the palette the
74
+ user chose, which the mode exists to apply. It is reserved for content whose meaning is
75
+ its colour, such as a palette swatch.
79
76
 
80
- Verified in both the light and dark high-contrast palettes. The captures and the defect
81
- this rule came from are in
77
+ The rule is verified in both the light and dark high-contrast palettes. The captures,
78
+ and the defect that led to the rule, are in
82
79
  `validation/captures/2026-09-17-forced-colours/`.
83
80
 
84
81
  ## Reduced motion
85
82
 
86
83
  `prefers-reduced-motion: reduce` is honoured by every one of the 59 motion recipes. Each
87
- recipe declares its own `reduced` behaviour rather than being globally switched off,
84
+ recipe declares its own `reduced` behaviour, and motion is not switched off globally,
88
85
  because "no animation" and "no *movement*" are different requirements.
89
86
 
90
- The contract is: **the semantic state change still happens, immediately; the decorative
91
- travel does not.** A menu that opens still opens. A button that has been pressed still
92
- shows it has been pressed. What is removed is the travel, the overshoot and the shader
93
- layer. Reduced motion resolves to zero displacement regardless of the recipe's spring —
94
- this is asserted by `tools/validate-motion.cjs`, not left to each implementation.
87
+ The contract is that the semantic state change still happens, immediately, and the
88
+ decorative travel does not. A menu that opens still opens, and a button that has been pressed still
89
+ shows it has been pressed. Reduced motion removes the travel, the overshoot and the
90
+ shader layer. It resolves to zero displacement regardless of the recipe's spring.
91
+ `tools/validate-motion.cjs` asserts this, so it does not depend on each implementation.
95
92
 
96
- The three continuous indicators are the one place this reads differently, because what they
97
- report is not a change but a state that lasts: work that is pending. Under reduced motion the
98
- movement goes and the whole track or fill stays, static — never a segment frozen part of the way
99
- along, which would report a measurement nobody took — and the text beside the indicator still
100
- says what is loading. With or without reduced motion, a continuous indicator stops when the work
101
- resolves; none of them repeats at rest.
93
+ The three continuous indicators are the one place the contract applies differently,
94
+ because what they report is a state that lasts: work that is pending. Under reduced motion
95
+ the movement goes and the whole track or fill stays, static. A segment frozen part of the
96
+ way along is never shown, because it would report a measurement nobody took. The text
97
+ beside the indicator still says what is loading. With or without reduced motion, a
98
+ continuous indicator stops when the work resolves; none of them repeats at rest.
102
99
 
103
100
  ## Reduced transparency
104
101
 
@@ -114,25 +111,25 @@ backdrop filter with a solid surface and a stronger border:
114
111
  }
115
112
  ```
116
113
 
117
- The border strengthens deliberately. Translucency was carrying some of the edge
118
- definition; removing it without compensating leaves surfaces that are technically opaque
119
- and visually unbounded. Contrast is re-checked in this mode — a regression here was found
120
- and fixed during verification, recorded in
114
+ The border is stronger because translucency carries some of the edge definition.
115
+ Removing it without compensating leaves surfaces that are opaque and visually unbounded.
116
+ Contrast is re-checked in this mode. A regression found and fixed during
117
+ verification is recorded in
121
118
  `validation/captures/2026-09-17-rtl-and-reduced-effects/`.
122
119
 
123
120
  ## Target size
124
121
 
125
- Every interactive control has a minimum target of **44 × 44 px**, including controls that
122
+ Every interactive control has a minimum target of 44 × 44 px, including controls that
126
123
  look smaller than that. A 24px icon button carries 44px of hit area; a menu entry is 44px
127
- tall even where the label is 19px. This is a floor, not a target — it is not reduced on
128
- dense layouts, because "dense" is a visual decision and the hand does not get more precise.
124
+ tall even where the label is 19px. This is a floor. It is not reduced on dense layouts,
125
+ because "dense" is a visual decision and the hand does not get more precise.
129
126
 
130
127
  ## Direction
131
128
 
132
- Right-to-left is a verified axis, not an aspiration. Layout uses logical properties
133
- throughout — `inset-inline-start`, `padding-inline-start`, `margin-inline-end` — so mirroring
134
- is a direction change rather than a stylesheet. The menu indentation, the drop indicator
135
- and the focus offset all follow.
129
+ Right-to-left is a verified axis. Layout uses logical properties throughout
130
+ (`inset-inline-start`, `padding-inline-start`, `margin-inline-end`), so mirroring needs a
131
+ direction change and no second stylesheet. The menu indentation, the drop indicator and
132
+ the focus offset all follow.
136
133
 
137
134
  Physical properties are correct only where the meaning is physical: a light source is
138
135
  above in both directions, so the Haze recess keeps `inset 0 1px` rather than becoming a
@@ -157,33 +154,32 @@ meaning when a product re-themes. See [Color](colors.html#status).
157
154
 
158
155
  <!-- generated:contrast -->
159
156
 
160
- **1,788 contrast cases** are computed across all six palettes in both
157
+ 1,836 contrast cases are computed across all six palettes in both
161
158
  modes, including bounded composites: Resin and Haze control labels are checked with the
162
159
  optical sheen beneath the protective fill, against content composites and RGB-corner
163
160
  backdrops with the fixed Resin fill.
164
161
 
165
162
  | Measure | Result |
166
163
  |---|---|
167
- | Cases computed | 1,788 |
164
+ | Cases computed | 1,836 |
168
165
  | Failures | 0 |
169
166
  | Lowest result of any kind | 3.07:1 |
170
167
  | Lowest normal-text result | 4.67:1 |
171
- | Checks run | 2026-09-29 |
168
+ | Checks run | 2026-10-03 |
172
169
 
173
- Normal text is held to 4.5:1. Essential non-text — focus rings, control boundaries,
174
- indicator lines — uses its separate 3:1 threshold, which is the correct standard for those
175
- elements rather than a relaxation for them.
170
+ Normal text is held to 4.5:1. Essential non-text (focus rings, control boundaries,
171
+ indicator lines) is held to the separate 3:1 threshold that applies to those elements.
176
172
  <!-- /generated:contrast -->
177
173
 
178
174
  **The field shell's rim is decorative, by ruling.** `.cr-field-shell` draws its edge in the
179
- white rim, which measures 1.06:1 against the page in light mode and 1.63:1 in dark — well
175
+ white rim, which measures 1.06:1 against the page in light mode and 1.63:1 in dark, well
180
176
  under the 3:1 above. Meridian ruled on 28 September 2026 (D-24) that the field is drawn as
181
- written: the rim is not the thing that identifies a field. What does is the Resin shell's
177
+ written: the rim does not identify a field. A field is identified by the Resin shell's
182
178
  fill and float shadow, the Haze well the value is read on, and the visible label every
183
- Crystal field carries. Those are not covered by the 1,788 checks above, and a product that
184
- needs a field boundary it can defend against WCAG 1.4.11 on its own terms should measure its
185
- own backdrops rather than rely on this table.
179
+ Crystal field carries. The 1,836 checks above do not cover those. A product that needs a
180
+ field boundary it can defend against WCAG 1.4.11 on its own terms should measure its own
181
+ backdrops and not rely on this table.
186
182
 
187
- What that does and does not establish is stated plainly in the
188
- [verification report](../verification/report.html): it is evidence about this reference
189
- package, not a claim of complete WCAG conformance for a product built with it.
183
+ The [verification report](../verification/report.html) states what these results
184
+ establish: they are evidence about this reference package and make no claim of complete
185
+ WCAG conformance for a product built with it.
package/docs/adoption.md CHANGED
@@ -14,7 +14,7 @@
14
14
  | `assets/site.css`, `assets/site.js` | Reference-site layout and local demonstration behavior |
15
15
  | `tokens/crystal.json` | Canonical editable palette, material and default configuration |
16
16
  | `docs/*.md` | Editable specifications; adjacent HTML is generated |
17
- | `docs/tokens.md`, `docs/catalogue.md` | **Generated** from the token sources — do not edit |
17
+ | `docs/tokens.md`, `docs/catalogue.md` | Generated from the token sources; do not edit |
18
18
  | `src/overview.md` | The site's index page, editable |
19
19
  | `src/pages/*.html` | Editable body fragments for the Playground and motion studies |
20
20
  | `tools/shell.py` | The only copy of the page header, side menu and footer |
@@ -25,7 +25,7 @@
25
25
  **Every HTML file in the site is generated.** `index.html`, `playground.html`,
26
26
  `motion.html`, the ten specification pages and the verification report are all written
27
27
  by `tools/build.py` and `tools/report.py` through `tools/shell.py`. Edit the markdown,
28
- the fragments under `src/pages/`, or the shell — never the HTML, which the next build
28
+ the fragments under `src/pages/`, or the shell. Never edit the HTML, which the next build
29
29
  overwrites. Sections between `<!-- generated:NAME -->` markers inside a markdown file
30
30
  are written by `tools/build-reference.cjs` and are overwritten too; the prose around
31
31
  them is not.
@@ -36,9 +36,9 @@ The site uses relative local assets without fetching fonts or services. Review i
36
36
 
37
37
  Copy `assets/crystal.css`, `assets/fonts/`, `assets/grain.svg`, and the theme CSS into the product. Preserve the primitive stylesheet’s relative asset paths. Load theme CSS before primitive CSS. The reference-site CSS/JS are not needed by a product.
38
38
 
39
- `assets/crystal.css` carries the Resin interaction surface, the components built on it — `.cr-control`, `.cr-field-shell`, `.cr-indicator`, `.cr-resin-haze` and `.cr-tag` — the dock, the table and its scroller, and every native form control: checkbox, radio, switch, range, file button, select option and menu item. As of 2.2.0 it also carries the four recipes the catalogue needed and no consumer could obtain: `.cr-nav-item` (a navigation entry, selected by label weight), `.cr-bare` (a control with no Resin coat, for controls inside a surface that already has one), `.cr-drag-handle`, and `.cr-resin.panel` (the Resin plane with the content radius). Before 2.1.0 it carried none of the control surface, and this page told you to copy a second stylesheet, `assets/controls.css`, that the package has never contained. There is no second stylesheet to copy.
39
+ `assets/crystal.css` carries the Resin interaction surface, the components built on it (`.cr-control`, `.cr-field-shell`, `.cr-indicator`, `.cr-resin-haze` and `.cr-tag`), the dock, the table and its scroller, and every native form control: checkbox, radio, switch, range, file button, select option and menu item. As of 2.2.0 it also carries the four recipes the catalogue needed and consumers could not obtain before: `.cr-nav-item` (a navigation entry, selected by label weight), `.cr-bare` (a control with no Resin coat, for controls inside a surface that already has one), `.cr-drag-handle`, and `.cr-resin.panel` (the Resin plane with the content radius). Before 2.1.0 it carried none of the control surface. There is no second stylesheet to copy: the package has never contained `assets/controls.css`.
40
40
 
41
- Every component in the catalogue names the surface it is made of, from the closed vocabulary in `tokens/surfaces.json` (exported as `@crystal-ui/core/surfaces`). A library implements each surface once — as a class, a mixin or a native view — and every component made of it inherits the implementation. The catalogue chapter lists the vocabulary with the `crystal.css` recipe behind each entry.
41
+ Every component in the catalogue names the surface it is made of, from the closed vocabulary in `tokens/surfaces.json` (exported as `@crystal-ui/core/surfaces`). A library implements each surface once, as a class, a mixin or a native view, and every component made of it inherits the implementation. The catalogue chapter lists the vocabulary with the `crystal.css` recipe behind each entry.
42
42
 
43
43
  ```html
44
44
  <link rel="stylesheet" href="crystal-theme.css">
@@ -55,7 +55,7 @@ Every component in the catalogue names the surface it is made of, from the close
55
55
 
56
56
  Set `data-crystal-mode="dark"` or `"light"` on the root HTML element to select a mode. An export made with Auto selected also follows the OS preference unless explicitly overridden. Export CSS from the playground to capture the selected palette and material settings in both modes.
57
57
 
58
- The product adapter supplies layout, padding and placement (at least 12px of inset for content on feathered fills): the snippet shows material assignment, not a complete application. Set `data-window-active="false"` on a foundation to select its neutral opaque inactive state; remove the attribute or set it to `"true"` to restore contextual tint. Wire this to supported host activation events where available. The browser study uses a manual switch and does not infer desktop activation or capture wallpaper.
58
+ The product adapter supplies layout, padding and placement (at least 12px of inset for content on feathered fills): the snippet shows material assignment only. Set `data-window-active="false"` on a foundation to select its neutral opaque inactive state; remove the attribute or set it to `"true"` to restore contextual tint. Wire this to supported host activation events where available. The browser study uses a manual switch and does not infer desktop activation or capture wallpaper.
59
59
 
60
60
  The primitive stylesheet includes element-level typography, focus and box-sizing rules intended for a Crystal product root.
61
61
 
@@ -74,7 +74,7 @@ Crystal's stylesheets are organised into cascade layers, declared once at the to
74
74
  | `crystal.component` | Crystal's controls and material surfaces | Crystal |
75
75
  | `crystal.override` | Deliberate overrides that beat Crystal's components | You |
76
76
 
77
- **An ordinary unlayered rule in your own stylesheet beats every layer.** Overriding Crystal no longer requires out-specifying it: `.cr-button { border-radius: 4px }` is enough. Use `crystal.override` when you want an override that still loses to your own unlayered rules, and `crystal.base` for page styles Crystal's components should win over.
77
+ **An ordinary unlayered rule in your own stylesheet beats every layer.** Overriding Crystal does not require out-specifying it: `.cr-button { border-radius: 4px }` is enough. Use `crystal.override` when you want an override that still loses to your own unlayered rules, and `crystal.base` for page styles Crystal's components should win over.
78
78
 
79
79
  If your page has inline `<style>` blocks that Crystal's components are expected to win over, declare them into `crystal.base`. Unlayered styles take precedence over all layers, which is usually what you want for product code and occasionally surprising for a page's own scaffolding. Review them when introducing Crystal into an existing application; scope these rules in your adapter if the page contains unrelated embedded products. `--cr-` variables are namespaced, but generic element selectors are not a CSS isolation boundary.
80
80
 
@@ -101,6 +101,20 @@ A product owns preference sync, account boundaries, device exceptions, migration
101
101
 
102
102
  Share color roles, typography relationships, radii, elevation hierarchy, status vocabulary and adaptation rules. Build real platform components and use supported native material APIs where appropriate. CSS shadows/blur values are visual references, not guaranteed equivalent compositor parameters. Verify real native accessibility, text scaling, keyboard/IME, input capture and performance on each target. No native adapter is included in this package.
103
103
 
104
+ ### Surface recipes as values
105
+
106
+ `core/tokens/surfaces.json` names the `crystal.css` selector that implements each surface. A SwiftUI or Compose library cannot wear a selector, so the recipe behind each one is also published as data: `tokens/surface-recipes.json`, exported as `@crystal-ui/core/surface-recipes`. It has one record per surface, in vocabulary order. Each record gives the fill, blur, saturation, rim, shadow, radius and padding the stylesheet resolves for an element that wears only that selector. Each value is written as the stylesheet writes it: a token reference such as `var(--cr-resin-fill)`, a literal such as `999px`, or an expression such as `calc(var(--cr-radius) + 6px)`. Resolve the tokens from the platform export (`exports/crystal-tokens.swift`, `.kt` or `.ts`) and every platform reaches the same values.
107
+
108
+ The platform guide in `libraries/CONTRACT.md` (§2) names the fallbacks a library must honour and works one record per material. Read a record in this order:
109
+
110
+ - `haze` is the feathered paint layer. Haze and Stone are painted on an isolated `::before` through a blur filter, so the element's own `fill` is often `transparent` and the reading fill is `haze.fill`, inset by `haze.inset` and feathered by `haze.feather`. Reproduce it as a separate layer behind the content. Text, icons and focus stay crisp.
111
+ - `layers` holds every pseudo-element the recipe paints, such as the Resin sheen on `::before` and `::after`.
112
+ - `fallbacks` lists what changes under `opaque`, `reducedTransparency`, `forcedColors` and `noBackdropFilter`. A branch lists only the declarations that change and take effect. `conditions` holds other conditional branches, such as narrow layouts.
113
+ - `shadowed` lists fallback declarations the cascade overrides, which therefore never render in the browser. `missing` names a material the surface claims that the recipe does not paint for that selector, and `why` says where it comes from instead: the selector is a part of a larger surface, or takes the value from what it is worn on. Do not copy a shadowed declaration, and draw a missing material as `why` describes it. A gap without a reason fails the contract tests.
114
+ - `tokens` lists every `--cr-*` property the record references.
115
+
116
+ States and variants (`:hover`, `.primary`, descendants such as `.cr-dock button`) are outside the record. The file is generated by `tools/build-surface-recipes.cjs` on every build and checked against the stylesheet by `tests/core-contracts.cjs`. Never edit it by hand.
117
+
104
118
  ## Named material API and compatibility
105
119
 
106
120
  Use `.cr-plastic`, `.cr-frost`, `.cr-resin`, `.cr-haze`, `.cr-stone` and `.cr-mirage` for new integrations. The canonical JSON’s `materials` catalog records all six names, roles, inspirations and primitives. Named CSS variables include `--cr-plastic-inactive`, `--cr-frost-fill`, `--cr-resin-fill`, `--cr-haze-fill`, `--cr-stone-fill`, and `--cr-mirage-fill`, with matching blur/feather variables where applicable.
@@ -126,19 +140,19 @@ Crystal follows semantic versioning against a stated public contract. These are
126
140
  - Exported file formats for CSS, JSON, TypeScript, Swift and Kotlin
127
141
  - Icon identifiers in the manifest
128
142
 
129
- Anything else — internal selectors, generated file ordering, the preview site — may change in a patch release.
143
+ Anything else (internal selectors, generated file ordering, the preview site) may change in a patch release.
130
144
 
131
- **Deprecate before removing.** A deprecated name keeps working for at least one minor version, and the version that will remove it is named at the moment it is deprecated. Removal happens only in a major release. The legacy material vocabulary — `--cr-acrylic-*`, `--cr-glass-*`, `--cr-mica-*` and the `.cr-acrylic` and `.cr-glass` classes — is deprecated in 2.0.0 and will be removed in 3.0.0; they currently ship as aliases of the Frost, Resin and Plastic tokens.
145
+ **Deprecate before removing.** A deprecated name keeps working for at least one minor version, and the version that will remove it is named at the moment it is deprecated. Removal happens only in a major release. The legacy material vocabulary (`--cr-acrylic-*`, `--cr-glass-*`, `--cr-mica-*` and the `.cr-acrylic` and `.cr-glass` classes) is deprecated in 2.0.0 and will be removed in 3.0.0; they currently ship as aliases of the Frost, Resin and Plastic tokens.
132
146
 
133
- Crystal publishes publicly to npm as **`@crystal-ui/core`**:
147
+ Crystal publishes publicly to npm as `@crystal-ui/core`:
134
148
 
135
149
  ```sh
136
150
  npm install @crystal-ui/core
137
151
  ```
138
152
 
139
- Products pin a version, which is what makes one-version-per-product and a CI parity check enforceable. Every release after 2.0.0 is published from a tag by GitHub Actions through npm Trusted Publishing and carries a provenance attestation, so a consumer can verify the tarball came from `boomerbowser/crystal` and from the commit the tag names. 2.0.0 itself was published by hand and is the one version without an attestation — npm cannot attach a trusted publisher to a package that does not exist yet.
153
+ Products pin a version, which makes one-version-per-product and a CI parity check enforceable. Every release after 2.0.0 is published from a tag by GitHub Actions through npm Trusted Publishing and carries a provenance attestation, so a consumer can verify the tarball came from `boomerbowser/crystal` and from the commit the tag names. 2.0.0 itself was published by hand and is the one version without an attestation, because npm cannot attach a trusted publisher to a package that does not exist yet.
140
154
 
141
- A specification bundle — the token files, the generated Swift and Kotlin exports and the parity contract — is attached to each GitHub release, for platform libraries that cannot install an npm package.
155
+ A specification bundle (the token files, the generated Swift and Kotlin exports and the parity contract) is attached to each GitHub release, for platform libraries that cannot install an npm package.
142
156
 
143
157
  ## Rebuild and validate
144
158
 
@@ -150,31 +164,31 @@ npm run build
150
164
  npm test
151
165
  ```
152
166
 
153
- `npm run build` regenerates everything the library generates rather than stores: the flat token file from the DTCG source, `tokens.js`, 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, the engine versions against the lockfile, documentation drift, and what the published package may contain. Node and nothing else — the library has no Python tooling.
167
+ `npm run build` regenerates everything the library generates rather than stores: the flat token file from the DTCG source, `tokens.js`, 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, the engine versions against the lockfile, documentation drift, and what the published package may contain. The library needs Node and nothing else; it has no Python tooling.
154
168
 
155
- The exported theme is produced by running the resolver, not by writing CSS. Any other method would be a second implementation of alias resolution, which is the divergence the token pipeline exists to prevent.
169
+ The exported theme is produced by running the resolver and never by writing CSS. Any other method would be a second implementation of alias resolution, which is the divergence the token pipeline exists to prevent.
156
170
 
157
- The documentation website is a separate repository, `crystal-preview`. It installs this package, renders the specification it installed, and runs the browser gates — pages, links, scrolling, interactions and the visual baselines — against what was published rather than against a working copy.
171
+ The documentation website is a separate repository, `crystal-preview`. It installs this package, renders the specification it installed, and runs the browser gates (pages, links, scrolling, interactions and the visual baselines) against what was published rather than against a working copy.
158
172
 
159
173
  ## Deploying the documentation website
160
174
 
161
- The website is `crystal-preview`, a separate repository that installs this package. How it is deployed — the Vercel settings, the caching rules, the relative-path and clean-URL constraints — is documented there, because it is a fact about that site rather than about Crystal. Nothing in this package depends on it.
175
+ The website is `crystal-preview`, a separate repository that installs this package. How it is deployed (the Vercel settings, the caching rules, the relative-path and clean-URL constraints) is documented there, because it concerns that site and not Crystal. Nothing in this package depends on it.
162
176
 
163
177
  ### User animation speed
164
178
 
165
- `Crystal.normalize({ motionSpeed: 1 })` accepts a factor from 0.25 to 2. Resolved durations divide by that factor and cap each animation at 5000ms; reduced motion produces zero durations. CSS and JSON exports retain this preference. The playground and Motion page share it, including real dialog/backdrop timing. Products should target 0–2 seconds by default and expose reduced motion independently of speed.
179
+ `Crystal.normalize({ motionSpeed: 1 })` accepts a factor from 0.25 to 2. Resolved durations divide by that factor and cap each animation at 5000ms; reduced motion produces zero durations. CSS and JSON exports retain this preference. The playground and Motion page share it, including real dialog/backdrop timing. Products should target 0 to 2 seconds by default and expose reduced motion independently of speed.
166
180
 
167
181
 
168
182
  ### Motion engine dependencies
169
183
 
170
184
  The motion runtime needs the engines and the recipe catalogue. `@crystal-ui/core` declares Motion 13.4.0 and GSAP 3.15.0 as dependencies and ships `engines.js`, which re-exports both; bundle it however your product bundles anything else. The recipes are `@crystal-ui/core/motion-recipes`. Ship `licenses/` with any bundle that includes the engines.
171
185
 
172
- **The token resolver and the static material CSS do not need either library.** A product that uses Crystal's colour, materials and geometry without its motion installs nothing extra. See [component motion](motion-components.html) for the integration and cancellation contracts.
186
+ The token resolver and the static material CSS do not need either library. A product that uses Crystal's colour, materials and geometry without its motion installs nothing extra. See [component motion](motion-components.html) for the integration and cancellation contracts.
173
187
 
174
188
  ### Interaction surfaces and revised motion
175
189
 
176
190
  Render the field shells in your component framework: a bare `<input>` cannot carry Crystal's focus ring, because the ring belongs to the shell around it and the input itself takes `outline: 0`. Compact information surfaces and ephemeral menus use `.cr-resin-haze`. Do not transplant the legacy solid button rules without this material layer. The 54-recipe catalogue declares material signatures and justified extended travel; the old 50px token describes compact motion only.
177
191
 
178
- `controls.css` is **not** part of this package and never will be — but as of 2.1.0 the part of it you needed is. It was the documentation site's own stylesheet, and it carried a great deal that this specification describes and the library did not ship, so a product following this page reached for `.cr-indicator` or `.cr-resin-haze` and got nothing, styled a `.cr-table-scroll` that never scrolled, and got no checkbox, radio, range or select styling at all.
192
+ `controls.css` is not part of this package and never will be, but as of 2.1.0 the part of it you needed is. It is the documentation site's own stylesheet, and it carried a great deal that this specification describes and the library did not ship: in the library `.cr-indicator` and `.cr-resin-haze` had no rules, `.cr-table-scroll` did not scroll, and checkbox, radio, range and select had no styling.
179
193
 
180
- It took two passes to find it. The first lifted five components and the interaction surface and was checked by rendering the site with and without them, which proved the lift faithful and said nothing about what the site still overrode — both sides of that comparison kept the sheet. The second measured the residual directly and moved a further 75 rules. Those now live in `assets/crystal.css`; the site keeps what is genuinely its own — its switches, its segmented controls, its colour swatches. What remains of `controls.css` is still not exportable: it styles bare elements, and exporting it once already caused a 32px chip to render 50px tall in Crystal React — D-9. `tools/verify-package.cjs` fails a tarball that contains it.
194
+ Five components, the interaction surface and a further 75 rules moved from it into `assets/crystal.css`. The site keeps what is its own: its switches, its segmented controls and its colour swatches. What remains of `controls.css` is not exportable. It styles bare elements, and exporting it made a 32px chip render 50px tall in Crystal React (D-9). `tools/verify-package.cjs` fails a tarball that contains it.