@crystal-ui/core 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +82 -23
  2. package/assets/core/preferences.d.ts +4 -4
  3. package/assets/core/preferences.js +4 -4
  4. package/assets/core/presets.d.ts +4 -3
  5. package/assets/core/presets.js +24 -18
  6. package/assets/core/spring.js +9 -10
  7. package/assets/core/state.js +7 -7
  8. package/assets/crystal.css +784 -284
  9. package/assets/crystal.d.ts +3 -3
  10. package/assets/crystal.js +100 -123
  11. package/assets/icons/heading-2.svg +1 -0
  12. package/assets/icons/heading-3.svg +1 -0
  13. package/assets/icons/heading-4.svg +1 -0
  14. package/assets/icons/link.svg +1 -0
  15. package/assets/icons/list-ordered.svg +1 -0
  16. package/assets/icons/list.svg +1 -0
  17. package/assets/icons/manifest.json +81 -2
  18. package/assets/icons/quote.svg +1 -0
  19. package/assets/icons/redo.svg +1 -0
  20. package/assets/icons/subscript.svg +1 -0
  21. package/assets/icons/undo.svg +1 -0
  22. package/assets/icons/unlink.svg +1 -0
  23. package/assets/motion.js +13 -12
  24. package/docs/accessibility.md +50 -54
  25. package/docs/adoption.md +33 -19
  26. package/docs/catalogue.md +113 -108
  27. package/docs/colors.md +67 -73
  28. package/docs/components.md +142 -66
  29. package/docs/icons.md +9 -3
  30. package/docs/materials.md +129 -117
  31. package/docs/motion-components.md +15 -15
  32. package/docs/motion.md +156 -158
  33. package/docs/principles.md +12 -12
  34. package/docs/tokens.md +129 -130
  35. package/engines.js +3 -3
  36. package/package.json +11 -3
  37. package/tokens/catalogue/01-layout.json +1 -1
  38. package/tokens/catalogue/02-navigation.json +4 -4
  39. package/tokens/catalogue/03-actions.json +2 -1
  40. package/tokens/catalogue/04-inputs.json +30 -22
  41. package/tokens/catalogue/05-data-display.json +9 -14
  42. package/tokens/catalogue/06-feedback.json +8 -6
  43. package/tokens/catalogue/07-overlays.json +4 -4
  44. package/tokens/catalogue/08-typography.json +12 -8
  45. package/tokens/catalogue/09-utility.json +1 -1
  46. package/tokens/catalogue/10-charts.json +7 -7
  47. package/tokens/catalogue/11-media.json +33 -20
  48. package/tokens/catalogue/12-commerce.json +4 -4
  49. package/tokens/catalogue/13-screens.json +2 -3
  50. package/tokens/catalogue/14-blocks.json +3 -3
  51. package/tokens/catalogue.json +176 -116
  52. package/tokens/crystal.tokens.json +6 -6
  53. package/tokens/motion-recipes.json +6 -6
  54. package/tokens/surface-recipes.json +3452 -0
  55. package/tokens/surfaces.json +48 -17
package/docs/materials.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Materials, depth and optical detail
2
2
 
3
- **The defining order is Plastic → Frost → Resin, from back to front.** Plastic is the foundation, Frost the intermediate material layer, and Resin the highest functional control layer. Haze reading wells preserve legibility within this hierarchy. It is a custom design system, not a vendor-certified combination of Microsoft and Apple systems.
3
+ **The defining order is Plastic → Frost → Resin, from back to front.** Plastic is the foundation, Frost the intermediate material layer, and Resin the highest functional control layer. Haze reading wells preserve legibility within this hierarchy. Crystal is a custom design system. It is not a vendor-certified combination of Microsoft and Apple systems.
4
4
 
5
5
  ## Visual acceptance requirement
6
6
 
7
- The approved Crystal material studies define the intended appearance, not merely inspiration. Every implementation must preserve their distinct opacity and diffusion, transmitted color, optical contours, elevation, soft reading-fill edges and crisp text. If a component or material departs from those qualities without an approved reason, treat it as a defect. Check actual UI screenshots as well as tokens. Dark mode and alternate palettes must preserve the same relationships; documented accessibility fallbacks remain required.
7
+ The approved Crystal material studies define the intended appearance. Every implementation must preserve their distinct opacity and diffusion, transmitted color, optical contours, elevation, soft reading-fill edges and crisp text. If a component or material departs from those qualities without an approved reason, treat it as a defect. Check actual UI screenshots as well as tokens. Dark mode and alternate palettes must preserve the same relationships; documented accessibility fallbacks remain required.
8
8
 
9
9
  ## Recommended defaults
10
10
 
@@ -14,24 +14,24 @@ Use these settings as Crystal’s recommended starting point across products:
14
14
 
15
15
  | Setting | Recommended default | Valid range |
16
16
  |---|---|---|
17
- | Color atmosphere | 90% | 15% – 90% |
18
- | Frost base tint | 35% | 35% – 85% |
19
- | Elevation | 125% | 60% – 150% |
20
- | Corner radius | 28px | 14px – 28px |
21
- | Motion speed | 1× | 0.25× – 2× |
22
- | Palette | `prism` | — |
23
- | Mode | `light` | — |
24
- | Density | `comfortable` | — |
25
- | Font | `manrope` | — |
26
- | Reduced | `false` | — |
27
- | Reduce motion | `false` | — |
17
+ | Color atmosphere | 90% | 15% to 90% |
18
+ | Frost base tint | 35% | 35% to 85% |
19
+ | Elevation | 125% | 60% to 150% |
20
+ | Corner radius | 28px | 14px to 28px |
21
+ | Motion speed | 1× | 0.25× to 2× |
22
+ | Palette | `prism` | None |
23
+ | Mode | `light` | None |
24
+ | Density | `comfortable` | None |
25
+ | Font | `manrope` | None |
26
+ | Reduced | `false` | None |
27
+ | Reduce motion | `false` | None |
28
28
  <!-- /generated:defaults -->
29
29
 
30
30
  The canonical tokens, generated theme and playground’s **Reset** action use these values. Saved user preferences remain customizable. Frost’s existing recipe adds 10 percentage points to its base tint, so the recommended 35% base produces a 45% surface fill. Resin remains fixed at 20% fill opacity; opaque accessibility fallbacks take precedence.
31
31
 
32
32
  ## Material family and inspiration
33
33
 
34
- Crystal has **six first-class materials: Plastic, Frost, Resin, Haze, Stone, and Mirage**. Each has its own named recipe and reusable primitive. Plastic → Frost → Resin is the main spatial stack; Haze and Stone are readable fills within components, while Mirage separates a modal from the rest of the interface.
34
+ Crystal has six first-class materials: Plastic, Frost, Resin, Haze, Stone, and Mirage. Each has its own named recipe and reusable primitive. Plastic → Frost → Resin is the main spatial stack. Haze and Stone are readable fills within components, and Mirage separates a modal from the rest of the interface.
35
35
 
36
36
  | Crystal material | Previous name / inspiration | Crystal adaptation |
37
37
  |---|---|---|
@@ -42,7 +42,7 @@ Crystal has **six first-class materials: Plastic, Frost, Resin, Haze, Stone, and
42
42
  | Stone | Protected labels | 55% light / 60% dark backing, feathered like Haze, with crisp labels |
43
43
  | Mirage | Smoke / modal scrim | Chromatic diffusion of the underlying scene, darkened behind a focused modal |
44
44
 
45
- Plastic, Frost and Resin are based in and inspired by their respective platform materials, then adjusted to work together as Crystal. They are not vendor-certified implementations. Microsoft’s [Mica](https://learn.microsoft.com/en-us/windows/apps/design/style/mica) describes an opaque contextual base; [Acrylic](https://learn.microsoft.com/en-us/windows/apps/design/style/acrylic) combines tint, diffusion and texture; Apple’s [material guidance](https://developer.apple.com/design/human-interface-guidelines/materials) informs Resin’s floating functional role. Haze, Stone and Mirage are Crystal’s adaptations of content fills, readability veils and modal scrims.
45
+ Plastic, Frost and Resin are based on and inspired by their respective platform materials, then adjusted to work together as Crystal. They are not vendor-certified implementations. Microsoft’s [Mica](https://learn.microsoft.com/en-us/windows/apps/design/style/mica) describes an opaque contextual base; [Acrylic](https://learn.microsoft.com/en-us/windows/apps/design/style/acrylic) combines tint, diffusion and texture; Apple’s [material guidance](https://developer.apple.com/design/human-interface-guidelines/materials) informs Resin’s floating functional role. Haze, Stone and Mirage are Crystal’s adaptations of content fills, readability veils and modal scrims.
46
46
 
47
47
  ## Material assignment
48
48
 
@@ -57,21 +57,21 @@ Plastic, Frost and Resin are based in and inspired by their respective platform
57
57
 
58
58
  Resin renders at a fixed 20% fill opacity in both modes, independent of the Frost base tint control. Frost retains its existing recipe (45% fill from the recommended 35% base). Text, rims and shadows retain their opacity. Label protection is 55% in light mode and 60% in dark mode, with the dark backing strengthened to preserve contrast over bright backdrops at this lower glass opacity. Opaque accessibility fallbacks remain fully opaque. This deliberately differs from the original recipes preserved in `reference/`.
59
59
 
60
- The persistent Frost task frame is an intentional Crystal hybrid, not a claim of strict Microsoft placement conformance. One frame can contain several softened content wells; avoid nesting independently blurred panes. All three live scenes show that same stack.
60
+ The persistent Frost task frame is a Crystal hybrid and does not claim strict Microsoft placement conformance. One frame can contain several softened content wells; avoid nesting independently blurred panes. All three live scenes show that same stack.
61
61
 
62
62
  Do not apply opacity to an entire pane containing text. Do not stack backdrop blur on adjacent cards or every message; the content recipe feathers only its own background paint. Do not sample the desktop, capture other windows or duplicate private content into canvases to create a refraction effect. This implementation provides CSS blur, tint, texture, highlights and shadows; it does not implement native optical lensing.
63
63
 
64
64
  ## Material recipe values
65
65
 
66
- The numbers every material resolves to, generated from `tokens/crystal.json`. This table
67
- is the authority; where the prose above describes a technique, these are the values that
68
- technique uses.
66
+ This table lists the numbers every material resolves to, generated from
67
+ `tokens/crystal.json`. It is the authority: where the prose above describes a technique,
68
+ these are the values that technique uses.
69
69
 
70
70
  <!-- generated:material-recipes -->
71
71
 
72
72
  | Material | Diffusion | Fill |
73
73
  |---|---|---|
74
- | **Plastic** | Opaque. No backdrop filter at all. | — |
74
+ | **Plastic** | Opaque. No backdrop filter at all. | None |
75
75
  | **Frost** | 40px blur, 125% saturation | grain 0.045 |
76
76
  | **Resin** | 20px blur, 165% saturation | fixed 20% fill, both modes |
77
77
  | **Haze** | 80% content fill | 1.95px feather |
@@ -81,9 +81,9 @@ technique uses.
81
81
 
82
82
  ## Haze: integrated reading surfaces
83
83
 
84
- Haze is Crystal’s named content material, previously called Solid. Its normal recipe now uses **80% fill opacity** and a **1.95px edge feather**, so the underlying Frost or Resin contributes color rather than ending abruptly at a sheet of blank fill. Plastic → Frost → Resin remains the governing hierarchy; a reading fill within a Resin component is part of that component.
84
+ Haze is Crystal’s named content material, previously called Solid. Its normal recipe uses 80% fill opacity and a 1.95px edge feather, so the underlying Frost or Resin contributes color rather than ending abruptly at a sheet of blank fill. Plastic → Frost → Resin remains the governing hierarchy; a reading fill within a Resin component is part of that component.
85
85
 
86
- The `.cr-haze`, `.cr-well`, `.cr-bubble`, `.cr-content-fill` and `.cr-dialog` primitives paint the fill on an isolated, non-interactive `::before` layer. Only that paint layer receives `filter: blur(1.95px)`; text, icons, selection, hit areas and focus outlines stay sharp and fully opaque. The broad interior remains at 80%, while the narrow perimeter feathers into its surroundings. Keep at least **12px of padding** between readable content and the feathered edge, including around rounded corners. Do not clip the feather with an ancestor’s overflow unless deliberately necessary for media.
86
+ The `.cr-haze`, `.cr-well`, `.cr-bubble`, `.cr-content-fill` and `.cr-dialog` primitives paint the fill on an isolated, non-interactive `::before` layer. Only that paint layer receives `filter: blur(1.95px)`; text, icons, selection, hit areas and focus outlines stay sharp and fully opaque. The broad interior remains at 80%, while the narrow perimeter feathers into its surroundings. Keep at least 12px of padding between readable content and the feathered edge, including around rounded corners. Do not clip the feather with an ancestor's overflow unless media requires the clip.
87
87
 
88
88
  Neutral and tinted message surfaces both follow this recipe. The Harbor palette uses stronger supporting ink and a deeper authored-message fill to retain contrast with the added transparency. This is separate from the palette’s solid action/status colors. Actual input controls, status badges and consequential action buttons retain explicit boundaries and their protected color pairs; their surrounding content surface uses the softened fill. Stone retains its own label-backing opacity, separate from Haze.
89
89
 
@@ -93,7 +93,7 @@ The contrast model tests 80% interior fill and a conservative 79% reading-area b
93
93
 
94
94
  ## Stone: protected labels
95
95
 
96
- Stone is the lighter-density backing shown inside Resin controls. It now has the **same 1.95px background feather as Haze**, while retaining **55% opacity in light mode and 60% in dark mode**. Haze remains 80%; these recipes are deliberately independent.
96
+ Stone is the lighter-density backing shown inside Resin controls. It has the same 1.95px background feather as Haze, with 55% opacity in light mode and 60% in dark mode. Haze remains 80%. The two recipes are independent.
97
97
 
98
98
  `.cr-stone` paints `--cr-stone-fill` on an isolated `::before` layer with `--cr-stone-feather`; text and icons are neither blurred nor faded. The dock’s `.cr-dock-inner` uses the same recipe. Keep readable content at least 12px from the feathered perimeter, counting both group and button padding. Shapes, marks and labels continue to convey state beyond color. Reduced transparency restores an opaque, unfeathered backing; forced colors uses system colors.
99
99
 
@@ -101,15 +101,15 @@ Stone’s contrast model includes Resin’s 20% fill, optical highlights and a c
101
101
 
102
102
  ## Mirage: modal separation
103
103
 
104
- Mirage is the named material formerly called Smoke. Its recipe blends the actual colors underneath into a dark, chromatic backdrop: **28px blur → 165% saturation → 88% brightness**, followed by a **38% `#111525` tint**. Broad diffusion merges shapes into color fields; saturation preserves their color through the dark veil. No fixed brand gradient, hue rotation, screenshot capture or duplicate page render is used. A Haze modal sits above it and remains crisp. Mirage is not a content surface and must not carry ordinary reading text.
104
+ Mirage is the named material formerly called Smoke. Its recipe blends the actual colors underneath into a dark, chromatic backdrop: 28px blur, then 165% saturation, then 88% brightness, followed by a 38% `#111525` tint. Broad diffusion merges shapes into color fields, and saturation preserves their color through the dark veil. No fixed brand gradient, hue rotation, screenshot capture or duplicate page render is used. A Haze modal sits above it and remains crisp. Mirage is not a content surface and must not carry ordinary reading text.
105
105
 
106
- The working native dialog uses Mirage through `::backdrop`. `.cr-mirage` exposes the same paint recipe for application-owned overlay implementations; it does not itself implement modal behavior, positioning or focus management. Products must provide actual modality, keyboard containment, a named dialog, dismissal and focus return. The preview’s **Preview Mirage** button opens the real dialog. Reduced transparency removes diffusion and color filtering and uses a stronger **64% `#111525` scrim**; the same scrim is the unsupported-filter fallback. Modal separation remains visible. The preview also includes a live artwork comparison: toggle Mirage to see the real underlying colors before and after the filter. Changing the palette changes the artwork and therefore the resulting chromatic blur.
106
+ The working native dialog uses Mirage through `::backdrop`. `.cr-mirage` exposes the same paint recipe for application-owned overlay implementations; it does not itself implement modal behavior, positioning or focus management. Products must provide actual modality, keyboard containment, a named dialog, dismissal and focus return. The preview’s **Preview Mirage** button opens the real dialog. Reduced transparency removes diffusion and color filtering and uses a stronger 64% `#111525` scrim; the same scrim is the unsupported-filter fallback. Modal separation remains visible. The preview also includes a live artwork comparison: toggle Mirage to see the real underlying colors before and after the filter. Changing the palette changes the artwork and therefore the resulting chromatic blur.
107
107
 
108
108
  ## Plastic: Mica inspiration and adaptation
109
109
 
110
110
  Plastic adapts Mica’s opacity, subtle contextual tint, light/dark awareness, and a neutral inactive-window fallback. The active/inactive study demonstrates those properties: the window remains fully opaque, and the context’s shapes do not pass through it. The browser uses a preselected product color impression; it does not access desktop wallpaper. Native implementations should use supported OS facilities for wallpaper influence and activation behavior.
111
111
 
112
- The broader Frost/Resin study contains deliberately vivid **artwork above the Plastic foundation** so blur can be inspected. That artwork is content, not a claim that native Mica itself paints saturated wallpaper detail. The ordinary app preview keeps a restrained contextual base and puts stronger colors into accents and content. [Fluent material roles](https://fluent2.microsoft.design/material).
112
+ The broader Frost/Resin study places vivid artwork above the Plastic foundation so blur can be inspected. That artwork is content. It does not claim that native Mica paints saturated wallpaper detail. The ordinary app preview keeps a restrained contextual base and puts stronger colors into accents and content. [Fluent material roles](https://fluent2.microsoft.design/material).
113
113
 
114
114
  The reusable `.cr-plastic[data-window-active="false"]` state removes contextual gradients and uses the opaque `--cr-plastic-inactive` token: `#f1f1f3` in light mode and `#202126` in dark. These are Crystal fallback values, not vendor constants. The host supplies activation state; the preview uses an explicit switch. Active tint is bounded by the atmosphere control: the two gradient alpha maxima are 21.6%/17.1% in light mode and 26.1%/20.7% in dark, always composited over an opaque canvas.
115
115
 
@@ -135,13 +135,13 @@ At 100% elevation, the reference geometry is shown below. The recommended defaul
135
135
  | Supporting panel | 0 3px 5px | 0 14px 28px | Inset top highlight |
136
136
  | Floating controls | 0 4px 7px | 0 20px 40px | Top highlight and lower inset contour |
137
137
 
138
- Shadow colors adapt to mode. The elevation control scales offsets and blur from 60–150%; hierarchy remains ordered. Depth is a visual relationship, not a z-index value. Products must also manage their actual overlay stack and focus order. Dark mode uses contours and tonal separation alongside shadows.
138
+ Shadow colors adapt to mode. The elevation control scales offsets and blur from 60% to 150%; hierarchy remains ordered. Depth is a visual relationship and sets no z-index, so products must also manage their actual overlay stack and focus order. Dark mode uses contours and tonal separation alongside shadows.
139
139
 
140
140
  ## Fallbacks
141
141
 
142
142
  Reduce transparency replaces supporting materials with opaque content surfaces, removes grain/blur, and restores a visible outline. CSS also honors reduced-transparency preferences where supported and falls back when backdrop filtering is unavailable. Reduced motion removes movement; forced colors use system colors and borders. None of these modes hides essential content.
143
143
 
144
- Support claims must be verified on actual target browsers/devices. A native implementation should use supported compositor APIs where appropriate and deliberately adapt the custom hierarchy elsewhere. The browser preview does not prove native rendering, energy performance or accessibility parity.
144
+ Support claims must be verified on actual target browsers/devices. A native implementation should use supported compositor APIs where appropriate and adapt the custom hierarchy elsewhere. The browser preview does not prove native rendering, energy performance or accessibility parity.
145
145
 
146
146
  ## Performance and composition
147
147
 
@@ -149,23 +149,23 @@ Keep backdrop filters confined to a few bounded surfaces, avoid continuous blur
149
149
 
150
150
  ## Spacing and the layout shell
151
151
 
152
- Two scales that had no tokens until the layout components needed them. Neither is a new design decision: they name what Crystal's own shell already does, so something other than the preview can reach the values.
152
+ This section defines two scales as tokens. They name what Crystal's own shell already does, so something other than the preview can reach the values. Neither is a new design decision.
153
153
 
154
- **The spacing scale** is the 4px rhythm, tied at two points to the reading rhythm so it is not an arbitrary ladder: `md` is the 16px reading size and `lg` is the 24px leading, which makes a `lg` gap exactly one blank line between blocks.
154
+ **The spacing scale** is the 4px rhythm, tied at two points to the reading rhythm: `md` is the 16px reading size and `lg` is the 24px leading, so a `lg` gap is exactly one blank line between blocks.
155
155
 
156
156
  | Step | `2xs` | `xs` | `sm` | `md` | `lg` | `xl` | `2xl` |
157
157
  |---|---|---|---|---|---|---|---|
158
158
  | Value | 4px | 8px | 12px | 16px | 24px | 32px | 48px |
159
159
 
160
- `--cr-space` is a different thing and stays: it is the density-aware padding step, 20px comfortable and 14px compact. The spacing scale does not vary with density, palette or mode.
160
+ `--cr-space` is separate and stays. It is the density-aware padding step, 20px comfortable and 14px compact. The spacing scale does not vary with density, palette or mode.
161
161
 
162
- **The breakpoints** are where the shell already changes: `sm` 600px, `md` 850px, `lg` 1150px, `xl` 1500px. They cannot be custom properties, because a custom property is not usable inside a media query — libraries compile against them from the generated exports.
162
+ **The breakpoints** are where the shell already changes: `sm` 600px, `md` 850px, `lg` 1150px, `xl` 1500px. They cannot be custom properties, because a custom property is not usable inside a media query. Libraries compile against them from the generated exports.
163
163
 
164
- **The shell** is a 1536px ceiling with gutters that step down at those breakpoints — 44px at `lg` and above, 26px between `sm` and `lg`, 18px below `sm` — and a 920px reading column inside it, which is what keeps a line of prose a comfortable length.
164
+ **The shell** is a 1536px ceiling with gutters that step down at those breakpoints: 44px at `lg` and above, 26px between `sm` and `lg`, and 18px below `sm`. Inside it is a 920px reading column, which keeps a line of prose a comfortable length.
165
165
 
166
166
  ## The type scale
167
167
 
168
- Crystal specifies a reading rhythm — Manrope at 16/24 — and the scale is derived from it rather than written down. Each step is a **ratio** of the reading size, so moving `typography.readingSize` moves all six instead of leaving six literals behind.
168
+ Crystal specifies a reading rhythm, Manrope at 16/24, and the scale is derived from it. Each step is a ratio of the reading size, so changing `typography.readingSize` changes all six steps and no step is a literal.
169
169
 
170
170
  | Step | Ratio | Size | Leading | Tracking |
171
171
  |---|---|---|---|---|
@@ -176,30 +176,30 @@ Crystal specifies a reading rhythm — Manrope at 16/24 — and the scale is der
176
176
  | `body` | 1 | 16px | 1.5 | 0 |
177
177
  | `caption` | 0.8125 | 13px | 1.45 | 0 |
178
178
 
179
- The scale is deliberately modest. Crystal's hierarchy is carried by weight and material as much as by size, and a dramatic scale fights that.
179
+ The scale is modest, because Crystal's hierarchy is carried by weight and material as much as by size, and a dramatic scale competes with both.
180
180
 
181
- Leading tightens as size grows — large text needs proportionally less to read as a block rather than as a list of lines — and tracking tightens with it, because default tracking reads loose at display sizes.
181
+ Leading tightens as size grows, because large text needs proportionally less leading to read as a block rather than as a list of lines. Tracking tightens with it, because default tracking reads loose at display sizes.
182
182
 
183
- The steps reach CSS as `--cr-text-<step>-size`, `-leading` and `-tracking`. **Density tightens leading and never the size**: shrinking text at higher density trades legibility for space, which Crystal does not do — density tightens spacing and never touches a 44px target or a reading size.
183
+ The steps reach CSS as `--cr-text-<step>-size`, `-leading` and `-tracking`. Density tightens leading and never the size. Shrinking text at higher density trades legibility for space, so density tightens spacing and never changes a 44px target or a reading size.
184
184
 
185
185
  **The level and the step are chosen separately.** A heading's level is its position in the document outline; its step is a design decision. A component where `level={2}` also means "medium" forces a choice between a correct outline and a correct appearance, and products reliably choose appearance.
186
186
 
187
187
  ## Scrolling
188
188
 
189
- A scrollbar belongs to the material it scrolls, not to the operating system. There are two, and which one a surface takes follows the hierarchy rather than taste.
189
+ A scrollbar belongs to the material it scrolls. There are two scrollbars, and the hierarchy decides which one a surface takes.
190
190
 
191
191
  | Class | Material | Thumb | Use it on |
192
192
  |---|---|---|---|
193
193
  | `.cr-scroll-frost` | Frost | palette ink at 55% | Panels, side navigation, long reading surfaces, and dialogs. Frost is the intermediate surface, so its scrollbar belongs to the panel the way the panel's own text does. |
194
194
  | `.cr-scroll-resin` | Resin | palette primary at 80% | Floating control planes, menus, popovers, and compact or horizontal scrollers such as `.cr-table-scroll`. Resin is the control plane, so a scrollbar there is tinted like a control. |
195
195
 
196
- `.cr-scroll` carries the behaviour both build on and is worth applying to any scroll container on its own:
196
+ `.cr-scroll` carries the behaviour both build on, and can be applied on its own to any scroll container:
197
197
 
198
- - `overscroll-behavior: contain` stops scroll chaining, so a swipe that reaches the end of a scroller does not carry on into the page underneath. This is invisible with a mouse and immediately obvious on a phone.
199
- - `scrollbar-gutter: stable` keeps content from shifting when a vertical scrollbar appears. It is not applied to horizontal-only scrollers, where the gutter would reserve space against a scrollbar that never arrives. A dialog takes `stable both-edges` so centred content stays centred.
198
+ - `overscroll-behavior: contain` stops scroll chaining, so a swipe that reaches the end of a scroller does not carry on into the page underneath. The effect shows on a phone and does not show with a mouse.
199
+ - `scrollbar-gutter: stable` keeps content from shifting when a vertical scrollbar appears. It is not applied to horizontal-only scrollers, where the gutter would reserve space for a scrollbar that never appears. A dialog takes `stable both-edges` so centred content stays centred.
200
200
  - `touch-action: pan-x pan-y` leaves the browser's own gesture handling in place, so momentum and rubber-banding still feel native.
201
201
 
202
- A horizontal scroller is the one case that needs care. Setting `overflow-x: auto` makes `overflow-y` compute to `auto` as well, so a gutter is reserved for a vertical scrollbar that can never appear — 12px lost at the inline edge.
202
+ A horizontal scroller needs one more declaration. Setting `overflow-x: auto` makes `overflow-y` compute to `auto` as well, so a gutter is reserved for a vertical scrollbar that can never appear, and 12px is lost at the inline edge.
203
203
 
204
204
  **Add `.cr-scroll-x` to say a scroller is horizontal-only.** CSS cannot work it out, so it has to be declared:
205
205
 
@@ -207,33 +207,33 @@ A horizontal scroller is the one case that needs care. Setting `overflow-x: auto
207
207
  <div class="cr-scroll-resin cr-scroll-x">…</div>
208
208
  ```
209
209
 
210
- It clips the block axis and releases the gutter, which is the same treatment `.cr-table-scroll` gets by being excluded from the gutter rule. `verify-scroll` fails any container that scrolls across but not down while still holding a gutter, so forgetting it is caught rather than merely costly.
210
+ It clips the block axis and releases the gutter, which is the same treatment `.cr-table-scroll` gets by being excluded from the gutter rule. `verify-scroll` fails any container that scrolls across but not down while still holding a gutter, so a missing `.cr-scroll-x` is caught.
211
211
 
212
212
  Both thumbs clear 3:1 against every Crystal surface in all six palettes and both modes; the token gate asserts it. Under reduced transparency and forced colors the thumb goes solid and takes the system or outline colour.
213
213
 
214
214
  ### Edge fades
215
215
 
216
- A scroll area fades its content where there is more beyond the edge — 24px, on the scrolling axis, at whichever ends have content past them. A fade says "there is more this way" on a touch device, where the scrollbar is an overlay that is not there until you are already scrolling.
216
+ A scroll area fades its content where there is more beyond the edge. The fade is 24px, on the scrolling axis, at whichever ends have content past them. A fade says "there is more this way" on a touch device, where the scrollbar is an overlay that appears only once you are scrolling.
217
217
 
218
- The fade is a **mask**, not a painted overlay. What an overlay would have to paint is the surrounding material, and a colour approximating a translucent material over an unknown backdrop is wrong at every edge except the one it was sampled at. A mask lets the real material show through.
218
+ The fade is a mask, not a painted overlay. An overlay would have to paint the surrounding material, and a colour approximating a translucent material over an unknown backdrop is wrong at every edge except the one it was sampled at. A mask lets the real material show through.
219
219
 
220
- Set `data-cr-scroll` to `start`, `end` or `both` — which edges have content beyond them — together with `data-cr-scroll-axis` of `x` or `y`. `start` means the container is *at* its start, so only the far edge fades. Without the attribute nothing fades, so a container with no runtime driving it is unmasked rather than permanently faded at both ends. Start and end are logical: the horizontal gradient turns around in right-to-left.
220
+ Set `data-cr-scroll` to `start`, `end` or `both`, which says which edges have content beyond them, together with `data-cr-scroll-axis` of `x` or `y`. `start` means the container is *at* its start, so only the far edge fades. Without the attribute nothing fades, so a container with no runtime driving it is unmasked rather than permanently faded at both ends. Start and end are logical: the horizontal gradient turns around in right-to-left.
221
221
 
222
- A mask fades the whole element — its own fill and border included — so the fade belongs on the element that scrolls. A material surface that also scrolls puts its material on a wrapper, or the panel dissolves along with the content it is holding.
222
+ A mask fades the whole element, its own fill and border included, so the fade belongs on the element that scrolls. A material surface that also scrolls puts its material on a wrapper. Otherwise the panel fades along with the content it holds.
223
223
 
224
- The same token is the container's `scroll-padding`, which is what keeps this accessible. Browsers scroll a newly focused element into view respecting scroll padding, so a focus ring can never come to rest underneath the fade — Crystal does not blur focus, and fading one would be the same defect by another route. Forced colors removes the fade entirely.
224
+ The same token is the container's `scroll-padding`, which keeps the fade accessible. Browsers respect scroll padding when they scroll a newly focused element into view, so a focus ring never comes to rest underneath the fade. Crystal does not blur focus, and a faded focus ring would be the same defect. Forced colors removes the fade entirely.
225
225
 
226
- What a native scrollbar cannot carry is the material itself — `backdrop-filter` has no effect on one, and the standard properties expose only two colours and a coarse width. A surface that needs the material in full uses the **scroll area** component, which draws its thumb as a real element.
226
+ A native scrollbar cannot carry the material itself: `backdrop-filter` has no effect on one, and the standard properties expose only two colours and a coarse width. A surface that needs the material in full uses the **scroll area** component, which draws its thumb as a real element.
227
227
 
228
228
  ## Acceptance
229
229
 
230
- Inspect light/dark, every palette, strongest atmosphere, both Frost tint extremes, reduced effects, narrow layouts, long labels, text zoom, keyboard focus and relevant backdrop extremes. The material comparison board intentionally places all samples over the same saturated motif so differences remain visible. Compare silhouettes and depth relationships, not only pixel similarity.
230
+ Inspect light/dark, every palette, strongest atmosphere, both Frost tint extremes, reduced effects, narrow layouts, long labels, text zoom, keyboard focus and relevant backdrop extremes. The material comparison board places all samples over the same saturated motif so differences remain visible. Compare silhouettes and depth relationships as well as pixel similarity.
231
231
 
232
232
  ## Resin with Haze: interactive and compact surfaces
233
233
 
234
- Resin is the primary background for buttons and all interaction surfaces. Its body stays at 20% fill with the existing blur, saturation, illuminated rim and elevation. When contrast requires protection, put an 80% Haze reading fill inside that shell, with the existing 1.95px feather and an 8px visible Resin perimeter, exported as `--cr-haze-inset`. That inset is a token rather than a number each library retypes: the fill and its feather were always exported, the inset was not, and a library can carry every Haze token and still paint no fill at all. Keep text sufficiently inset from the feather. The adjustable preview always uses this protected construction.
234
+ Resin is the primary background for buttons and all interaction surfaces. Its body stays at 20% fill with the existing blur, saturation, illuminated rim and elevation. When contrast requires protection, put an 80% Haze reading fill inside that shell, with the existing 1.95px feather and an 8px visible Resin perimeter, exported as `--cr-haze-inset`. The inset is exported as a token, like the fill and its feather, so that no library retypes the number. Without the inset a library can carry every other Haze token and still paint no fill at all. Keep text sufficiently inset from the feather. The adjustable preview always uses this protected construction.
235
235
 
236
- This same composition is required for small information displays that sit on content — labels, tags, badges and keyboard caps. Transient overlays — tooltips, toasts, menus, dropdowns, flyouts and popovers — are **Frost** (R15e): they open over content, so they are intermediate panels rather than compact controls, and their reading content sits on Haze inside them. It does not replace the structural Plastic → Frost → Resin hierarchy or turn every large component into Resin. Stone remains a named material with its own standalone specifications; compact UI labels now choose Resin/Haze instead of an isolated Stone slab.
236
+ This same composition is required for small information displays that sit on content: labels, tags, badges and keyboard caps. Transient overlays (tooltips, toasts, menus, dropdowns, flyouts and popovers) are **Frost** (R15e). They open over content, so they are intermediate panels rather than compact controls, and their reading content sits on Haze inside them. The composition does not replace the structural Plastic → Frost → Resin hierarchy or turn every large component into Resin. Stone remains a named material with its own standalone specifications; compact UI labels choose Resin/Haze instead of an isolated Stone slab.
237
237
 
238
238
  Optical highlights remain below the Haze reading fill, including during animation. They can cross the exposed Resin perimeter without bleaching the protected label background. Contrast models check this actual ordering across all six palettes, both modes and RGB-corner backdrops.
239
239
 
@@ -246,84 +246,84 @@ Toolbars, segmented controls and tab groups share one Resin/Haze surface. Their
246
246
 
247
247
  ## Material definition on small and nested surfaces
248
248
 
249
- A small Resin control over a Haze reading well can lose the color and depth visible in the larger material studies. Keep the 20% Resin body and 80% inset Haze fill. Supply restrained contextual light **under** the Haze rather than increasing body opacity or painting the label. The control optical layer mixes glow at 12.6% and decorative color at 8.4% in light mode; dark mode uses 9.8% and 7% (a 30% reduction from the previous rim color opacity). On buttons and action links, inset the chromatic paint by 2px and feather that paint by 2px beneath Haze, so the color blends inward into the content fill. Keep the outer optical contour and all text crisp. Palette specimen colors and selection marks are not blurred. These are local gradient maxima, not changes to the global atmosphere or material opacity. Do not increase saturation to compensate for every additional nested surface. The approved material studies remain the visual authority.
249
+ A small Resin control over a Haze reading well can lose the color and depth visible in the larger material studies. Keep the 20% Resin body and 80% inset Haze fill. Supply restrained contextual light under the Haze rather than increasing body opacity or painting the label. The control optical layer mixes glow at 12.6% and decorative color at 8.4% in light mode; dark mode uses 9.8% and 7% (a 30% reduction from the previous rim color opacity). On buttons and action links, inset the chromatic paint by 2px and feather that paint by 2px beneath Haze, so the color blends inward into the content fill. Keep the outer optical contour and all text crisp. Palette specimen colors and selection marks are not blurred. These values are local gradient maxima and leave the global atmosphere and material opacity unchanged. Do not increase saturation to compensate for every additional nested surface. The approved material studies remain the visual authority.
250
250
 
251
251
  Use a luminous outer contour and soft paired shadows instead of a dark hairline around every control. Text fields have a circular Resin/Haze field-state badge within the Resin surround; keyboard focus still adds a full, clearly visible ring. Checkboxes and radios use contained selection marks, switches retain a contrast-bearing thumb, and sliders use a value-driven track and marked glass thumb. Keep labels and native semantics. Status badges use their semantic symbol and words, with the tested semantic ink/surface pair behind the symbol, rather than a colored perimeter stroke. Selection, errors and focus must remain distinguishable without color.
252
252
 
253
- When adapting controls to different sizes, preserve enough exposed Resin to show the rim and enough protected Haze to keep text crisp. Do not blur the element or its foreground. Opaque, reduced-transparency and forced-color modes remain functional alternatives. Validate actual composed controls in both modes and at narrow widths; a beautiful isolated material swatch does not establish component fidelity.
253
+ When adapting controls to different sizes, preserve enough exposed Resin to show the rim and enough protected Haze to keep text crisp. Do not blur the element or its foreground. Opaque, reduced-transparency and forced-color modes remain functional alternatives. Validate actual composed controls in both modes and at narrow widths. An isolated material swatch does not establish component fidelity.
254
254
 
255
255
  ## Light
256
256
 
257
257
  Every material has an optical behaviour, and the behaviour follows from what the material
258
- physically is. These are rules, not effects.
258
+ physically is. Each behaviour in this table is a rule.
259
259
 
260
260
  | Material | What it does with light | Why |
261
261
  | --- | --- | --- |
262
- | **Plastic** | **Emits.** Carries its palette's glow over the atmosphere tint, drifting slowly. | Opaque things cannot bend light. A foundation that refracted would be claiming a transparency it does not have. |
263
- | **Frost** | **Refracts broadly.** A slow, low-amplitude wander of colour temperature across the surface. | At 40px of diffusion nothing sharp survives. Light through frosted glass shows you colour, not shape — so Frost's refraction is chromatic and formless. |
262
+ | **Plastic** | **Emits.** Carries its palette's glow over the atmosphere tint, drifting slowly. | Plastic is opaque, and an opaque material cannot bend light, so the foundation does not refract. |
263
+ | **Frost** | **Refracts broadly.** A slow, low-amplitude wander of colour temperature across the surface. | At 40px of diffusion nothing sharp survives. Light through frosted glass carries colour and loses shape, so Frost's refraction is chromatic and formless. |
264
264
  | **Resin** | **Refracts sharply.** Dispersion concentrated at the rim, with the specular band tracking interaction. | At 20px, detail survives. Resin is the front layer and the one the user is closest to, so its optics are the most defined of the three. |
265
- | **Haze** | **Breathes.** Its boundary travels outward and inward. | Haze *is* its feathered edge. A fill that pulses in opacity is not an edge that moves; it is the same edge getting fainter. |
265
+ | **Haze** | **Breathes.** Its boundary travels outward and inward. | Haze is defined by its feathered edge, so the edge is what moves. A fill that pulses in opacity leaves the edge where it is and makes it fainter. |
266
266
  | **Stone** | **Breathes, more tightly.** The same boundary motion at a shorter period. | Stone is a label backing, so its edge is smaller and closer to text. It moves less far and settles sooner. |
267
267
  | **Mirage** | **Flows.** A slow current while a dialog is open. | The scrim is the only surface with nothing above it competing for attention. |
268
268
 
269
- Resin and Frost differ in **amount and in kind**, not merely in intensity. Turning Resin's
270
- dispersion down does not produce Frost; it produces weak Resin. The diffusion radius
271
- decides which is correct.
269
+ Resin and Frost differ in kind as well as in amount. Turning Resin's dispersion down
270
+ produces weak Resin and does not produce Frost. The diffusion radius decides which is
271
+ correct.
272
272
 
273
273
  ### Light reaches the shadow
274
274
 
275
275
  The light a material refracts is the light that reaches the surface beneath it, so a
276
276
  Crystal shadow is not neutral grey. The active palette's companion mixes into the shadow
277
- ink — 34% in light mode, 40% in dark.
277
+ ink at 34% in light mode and 40% in dark.
278
278
 
279
279
  **The mix is on the colour only.** Each shadow layer keeps its authored alpha exactly,
280
- because a shadow that is tinted must not also become heavier. Prism's content shadow moves
281
- from `rgba(39,24,68,.15)` to `rgba(107,40,112,.15)`: the same weight, carrying colour.
280
+ because a tinted shadow must not also become heavier. Prism's content shadow moves from
281
+ `rgba(39,24,68,.15)` to `rgba(107,40,112,.15)`: the alpha is the same and the colour is
282
+ tinted.
282
283
 
283
284
  ### Motion at rest
284
285
 
285
- **Deferred.** This subsection describes the ambient tier Crystal 2.0 specified, built,
286
- measured and then withdrew at Meridian's direction (R22; §8 of the library contract). It is
287
- kept as the record of what will return, not as a rule in force: **nothing in 2.x moves at
288
- rest**, and the optical behaviours in the table above run only for the duration of a
289
- motion a person started. Plastic's glow is a material property and stays; its drift was
290
- ambient and does not.
286
+ **Deferred.** This subsection describes the ambient tier that Crystal 2.0 specified, built
287
+ and measured, and then withdrew at Meridian's direction (R22; §8 of the library contract).
288
+ It is kept as the record of what will return and is not a rule in force. **Nothing in 2.x
289
+ moves at rest.** The optical behaviours in the table above run only for the duration of a
290
+ motion a person started. Plastic's glow is a material property and stays. Its drift was
291
+ ambient and is withdrawn.
291
292
 
292
- What was specified, for when it returns: these behaviours are the material's **rest
293
- state**, not a response to being used. A Crystal surface is alive before anyone touches it,
294
- and interaction *adds* energy rather than starting the effect: rest, faster on hover,
295
- faster still on press, decaying back.
293
+ What was specified, for when it returns: these behaviours are the material's rest state. A
294
+ Crystal surface shows them before anyone touches it, and interaction adds energy to an
295
+ effect that is already running: the rest rate, faster on hover, faster still on press, then
296
+ decaying back.
296
297
 
297
- The single exception is text entry. A field being typed into is the one place where motion
298
- genuinely competes with the task, so ambient pauses there and nowhere else.
298
+ The single exception is text entry. Motion competes with the task in a field that is being
299
+ typed into, so ambient motion pauses there and nowhere else.
299
300
 
300
- Three rules bound all of it. It runs on the rim and the fill and **never on a surface being
301
- read** — the same argument that makes Resin lens at its edge rather than ripple through its
302
- middle. It is the **first thing `prefers-reduced-motion` removes**, entirely rather than
303
- gently. And it is an **enhancement on top of a complete floor**: with the shader layer
304
- unavailable and ambient disabled, every page renders exactly its reference baseline, which
305
- is what gate G8 proves.
301
+ Three rules bound the ambient tier. It runs on the rim and the fill and never on a surface
302
+ being read, for the same reason that Resin lenses at its edge and does not ripple through
303
+ its middle. It is the first thing `prefers-reduced-motion` removes, and it is removed
304
+ entirely. It is an enhancement on top of a complete floor: with the shader layer
305
+ unavailable and ambient disabled, every page renders exactly its reference baseline, and
306
+ gate G8 proves it.
306
307
 
307
308
 
308
309
  ## Resin never contains Resin
309
310
 
310
311
  **A Resin surface may not contain another Resin surface.** When something has to sit on
311
- top of a Resin element — a label, a badge, a nested control, a content area — that upper
312
- layer becomes a **Haze content fill**. This is a hard rule, and it is the one adopters
313
- break most often.
312
+ top of a Resin element (a label, a badge, a nested control or a content area), that upper
313
+ layer becomes a Haze content fill. This is a hard rule, and it is the one adopters break
314
+ most often.
314
315
 
315
316
  ### Why
316
317
 
317
318
  Resin is a backdrop filter: it samples what is behind it, blurs at 20px and saturates to
318
- 165%. Nest a second Resin surface inside the first and the inner one samples *the already
319
- blurred output of the outer one*. The result is a blur of a blur — contrast collapses,
320
- edge definition disappears, and any text on the inner surface is sitting on a field of
321
- mush that changes as the page scrolls behind it.
319
+ 165%. A second Resin surface nested inside the first samples the already blurred output of
320
+ the outer one. The result is a blur of a blur. Contrast collapses, edge definition
321
+ disappears, and any text on the inner surface sits on a smeared field that changes as the
322
+ page scrolls behind it.
322
323
 
323
- This is the specific, repeatedly documented failure of translucent interface materials
324
- generally: stacked translucency reads as beautiful in a static mock and as illegible in
325
- use. Crystal's answer is not to soften Resin — that would regress the material — but to
326
- change what the upper layer is made of.
324
+ This is a repeatedly documented failure of translucent interface materials: stacked
325
+ translucency looks good in a static mock and is illegible in use. Crystal changes what the
326
+ upper layer is made of. Softening Resin would regress the material.
327
327
 
328
328
  ### The fix is always the upper layer
329
329
 
@@ -334,12 +334,12 @@ change what the upper layer is made of.
334
334
  | A content area in a Resin panel | Nested `.cr-resin` | `.cr-haze` recessed into the frame |
335
335
 
336
336
  Never weaken the outer Resin to make a nested one legible. Resin's parameters are fixed
337
- at 20px blur, 165% saturation and a 20% fill; changing them to accommodate a composition
338
- that should not exist trades a real material for a local convenience.
337
+ at 20px blur, 165% saturation and a 20% fill, and they do not change to accommodate a
338
+ composition that should not exist.
339
339
 
340
340
  ### How it is enforced
341
341
 
342
- The rule is enforced in CSS, so a mistake is corrected rather than merely reported:
342
+ The rule is enforced in CSS, which corrects a mistake where it occurs:
343
343
 
344
344
  ```css
345
345
  /* Any control inside a Resin surface loses its own backdrop filter and gets its
@@ -354,19 +354,19 @@ The rule is enforced in CSS, so a mistake is corrected rather than merely report
354
354
  It is also checked. `npm run audit:materials` loads every page in the site, reads the
355
355
  *computed* backdrop filter of every element, classifies each surface by its blur radius
356
356
  against the live `--cr-resin-blur` and `--cr-frost-blur` tokens, and fails on any Resin
357
- nested inside Resin. Classifying by radius rather than by "has a backdrop filter" matters:
358
- Resin inside **Frost** is the intended hierarchy and must not be flagged.
357
+ nested inside Resin. The audit classifies by radius and not by "has a backdrop filter",
358
+ because Resin inside Frost is the intended hierarchy and must not be flagged.
359
359
 
360
- There is deliberately no live counter-example on this page. A rendered Resin-on-Resin
361
- specimen would make the specification violate the rule it specifies, and the audit —
362
- which reads these pages like any other — would fail the build. The failure is described;
363
- only the correct composition is real.
360
+ This page has no live counter-example. A rendered Resin-on-Resin specimen would break the
361
+ rule on the page that specifies it, and the audit, which reads these pages like any other,
362
+ would fail the build. The failure is described in words, and only the correct composition
363
+ is rendered.
364
364
 
365
365
  ### The correct composition, live
366
366
 
367
- Haze is the readable fill *inside* a translucent frame. It is recessed rather than
368
- raised, because a fill that floats above its own frame reads as a separate object rather
369
- than as the frame's content:
367
+ Haze is the readable fill inside a translucent frame. It is recessed, because a raised
368
+ fill that floats above its own frame reads as a separate object and no longer as the
369
+ frame's content:
370
370
 
371
371
  <div id="haze-in-resin-demo" class="cr-resin" style="padding:18px;max-width:420px" markdown="1">
372
372
  <div class="cr-haze" style="padding:14px 16px;border-radius:14px" markdown="1">
@@ -375,10 +375,10 @@ with a 1.95px feather, and it is recessed into the frame with an inset shadow.
375
375
  </div>
376
376
  </div>
377
377
 
378
- The recess is a single pair of inset shadows — a dark inner top edge and a light inner
379
- bottom edge — which is how neumorphic surfaces express recession under a consistent
380
- light source. Crystal's light source is above, so the shadow is at the top and the
381
- highlight at the bottom. Inverting that pair is what makes a surface read as raised:
378
+ The recess is a single pair of inset shadows: a dark inner top edge and a light inner
379
+ bottom edge. Neumorphic surfaces express recession this way under a consistent light
380
+ source. Crystal's light source is above, so the shadow is at the top and the highlight at
381
+ the bottom. Inverting that pair makes a surface read as raised:
382
382
 
383
383
  ```css
384
384
  :is(.cr-resin,.cr-glass,.cr-resin-haze) :is(.cr-haze,.cr-surface,.cr-well,.cr-content-fill){
@@ -387,18 +387,30 @@ highlight at the bottom. Inverting that pair is what makes a surface read as rai
387
387
  }
388
388
  ```
389
389
 
390
- Crystal takes the recession model from neumorphism and rejects its palette. Neumorphism's
391
- characteristic failure is that it tints the surface, the highlight and the shadow from one
392
- near-identical hue, so nothing has enough contrast to be found or read. Here the geometry
393
- is neumorphic and the contrast is not: the fill is 80% opaque, and the text on it is
394
- checked against the same ratios as text anywhere else.
390
+ Crystal takes the recession model from neumorphism and rejects its palette. Neumorphism
391
+ tints the surface, the highlight and the shadow from one near-identical hue, so nothing
392
+ has enough contrast to be found or read. Crystal keeps the neumorphic geometry and its own
393
+ contrast: the fill is 80% opaque, and the text on it is checked against the same ratios as
394
+ text anywhere else.
395
395
 
396
396
  ### Feathering never touches content
397
397
 
398
398
  Haze's 1.95px feather applies to an isolated paint layer only. Text, icons, hit areas and
399
- focus rings stay crisp. A feathered glyph is a blurry glyph, and no amount of material
400
- intent makes that legible — the feather exists to soften the *edge of the fill* against
401
- the frame behind it, nothing more.
399
+ focus rings stay crisp, because a feathered glyph is blurred and is not legible. The
400
+ feather softens the edge of the fill against the frame behind it and does nothing else.
401
+
402
+ ## Media and text compositions
403
+
404
+ The media and text recipes of 2.4.0 compose the materials above and add none. The [components chapter](components.html#media-and-text) has each recipe's values and a specimen.
405
+
406
+ - **The media stage is a frame, not a material.** It clips the picture to the content radius and letterboxes it in `--cr-surface-alt`, so it follows the palette and mode.
407
+ - **The transport is a Resin plane over the picture.** Its controls give up their own diffusion, because Resin never contains Resin. Its time readouts are labels read through a 20% fill over moving pictures, so each sits on its own Haze pill.
408
+ - **A caption cue is Stone,** which exists for a label over an unknown or moving backdrop. The cue keeps its crisp text over a feathered backing and sits above the transport, never under it.
409
+ - **The audio card is Haze.** With no picture, the player is a reading surface holding a title and the transport.
410
+ - **The selection toolbar is Frost,** because every transient overlay is (R15e). It takes a pill silhouette because it holds a row of controls, not a paragraph.
411
+ - **The editor is the field shell:** a Resin surround with the Haze well the document is written on. Prose has no material of its own and reads on whatever surface holds it.
412
+
413
+ Under reduced transparency and in opaque mode the caption's backing becomes the opaque surface; under forced colours the cue, the readouts and the stage take system colours with a CanvasText border.
402
414
 
403
415
  ## See it working
404
416