@crystal-ui/core 2.3.1 → 2.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +82 -23
- package/assets/core/preferences.d.ts +4 -4
- package/assets/core/preferences.js +4 -4
- package/assets/core/presets.d.ts +4 -3
- package/assets/core/presets.js +24 -18
- package/assets/core/spring.js +9 -10
- package/assets/core/state.js +7 -7
- package/assets/crystal.css +783 -288
- package/assets/crystal.d.ts +3 -3
- package/assets/crystal.js +100 -123
- package/assets/icons/heading-2.svg +1 -0
- package/assets/icons/heading-3.svg +1 -0
- package/assets/icons/heading-4.svg +1 -0
- package/assets/icons/link.svg +1 -0
- package/assets/icons/list-ordered.svg +1 -0
- package/assets/icons/list.svg +1 -0
- package/assets/icons/manifest.json +81 -2
- package/assets/icons/quote.svg +1 -0
- package/assets/icons/redo.svg +1 -0
- package/assets/icons/subscript.svg +1 -0
- package/assets/icons/undo.svg +1 -0
- package/assets/icons/unlink.svg +1 -0
- package/assets/motion.js +13 -12
- package/docs/accessibility.md +50 -54
- package/docs/adoption.md +33 -19
- package/docs/catalogue.md +113 -108
- package/docs/colors.md +67 -73
- package/docs/components.md +142 -66
- package/docs/icons.md +9 -3
- package/docs/materials.md +129 -117
- package/docs/motion-components.md +15 -15
- package/docs/motion.md +156 -158
- package/docs/principles.md +12 -12
- package/docs/tokens.md +129 -130
- package/engines.js +3 -3
- package/package.json +11 -3
- package/tokens/catalogue/01-layout.json +1 -1
- package/tokens/catalogue/02-navigation.json +4 -4
- package/tokens/catalogue/03-actions.json +2 -1
- package/tokens/catalogue/04-inputs.json +30 -22
- package/tokens/catalogue/05-data-display.json +9 -14
- package/tokens/catalogue/06-feedback.json +8 -6
- package/tokens/catalogue/07-overlays.json +4 -4
- package/tokens/catalogue/08-typography.json +12 -8
- package/tokens/catalogue/09-utility.json +1 -1
- package/tokens/catalogue/10-charts.json +7 -7
- package/tokens/catalogue/11-media.json +33 -20
- package/tokens/catalogue/12-commerce.json +4 -4
- package/tokens/catalogue/13-screens.json +2 -3
- package/tokens/catalogue/14-blocks.json +3 -3
- package/tokens/catalogue.json +176 -116
- package/tokens/crystal.tokens.json +6 -6
- package/tokens/motion-recipes.json +6 -6
- package/tokens/surface-recipes.json +3452 -0
- package/tokens/surfaces.json +48 -17
package/docs/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.
|
|
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
|
|
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%
|
|
18
|
-
| Frost base tint | 35% | 35%
|
|
19
|
-
| Elevation | 125% | 60%
|
|
20
|
-
| Corner radius | 28px | 14px
|
|
21
|
-
| Motion speed | 1× | 0.25×
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
67
|
-
is the authority
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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`.
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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`.
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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. |
|
|
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
|
|
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
|
|
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
|
|
270
|
-
|
|
271
|
-
|
|
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
|
|
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
|
|
281
|
-
|
|
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).
|
|
287
|
-
kept as the record of what will return
|
|
288
|
-
rest
|
|
289
|
-
motion a person started. Plastic's glow is a material property and stays
|
|
290
|
-
ambient and
|
|
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
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
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.
|
|
298
|
-
|
|
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
|
|
301
|
-
read
|
|
302
|
-
middle. It is the
|
|
303
|
-
|
|
304
|
-
unavailable and ambient disabled, every page renders exactly its reference baseline,
|
|
305
|
-
|
|
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
|
|
312
|
-
layer becomes a
|
|
313
|
-
|
|
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%.
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
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
|
|
324
|
-
|
|
325
|
-
|
|
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
|
|
338
|
-
that should not exist
|
|
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,
|
|
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.
|
|
358
|
-
Resin inside
|
|
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
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
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
|
|
368
|
-
|
|
369
|
-
|
|
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
|
|
379
|
-
bottom edge
|
|
380
|
-
|
|
381
|
-
|
|
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
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
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
|
|
400
|
-
|
|
401
|
-
|
|
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
|
|