@crystal-ui/core 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +82 -23
  2. package/assets/core/preferences.d.ts +4 -4
  3. package/assets/core/preferences.js +4 -4
  4. package/assets/core/presets.d.ts +4 -3
  5. package/assets/core/presets.js +24 -18
  6. package/assets/core/spring.js +9 -10
  7. package/assets/core/state.js +7 -7
  8. package/assets/crystal.css +784 -284
  9. package/assets/crystal.d.ts +3 -3
  10. package/assets/crystal.js +100 -123
  11. package/assets/icons/heading-2.svg +1 -0
  12. package/assets/icons/heading-3.svg +1 -0
  13. package/assets/icons/heading-4.svg +1 -0
  14. package/assets/icons/link.svg +1 -0
  15. package/assets/icons/list-ordered.svg +1 -0
  16. package/assets/icons/list.svg +1 -0
  17. package/assets/icons/manifest.json +81 -2
  18. package/assets/icons/quote.svg +1 -0
  19. package/assets/icons/redo.svg +1 -0
  20. package/assets/icons/subscript.svg +1 -0
  21. package/assets/icons/undo.svg +1 -0
  22. package/assets/icons/unlink.svg +1 -0
  23. package/assets/motion.js +13 -12
  24. package/docs/accessibility.md +50 -54
  25. package/docs/adoption.md +33 -19
  26. package/docs/catalogue.md +113 -108
  27. package/docs/colors.md +67 -73
  28. package/docs/components.md +142 -66
  29. package/docs/icons.md +9 -3
  30. package/docs/materials.md +129 -117
  31. package/docs/motion-components.md +15 -15
  32. package/docs/motion.md +156 -158
  33. package/docs/principles.md +12 -12
  34. package/docs/tokens.md +129 -130
  35. package/engines.js +3 -3
  36. package/package.json +11 -3
  37. package/tokens/catalogue/01-layout.json +1 -1
  38. package/tokens/catalogue/02-navigation.json +4 -4
  39. package/tokens/catalogue/03-actions.json +2 -1
  40. package/tokens/catalogue/04-inputs.json +30 -22
  41. package/tokens/catalogue/05-data-display.json +9 -14
  42. package/tokens/catalogue/06-feedback.json +8 -6
  43. package/tokens/catalogue/07-overlays.json +4 -4
  44. package/tokens/catalogue/08-typography.json +12 -8
  45. package/tokens/catalogue/09-utility.json +1 -1
  46. package/tokens/catalogue/10-charts.json +7 -7
  47. package/tokens/catalogue/11-media.json +33 -20
  48. package/tokens/catalogue/12-commerce.json +4 -4
  49. package/tokens/catalogue/13-screens.json +2 -3
  50. package/tokens/catalogue/14-blocks.json +3 -3
  51. package/tokens/catalogue.json +176 -116
  52. package/tokens/crystal.tokens.json +6 -6
  53. package/tokens/motion-recipes.json +6 -6
  54. package/tokens/surface-recipes.json +3452 -0
  55. package/tokens/surfaces.json +48 -17
package/docs/colors.md CHANGED
@@ -35,32 +35,31 @@ The seed is not automatically a text color. The canonical [token JSON](../tokens
35
35
 
36
36
  ### There is no secondary colour, and that is a decision
37
37
 
38
- Crystal defines **one action pair per palette** — `primary` with `onPrimary`, and
38
+ Crystal defines one action pair per palette: `primary` with `onPrimary`, and
39
39
  `primarySoft` with `onPrimarySoft` for the container form. There is no
40
40
  `secondary`, and nothing in the token set, the exported theme or the component
41
41
  vocabulary names one.
42
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.
43
+ A palette has more than one hue: each carries a seed, a companion and a glow, and
44
+ all three ship as `--cr-decorative`, `--cr-companion` and `--cr-glow`. None of
45
+ them carries an ink. They sit in the Expressive layer above because they have
46
+ never been given a tested foreground. The resolver consumes them in four places,
47
+ all of them paint and none of them ground: the three atmosphere stops and the
48
+ focus shadow.
49
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
50
+ The companion cannot be promoted by 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
52
  dark 3.27 against white and 3.00 against the text ink, Amethyst dark 4.02 / 3.68,
53
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.
54
+ palette-and-mode combinations clear it between 4.54 and 6.60, and eight of twelve
55
+ is too few to define a role. A secondary action colour would need its own tuned
56
+ tones and its own tested ink authored per palette per mode. That work has not
57
+ been done, and promotion does not replace it.
58
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.
59
+ For components, the consequence is that **no variant may be named after it**. A
60
+ `.secondary` button existed until 22 September 2026 and was withdrawn for this
61
+ reason: the system does not define the colour the variant was named after.
62
+ Emphasis is carried by `.primary` being opt-in, by label weight, and by placement.
64
63
 
65
64
  ### The chart series scale, which is not that
66
65
 
@@ -69,53 +68,50 @@ therefore publishes a **series scale**: six categorical colours per palette per
69
68
  mode, as `--cr-chart-series-1` through `--cr-chart-series-6`, alongside
70
69
  `--cr-chart-axis` and `--cr-chart-grid`.
71
70
 
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.
71
+ The series scale is not a secondary colour. A series colour is for data marks
72
+ only: a bar, a line, a segment, a cell. It is never ink, an action fill, a
73
+ surface or a state. It has no tested foreground, because nothing is ever set on
74
+ top of it. The companion lacks that property and cannot be given it by renaming.
78
75
 
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:
76
+ They are derived in `tools/build-tokens.cjs` and not picked by hand, because
77
+ what has to be true of seventy-two colours is a measurement. Take the palette's
78
+ seed hue, turn half a step off it, step six times around the hue circle, and draw
79
+ all six at one OKLab lightness (0.55 light, 0.72 dark) and one chroma (0.18).
80
+ Then:
84
81
 
85
- - **Every one clears 3:1 against both the surface and the canvas of its mode.** A
82
+ - Every one clears 3:1 against both the surface and the canvas of its mode. A
86
83
  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.
84
+ Where a hue cannot reach the floor at the stated lightness, its lightness moves
85
+ until it does: the floor takes priority over the family resemblance.
86
+ - No two in a scale are closer than 0.10 in OKLab. Segments and stacked bars
87
+ are adjacent to each other as well as to the ground.
88
+ - All six share one lightness: a categorical scale must not imply an order, and
89
+ a ramp does.
90
+ - The ring is centred on the palette hue and does not start from it. A slot on
91
+ the seed hue at these lightnesses is the palette's action colour, and people
92
+ try to press a data mark that has the colour of every button on the page.
96
93
 
97
94
  All four are asserted in `tests/core-contracts.cjs` for all twelve
98
95
  palette-and-mode combinations.
99
96
 
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.
97
+ Beside the series scale, Crystal 2.1.0 publishes an **intensity ramp**:
98
+ `--cr-chart-heat-1` through `--cr-chart-heat-5`, for a heatmap cell or a calendar
99
+ day, each with its own ink as `--cr-chart-on-heat-N`. A cell is a ground and not
100
+ a mark, because the value is written on it, so the floor that applies is the text
101
+ one, 4.5:1, and it applies to every step. The ink changes partway along the ramp
102
+ in some palettes, as a ramp spanning light to dark has to. The construction
103
+ guarantees that no step falls in the gap where neither of a mode's inks reaches
104
+ the floor. It is a search and not a constant because of Harbor: its body ink is a
105
+ soft grey rather than a near-black, and a ramp built for the other five would be
106
+ unreadable in Harbor.
107
+
108
+ Hue separation runs out at six, and a chart may have more series. **A seventh
109
+ series repeats the first colour and must differ by another channel**: a dash
110
+ pattern, a fill pattern, a marker shape. The rule applies at every count, not
111
+ only from the seventh series: colour is never the sole carrier of a series,
112
+ because six hues at sixty degrees do not survive dichromatic vision. Two of the
113
+ six also sit near the danger and success hues; they carry no such meaning, and a
114
+ chart that needs to say "bad" says it in words.
119
115
 
120
116
  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.
121
117
 
@@ -132,7 +128,7 @@ Use context-specific phrases rather than “red item” or “green action.” K
132
128
 
133
129
  ## Atmosphere and contrast
134
130
 
135
- Color atmosphere ranges from 15–90%, with a recommended default of 90%. This value controls a bounded decorative contribution to the opaque foundation; it is not whole-page opacity or text opacity. Frost base tint ranges from 35–85%, with a recommended default of 35%, with Frost receiving ten additional percentage points, capped at 94%. Resin is independent of that control and renders at a fixed 20% fill opacity. Stone, a separate 55% light / 60% dark fill with a 1.95px feather, protects Resin labels without turning the inner plane nearly opaque. Its safety depends on the supporting glass tint and optical sheen; test the full composite, not the veil alone. These are independent design choices, not copied vendor compositor constants.
131
+ Color atmosphere ranges from 15% to 90%, with a recommended default of 90%. This value controls a bounded decorative contribution to the opaque foundation; it is not whole-page opacity or text opacity. Frost base tint ranges from 35% to 85%, with a recommended default of 35%, with Frost receiving ten additional percentage points, capped at 94%. Resin is independent of that control and renders at a fixed 20% fill opacity. Stone, a separate 55% light / 60% dark fill with a 1.95px feather, protects Resin labels without turning the inner plane nearly opaque. Its safety depends on the supporting glass tint and optical sheen; test the full composite, not the veil alone. These are independent design choices, not copied vendor compositor constants.
136
132
 
137
133
  Contrast calculations use sRGB relative luminance. Normal text pairs target at least 4.5:1; essential non-text identification targets at least 3:1 where applicable. The live table checks defined solid pairs. Transparent composites require additional verification against supported backdrop extremes. A high body-text ratio does not certify all UI states.
138
134
 
@@ -153,11 +149,10 @@ Crystal ships six product palettes. Every one of them changes the primary, the c
153
149
  the decorative and the glow. None of them changes what success, warning, error or
154
150
  information look like.
155
151
 
156
- The reason is that a status colour is a *shared vocabulary*, not a brand expression. If
157
- error is red in one Meridian product and magenta in another because magenta suited the
158
- palette, then red stops meaning error and the user has to re-learn a safety signal per
159
- product. Brand identity is expressed in the primary; safety is not available for
160
- expression.
152
+ The reason is that a status colour is a shared vocabulary. If error is red in one
153
+ Meridian product and magenta in another because magenta suited the palette, then red
154
+ stops meaning error and the user has to re-learn a safety signal per product. Brand
155
+ identity is expressed in the primary, and status colours are not used to express it.
161
156
 
162
157
  <div class="feedback-grid">
163
158
  <span class="cr-status" data-status="success"><span aria-hidden="true"><svg aria-hidden="true" focusable="false" viewBox="0 0 24 24"><use href="../assets/icons.svg#check"/></svg></span>Ready</span>
@@ -167,11 +162,11 @@ expression.
167
162
  </div>
168
163
 
169
164
  These render identically under all six palettes. Switch palettes in the
170
- [Playground](../playground.html) and watch them not move.
165
+ [Playground](../playground.html) to see that they do not change.
171
166
 
172
- Status colours still respond to **mode** — a red that is legible on a light canvas is not
173
- the same red that is legible on a dark one — but the pair is derived from the status
174
- token, not from the active palette.
167
+ Status colours still respond to mode, because a red that is legible on a light canvas
168
+ is not the same red that is legible on a dark one. The pair is derived from the status
169
+ token and never from the active palette.
175
170
 
176
171
  Status is never the only signal. Each status carries an icon and a text message; see
177
172
  [colour is never the only signal](accessibility.html#colour-is-never-the-only-signal).
@@ -180,11 +175,10 @@ Status is never the only signal. Each status carries an icon and a text message;
180
175
 
181
176
  | Token | Re-pointable by a product palette? |
182
177
  | --- | --- |
183
- | `semantic.material.primary` and its companions | Yes — this is what a palette is |
178
+ | `semantic.material.primary` and its companions | Yes. This is what a palette is |
184
179
  | `primitive.palette.*` seeds | Yes, by adding a palette |
185
180
  | `semantic.feedback.*` | **No** |
186
- | `component.focus.*` | No — focus follows the primary automatically |
181
+ | `component.focus.*` | No. Focus follows the primary automatically |
187
182
 
188
- A product that needs a status colour changed does not have a theming problem; it has a
189
- semantics problem, and the answer is a new semantic token, not a redefinition of an
190
- existing one.
183
+ A product that needs a status colour changed has a semantics problem, which theming
184
+ does not solve. The answer is a new semantic token. An existing one is never redefined.