@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.
- package/README.md +82 -23
- package/assets/core/preferences.d.ts +4 -4
- package/assets/core/preferences.js +4 -4
- package/assets/core/presets.d.ts +4 -3
- package/assets/core/presets.js +24 -18
- package/assets/core/spring.js +9 -10
- package/assets/core/state.js +7 -7
- package/assets/crystal.css +784 -284
- package/assets/crystal.d.ts +3 -3
- package/assets/crystal.js +100 -123
- package/assets/icons/heading-2.svg +1 -0
- package/assets/icons/heading-3.svg +1 -0
- package/assets/icons/heading-4.svg +1 -0
- package/assets/icons/link.svg +1 -0
- package/assets/icons/list-ordered.svg +1 -0
- package/assets/icons/list.svg +1 -0
- package/assets/icons/manifest.json +81 -2
- package/assets/icons/quote.svg +1 -0
- package/assets/icons/redo.svg +1 -0
- package/assets/icons/subscript.svg +1 -0
- package/assets/icons/undo.svg +1 -0
- package/assets/icons/unlink.svg +1 -0
- package/assets/motion.js +13 -12
- package/docs/accessibility.md +50 -54
- package/docs/adoption.md +33 -19
- package/docs/catalogue.md +113 -108
- package/docs/colors.md +67 -73
- package/docs/components.md +142 -66
- package/docs/icons.md +9 -3
- package/docs/materials.md +129 -117
- package/docs/motion-components.md +15 -15
- package/docs/motion.md +156 -158
- package/docs/principles.md +12 -12
- package/docs/tokens.md +129 -130
- package/engines.js +3 -3
- package/package.json +11 -3
- package/tokens/catalogue/01-layout.json +1 -1
- package/tokens/catalogue/02-navigation.json +4 -4
- package/tokens/catalogue/03-actions.json +2 -1
- package/tokens/catalogue/04-inputs.json +30 -22
- package/tokens/catalogue/05-data-display.json +9 -14
- package/tokens/catalogue/06-feedback.json +8 -6
- package/tokens/catalogue/07-overlays.json +4 -4
- package/tokens/catalogue/08-typography.json +12 -8
- package/tokens/catalogue/09-utility.json +1 -1
- package/tokens/catalogue/10-charts.json +7 -7
- package/tokens/catalogue/11-media.json +33 -20
- package/tokens/catalogue/12-commerce.json +4 -4
- package/tokens/catalogue/13-screens.json +2 -3
- package/tokens/catalogue/14-blocks.json +3 -3
- package/tokens/catalogue.json +176 -116
- package/tokens/crystal.tokens.json +6 -6
- package/tokens/motion-recipes.json +6 -6
- package/tokens/surface-recipes.json +3452 -0
- package/tokens/surfaces.json +48 -17
package/docs/accessibility.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
56
|
-
label. In the dark high-contrast palette `HighlightText` and `Canvas` are both black
|
|
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
|
-
|
|
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
|
-
|
|
77
|
-
|
|
78
|
-
|
|
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
|
-
|
|
81
|
-
|
|
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
|
|
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
|
|
91
|
-
travel does not
|
|
92
|
-
shows it has been pressed.
|
|
93
|
-
layer.
|
|
94
|
-
|
|
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
|
|
97
|
-
|
|
98
|
-
movement goes and the whole track or fill stays, static
|
|
99
|
-
along,
|
|
100
|
-
says what is loading. With or without reduced motion, a
|
|
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
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
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
|
|
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
|
|
128
|
-
|
|
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
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|
-
|
|
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,
|
|
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-
|
|
168
|
+
| Checks run | 2026-10-03 |
|
|
172
169
|
|
|
173
|
-
Normal text is held to 4.5:1. Essential non-text
|
|
174
|
-
indicator lines
|
|
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
|
|
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
|
|
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.
|
|
184
|
-
|
|
185
|
-
|
|
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
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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` |
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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.
|