@crystal-ui/core 2.3.1 → 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 +783 -288
- 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/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
|
|
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
|
|
44
|
-
all three ship as `--cr-decorative`, `--cr-companion` and `--cr-glow`.
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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
|
-
|
|
51
|
-
fails the 4.5 floor with
|
|
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
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
-
|
|
60
|
-
`.secondary` button existed until 22 September 2026 and was withdrawn for
|
|
61
|
-
|
|
62
|
-
|
|
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
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
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
|
-
-
|
|
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
|
|
89
|
-
-
|
|
90
|
-
are adjacent to each other
|
|
91
|
-
-
|
|
92
|
-
|
|
93
|
-
-
|
|
94
|
-
|
|
95
|
-
mark the colour of every button on the page
|
|
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,
|
|
101
|
-
|
|
102
|
-
`--cr-chart-heat-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|
|
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
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
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)
|
|
165
|
+
[Playground](../playground.html) to see that they do not change.
|
|
171
166
|
|
|
172
|
-
Status colours still respond to
|
|
173
|
-
the same red that is legible on a dark one
|
|
174
|
-
token
|
|
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
|
|
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
|
|
181
|
+
| `component.focus.*` | No. Focus follows the primary automatically |
|
|
187
182
|
|
|
188
|
-
A product that needs a status colour changed
|
|
189
|
-
|
|
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.
|