@crystal-ui/core 2.0.0 → 2.2.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 (38) hide show
  1. package/assets/crystal-theme.css +126 -3
  2. package/assets/crystal.css +1192 -5
  3. package/assets/crystal.js +106 -11
  4. package/assets/motion.js +17 -2
  5. package/assets/tokens.js +1 -1
  6. package/docs/accessibility.md +9 -2
  7. package/docs/adoption.md +29 -48
  8. package/docs/catalogue.md +465 -33
  9. package/docs/colors.md +84 -0
  10. package/docs/components.md +55 -25
  11. package/docs/materials.md +12 -4
  12. package/docs/motion-components.md +16 -12
  13. package/docs/motion.md +12 -2
  14. package/docs/tokens.md +31 -3
  15. package/engines.js +13 -2
  16. package/exports/crystal-tokens.kt +19 -1
  17. package/exports/crystal-tokens.swift +19 -1
  18. package/exports/crystal-tokens.ts +19 -1
  19. package/package.json +2 -1
  20. package/tokens/catalogue/01-layout.json +45 -0
  21. package/tokens/catalogue/02-navigation.json +89 -2
  22. package/tokens/catalogue/03-actions.json +42 -1
  23. package/tokens/catalogue/04-inputs.json +366 -5
  24. package/tokens/catalogue/05-data-display.json +187 -1
  25. package/tokens/catalogue/06-feedback.json +78 -6
  26. package/tokens/catalogue/07-overlays.json +50 -3
  27. package/tokens/catalogue/08-typography.json +54 -0
  28. package/tokens/catalogue/09-utility.json +79 -0
  29. package/tokens/catalogue/10-charts.json +89 -1
  30. package/tokens/catalogue/11-media.json +33 -0
  31. package/tokens/catalogue/12-commerce.json +134 -1
  32. package/tokens/catalogue/13-screens.json +81 -0
  33. package/tokens/catalogue/14-blocks.json +101 -0
  34. package/tokens/catalogue.json +1652 -21
  35. package/tokens/crystal.json +253 -13
  36. package/tokens/crystal.tokens.json +98 -2
  37. package/tokens/motion-recipes.json +216 -0
  38. package/tokens/surfaces.json +167 -0
package/assets/crystal.js CHANGED
@@ -15,7 +15,12 @@
15
15
  const data=root.CRYSTAL_TOKENS
16
16
  || (typeof module!=='undefined'&&module.exports?require('../tokens/crystal.json'):null);
17
17
  if(!data) throw new Error('Load tokens.js before crystal.js');
18
- const camelToKebab=s=>s.replace(/[A-Z]/g,m=>'-'+m.toLowerCase());
18
+ /* `chartSeries1` is `--cr-chart-series-1`, not `--cr-chart-series1`. The digit
19
+ boundary is a word boundary here because Crystal already writes its numbered
20
+ properties that way — `--cr-focus-feather-1` predates this — and a scale a
21
+ stylesheet indexes with `var(--cr-chart-series-#{$i})` reads as one. No role
22
+ name carried a digit before the series scale, so nothing renamed. */
23
+ const camelToKebab=s=>s.replace(/[A-Z]/g,m=>'-'+m.toLowerCase()).replace(/([a-z])(\d)/g,'$1-$2');
19
24
  const rgb=hex=>[1,3,5].map(i=>parseInt(hex.slice(i,i+2),16));
20
25
  const rgba=(hex,alpha)=>`rgba(${rgb(hex).join(', ')}, ${Number(alpha.toFixed(3))})`;
21
26
  function luminance(hex){const c=rgb(hex).map(v=>v/255).map(v=>v<=.04045?v/12.92:((v+.055)/1.055)**2.4);return c[0]*.2126+c[1]*.7152+c[2]*.0722;}
@@ -76,6 +81,33 @@
76
81
  exactly what Crystal React did on sixteen surfaces. A recipe that only
77
82
  one renderer knows is not a specification. */
78
83
  '--cr-haze-inset':data.component.haze.inset+'px',
84
+ /* Control geometry that `crystal.css` used to carry as literals — 26px
85
+ boxes, a 44×28 track, .55 for a disabled control — while the same
86
+ numbers were published as tokens a platform library reads. Two
87
+ statements of one value is the drift CONTRACT §1 forbids, so the
88
+ stylesheet now reads these and the literal is the fallback only. */
89
+ '--cr-action-disabled-opacity':String(data.component.action.disabledOpacity),
90
+ '--cr-choice-box-size':data.component.choice.boxSize+'px',
91
+ '--cr-choice-box-radius':data.component.choice.boxRadius+'px',
92
+ '--cr-switch-track-width':data.component.switch.trackWidth+'px',
93
+ '--cr-switch-track-height':data.component.switch.trackHeight+'px',
94
+ /* Chart geometry. A chart's colours vary with the palette and arrive with
95
+ the other roles above; these do not vary at all. They are published
96
+ rather than left to each renderer because the catalogue says "line
97
+ weight follows the stroke scale" and "point size is a scale, not an
98
+ arbitrary radius" as though both scales existed, and until now neither
99
+ did — which is how two renderers end up with two of them. */
100
+ '--cr-chart-stroke':data.component.chart.stroke+'px',
101
+ '--cr-chart-hairline':data.component.chart.hairline+'px',
102
+ '--cr-chart-point-min':data.component.chart.pointMin+'px',
103
+ '--cr-chart-point-max':data.component.chart.pointMax+'px',
104
+ '--cr-chart-bar-radius':data.component.chart.barRadius+'px',
105
+ '--cr-chart-cell-gap':data.component.chart.cellGap+'px',
106
+ '--cr-chart-ring-thickness':String(data.component.chart.ringThickness),
107
+ '--cr-chart-fill-opacity':String(data.component.chart.fillOpacity),
108
+ '--cr-chart-link-opacity':String(data.component.chart.linkOpacity),
109
+ '--cr-chart-gauge-sweep':data.component.chart.gaugeSweep+'deg',
110
+ '--cr-progress-ring-stroke':data.component.progress.ringStroke+'px',
79
111
  '--cr-content-muted':s.palette==='harbor'?p.text:p.muted,
80
112
  '--cr-content-own-text':s.palette==='harbor'?p.text:p.onPrimarySoft,
81
113
  '--cr-stone-feather':s.reduced?'0px':data.material.stoneFeather+'px',
@@ -113,19 +145,82 @@
113
145
  nothing, and those two inset shadows have never painted. A value two
114
146
  components depend on belongs to the system. */
115
147
  '--cr-control-edge':rgba(p.outline,0.18),
148
+ /* The two tints the Resin control sheen is built from, and the same story
149
+ as `--cr-control-edge` above: they lived only in the preview's
150
+ `controls.css`, so the optical sheen on every Crystal control was a
151
+ thing the library described and did not ship. Adopted 21 September 2026
152
+ with the rest of D-11.
153
+
154
+ `--cr-control-color` is the decorative tint that gives the control its
155
+ body; `--cr-control-light` is the glow that lights its top-left corner.
156
+ Both go *down* in dark mode rather than up — the opposite of the focus
157
+ feathers, and deliberately: on a deep canvas the sheen is already
158
+ reading against very little, and holding it at the light-mode strength
159
+ makes a control look lit from inside rather than lit from above. */
160
+ /* `color-mix` rather than a resolved `rgba`, and it is the one place in
161
+ this theme that departs from the convention. Two reasons, both checked
162
+ rather than assumed. A resolved `rgba` alpha is quantised to 8 bits by
163
+ the time a browser serialises it — 0.126 comes back as 0.125 — and an
164
+ A/B of the site against this library put a worst channel delta of 2 on
165
+ the playground's controls purely from that. And a mix keeps the tint
166
+ tracking `--cr-glow` and `--cr-decorative`, so a product that retints
167
+ either gets a sheen that follows; a resolved value silently would not.
168
+ The preview has always written these as mixes, so this is also what
169
+ makes the adoption exact. */
170
+ '--cr-control-color':`color-mix(in srgb,var(--cr-decorative) ${dark?7:8.4}%,transparent)`,
171
+ '--cr-control-light':`color-mix(in srgb,var(--cr-glow) ${dark?9.8:12.6}%,transparent)`,
116
172
  '--cr-focus-core':p.primary,
117
173
  '--cr-focus-core-width':'2px',
118
174
  '--cr-focus-core-offset':'3px',
119
- /* Spreads 1/3/6/11, not 2/6/12/22. The halo was halved at Meridian's
120
- request and the change was made in the preview's own stylesheet, which
121
- overrides this one — so Crystal's site rendered the halved halo, the
122
- specification was generated from that stylesheet and documented the
123
- halved halo, and the library went on shipping the withdrawn one to
124
- every consumer that reads the theme. Crystal React's focus ring was
125
- visibly wider than Crystal's for as long as that was true. The blur
126
- radii and alphas were always identical; only the spread was behind. */
127
- '--cr-focus-ring':[[6,1,46],[16,3,30],[30,6,17],[54,11,8]]
128
- .map(([blur,spread,pct])=>`0 0 ${blur}px ${spread}px ${rgba(p.primary,pct/100)}`).join(','),
175
+ /* The four feather colours, published rather than inlined.
176
+
177
+ They were the preview's own — `--cr-focus-feather-1` … `-4` in
178
+ `controls.css` — and the library had no equivalent, because it baked its
179
+ alphas straight into `--cr-focus-ring`. That is precisely why the
180
+ dark-mode divergence could hide for so long: there was no property to
181
+ compare, so no gate could have been written that would have caught it.
182
+ Naming them is half of D-11's fix; the other half is that a product can
183
+ now retint the falloff without restating the whole recipe.
184
+
185
+ **Dark mode lifts them**, 56/38/22/11 against light's 46/30/17/8. The
186
+ preview has carried the lift since the halo was specified and the
187
+ library never did, so Crystal's site held its falloff against a deep
188
+ canvas and every consumer's went thin. Meridian decided on 21 September
189
+ 2026 that the library carries it. */
190
+ ...Object.fromEntries((dark?[56,38,22,11]:[46,30,17,8])
191
+ .map((pct,i)=>[`--cr-focus-feather-${i+1}`,rgba(p.primary,pct/100)])),
192
+ /* The broad layer's colour, and the one part of focus that is not the
193
+ primary: it is `--cr-decorative`, so the lift under a focused control
194
+ carries the palette's own shadow hue rather than tinting everything
195
+ purple. Also the preview's, also never exported. */
196
+ '--cr-focus-shadow':rgba(p.decorative,0.27),
197
+ /* Six layers: the four-layer halo, then two that lift.
198
+
199
+ Spreads 1/3/6/11, not 2/6/12/22 — the halo was halved at Meridian's
200
+ request, the change was made in the preview's stylesheet, and the
201
+ library went on shipping the withdrawn one to every consumer. That much
202
+ was fixed on 20 September.
203
+
204
+ What was still missing is the pair beneath: `0 8px 18px` directional and
205
+ `0 22px 40px` broad. A focused control on Crystal's site lifts, and in
206
+ every consumer it did not — not a spread this time but two whole layers,
207
+ and `components.md` had described lifting on focus as Crystal's own
208
+ behaviour throughout. Meridian decided on 21 September that the library
209
+ carries them, so this is now the whole recipe and the preview's copy is
210
+ redundant rather than authoritative.
211
+
212
+ Written as `var()` references to the properties above, which is the
213
+ shape the preview used. It keeps the recipe readable at the point of
214
+ use and it is what lets the two be compared layer by layer. */
215
+ '--cr-focus-ring':[
216
+ ...[[6,1,1],[16,3,2],[30,6,3],[54,11,4]]
217
+ .map(([blur,spread,n])=>`0 0 ${blur}px ${spread}px var(--cr-focus-feather-${n})`),
218
+ /* The directional layer borrows the second feather rather than naming a
219
+ fifth colour — the preview's choice, kept, because a lift that is a
220
+ shade of the halo above it reads as the same light source. */
221
+ '0 8px 18px var(--cr-focus-feather-2)',
222
+ '0 22px 40px var(--cr-focus-shadow)',
223
+ ].join(','),
129
224
  /* The spacing scale and the shell's geometry. Neither varies with palette,
130
225
  mode or density; they are published as custom properties so a product
131
226
  writing plain CSS reaches the same values the libraries compile against.
package/assets/motion.js CHANGED
@@ -1,4 +1,6 @@
1
- /* Crystal material choreography. All effects are finite and cancellable. */
1
+ /* Crystal material choreography. Every effect is cancellable, and every effect is finite
2
+ except a continuous indicator — activity-turn, activity-travel, skeleton-sweep — which
3
+ repeats while its work is pending and is stopped by the caller when the work resolves. */
2
4
  (function(root){
3
5
  'use strict';
4
6
  const media=matchMedia('(prefers-reduced-motion: reduce)'),active=new Map();
@@ -53,8 +55,21 @@
53
55
  element.dataset.crMotionSignature=recipe.signature||'measured-layout';
54
56
  if(reduced()){element.dataset.crMotionState='instant';return Promise.resolve({status:'instant'});}
55
57
  const opts={duration:duration(base,options.rate),engine,easing:recipe.signature==='inertia'?'cubic-bezier(0.16, 0.7, 0.2, 1)':recipe.signature==='coalesce'?'cubic-bezier(0.34, 0.08, 0.24, 1)':'cubic-bezier(0.22, 0.65, 0.22, 1)'};
58
+ /* A continuous recipe travels at constant speed and repeats until stop() — the
59
+ returned promise settles only when it is cancelled, which is the caller's to do
60
+ the moment the pending work resolves. */
61
+ if(recipe.loop){opts.easing=recipe.easing||'linear';opts.repeat=Infinity;}
62
+ /* A staggered mark waits its turn: `index` is its position and `count` how many
63
+ marks arrive together. Past the recipe's ceiling every mark arrives at once, so
64
+ a stagger never needs a count nobody can see; without a count there is no
65
+ stagger, because a mark cannot know it is the last. */
66
+ if(recipe.stagger&&Number.isInteger(options.index)&&Number.isInteger(options.count)&&options.count<=recipe.stagger.maxMarks)
67
+ opts.delay=duration(options.index*recipe.stagger.step,options.rate);
56
68
  const animations=[CrystalEngines.frames(element,frames,opts)];
57
- opticalLayers(element,recipe,opts,animations);
69
+ /* The optical layers are finite decoration on a transition. On a loop they would
70
+ repeat with it, and a feathered edge that ripples for as long as something is
71
+ loading is ambient motion by another route. */
72
+ if(!recipe.loop)opticalLayers(element,recipe,opts,animations);
58
73
  active.set(element,animations);element.dataset.crMotionState='running';
59
74
  return Promise.all(animations.map(animation=>animation.finished.then(()=>true,error=>{if(error.name!=='AbortError')throw error;return false;}))).then(results=>{
60
75
  const status=results.every(Boolean)?'finished':'cancelled';
package/assets/tokens.js CHANGED
@@ -1 +1 @@
1
- window.CRYSTAL_TOKENS = {"version":"2.0.0","name":"Crystal","basis":"crystal-03-balanced; Meridian Digital design system","default":{"palette":"prism","mode":"light","atmosphere":90,"translucency":35,"elevation":125,"radius":28,"density":"comfortable","reduced":false,"font":"manrope","reduceMotion":false,"motionSpeed":1},"palettes":{"prism":{"name":"Prism","description":"Electric violet, orchid light. The shared signature.","seed":"#7338EF","companion":"#EF48C6","glow":"#52BDF3","modes":{"light":{"canvas":"#f9f6fe","surface":"#ffffff","surfaceAlt":"#f2edfe","text":"#171130","muted":"#402e76","primary":"#7338EF","onPrimary":"#ffffff","primarySoft":"#e6dbfc","onPrimarySoft":"#2b195a","outline":"#624a9f","decorative":"#7338EF","companion":"#EF48C6","glow":"#52BDF3"},"dark":{"canvas":"#120d26","surface":"#1d1730","surfaceAlt":"#332756","text":"#f7f3fe","muted":"#dbcbfb","primary":"#c8b1f9","onPrimary":"#16102e","primarySoft":"#331e65","onPrimarySoft":"#ebe3fd","outline":"#bfa3f8","decorative":"#7e48f0","companion":"#EF48C6","glow":"#52BDF3"}}},"fuchsia":{"name":"Fuchsia","description":"Confident magenta for creative products.","seed":"#C01993","companion":"#7C4DFF","glow":"#FF96DA","modes":{"light":{"canvas":"#fcf5fa","surface":"#ffffff","surfaceAlt":"#f9eaf5","text":"#210d25","muted":"#5b2356","primary":"#C01993","onPrimary":"#ffffff","primarySoft":"#f4d6ec","onPrimarySoft":"#440f3d","outline":"#813e7a","decorative":"#C01993","companion":"#7C4DFF","glow":"#FF96DA"},"dark":{"canvas":"#190a1e","surface":"#241427","surfaceAlt":"#422144","text":"#fbf1f9","muted":"#efc3e3","primary":"#e6a5d5","onPrimary":"#1f0d23","primarySoft":"#4e1344","onPrimarySoft":"#f6dff0","outline":"#e295cd","decorative":"#c52b9c","companion":"#7C4DFF","glow":"#FF96DA"}}},"cobalt":{"name":"Cobalt","description":"Clear blue with a violet undertone.","seed":"#2758E8","companion":"#6D47F2","glow":"#48C6F0","modes":{"light":{"canvas":"#f5f7fe","surface":"#ffffff","surfaceAlt":"#ecf0fd","text":"#0d1530","muted":"#263974","primary":"#2758E8","onPrimary":"#ffffff","primarySoft":"#d8e1fb","onPrimarySoft":"#132458","outline":"#44579c","decorative":"#2758E8","companion":"#6D47F2","glow":"#48C6F0"},"dark":{"canvas":"#0b1025","surface":"#151a30","surfaceAlt":"#252d55","text":"#f2f5fe","muted":"#c7d4f9","primary":"#abbef6","onPrimary":"#0d142d","primarySoft":"#182962","onPrimarySoft":"#e1e8fc","outline":"#9cb2f4","decorative":"#3865ea","companion":"#6D47F2","glow":"#48C6F0"}}},"ion":{"name":"Ion","description":"Vivid cyan and indigo for focused tools.","seed":"#007E97","companion":"#3D45E5","glow":"#36DCD1","modes":{"light":{"canvas":"#f4f9fa","surface":"#ffffff","surfaceAlt":"#e8f3f6","text":"#081a25","muted":"#184757","primary":"#007E97","onPrimary":"#ffffff","primarySoft":"#d1e8ec","onPrimarySoft":"#06303e","outline":"#34667c","decorative":"#007E97","companion":"#3D45E5","glow":"#36DCD1"},"dark":{"canvas":"#07141e","surface":"#111e27","surfaceAlt":"#1d3445","text":"#f0f7f9","muted":"#bddde4","primary":"#9ccdd6","onPrimary":"#081924","primarySoft":"#0a3646","onPrimarySoft":"#dbedf0","outline":"#8ac4cf","decorative":"#14889f","companion":"#3D45E5","glow":"#36DCD1"}}},"amethyst":{"name":"Amethyst","description":"Rich purple with a warm luminous edge.","seed":"#8430C6","companion":"#CE49B2","glow":"#9198FF","modes":{"light":{"canvas":"#f9f6fc","surface":"#ffffff","surfaceAlt":"#f4ecfa","text":"#19102b","muted":"#462b68","primary":"#8430C6","onPrimary":"#ffffff","primarySoft":"#e9daf5","onPrimarySoft":"#30174d","outline":"#69478f","decorative":"#8430C6","companion":"#CE49B2","glow":"#9198FF"},"dark":{"canvas":"#130d22","surface":"#1e162c","surfaceAlt":"#36254e","text":"#f8f3fc","muted":"#dfc9f0","primary":"#cfaee9","onPrimary":"#180f29","primarySoft":"#391b56","onPrimarySoft":"#eee2f7","outline":"#c6a0e5","decorative":"#8e41cb","companion":"#CE49B2","glow":"#9198FF"}}},"harbor":{"name":"Harbor","description":"The original palette, mapped to shared roles.","seed":"#4669B2","companion":"#8970B5","glow":"#72C4DF","modes":{"light":{"canvas":"#faf8fe","surface":"#ffffff","surfaceAlt":"#e7e7f1","text":"#30323a","muted":"#5c5f68","primary":"#4b5e8b","onPrimary":"#f9f8ff","primarySoft":"#b8cbff","onPrimarySoft":"#2f436e","outline":"#787a84","decorative":"#4669B2","companion":"#8970B5","glow":"#72C4DF"},"dark":{"canvas":"#0d0e12","surface":"#111318","surfaceAlt":"#1d1f26","text":"#e4e5f0","muted":"#a9aab5","primary":"#b8c6ee","onPrimary":"#314060","primarySoft":"#445274","onPrimarySoft":"#dae3ff","outline":"#73757f","decorative":"#4669B2","companion":"#8970B5","glow":"#72C4DF","contentOwnSurface":"#283c60"}}}},"status":{"light":{"success":{"ink":"#175D38","surface":"#E5F4EA","symbol":"\u2713","label":"Ready"},"attention":{"ink":"#714B00","surface":"#FFF0CD","symbol":"\u25b3","label":"Review needed"},"danger":{"ink":"#941D36","surface":"#FFE8EC","symbol":"!","label":"Action blocked"},"info":{"ink":"#334155","surface":"#E8EDF4","symbol":"i","label":"Information"}},"dark":{"success":{"ink":"#9BE2B3","surface":"#173525","symbol":"\u2713","label":"Ready"},"attention":{"ink":"#FFDA8A","surface":"#3D2D0E","symbol":"\u25b3","label":"Review needed"},"danger":{"ink":"#FFB2C0","surface":"#481C29","symbol":"!","label":"Action blocked"},"info":{"ink":"#D2DCEC","surface":"#263244","symbol":"i","label":"Information"}}},"material":{"acrylicBlur":40,"acrylicSaturation":125,"glassBlur":20,"glassSaturation":165,"glassOpacity":0.2,"grainOpacity":0.045,"labelVeil":0.55,"labelVeilDark":0.6,"contentOpacity":0.8,"contentFeather":1.95,"stoneFeather":1.95,"mirageColor":"#111525","mirageOpacity":0.38,"mirageBlur":28,"mirageSaturation":165,"mirageBrightness":88,"mirageFallbackOpacity":0.64,"micaInactive":{"light":"#f1f1f3","dark":"#202126"}},"motion":{"press":120,"state":213.33,"spatial":293.33,"exit":160,"easing":{"enter":"cubic-bezier(0.22, 0.65, 0.22, 1)","settle":"cubic-bezier(0.2, 0, 0.2, 1)","exit":"cubic-bezier(0.4, 0, 0.6, 1)"},"distance":{"panel":24,"floating":30,"content":0,"exit":20,"depth":50,"feather":6},"material":1000,"liquid":1400,"flow":1200,"departure":650,"maxDuration":5000,"maxTravel":50,"travelPolicy":{"ordinaryRange":[5,30],"compactGuideline":50,"extended":"Documented large compositions and measured layout may exceed 50px.","stationaryMaterials":["haze","stone"]}},"typography":{"readingSize":16,"readingLeading":24,"family":"Manrope","scale":{"display":{"ratio":2,"leading":1.1,"tracking":"-0.055em"},"title":{"ratio":1.5,"leading":1.2,"tracking":"-0.04em"},"heading":{"ratio":1.25,"leading":1.3,"tracking":"-0.03em"},"subheading":{"ratio":1.0625,"leading":1.45,"tracking":"-0.01em"},"body":{"ratio":1,"leading":1.5,"tracking":"0"},"caption":{"ratio":0.8125,"leading":1.45,"tracking":"0"}}},"component":{"action":{"radius":999,"minTarget":44,"paddingBlock":15,"paddingInline":24,"gap":9,"disabledOpacity":0.55},"scrollbar":{"width":10,"thumbMinLength":32,"inset":2},"scrollArea":{"fadeDepth":24},"layout":{"containerMax":1536,"readingMax":920,"gutterCompact":18,"gutterBase":26,"gutterWide":44,"minCellWidth":240,"sidebarWidth":280},"icon":{"size":20,"action":24},"choice":{"boxSize":26,"boxRadius":9},"switch":{"trackWidth":44,"trackHeight":28},"slider":{"trackHeight":8,"thumbSize":26},"chip":{"height":32},"overlayArrow":{"size":14,"radius":3},"overlay":{"maxWidth":480,"tooltipMaxWidth":352},"field":{"wellInset":7},"card":{"radius":28},"focus":{"coreWidth":2,"coreOffset":3},"indicator":{"size":20,"fieldSize":24,"lineWidth":3},"anchor":{"underlineOffset":4},"tree":{"indentStep":20},"haze":{"inset":8}},"spacing":{"2xs":4,"xs":8,"sm":12,"md":16,"lg":24,"xl":32,"2xl":48},"schemaNote":"Generated from core/tokens/crystal.tokens.json (W3C DTCG). Edit the DTCG source, not this file.","materials":{"plastic":{"name":"Plastic","role":"Opaque contextual foundation","inspiration":"Microsoft Mica","primitive":".cr-plastic"},"frost":{"name":"Frost","role":"Diffused intermediate surface","inspiration":"Microsoft Acrylic","primitive":".cr-frost"},"resin":{"name":"Resin","role":"Floating optical control surface","inspiration":"Apple Liquid Glass","primitive":".cr-resin"},"haze":{"name":"Haze","role":"Soft content fill","inspiration":"Crystal solid content recipe","primitive":".cr-haze"},"stone":{"name":"Stone","role":"Protected label backing","inspiration":"Crystal protected-label veil","primitive":".cr-stone"},"mirage":{"name":"Mirage","role":"Chromatic diffusion and dark modal separation","inspiration":"Modal smoke/scrim pattern","primitive":".cr-mirage and dialog::backdrop"}}};
1
+ window.CRYSTAL_TOKENS = {"version":"2.0.0","name":"Crystal","basis":"crystal-03-balanced; Meridian Digital design system","default":{"palette":"prism","mode":"light","atmosphere":90,"translucency":35,"elevation":125,"radius":28,"density":"comfortable","reduced":false,"font":"manrope","reduceMotion":false,"motionSpeed":1},"palettes":{"prism":{"name":"Prism","description":"Electric violet, orchid light. The shared signature.","seed":"#7338EF","companion":"#EF48C6","glow":"#52BDF3","modes":{"light":{"canvas":"#f9f6fe","surface":"#ffffff","surfaceAlt":"#f2edfe","text":"#171130","muted":"#402e76","primary":"#7338EF","onPrimary":"#ffffff","primarySoft":"#e6dbfc","onPrimarySoft":"#2b195a","outline":"#624a9f","decorative":"#7338EF","companion":"#EF48C6","glow":"#52BDF3","chartSeries1":"#9D45B2","chartSeries2":"#C43444","chartSeries3":"#956800","chartSeries4":"#298800","chartSeries5":"#008287","chartSeries6":"#286CD8","chartHeat1":"#EFEEFD","chartOnHeat1":"#171130","chartHeat2":"#D6D3F9","chartOnHeat2":"#171130","chartHeat3":"#BEB7F4","chartOnHeat3":"#171130","chartHeat4":"#A79CEE","chartOnHeat4":"#171130","chartHeat5":"#9280E7","chartOnHeat5":"#171130","chartAxis":"#624a9f","chartGrid":"rgba(23, 17, 48, 0.12)"},"dark":{"canvas":"#120d26","surface":"#1d1730","surfaceAlt":"#332756","text":"#f7f3fe","muted":"#dbcbfb","primary":"#c8b1f9","onPrimary":"#16102e","primarySoft":"#331e65","onPrimarySoft":"#ebe3fd","outline":"#bfa3f8","decorative":"#7e48f0","companion":"#EF48C6","glow":"#52BDF3","chartSeries1":"#D57BEA","chartSeries2":"#FF7077","chartSeries3":"#D59800","chartSeries4":"#60BE48","chartSeries5":"#00BBC2","chartSeries6":"#6CA4FF","chartHeat1":"#1B1929","chartOnHeat1":"#f7f3fe","chartHeat2":"#292443","chartOnHeat2":"#f7f3fe","chartHeat3":"#372E60","chartOnHeat3":"#f7f3fe","chartHeat4":"#46387D","chartOnHeat4":"#f7f3fe","chartHeat5":"#56429C","chartOnHeat5":"#f7f3fe","chartAxis":"#bfa3f8","chartGrid":"rgba(247, 243, 254, 0.16)"}}},"fuchsia":{"name":"Fuchsia","description":"Confident magenta for creative products.","seed":"#C01993","companion":"#7C4DFF","glow":"#FF96DA","modes":{"light":{"canvas":"#fcf5fa","surface":"#ffffff","surfaceAlt":"#f9eaf5","text":"#210d25","muted":"#5b2356","primary":"#C01993","onPrimary":"#ffffff","primarySoft":"#f4d6ec","onPrimarySoft":"#440f3d","outline":"#813e7a","decorative":"#C01993","companion":"#7C4DFF","glow":"#FF96DA","chartSeries1":"#C33353","chartSeries2":"#9B6400","chartSeries3":"#4B8300","chartSeries4":"#008380","chartSeries5":"#0071D0","chartSeries6":"#9549BB","chartHeat1":"#FAEBF4","chartOnHeat1":"#210d25","chartHeat2":"#F2CBE1","chartOnHeat2":"#210d25","chartHeat3":"#E8ABCF","chartOnHeat3":"#210d25","chartHeat4":"#DC8ABD","chartOnHeat4":"#210d25","chartHeat5":"#CF69AB","chartOnHeat5":"#210d25","chartAxis":"#813e7a","chartGrid":"rgba(33, 13, 37, 0.12)"},"dark":{"canvas":"#190a1e","surface":"#241427","surfaceAlt":"#422144","text":"#fbf1f9","muted":"#efc3e3","primary":"#e6a5d5","onPrimary":"#1f0d23","primarySoft":"#4e1344","onPrimarySoft":"#f6dff0","outline":"#e295cd","decorative":"#c52b9c","companion":"#7C4DFF","glow":"#FF96DA","chartSeries1":"#FF6D85","chartSeries2":"#DE9200","chartSeries3":"#76BB32","chartSeries4":"#00BCB9","chartSeries5":"#5AA8FF","chartSeries6":"#CB7EF4","chartHeat1":"#26161F","chartOnHeat1":"#fbf1f9","chartHeat2":"#3C1D31","chartOnHeat2":"#fbf1f9","chartHeat3":"#542343","chartOnHeat3":"#fbf1f9","chartHeat4":"#6D2856","chartOnHeat4":"#fbf1f9","chartHeat5":"#862D6A","chartOnHeat5":"#fbf1f9","chartAxis":"#e295cd","chartGrid":"rgba(251, 241, 249, 0.16)"}}},"cobalt":{"name":"Cobalt","description":"Clear blue with a violet undertone.","seed":"#2758E8","companion":"#6D47F2","glow":"#48C6F0","modes":{"light":{"canvas":"#f5f7fe","surface":"#ffffff","surfaceAlt":"#ecf0fd","text":"#0d1530","muted":"#263974","primary":"#2758E8","onPrimary":"#ffffff","primarySoft":"#d8e1fb","onPrimarySoft":"#132458","outline":"#44579c","decorative":"#2758E8","companion":"#6D47F2","glow":"#48C6F0","chartSeries1":"#7C54CD","chartSeries2":"#BC3577","chartSeries3":"#AD5700","chartSeries4":"#707900","chartSeries5":"#00856E","chartSeries6":"#007BAC","chartHeat1":"#EAF0FE","chartOnHeat1":"#0d1530","chartHeat2":"#C7D8FC","chartOnHeat2":"#0d1530","chartHeat3":"#A5C0F8","chartOnHeat3":"#0d1530","chartHeat4":"#84A7F3","chartOnHeat4":"#0d1530","chartHeat5":"#648EED","chartOnHeat5":"#0d1530","chartAxis":"#44579c","chartGrid":"rgba(13, 21, 48, 0.12)"},"dark":{"canvas":"#0b1025","surface":"#151a30","surfaceAlt":"#252d55","text":"#f2f5fe","muted":"#c7d4f9","primary":"#abbef6","onPrimary":"#0d142d","primarySoft":"#182962","onPrimarySoft":"#e1e8fc","outline":"#9cb2f4","decorative":"#3865ea","companion":"#6D47F2","glow":"#48C6F0","chartSeries1":"#AD8DFF","chartSeries2":"#F86DAA","chartSeries3":"#F78000","chartSeries4":"#A3AF00","chartSeries5":"#00C09F","chartSeries6":"#00B2F6","chartHeat1":"#151C2A","chartOnHeat1":"#f2f5fe","chartHeat2":"#1B2846","chartOnHeat2":"#f2f5fe","chartHeat3":"#213563","chartOnHeat3":"#f2f5fe","chartHeat4":"#274282","chartOnHeat4":"#f2f5fe","chartHeat5":"#2E4FA2","chartOnHeat5":"#f2f5fe","chartAxis":"#9cb2f4","chartGrid":"rgba(242, 245, 254, 0.16)"}}},"ion":{"name":"Ion","description":"Vivid cyan and indigo for focused tools.","seed":"#007E97","companion":"#3D45E5","glow":"#36DCD1","modes":{"light":{"canvas":"#f4f9fa","surface":"#ffffff","surfaceAlt":"#e8f3f6","text":"#081a25","muted":"#184757","primary":"#007E97","onPrimary":"#ffffff","primarySoft":"#d1e8ec","onPrimarySoft":"#06303e","outline":"#34667c","decorative":"#007E97","companion":"#3D45E5","glow":"#36DCD1","chartSeries1":"#0075C4","chartSeries2":"#8F4CC0","chartSeries3":"#C2335D","chartSeries4":"#9F6200","chartSeries5":"#588000","chartSeries6":"#00837C","chartHeat1":"#E2F4F9","chartOnHeat1":"#081a25","chartHeat2":"#B2E1EF","chartOnHeat2":"#081a25","chartHeat3":"#7ECEE5","chartOnHeat3":"#081a25","chartHeat4":"#38BADA","chartOnHeat4":"#081a25","chartHeat5":"#00A3C3","chartOnHeat5":"#081a25","chartAxis":"#34667c","chartGrid":"rgba(8, 26, 37, 0.12)"},"dark":{"canvas":"#07141e","surface":"#111e27","surfaceAlt":"#1d3445","text":"#f0f7f9","muted":"#bddde4","primary":"#9ccdd6","onPrimary":"#081924","primarySoft":"#0a3646","onPrimarySoft":"#dbedf0","outline":"#8ac4cf","decorative":"#14889f","companion":"#3D45E5","glow":"#36DCD1","chartSeries1":"#4AAAFF","chartSeries2":"#C481FA","chartSeries3":"#FE6C8F","chartSeries4":"#E48E00","chartSeries5":"#83B81E","chartSeries6":"#00BDB3","chartHeat1":"#091F25","chartOnHeat1":"#f0f7f9","chartHeat2":"#002F3B","chartOnHeat2":"#f0f7f9","chartHeat3":"#003F4D","chartOnHeat3":"#f0f7f9","chartHeat4":"#004F60","chartOnHeat4":"#f0f7f9","chartHeat5":"#006073","chartOnHeat5":"#f0f7f9","chartAxis":"#8ac4cf","chartGrid":"rgba(240, 247, 249, 0.16)"}}},"amethyst":{"name":"Amethyst","description":"Rich purple with a warm luminous edge.","seed":"#8430C6","companion":"#CE49B2","glow":"#9198FF","modes":{"light":{"canvas":"#f9f6fc","surface":"#ffffff","surfaceAlt":"#f4ecfa","text":"#19102b","muted":"#462b68","primary":"#8430C6","onPrimary":"#ffffff","primarySoft":"#e9daf5","onPrimarySoft":"#30174d","outline":"#69478f","decorative":"#8430C6","companion":"#CE49B2","glow":"#9198FF","chartSeries1":"#AD3D9A","chartSeries2":"#C43B15","chartSeries3":"#867000","chartSeries4":"#00884D","chartSeries5":"#007F95","chartSeries6":"#5761D8","chartHeat1":"#F3EDFB","chartOnHeat1":"#19102b","chartHeat2":"#E0D0F4","chartOnHeat2":"#19102b","chartHeat3":"#CDB3ED","chartOnHeat3":"#19102b","chartHeat4":"#BA95E4","chartOnHeat4":"#19102b","chartHeat5":"#A878DB","chartOnHeat5":"#19102b","chartAxis":"#69478f","chartGrid":"rgba(25, 16, 43, 0.12)"},"dark":{"canvas":"#130d22","surface":"#1e162c","surfaceAlt":"#36254e","text":"#f8f3fc","muted":"#dfc9f0","primary":"#cfaee9","onPrimary":"#180f29","primarySoft":"#391b56","onPrimarySoft":"#eee2f7","outline":"#c6a0e5","decorative":"#8e41cb","companion":"#CE49B2","glow":"#9198FF","chartSeries1":"#E773D0","chartSeries2":"#FF7452","chartSeries3":"#C2A200","chartSeries4":"#00C471","chartSeries5":"#00B8D6","chartSeries6":"#8B9BFF","chartHeat1":"#1F1827","chartOnHeat1":"#f8f3fc","chartHeat2":"#302140","chartOnHeat2":"#f8f3fc","chartHeat3":"#422A5A","chartOnHeat3":"#f8f3fc","chartHeat4":"#543375","chartOnHeat4":"#f8f3fc","chartHeat5":"#683B92","chartOnHeat5":"#f8f3fc","chartAxis":"#c6a0e5","chartGrid":"rgba(248, 243, 252, 0.16)"}}},"harbor":{"name":"Harbor","description":"The original palette, mapped to shared roles.","seed":"#4669B2","companion":"#8970B5","glow":"#72C4DF","modes":{"light":{"canvas":"#faf8fe","surface":"#ffffff","surfaceAlt":"#e7e7f1","text":"#30323a","muted":"#5c5f68","primary":"#4b5e8b","onPrimary":"#f9f8ff","primarySoft":"#b8cbff","onPrimarySoft":"#2f436e","outline":"#787a84","decorative":"#4669B2","companion":"#8970B5","glow":"#72C4DF","chartSeries1":"#7955CF","chartSeries2":"#BB367A","chartSeries3":"#AE5600","chartSeries4":"#727800","chartSeries5":"#00856C","chartSeries6":"#007BAA","chartHeat1":"#E9F0FE","chartOnHeat1":"#30323a","chartHeat2":"#B3C5E7","chartOnHeat2":"#30323a","chartHeat3":"#7F9AD0","chartOnHeat3":"#30323a","chartHeat4":"#4E70B7","chartOnHeat4":"#f9f8ff","chartHeat5":"#1F459D","chartOnHeat5":"#f9f8ff","chartAxis":"#787a84","chartGrid":"rgba(48, 50, 58, 0.12)"},"dark":{"canvas":"#0d0e12","surface":"#111318","surfaceAlt":"#1d1f26","text":"#e4e5f0","muted":"#a9aab5","primary":"#b8c6ee","onPrimary":"#314060","primarySoft":"#445274","onPrimarySoft":"#dae3ff","outline":"#73757f","decorative":"#4669B2","companion":"#8970B5","glow":"#72C4DF","contentOwnSurface":"#283c60","chartSeries1":"#AA8EFF","chartSeries2":"#F76EAD","chartSeries3":"#F87E08","chartSeries4":"#A5AE00","chartSeries5":"#00C09D","chartSeries6":"#00B2F3","chartHeat1":"#141C2A","chartOnHeat1":"#e4e5f0","chartHeat2":"#1A2845","chartOnHeat2":"#e4e5f0","chartHeat3":"#203563","chartOnHeat3":"#e4e5f0","chartHeat4":"#254282","chartOnHeat4":"#e4e5f0","chartHeat5":"#2A50A2","chartOnHeat5":"#e4e5f0","chartAxis":"#73757f","chartGrid":"rgba(228, 229, 240, 0.16)"}}}},"status":{"light":{"success":{"ink":"#175D38","surface":"#E5F4EA","symbol":"✓","label":"Ready"},"attention":{"ink":"#714B00","surface":"#FFF0CD","symbol":"△","label":"Review needed"},"danger":{"ink":"#941D36","surface":"#FFE8EC","symbol":"!","label":"Action blocked"},"info":{"ink":"#334155","surface":"#E8EDF4","symbol":"i","label":"Information"}},"dark":{"success":{"ink":"#9BE2B3","surface":"#173525","symbol":"✓","label":"Ready"},"attention":{"ink":"#FFDA8A","surface":"#3D2D0E","symbol":"△","label":"Review needed"},"danger":{"ink":"#FFB2C0","surface":"#481C29","symbol":"!","label":"Action blocked"},"info":{"ink":"#D2DCEC","surface":"#263244","symbol":"i","label":"Information"}}},"material":{"acrylicBlur":40,"acrylicSaturation":125,"glassBlur":20,"glassSaturation":165,"glassOpacity":0.2,"grainOpacity":0.045,"labelVeil":0.55,"labelVeilDark":0.6,"contentOpacity":0.8,"contentFeather":1.95,"stoneFeather":1.95,"mirageColor":"#111525","mirageOpacity":0.38,"mirageBlur":28,"mirageSaturation":165,"mirageBrightness":88,"mirageFallbackOpacity":0.64,"micaInactive":{"light":"#f1f1f3","dark":"#202126"}},"motion":{"press":120,"state":213.33,"spatial":293.33,"exit":160,"easing":{"enter":"cubic-bezier(0.22, 0.65, 0.22, 1)","settle":"cubic-bezier(0.2, 0, 0.2, 1)","exit":"cubic-bezier(0.4, 0, 0.6, 1)"},"distance":{"panel":24,"floating":30,"content":0,"exit":20,"depth":50,"feather":6},"material":1000,"liquid":1400,"flow":1200,"departure":650,"maxDuration":5000,"maxTravel":50,"travelPolicy":{"ordinaryRange":[5,30],"compactGuideline":50,"extended":"Documented large compositions and measured layout may exceed 50px.","stationaryMaterials":["haze","stone"]}},"typography":{"readingSize":16,"readingLeading":24,"family":"Manrope","scale":{"display":{"ratio":2,"leading":1.1,"tracking":"-0.055em"},"title":{"ratio":1.5,"leading":1.2,"tracking":"-0.04em"},"heading":{"ratio":1.25,"leading":1.3,"tracking":"-0.03em"},"subheading":{"ratio":1.0625,"leading":1.45,"tracking":"-0.01em"},"body":{"ratio":1,"leading":1.5,"tracking":"0"},"caption":{"ratio":0.8125,"leading":1.45,"tracking":"0"}}},"component":{"action":{"radius":999,"minTarget":48,"paddingBlock":15,"paddingInline":24,"gap":9,"disabledOpacity":0.55},"scrollbar":{"width":10,"thumbMinLength":32,"inset":2},"scrollArea":{"fadeDepth":24},"layout":{"containerMax":1536,"readingMax":920,"gutterCompact":18,"gutterBase":26,"gutterWide":44,"minCellWidth":240,"sidebarWidth":280},"icon":{"size":20,"action":24},"choice":{"boxSize":26,"boxRadius":9},"switch":{"trackWidth":44,"trackHeight":28},"slider":{"trackHeight":8,"thumbSize":26},"chip":{"height":32},"overlayArrow":{"size":14,"radius":3},"overlay":{"maxWidth":480,"tooltipMaxWidth":352},"field":{"wellInset":7},"card":{"radius":28},"focus":{"coreWidth":2,"coreOffset":3},"indicator":{"size":20,"fieldSize":24,"lineWidth":3},"anchor":{"underlineOffset":4},"tree":{"indentStep":20},"haze":{"inset":8},"chart":{"seriesCount":6,"seriesLightness":{"light":0.55,"dark":0.72},"seriesChroma":0.18,"seriesHueOffset":30,"seriesContrast":3,"stroke":2,"hairline":1,"pointMin":6,"pointMax":18,"barRadius":4,"cellGap":2,"ringThickness":0.32,"fillOpacity":0.25,"linkOpacity":0.45,"intensitySteps":5,"gaugeSweep":270},"progress":{"ringStroke":8}},"spacing":{"2xs":4,"xs":8,"sm":12,"md":16,"lg":24,"xl":32,"2xl":48},"schemaNote":"Generated from core/tokens/crystal.tokens.json (W3C DTCG). Edit the DTCG source, not this file.","materials":{"plastic":{"name":"Plastic","role":"Opaque contextual foundation","inspiration":"Microsoft Mica","primitive":".cr-plastic"},"frost":{"name":"Frost","role":"Diffused intermediate surface","inspiration":"Microsoft Acrylic","primitive":".cr-frost"},"resin":{"name":"Resin","role":"Floating optical control surface","inspiration":"Apple Liquid Glass","primitive":".cr-resin"},"haze":{"name":"Haze","role":"Soft content fill","inspiration":"Crystal solid content recipe","primitive":".cr-haze"},"stone":{"name":"Stone","role":"Protected label backing","inspiration":"Crystal protected-label veil","primitive":".cr-stone"},"mirage":{"name":"Mirage","role":"Chromatic diffusion and dark modal separation","inspiration":"Modal smoke/scrim pattern","primitive":".cr-mirage and dialog::backdrop"}}};
@@ -83,7 +83,7 @@ this rule came from are in
83
83
 
84
84
  ## Reduced motion
85
85
 
86
- `prefers-reduced-motion: reduce` is honoured by every one of the 55 motion recipes. Each
86
+ `prefers-reduced-motion: reduce` is honoured by every one of the 61 motion recipes. Each
87
87
  recipe declares its own `reduced` behaviour rather than being globally switched off,
88
88
  because "no animation" and "no *movement*" are different requirements.
89
89
 
@@ -93,6 +93,13 @@ shows it has been pressed. What is removed is the travel, the overshoot and the
93
93
  layer. Reduced motion resolves to zero displacement regardless of the recipe's spring —
94
94
  this is asserted by `tools/validate-motion.cjs`, not left to each implementation.
95
95
 
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.
102
+
96
103
  ## Reduced transparency
97
104
 
98
105
  `prefers-reduced-transparency: reduce` sets `data-effects="opaque"`, which replaces every
@@ -161,7 +168,7 @@ backdrops with the fixed Resin fill.
161
168
  | Failures | 0 |
162
169
  | Lowest result of any kind | 3.07:1 |
163
170
  | Lowest normal-text result | 4.67:1 |
164
- | Checks run | 2026-09-20 |
171
+ | Checks run | 2026-09-28 |
165
172
 
166
173
  Normal text is held to 4.5:1. Essential non-text — focus rings, control boundaries,
167
174
  indicator lines — uses its separate 3:1 threshold, which is the correct standard for those
package/docs/adoption.md CHANGED
@@ -34,12 +34,15 @@ The site uses relative local assets without fetching fonts or services. Review i
34
34
 
35
35
  ## Static CSS adoption
36
36
 
37
- Copy `assets/crystal.css`, `assets/controls.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.
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
+
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.
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.
38
42
 
39
43
  ```html
40
44
  <link rel="stylesheet" href="crystal-theme.css">
41
45
  <link rel="stylesheet" href="assets/crystal.css">
42
- <link rel="stylesheet" href="assets/controls.css">
43
46
  <section class="cr-plastic">
44
47
  <section class="cr-frost">
45
48
  <article class="cr-haze">Readable product content</article>
@@ -127,63 +130,35 @@ Anything else — internal selectors, generated file ordering, the preview site
127
130
 
128
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.
129
132
 
130
- Crystal publishes privately to GitHub Packages under the `@meridian` scope. Products pin a version, which is what makes one-version-per-product and a CI parity check enforceable. The packaged ZIP remains available as a release asset for consumers that do not use a package manager.
131
-
132
- ## Rebuild and validate
133
-
134
- Use an isolated environment for documentation tools, then run from the package root:
133
+ Crystal publishes publicly to npm as **`@crystal-ui/core`**:
135
134
 
136
135
  ```sh
137
- python3 -m venv .venv
138
- .venv/bin/pip install -r tools/requirements.txt
139
- .venv/bin/python tools/build.py
140
- node tools/validate-tokens.cjs
141
- .venv/bin/python tools/validate.py
142
- .venv/bin/python tools/report.py
143
- .venv/bin/python tools/package.py
136
+ npm install @crystal-ui/core
144
137
  ```
145
138
 
146
- Node is used for the same resolver/exporter consumed by the browser; no Node package installation is required. Python requirements support Markdown rendering and HTML link checks. Browser checks are recorded separately as actual UI observations. Rebuilding never reads or writes the originating project. Keep dependencies and temporary environments out of distributable ZIPs.
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.
147
140
 
148
- ## Deploying the preview
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.
149
142
 
150
- The preview is static. Every page, stylesheet, script, icon and shader in this directory is
151
- committed, so a host only has to serve the directory — there is no build step at deploy time,
152
- and adding one would only introduce a way for the published site to disagree with the
153
- validated one.
143
+ ## Rebuild and validate
154
144
 
155
- `vercel.json` at the repository root serves `design-system/` as the site root with no build
156
- and no install. The constraints worth knowing before changing it:
145
+ From the `crystal` repository:
157
146
 
158
- **Every path is relative and must stay that way.** Nothing references an absolute `/path`, so
159
- the site works at a domain root, under a subpath, or from a preview URL without alteration.
160
- An absolute path added anywhere would break the last two.
147
+ ```sh
148
+ npm ci
149
+ npm run build
150
+ npm test
151
+ ```
161
152
 
162
- **Scripts that fetch must resolve against their own URL, not the page's.** `motion-shaders.js`
163
- derives its base from `document.currentScript.src`. A page-relative `assets/…` only works for
164
- pages at the site root; from `/docs/materials.html` it resolves to `/docs/assets/…`. Because
165
- the shader runtime fails quietly by design, that broke the optical layer on ten documentation
166
- pages with no visible symptom until it was measured.
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
154
 
168
- **Caching assumes filenames are not content-hashed, because they are not.** Assets carry
169
- `max-age=0, must-revalidate` for browsers and a long `s-maxage` for the edge, which Vercel
170
- purges on each deployment: the edge serves cached bytes, browsers always revalidate, and a
171
- redeploy is picked up immediately. Fonts are the exception and are cached immutably for a
172
- year. Do not mark the stylesheets or scripts `immutable` unless their names gain hashes;
173
- clients would hold a stale Crystal for a year.
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.
174
156
 
175
- **Shader sources are served as text.** `.frag` and `.glsl` are given an explicit
176
- `text/plain` content type, which matters because `X-Content-Type-Options: nosniff` is set.
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.
177
158
 
178
- **`cleanUrls` is deliberately off.** Every internal link is written with its `.html`
179
- extension and `tools/validate.py` checks that link graph. Enabling clean URLs would redirect
180
- each of those and publish a site whose routes differ from the validated ones.
159
+ ## Deploying the documentation website
181
160
 
182
- `.vercelignore` keeps the build and test machinery out of the upload. Only two directories
183
- are excluded, `tools/` and `src/`, and both were verified to be referenced by no page. The
184
- link graph resolves with zero errors against the exact tree that gets uploaded; `tests/`,
185
- `reference/`, `tokens/`, `artifacts/` and the Markdown sources are all linked and are all
186
- published.
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.
187
162
 
188
163
  ### User animation speed
189
164
 
@@ -192,8 +167,14 @@ published.
192
167
 
193
168
  ### Motion engine dependencies
194
169
 
195
- The motion runtime now requires the locally bundled engines and recipe catalog. Load `assets/vendor/crystal-engines.js`, `assets/motion-catalog.js`, then `assets/motion.js`. `npm ci` reproduces the pinned Motion 13.4.0 and GSAP 3.15.0 dependencies; `npm run build:motion` rebuilds the bundle with esbuild. Preserve the vendor legal-comment file and `reference/licenses/` when distributing it. The token resolver and static material CSS do not require these libraries. See [component motion](motion-components.html) for integration and cancellation contracts.
170
+ 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
+
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.
196
173
 
197
174
  ### Interaction surfaces and revised motion
198
175
 
199
- Include `assets/controls.css` after base/layout styles. Use `assets/controls.js` for the preview's native field shells, or render equivalent shells in your component framework. 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 catalog declares material signatures and justified extended travel; the old 50px token describes compact motion only.
176
+ 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
+
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.
179
+
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.