@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,6 +1,6 @@
1
1
  {
2
- "$description": "Crystal's surface vocabulary: the closed set of material compositions a component may be made of, and the crystal.css recipe that implements each. Every catalogue entry names one or more of these in its `surface` field. tools/build-catalogue.cjs refuses an entry naming a surface not listed here, and refuses a surface whose `class` does not exist in core/assets/crystal.css — so a component cannot be specified in a material Crystal has not published a recipe for.",
3
- "$rule": "The vocabulary is small on purpose. A component that seems to need a new surface almost always needs one of these on a different element; a new entry here is a new material composition for every platform library, and is added with a recipe, a fallback for reduced transparency and forced colours, a contract row in docs/components.md and a changelog entry — never alone.",
2
+ "$description": "Crystal's surface vocabulary: the closed set of material compositions a component may be made of, and the crystal.css recipe that implements each. Every catalogue entry names one or more of these in its `surface` field. tools/build-catalogue.cjs refuses an entry naming a surface not listed here, and refuses a surface whose `class` does not exist in core/assets/crystal.css, so a component cannot be specified in a material Crystal has not published a recipe for.",
3
+ "$rule": "The vocabulary is kept small. A component that seems to need a new surface almost always needs one of these on a different element. A new entry here is a new material composition for every platform library, so it is added together with a recipe, a fallback for reduced transparency and forced colours, a contract row in docs/components.md and a changelog entry.",
4
4
  "surfaces": [
5
5
  {
6
6
  "id": "plastic",
@@ -14,7 +14,8 @@
14
14
  "name": "Frost panel",
15
15
  "materials": ["Frost"],
16
16
  "class": ".cr-frost",
17
- "use": "Intermediate task frames and every transient surface that opens over content: side panels, drawers, sheets, app bars, and — at Meridian's direction (R15e) — menus, popovers, tooltips and toasts. Reading content inside it sits on Haze."
17
+ "use": "Intermediate task frames and every transient surface that opens over content: side panels, drawers, sheets and app bars, and menus, popovers, tooltips and toasts (R15e). Reading content inside it sits on Haze. `.cr-frost.bar` is a transient overlay shaped as a row of controls, a pill with 4px padding: the selection toolbar over highlighted text.",
18
+ "also": [".cr-frost.bar"]
18
19
  },
19
20
  {
20
21
  "id": "haze",
@@ -29,7 +30,8 @@
29
30
  "name": "Resin plane",
30
31
  "materials": ["Resin"],
31
32
  "class": ".cr-resin",
32
- "use": "One floating Resin plane with no reading fill of its own, pill-shaped unless it is a panel: a player's transport bar, a pinned element, a Resin handle over imagery or between regions. Controls inside it lose their own backdrop filter — Resin never contains Resin. A plane whose controls are labels to be read holds a Haze fill as well, and is a dock."
33
+ "use": "One floating Resin plane with no reading fill of its own, pill-shaped unless it is a panel: a player's transport bar, a pinned element, a Resin handle over imagery or between regions. Controls inside it lose their own backdrop filter, because Resin never contains Resin. A plane whose controls are labels to be read holds a Haze fill as well, and is a dock. `.cr-resin.transport` is the media transport: the pill with 4px block and 12px inline padding around its 48px controls (58px tall with its rim), with tabular time readouts, wrapping to a second row in a player narrower than 420px. `.cr-media` is the stage it sits on (the content radius, the letterbox, `--cr-media-aspect` and `--cr-media-fit`), and `.cr-media-bar` is the region inset 12px, or the safe area in full screen, that holds the transport.",
34
+ "also": [".cr-resin.transport"]
33
35
  },
34
36
  {
35
37
  "id": "resin-panel",
@@ -44,14 +46,23 @@
44
46
  "materials": ["Resin", "Haze"],
45
47
  "class": ".cr-button",
46
48
  "also": [".cr-control", "button", "a.cr-button"],
47
- "use": "An action: a Resin shell with the 8px-inset Haze reading pad and the optical sheen. Pill geometry. `.primary` tints the pad, `.quiet` removes it, `.danger` adds the destructive boundary. Selected state is the primary pad plus label weight 800."
49
+ "use": "An action: a Resin shell with the 8px-inset Haze reading pad and the optical sheen. Pill geometry with `.cr-button`, which coats a `button` or an `a`; `.cr-control` coats any element. `.primary` tints the pad, `.quiet` removes it, `.danger` adds the destructive boundary. Selected state is the primary pad plus label weight 800.",
50
+ "partial": {
51
+ ".cr-button": "Element-keyed: `.cr-button` coats a `button` or an `a`. On any other element, wear `.cr-control`, which coats any element.",
52
+ ".cr-control": "Takes the radius of what it is: the pill comes with `.cr-button`, and a card-shaped control keeps the content radius of the surface it also wears.",
53
+ "button": "Takes the radius of what it is: the pill comes with `.cr-button`, and a card-shaped button keeps the content radius of the surface it also wears."
54
+ }
48
55
  },
49
56
  {
50
57
  "id": "field",
51
58
  "name": "Field shell",
52
59
  "materials": ["Resin", "Haze"],
53
60
  "class": ".cr-field-shell",
54
- "use": "The Resin surround of a native text entry, with the Haze well the value is read on and the circular field-state badge. The native control keeps its functional boundary and semantics."
61
+ "use": "The Resin surround of a native text entry, with the Haze well the value is read on and the circular field-state badge. The native control keeps its functional boundary and semantics. `.cr-editor` is the editable surface inside a rich text field: the shared prose vocabulary (headings, lists, checklists, marks, insertions and deletions) with the primary caret and a 28% primary selection, distinct from the primary-soft highlight (D-34). `.cr-editor-toolbar` is its toolbar, above the text on a fine pointer and below it, clear of the touch keyboard, on a coarse one.",
62
+ "also": [".cr-editor"],
63
+ "partial": {
64
+ ".cr-editor": "A part: the document inside the field shell, which carries the Resin surround and the Haze well."
65
+ }
55
66
  },
56
67
  {
57
68
  "id": "compact",
@@ -59,14 +70,22 @@
59
70
  "materials": ["Resin", "Haze"],
60
71
  "class": ".cr-resin-haze",
61
72
  "also": [".cr-tag", ".cr-resin-haze.count"],
62
- "use": "Small information displays that sit on content: tags, badges, labels, keyboard caps. A Resin shell with the inset Haze pad, 18px radius. Not for anything that opens — transient overlays are Frost. `.count` is the size for a count: a 20px circle that grows to a pill, filled to its own edge, with no block padding."
73
+ "use": "Small information displays that sit on content: tags, badges, labels, keyboard caps. A Resin shell with the inset Haze pad, 18px radius. Not for anything that opens. Transient overlays are Frost. `.count` is the size for a count: a 20px circle that grows to a pill, filled to its own edge, with no block padding.",
74
+ "partial": {
75
+ ".cr-tag": "The tag's geometry (the pill, the 48px floor, the type size), worn with `.cr-resin-haze`, which carries the coat."
76
+ }
63
77
  },
64
78
  {
65
79
  "id": "stone",
66
80
  "name": "Stone label backing",
67
81
  "materials": ["Stone"],
68
82
  "class": ".cr-stone",
69
- "use": "A label over an unknown or moving backdrop — a caption on media, a status bar over a scene. 55% light / 60% dark fill, feathered like Haze, crisp text."
83
+ "use": "A label over an unknown or moving backdrop: a caption on media, a status bar over a scene. 55% light / 60% dark fill, feathered like Haze, crisp text. `.cr-media-caption` is a caption cue rendered by the library: the Stone backing on a box above the transport, never under it. `::cue` on a `.cr-media` video is the flat fill for the browser's own renderer.",
84
+ "also": [".cr-media-caption"],
85
+ "partial": {
86
+ ".cr-stone": "Stone backs a label and takes the radius of the element it backs.",
87
+ ".cr-media-caption": "A part: the outer element positions the cue, and its inner box (`.cr-media-caption > *`) carries the Stone backing and the radius."
88
+ }
70
89
  },
71
90
  {
72
91
  "id": "mirage",
@@ -82,7 +101,10 @@
82
101
  "materials": ["Haze", "Mirage"],
83
102
  "class": ".cr-dialog",
84
103
  "use": "A Haze decision surface over a Mirage scrim, with the float shadow. Modality, focus and dismissal are the product's. The surface does not scroll: `.cr-dialog-body`, worn with `.cr-scroll-frost`, scrolls inside it, so the title stays in view and the edge fade does not dissolve the surface. `position: fixed` is for a native `<dialog>`; on any other element the host positions it.",
85
- "also": [".cr-dialog-body"]
104
+ "also": [".cr-dialog-body"],
105
+ "partial": {
106
+ ".cr-dialog-body": "A part: the scrolling body inside the dialog's Haze surface, which carries the material; the body adds the scroll contract."
107
+ }
86
108
  },
87
109
  {
88
110
  "id": "indicator",
@@ -111,15 +133,21 @@
111
133
  "materials": ["Resin", "Haze"],
112
134
  "class": ".cr-table-scroll",
113
135
  "also": [".cr-table"],
114
- "use": "A Resin shell with an inset Haze fill holding the table, with the primary-soft header and the Resin scrollbar. Rows are read on the Haze; sort and selection are announced, and selection is label weight."
136
+ "use": "A Resin shell with an inset Haze fill holding the table, with the primary-soft header and the Resin scrollbar. Rows are read on the Haze; sort and selection are announced, and selection is label weight.",
137
+ "partial": {
138
+ ".cr-table": "A part: the table inside `.cr-table-scroll`, which carries the Resin shell and the Haze fill; the table is transparent on it."
139
+ }
115
140
  },
116
141
  {
117
142
  "id": "dock",
118
143
  "name": "Dock",
119
- "materials": ["Resin", "Haze"],
144
+ "materials": ["Resin", "Haze", "Stone"],
120
145
  "class": ".cr-dock",
121
146
  "also": [".cr-dock-inner"],
122
- "use": "A Resin plane holding labelled controls on one Haze fill, so every label reads on the same protected ground: a dock of destinations, and the strips that group controls the same way — tab strips, segmented controls, toolbars, command and action bars. The controls inside are transparent; the current or selected one takes weight 800 and the primary fill, whether it is a dock's destination, a tab or a segment. The controls may be buttons, tabs (`[role=tab]`, selected by `aria-selected`), radio labels (selected by `:checked`) or links (current by `aria-current`); only buttons were reached before 2.3.0."
147
+ "use": "A Resin plane with a Haze perimeter, holding labelled controls on one Stone label backing (`.cr-dock-inner`), so every label reads on the same protected ground: a dock of destinations, and the strips that group controls the same way (tab strips, segmented controls, toolbars, command and action bars). The controls inside are transparent; the current or selected one takes weight 800 and the primary fill, whether it is a dock's destination, a tab or a segment. The controls may be buttons, tabs (`[role=tab]`, selected by `aria-selected`), radio labels (selected by `:checked`) or links (current by `aria-current`); only buttons were reached before 2.3.0.",
148
+ "partial": {
149
+ ".cr-dock-inner": "The Stone label backing inside the dock. The dock carries the Resin blur, and Resin never contains Resin, so the inner fill has none."
150
+ }
123
151
  },
124
152
  {
125
153
  "id": "group",
@@ -132,16 +160,16 @@
132
160
  {
133
161
  "id": "nav-item",
134
162
  "name": "Navigation entry",
135
- "materials": ["Plastic"],
163
+ "materials": [],
136
164
  "class": ".cr-nav-item",
137
- "use": "An entry in side navigation, a rail or a tree of destinations. It has no material of its own — it is furniture on the panel beneath it — and carries selection by label weight alone. Pill hit area, 44px target. `.stacked` puts the icon above the label for a rail. Adopted from the documentation site's side menu, which docs/components.md names as the reference implementation of selection."
165
+ "use": "An entry in side navigation, a rail or a tree of destinations. It has no material of its own, sits on the panel beneath it, and carries selection by label weight alone. Pill hit area, 44px target. `.stacked` puts the icon above the label for a rail. Adopted from the documentation site's side menu, which docs/components.md names as the reference implementation of selection."
138
166
  },
139
167
  {
140
168
  "id": "bare",
141
169
  "name": "Bare control",
142
170
  "materials": [],
143
171
  "class": ".cr-bare",
144
- "use": "A control that must not wear the Resin coat because it sits inside a surface that already has one: a disclosure chevron, a chip's remove button, a sort header, a stepper's arrows, a dismiss button on a toast. Crystal paints every button by element, so bare means subtracting the fill, the shadow, the backdrop filter and both pseudo-layers — this class does all four. The focus ring and the target floor stay."
172
+ "use": "A control that must not wear the Resin coat because it sits inside a surface that already has one: a disclosure chevron, a chip's remove button, a sort header, a stepper's arrows, a dismiss button on a toast. Crystal paints every button by element, so this class subtracts the fill, the shadow, the backdrop filter and both pseudo-layers. The focus ring and the target floor stay."
145
173
  },
146
174
  {
147
175
  "id": "drag-handle",
@@ -156,7 +184,10 @@
156
184
  "materials": ["Resin"],
157
185
  "class": "input:is([type=checkbox],[type=radio])",
158
186
  "also": ["input[type=checkbox][role=switch]", "input[type=range]"],
159
- "use": "Native checkbox, radio, switch and range, styled by element: a Resin box, circle or track with a contained mark, and the marked glass thumb. Semantics stay native."
187
+ "use": "Native checkbox, radio, switch and range, styled by element: a Resin box, circle or track with a contained mark, and the marked glass thumb. Semantics stay native.",
188
+ "partial": {
189
+ "input[type=range]": "A track and a thumb, painted on the slider's pseudo-elements (`::-webkit-slider-runnable-track`, `::-webkit-slider-thumb` and their `::-moz-range-` forms), which this record does not read."
190
+ }
160
191
  },
161
192
  {
162
193
  "id": "native",
@@ -171,7 +202,7 @@
171
202
  "name": "No surface of its own",
172
203
  "materials": [],
173
204
  "class": null,
174
- "use": "Layout, typography, behaviour and drawing components that inherit whatever they sit on. A chart's marks, a divider, a provider. Nothing to paint and nothing to wear."
205
+ "use": "Layout, typography, behaviour and drawing components that inherit whatever they sit on. A chart's marks, a divider, a provider."
175
206
  }
176
207
  ]
177
208
  }