@crystal-ui/core 2.0.0 → 2.1.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/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,23 @@
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
+ /* Chart geometry. A chart's colours vary with the palette and arrive with
85
+ the other roles above; these do not vary at all. They are published
86
+ rather than left to each renderer because the catalogue says "line
87
+ weight follows the stroke scale" and "point size is a scale, not an
88
+ arbitrary radius" as though both scales existed, and until now neither
89
+ did — which is how two renderers end up with two of them. */
90
+ '--cr-chart-stroke':data.component.chart.stroke+'px',
91
+ '--cr-chart-hairline':data.component.chart.hairline+'px',
92
+ '--cr-chart-point-min':data.component.chart.pointMin+'px',
93
+ '--cr-chart-point-max':data.component.chart.pointMax+'px',
94
+ '--cr-chart-bar-radius':data.component.chart.barRadius+'px',
95
+ '--cr-chart-cell-gap':data.component.chart.cellGap+'px',
96
+ '--cr-chart-ring-thickness':String(data.component.chart.ringThickness),
97
+ '--cr-chart-fill-opacity':String(data.component.chart.fillOpacity),
98
+ '--cr-chart-link-opacity':String(data.component.chart.linkOpacity),
99
+ '--cr-chart-gauge-sweep':data.component.chart.gaugeSweep+'deg',
100
+ '--cr-progress-ring-stroke':data.component.progress.ringStroke+'px',
79
101
  '--cr-content-muted':s.palette==='harbor'?p.text:p.muted,
80
102
  '--cr-content-own-text':s.palette==='harbor'?p.text:p.onPrimarySoft,
81
103
  '--cr-stone-feather':s.reduced?'0px':data.material.stoneFeather+'px',
@@ -113,19 +135,82 @@
113
135
  nothing, and those two inset shadows have never painted. A value two
114
136
  components depend on belongs to the system. */
115
137
  '--cr-control-edge':rgba(p.outline,0.18),
138
+ /* The two tints the Resin control sheen is built from, and the same story
139
+ as `--cr-control-edge` above: they lived only in the preview's
140
+ `controls.css`, so the optical sheen on every Crystal control was a
141
+ thing the library described and did not ship. Adopted 21 September 2026
142
+ with the rest of D-11.
143
+
144
+ `--cr-control-color` is the decorative tint that gives the control its
145
+ body; `--cr-control-light` is the glow that lights its top-left corner.
146
+ Both go *down* in dark mode rather than up — the opposite of the focus
147
+ feathers, and deliberately: on a deep canvas the sheen is already
148
+ reading against very little, and holding it at the light-mode strength
149
+ makes a control look lit from inside rather than lit from above. */
150
+ /* `color-mix` rather than a resolved `rgba`, and it is the one place in
151
+ this theme that departs from the convention. Two reasons, both checked
152
+ rather than assumed. A resolved `rgba` alpha is quantised to 8 bits by
153
+ the time a browser serialises it — 0.126 comes back as 0.125 — and an
154
+ A/B of the site against this library put a worst channel delta of 2 on
155
+ the playground's controls purely from that. And a mix keeps the tint
156
+ tracking `--cr-glow` and `--cr-decorative`, so a product that retints
157
+ either gets a sheen that follows; a resolved value silently would not.
158
+ The preview has always written these as mixes, so this is also what
159
+ makes the adoption exact. */
160
+ '--cr-control-color':`color-mix(in srgb,var(--cr-decorative) ${dark?7:8.4}%,transparent)`,
161
+ '--cr-control-light':`color-mix(in srgb,var(--cr-glow) ${dark?9.8:12.6}%,transparent)`,
116
162
  '--cr-focus-core':p.primary,
117
163
  '--cr-focus-core-width':'2px',
118
164
  '--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(','),
165
+ /* The four feather colours, published rather than inlined.
166
+
167
+ They were the preview's own — `--cr-focus-feather-1` … `-4` in
168
+ `controls.css` — and the library had no equivalent, because it baked its
169
+ alphas straight into `--cr-focus-ring`. That is precisely why the
170
+ dark-mode divergence could hide for so long: there was no property to
171
+ compare, so no gate could have been written that would have caught it.
172
+ Naming them is half of D-11's fix; the other half is that a product can
173
+ now retint the falloff without restating the whole recipe.
174
+
175
+ **Dark mode lifts them**, 56/38/22/11 against light's 46/30/17/8. The
176
+ preview has carried the lift since the halo was specified and the
177
+ library never did, so Crystal's site held its falloff against a deep
178
+ canvas and every consumer's went thin. Meridian decided on 21 September
179
+ 2026 that the library carries it. */
180
+ ...Object.fromEntries((dark?[56,38,22,11]:[46,30,17,8])
181
+ .map((pct,i)=>[`--cr-focus-feather-${i+1}`,rgba(p.primary,pct/100)])),
182
+ /* The broad layer's colour, and the one part of focus that is not the
183
+ primary: it is `--cr-decorative`, so the lift under a focused control
184
+ carries the palette's own shadow hue rather than tinting everything
185
+ purple. Also the preview's, also never exported. */
186
+ '--cr-focus-shadow':rgba(p.decorative,0.27),
187
+ /* Six layers: the four-layer halo, then two that lift.
188
+
189
+ Spreads 1/3/6/11, not 2/6/12/22 — the halo was halved at Meridian's
190
+ request, the change was made in the preview's stylesheet, and the
191
+ library went on shipping the withdrawn one to every consumer. That much
192
+ was fixed on 20 September.
193
+
194
+ What was still missing is the pair beneath: `0 8px 18px` directional and
195
+ `0 22px 40px` broad. A focused control on Crystal's site lifts, and in
196
+ every consumer it did not — not a spread this time but two whole layers,
197
+ and `components.md` had described lifting on focus as Crystal's own
198
+ behaviour throughout. Meridian decided on 21 September that the library
199
+ carries them, so this is now the whole recipe and the preview's copy is
200
+ redundant rather than authoritative.
201
+
202
+ Written as `var()` references to the properties above, which is the
203
+ shape the preview used. It keeps the recipe readable at the point of
204
+ use and it is what lets the two be compared layer by layer. */
205
+ '--cr-focus-ring':[
206
+ ...[[6,1,1],[16,3,2],[30,6,3],[54,11,4]]
207
+ .map(([blur,spread,n])=>`0 0 ${blur}px ${spread}px var(--cr-focus-feather-${n})`),
208
+ /* The directional layer borrows the second feather rather than naming a
209
+ fifth colour — the preview's choice, kept, because a lift that is a
210
+ shade of the halo above it reads as the same light source. */
211
+ '0 8px 18px var(--cr-focus-feather-2)',
212
+ '0 22px 40px var(--cr-focus-shadow)',
213
+ ].join(','),
129
214
  /* The spacing scale and the shell's geometry. Neither varies with palette,
130
215
  mode or density; they are published as custom properties so a product
131
216
  writing plain CSS reaches the same values the libraries compile against.
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":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},"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 57 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
 
@@ -161,7 +161,7 @@ backdrops with the fixed Resin fill.
161
161
  | Failures | 0 |
162
162
  | Lowest result of any kind | 3.07:1 |
163
163
  | Lowest normal-text result | 4.67:1 |
164
- | Checks run | 2026-09-20 |
164
+ | Checks run | 2026-09-24 |
165
165
 
166
166
  Normal text is held to 4.5:1. Essential non-text — focus rings, control boundaries,
167
167
  indicator lines — uses its separate 3:1 threshold, which is the correct standard for those
package/docs/adoption.md CHANGED
@@ -34,12 +34,13 @@ 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, range, file button, select option and menu item. Before 2.1.0 it carried none of that, 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.
38
40
 
39
41
  ```html
40
42
  <link rel="stylesheet" href="crystal-theme.css">
41
43
  <link rel="stylesheet" href="assets/crystal.css">
42
- <link rel="stylesheet" href="assets/controls.css">
43
44
  <section class="cr-plastic">
44
45
  <section class="cr-frost">
45
46
  <article class="cr-haze">Readable product content</article>
@@ -127,63 +128,35 @@ Anything else — internal selectors, generated file ordering, the preview site
127
128
 
128
129
  **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
130
 
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:
131
+ Crystal publishes publicly to npm as **`@crystal-ui/core`**:
135
132
 
136
133
  ```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
134
+ npm install @crystal-ui/core
144
135
  ```
145
136
 
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.
137
+ 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
138
 
148
- ## Deploying the preview
139
+ 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
140
 
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.
141
+ ## Rebuild and validate
154
142
 
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:
143
+ From the `crystal` repository:
157
144
 
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.
145
+ ```sh
146
+ npm ci
147
+ npm run build
148
+ npm test
149
+ ```
161
150
 
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.
151
+ `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
152
 
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.
153
+ 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
154
 
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.
155
+ 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
156
 
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.
157
+ ## Deploying the documentation website
181
158
 
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.
159
+ 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
160
 
188
161
  ### User animation speed
189
162
 
@@ -192,8 +165,14 @@ published.
192
165
 
193
166
  ### Motion engine dependencies
194
167
 
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.
168
+ 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.
169
+
170
+ **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
171
 
197
172
  ### Interaction surfaces and revised motion
198
173
 
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.
174
+ 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.
175
+
176
+ `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.
177
+
178
+ 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.
package/docs/catalogue.md CHANGED
@@ -388,7 +388,7 @@ Nested disclosure rows with indentation guides and expand controls.
388
388
  <tr><th scope="row">States</th><td>collapsed, expanded, selected, focus, disabled, loading</td></tr>
389
389
  <tr><th scope="row">Material</th><td>Haze rows on the surrounding surface</td></tr>
390
390
  <tr><th scope="row">Geometry</th><td>Indent step 20px; guides use the edge token</td></tr>
391
- <tr><th scope="row">Semantics</th><td>role=tree/treeitem/group with aria-expanded, aria-level and full arrow-key navigation</td></tr>
391
+ <tr><th scope="row">Semantics</th><td>role=treegrid/row/gridcell with aria-expanded, aria-level, aria-posinset, aria-setsize and full arrow-key navigation. Not role=tree: a treeitem is a single navigable unit, so it cannot contain the expand control this anatomy requires — treegrid is the pattern ARIA provides for a row that holds its own control. See M-3.</td></tr>
392
392
  <tr><th scope="row">Crystal supplies</th><td>Row treatment, indentation guides, label weight for the selected row</td></tr>
393
393
  <tr><th scope="row">Product owns</th><td>The keyboard navigation implementation, data and lazy loading</td></tr>
394
394
  <tr><th scope="row">Motion</th><td><code>accordion-in</code>, <code>accordion-out</code></td></tr>
@@ -489,7 +489,7 @@ Resin shell, 8px-inset Haze reading fill, directional optical sheen, label and o
489
489
 
490
490
  <div class="cr-table-scroll"><table class="cr-table cr-table-properties"><tbody>
491
491
  <tr><th scope="row">States</th><td>default, hover, pressed, focus, disabled, loading</td></tr>
492
- <tr><th scope="row">Material</th><td>Resin shell with Haze fill; primary, secondary, quiet and danger variants</td></tr>
492
+ <tr><th scope="row">Material</th><td>Resin shell with Haze fill; the fill is neutral by default, the primary colour on .primary, and absent on .quiet. A danger boundary on .danger</td></tr>
493
493
  <tr><th scope="row">Geometry</th><td>Pill (999px); 48px height; 15px/24px padding; 44px minimum target</td></tr>
494
494
  <tr><th scope="row">Semantics</th><td>Native button. A disabled button must not be the only explanation of unavailability.</td></tr>
495
495
  <tr><th scope="row">Crystal supplies</th><td>Material, pill geometry, optical pressure, focus ring, variant hierarchy</td></tr>
@@ -3694,6 +3694,7 @@ Pushed views with a back affordance.
3694
3694
  <tr><th scope="row">Semantics</th><td>Focus moves to the new view and returns on pop; the back control is a real button.</td></tr>
3695
3695
  <tr><th scope="row">Crystal supplies</th><td>Enter and exit recipes, focus management</td></tr>
3696
3696
  <tr><th scope="row">Product owns</th><td>The stack and routing</td></tr>
3697
+ <tr><th scope="row">Motion</th><td><code>view-push-in</code>, <code>view-push-out</code></td></tr>
3697
3698
  <tr><th scope="row">Parity</th><td>react-aria:RouterProvider</td></tr>
3698
3699
  </tbody></table></div>
3699
3700
 
package/docs/colors.md CHANGED
@@ -33,6 +33,90 @@ The seed is not automatically a text color. The canonical [token JSON](../tokens
33
33
  | Functional | `success`, `attention`, `danger`, `info` ink/surface pairs | Independent of brand palette and mode-aware |
34
34
  | Component/material | Resin fill, Stone backing, edge, shadows, radii | Derived from the chosen palette and settings |
35
35
 
36
+ ### There is no secondary colour, and that is a decision
37
+
38
+ Crystal defines **one action pair per palette** — `primary` with `onPrimary`, and
39
+ `primarySoft` with `onPrimarySoft` for the container form. There is no
40
+ `secondary`, and nothing in the token set, the exported theme or the component
41
+ vocabulary names one.
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.
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
52
+ dark 3.27 against white and 3.00 against the text ink, Amethyst dark 4.02 / 3.68,
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.
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.
64
+
65
+ ### The chart series scale, which is not that
66
+
67
+ Charts need several colours at once and a palette gives one. Crystal 2.1.0
68
+ therefore publishes a **series scale**: six categorical colours per palette per
69
+ mode, as `--cr-chart-series-1` through `--cr-chart-series-6`, alongside
70
+ `--cr-chart-axis` and `--cr-chart-grid`.
71
+
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.
78
+
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:
84
+
85
+ - **Every one clears 3:1 against both the surface and the canvas of its mode.** A
86
+ 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.
96
+
97
+ All four are asserted in `tests/core-contracts.cjs` for all twelve
98
+ palette-and-mode combinations.
99
+
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.
119
+
36
120
  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.
37
121
 
38
122
  ## Functional meanings
@@ -9,18 +9,19 @@ The package contains working CSS primitives and a bounded interactive reference.
9
9
  | Foundation | Opaque canvas and contextual gradients; light/dark | `.cr-plastic`; product chooses composition |
10
10
  | Haze content card | 80% fill, 1.95px feathered perimeter, radius, content depth | `.cr-haze`; use semantic article or button according to behavior |
11
11
  | Frost panel | Frosted surround, grain, Haze reading wells | `.cr-frost`; app supplies menu/sheet behavior and focus |
12
- | Resin toolbar | Single floating plane, protected label group, selected destination | `.cr-resin`, `.cr-dock`, `.cr-dock-inner`; local preview switches actual scenes; app supplies routing |
12
+ | Resin toolbar | Single floating plane, protected label group, selected destination | `.cr-resin`, `.cr-dock` (a Resin pill, 9px padding, Haze perimeter, 7px when narrow), `.cr-dock-inner`; local preview switches actual scenes; app supplies routing |
13
13
  | Stone label backing | 55% light / 60% dark, 1.95px feather, crisp text | `.cr-stone`; `.cr-dock-inner` shares the recipe |
14
14
  | Mirage modal scrim | Dark tint with chromatic diffusion of the scene behind the active modal | `.cr-mirage` and dialog `::backdrop`; standalone paint requires real application modal behavior |
15
- | Primary action | Resin shell, Haze reading fill, optical pressure and light; hover/pressed/focus/disabled | `.cr-button`; real action and progress/error handling are app-owned |
16
- | Secondary/quiet action | Resin shell with neutral Haze reading fill | `.secondary`, `.quiet`; same semantics as primary |
15
+ | Action | Resin shell with the neutral Haze reading fill, optical pressure and light; hover/pressed/focus/disabled | `.cr-button`. Real action and progress/error handling are app-owned |
16
+ | Primary action | The same control with its Haze reading fill **in the primary colour** and the tested ink on it | `.cr-button.primary`; `--cr-primary` on the fill, `--cr-on-primary` as the ink. Opt-in, so a button is emphatic only where somebody said so |
17
+ | Quiet action | The same shell with **no** reading fill, so the label sits directly on the material | `.cr-button.quiet`; same semantics as any action |
17
18
  | Destructive action | Resin/Haze with independent danger boundary and explicit label | `.danger`; app supplies consequence-specific confirmation and recovery |
18
19
  | Text field | Visible label, state badge, glowing focus ring, validation, helper/error association | `.cr-input`; working native form example; app supplies validation rules |
19
- | Selection control | Explicit selected state plus text/mark | Native checkbox/select and preview button groups; keyboard semantics must match the component |
20
- | Range control | Visible label/value, keyboard adjustable range | Native sliders in the lab; product limits require domain validation |
20
+ | Selection control | Explicit selected state plus text/mark | Native checkbox, radio and select, styled by `assets/crystal.css` as of 2.1.0; keyboard semantics must match the component |
21
+ | Range control | Visible label/value, keyboard adjustable range | Native `input[type=range]`, styled by `assets/crystal.css` as of 2.1.0, including its RTL track direction; product limits require domain validation |
21
22
  | Authored bubble | Haze, directional tight corner, optional author metadata | `.cr-bubble`, `.own`; app supplies content/Markdown semantics |
22
23
  | Composer surround | Frost frame and softened content well around protected input controls | CSS composition; no rich-text editor or delivery service is implemented |
23
- | Status badge | Independent ink/surface pair, symbol and visible label | `.cr-status` with `data-status`; dynamic announcements are app-owned |
24
+ | Status badge | Independent ink/surface pair, symbol and visible label | `.cr-status` with `data-status`; 18px radius, 12px/18px padding, 36px floor, as the preview has always rendered it; dynamic announcements are app-owned |
24
25
  | Avatar | Circular image/initials, accessible identity when needed | Reference styling; app handles real identity, image failure and privacy |
25
26
  | Dialog | 80% feathered surface over Mirage; title, body and named actions | Working native HTML dialog example; Escape/focus return; app owns transactions |
26
27
  | Tooltip | Short supplemental text; never sole label | Working Resin/Haze tooltip in the motion suite; focus, hover and Escape |
@@ -63,7 +64,11 @@ Maintain a production Storybook or equivalent gallery for actual components with
63
64
 
64
65
  ## Resin interaction and information surfaces
65
66
 
66
- Use `assets/controls.css` after the base and layout styles. Buttons, action links, tabs, selectable controls and field shells use Resin as their interaction surface. The preview supplies Haze reading protection inside a visible Resin perimeter. `assets/controls.js` adds only a nonsemantic shell to native fields; labels, input values, validation and form submission remain native.
67
+ Buttons, action links, tabs, selectable controls and field shells use Resin as their interaction surface, with Haze reading protection inside a visible Resin perimeter. **On the primary action that reading fill is the primary colour, and the perimeter is the ordinary glass rim** — `--cr-primary` on the fill, `--cr-on-primary` as the ink, which is the palette's own tested pair and measures 4.74 to 10.31 against the rendered composite across all six palettes and both modes. The fill is opaque there where the neutral one is 80%, and that is the single deliberate deviation in this recipe. An 80% fill transmits a fifth of what is behind it: white over a light page is still white, so the neutral pad loses nothing, but a mid-tone primary at 80% over the Resin shell composites to a washed-out lilac sitting at the luminance where neither a white nor a near-black label clears 4.5 — 3.37 to 4.55 with `onPrimary`, 2.95 to 5.06 with `text`, failing in every light palette. A reading ground whose job is to make the label independent of the backdrop cannot be the one thing that depends on it.
68
+
69
+ **A quiet button has no reading fill.** It keeps the whole Resin shell — rim, float shadow, sheen — and drops the pad, which makes it the only variant that is glass all the way through. The cost is the pad's whole purpose: a quiet label reads against the Resin fill and therefore against whatever is behind the control. On Crystal's own foundation that is a wide margin — `--cr-text` over the Resin fill over canvas, surface, surface-alt and foundation measures 10.88 to 18.28 across all six palettes and both modes — but a quiet button placed over artwork has no protected ground, and that composition is the one to avoid. The recipe is in `assets/crystal.css`, in `@layer crystal.component`: a Resin fill with a rim and a float shadow, a `::before` carrying the inset Haze fill at the material's feather, and a `::after` carrying the optical sheen from `--cr-control-color` and `--cr-control-light`. Both pseudo-elements are dropped under reduced transparency and under forced colours.
70
+
71
+ Until 2.1.0 this paragraph told you to load `assets/controls.css`, which is the documentation site's stylesheet and has never been in the package — so the surface this specification describes was one no consumer could obtain. `assets/controls.js` adds only a nonsemantic shell to native fields; labels, input values, validation and form submission remain native.
67
72
 
68
73
  Small display elements (tooltips, toasts, labels, tags and badges) and temporary menus (secondary menus, dropdowns, flyouts and popovers) use `.cr-resin-haze`. This is a reusable composition of existing materials, not a seventh material. Larger persistent components retain their structural material. Native OS popup internals are platform-owned; use an actual accessible custom component when full Crystal popup rendering is required.
69
74
 
@@ -100,7 +105,13 @@ Icons next to text are decorative and hidden from assistive technology. Icon-onl
100
105
 
101
106
  ## Focus light and circular state badges
102
107
 
103
- Focus uses an immediate 2px primary-color core at a 3px offset, surrounded by a broadly feathered halo. The halo is four graded layers of the primary color — 46% at 6px blur / 2px spread, 30% at 16px / 6px, 17% at 30px / 12px and 8% at 54px / 22px — so the light falls off smoothly instead of ending on a hard edge. Dark mode raises those alphas to 56/38/22/11% to carry the same falloff against a deep canvas. Its elevation shadow stays chromatic: the 30% layer supplies the close glow and decorative color at 27% supplies the broad shadow. The single token `--cr-focus-ring` composes the halo so every focusable surface shares one recipe. The core remains defined for visibility; text and icons are never blurred. Keyboard focus applies to all interactive elements. Text entry lights its Resin shell through `:focus-within`. Motion must neither delay nor remove the focus cue. Forced colors substitute a system Highlight outline and remove decorative shadows.
108
+ Focus uses an immediate 2px primary-color core at a 3px offset, surrounded by a broadly feathered halo. The halo is four graded layers of the primary color — 46% at 6px / 1px, 30% at 16px / 3px, 17% at 30px / 6px and 8% at 54px / 11px (blur / spread) — so the light falls off smoothly instead of ending on a hard edge. The spreads were halved from 2/6/12/22 at Meridian's request; the blur radii were deliberately left alone, so the ring thins without the falloff flattening.
109
+
110
+ **A focused control also lifts.** Beneath the halo sit two elevation layers: a directional 8px / 18px (offset / blur) at 30% of the primary color, and a broad 22px / 40px at 27% of the *decorative* color. The directional layer reuses the halo's second feather so the lift reads as the same light source; the broad one is decorative rather than primary so the shadow under a focused control carries the palette's own shadow hue instead of tinting the page purple. Focus changes the elevation shadow's hue without blurring any foreground.
111
+
112
+ **In dark mode the feather alphas lift**, to 56 / 38 / 22 / 11 against light's 46 / 30 / 17 / 8. A deep canvas swallows the falloff at the lighter values, so the ring reads as a hard edge with nothing around it. Blur, spread and the elevation layers are identical in both modes.
113
+
114
+ The four feather colors are published as `--cr-focus-feather-1` through `-4` and the broad shadow as `--cr-focus-shadow`, so a product can retint the falloff without restating the recipe. The single token `--cr-focus-ring` composes all six layers so every focusable surface shares one recipe. The core remains defined for visibility; text and icons are never blurred. Keyboard focus applies to all interactive elements. Text entry lights its Resin shell through `:focus-within`. Motion must neither delay nor remove the focus cue. Forced colors substitute a system Highlight outline and remove decorative shadows.
104
115
 
105
116
  A `.cr-indicator` is a 20px circular Resin surface with a 3px-inset 80% Haze fill and a 1px feather on that fill. Field badges are 24px. Their foreground remains crisp and uses the tested body ink. They sit beside the content, never over text or a native select arrow. These are informational, non-interactive marks, not small click targets.
106
117
 
@@ -109,18 +120,20 @@ A `.cr-indicator` is a 20px circular Resin surface with a 3px-inset 80% Haze fil
109
120
  | Layer | Blur | Spread | Role |
110
121
  |---|---|---|---|
111
122
  | `outline: 2px solid var(--cr-focus-core)` at `outline-offset: 3px` | — | — | The crisp core. Never feathered, and the only part that survives forced colours. |
112
- | `--cr-focus-feather-1` | 6px | 1px | Feathered halo; increasing blur at decreasing opacity |
113
- | `--cr-focus-feather-2` | 16px | 3px | Feathered halo; increasing blur at decreasing opacity |
114
- | `--cr-focus-feather-3` | 30px | 6px | Feathered halo; increasing blur at decreasing opacity |
115
- | `--cr-focus-feather-4` | 54px | 11px | Feathered halo; increasing blur at decreasing opacity |
116
- | `--cr-focus-feather-2` | 18px | 0 | Directional elevation |
117
- | `--cr-focus-shadow` | 40px | 0 | Elevation beneath the control |
123
+ | Halo 1 | 6px | 1px | 46% of the primary colour |
124
+ | Halo 2 | 16px | 3px | 30% of the primary colour |
125
+ | Halo 3 | 30px | 6px | 17% of the primary colour |
126
+ | Halo 4 | 54px | 11px | 8% of the primary colour |
127
+ | Elevation 1 | 18px | — | 30% of the primary colour, offset 8px — the directional lift |
128
+ | Elevation 2 | 40px | — | 27% of the decorative colour, offset 22px — the broad lift |
118
129
  <!-- /generated:focus-recipe -->
119
130
 
120
- Each halo layer is read from `--cr-focus-ring` in `assets/controls.css`, so this table
121
- cannot disagree with what ships. The core is never feathered and the offset is never
122
- zero: a ring drawn *on* the border is hard to tell from a hover state, and on a pill it
123
- reads as a thicker stroke rather than as focus.
131
+ Every layer is read from `--cr-focus-ring` in the library's own exported theme, so this
132
+ table cannot disagree with what ships. It used to be read from the preview site's
133
+ `assets/controls.css` — a stylesheet the package does not contain — which is how Crystal
134
+ came to document a halo it did not export and a lift no consumer received. The core is
135
+ never feathered and the offset is never zero: a ring drawn *on* the border is hard to
136
+ tell from a hover state, and on a pill it reads as a thicker stroke rather than as focus.
124
137
 
125
138
  A check mark is reserved for validation and information display — the status badges in `.cr-status` and a checkbox's own `:checked` indicator. It never marks a selected, pressed or focused control. Selection instead uses a heavier label weight, which changes no metric that would reflow the group. Round specimen swatches, which cannot carry a weight change, use an inset ring gap. Ordinary prose links retain their link styling. Badges are `aria-hidden`: the real control supplies its accessible name, required/invalid/selected/busy state and error association. The visual symbol never gets appended to the control's text content. Native checkbox/radio indicators and functional labels remain intact. Small controls retain full-sized hit targets. Badges have solid, unblurred alternatives under reduced transparency and forced colors.
126
139