@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
@@ -13,8 +13,8 @@ The package contains working CSS primitives and a bounded interactive reference.
13
13
  | Stone label backing | 55% light / 60% dark, 1.95px feather, crisp text | `.cr-stone`; `.cr-dock-inner` shares the recipe |
14
14
  | Mirage modal scrim | Dark tint with chromatic diffusion of the scene behind the active modal | `.cr-mirage` and dialog `::backdrop`; standalone paint requires real application modal behavior |
15
15
  | Action | Resin shell with the neutral Haze reading fill, optical pressure and light; hover/pressed/focus/disabled | `.cr-button`. Real action and progress/error handling are app-owned |
16
- | Primary action | The same control with its Haze reading fill **in the primary colour** and the tested ink on it | `.cr-button.primary`; `--cr-primary` on the fill, `--cr-on-primary` as the ink. Opt-in, so a button is emphatic only where somebody said so |
17
- | Quiet action | The same shell with **no** reading fill, so the label sits directly on the material | `.cr-button.quiet`; same semantics as any action |
16
+ | Primary action | The same control with its Haze reading fill in the primary colour and the tested ink on it | `.cr-button.primary`; `--cr-primary` on the fill, `--cr-on-primary` as the ink. Opt-in, so a button is emphatic only where an author chose it |
17
+ | Quiet action | The same shell with no reading fill, so the label sits directly on the material | `.cr-button.quiet`; same semantics as any action |
18
18
  | Destructive action | Resin/Haze with independent danger boundary and explicit label | `.danger`; app supplies consequence-specific confirmation and recovery |
19
19
  | Text field | Visible label, state badge, glowing focus ring, validation, helper/error association | `.cr-input`; working native form example; app supplies validation rules |
20
20
  | Selection control | Explicit selected state plus text/mark | Native checkbox, radio and select, styled by `assets/crystal.css` as of 2.1.0, and the native switch (`input[type=checkbox][role=switch]`) as of 2.2.0; keyboard semantics must match the component |
@@ -25,7 +25,7 @@ The package contains working CSS primitives and a bounded interactive reference.
25
25
  | Range control | Visible label/value, keyboard adjustable range | Native `input[type=range]`, styled by `assets/crystal.css` as of 2.1.0, including its RTL track direction; product limits require domain validation |
26
26
  | Authored bubble | Haze, directional tight corner, optional author metadata | `.cr-bubble`, `.own`; app supplies content/Markdown semantics |
27
27
  | Composer surround | Frost frame and softened content well around protected input controls | CSS composition; no rich-text editor or delivery service is implemented |
28
- | Status badge | Independent ink/surface pair, symbol and visible label | `.cr-status` with `data-status`; 18px radius, 12px/18px padding, 36px floor, as the preview has always rendered it; dynamic announcements are app-owned |
28
+ | Status badge | Independent ink/surface pair, symbol and visible label | `.cr-status` with `data-status`; 18px radius, 12px/18px padding, 36px floor, as the preview renders it; dynamic announcements are app-owned |
29
29
  | Avatar | Circular image/initials, accessible identity when needed | Reference styling; app handles real identity, image failure and privacy |
30
30
  | Dialog | 80% feathered surface over Mirage; title, body and named actions | Working native HTML dialog example; Escape/focus return; app owns transactions |
31
31
  | Tooltip | Short supplemental text; never sole label | Frost (`.cr-frost`, R15e); working tooltip in the motion suite with focus, hover and Escape |
@@ -42,9 +42,9 @@ The package contains working CSS primitives and a bounded interactive reference.
42
42
 
43
43
  Every production control needs default, hover where meaningful, pressed, focus-visible, disabled, loading and error states as applicable. Disabled elements must not be the only explanation of unavailable functionality. Do not simulate success for an unimplemented action.
44
44
 
45
- Primary application buttons are at least 44px high. Compact documentation controls may be smaller but must meet applicable target-size/spacing criteria; do not infer that every clickable element is 44px from the button class. Validate touch use, not only a desktop screenshot.
45
+ Primary application buttons are at least 44px high. Compact documentation controls may be smaller but must meet applicable target-size/spacing criteria; do not infer that every clickable element is 44px from the button class. Validate touch use as well as a desktop screenshot.
46
46
 
47
- The selected destination carries its state by `aria-pressed` and by label weight; palette swatches, which cannot carry a weight change, use an inset ring gap. Functional statuses have words and distinct symbols. These cues survive color changes, and none of them is a check mark — a check means validated, never selected.
47
+ The selected destination carries its state by `aria-pressed` and by label weight; palette swatches, which cannot carry a weight change, use an inset ring gap. Functional statuses have words and distinct symbols. These cues survive color changes, and none of them is a check mark. A check means validated, never selected.
48
48
 
49
49
  The preview product-name form performs a real local update with native validation; it does not save a brand to a remote service. Dialogs inspect actual specifications or exported tokens. The export buttons produce files from the current configuration. Fictional messages, avatars and library cards remain clearly labeled design content.
50
50
 
@@ -52,7 +52,7 @@ The preview product-name form performs a real local update with native validatio
52
52
 
53
53
  **Navigation:** Use a floating toolbar when it improves the task. Keep the active destination labeled and avoid nested floating material planes. Side navigation may be more appropriate for dense tools. Do not require one product's destination set in unrelated products.
54
54
 
55
- **Editing:** Give content a stable 80% reading fill with feathered edges and crisp text, then surround it with tools at an appropriate elevation. Native input controls retain protected backgrounds and explicit boundaries. Separate draft state from publication and communicate unsaved/error states honestly.
55
+ **Editing:** Give content a stable 80% reading fill with feathered edges and crisp text, then surround it with tools at an appropriate elevation. Native input controls retain protected backgrounds and explicit boundaries. Separate draft state from publication and communicate unsaved/error states accurately.
56
56
 
57
57
  **Consequential actions:** Use a Haze dialog with explicit action names, clear consequences, safe dismissal where appropriate, and actual pending/failure handling. Decorative Resin must not obscure the decision.
58
58
 
@@ -68,24 +68,24 @@ Maintain a production Storybook or equivalent gallery for actual components with
68
68
 
69
69
  ## Resin interaction and information surfaces
70
70
 
71
- Buttons, action links, tabs, selectable controls and field shells use Resin as their interaction surface, with Haze reading protection inside a visible Resin perimeter. **On the primary action that reading fill is the primary colour, and the perimeter is the ordinary glass rim** — `--cr-primary` on the fill, `--cr-on-primary` as the ink, which is the palette's own tested pair and measures 4.74 to 10.31 against the rendered composite across all six palettes and both modes. The fill is opaque there where the neutral one is 80%, and that is the single deliberate deviation in this recipe. An 80% fill transmits a fifth of what is behind it: white over a light page is still white, so the neutral pad loses nothing, but a mid-tone primary at 80% over the Resin shell composites to a washed-out lilac sitting at the luminance where neither a white nor a near-black label clears 4.5 — 3.37 to 4.55 with `onPrimary`, 2.95 to 5.06 with `text`, failing in every light palette. A reading ground whose job is to make the label independent of the backdrop cannot be the one thing that depends on it.
71
+ Buttons, action links, tabs, selectable controls and field shells use Resin as their interaction surface, with Haze reading protection inside a visible Resin perimeter. On the primary action that reading fill is the primary colour, and the perimeter is the ordinary glass rim: `--cr-primary` on the fill and `--cr-on-primary` as the ink. That is the palette's own tested pair, and it measures 4.74 to 10.31 against the rendered composite across all six palettes and both modes. The fill is opaque there where the neutral one is 80%, and that is the only deviation in this recipe. An 80% fill transmits a fifth of what is behind it. White over a light page is still white, so the neutral pad loses nothing. A mid-tone primary at 80% over the Resin shell composites to a washed-out lilac, at the luminance where neither a white nor a near-black label clears 4.5: 3.37 to 4.55 with `onPrimary` and 2.95 to 5.06 with `text`, failing in every light palette. The reading fill exists to make the label independent of the backdrop, so the primary fill is opaque.
72
72
 
73
- **A quiet button has no reading fill.** It keeps the whole Resin shell — rim, float shadow, sheen — and drops the pad, which makes it the only variant that is glass all the way through. The cost is the pad's whole purpose: a quiet label reads against the Resin fill and therefore against whatever is behind the control. On Crystal's own foundation that is a wide margin — `--cr-text` over the Resin fill over canvas, surface, surface-alt and foundation measures 10.88 to 18.28 across all six palettes and both modes — but a quiet button placed over artwork has no protected ground, and that composition is the one to avoid. The recipe is in `assets/crystal.css`, in `@layer crystal.component`: a Resin fill with a rim and a float shadow, a `::before` carrying the inset Haze fill at the material's feather, and a `::after` carrying the optical sheen from `--cr-control-color` and `--cr-control-light`. Both pseudo-elements are dropped under reduced transparency and under forced colours.
73
+ **A quiet button has no reading fill.** It keeps the whole Resin shell (rim, float shadow and sheen) and drops the pad, so it is the only variant that is glass all the way through. Without the pad, a quiet label reads against the Resin fill and therefore against whatever is behind the control. On Crystal's own foundation the margin is wide: `--cr-text` over the Resin fill over canvas, surface, surface-alt and foundation measures 10.88 to 18.28 across all six palettes and both modes. A quiet button placed over artwork has no protected ground, so avoid that composition. The recipe is in `assets/crystal.css`, in `@layer crystal.component`: a Resin fill with a rim and a float shadow, a `::before` carrying the inset Haze fill at the material's feather, and a `::after` carrying the optical sheen from `--cr-control-color` and `--cr-control-light`. Both pseudo-elements are dropped under reduced transparency and under forced colours.
74
74
 
75
- Until 2.1.0 this paragraph told you to load `assets/controls.css`, which is the documentation site's stylesheet and has never been in the package — so the surface this specification describes was one no consumer could obtain. The field shell is markup a product wraps around a native field — `<span class="cr-field-shell">` around the `<input>` — and adds no semantics of its own; labels, input values, validation and form submission remain native.
75
+ The recipe is not in `assets/controls.css`, which is the documentation site's stylesheet and is not in the package. The field shell is markup a product wraps around a native field, `<span class="cr-field-shell">` around the `<input>`, and it adds no semantics of its own. Labels, input values, validation and form submission remain native.
76
76
 
77
- Small display elements that sit *on* content — labels, tags, badges and keyboard caps — use `.cr-resin-haze`. This is a reusable composition of existing materials, not a seventh material. Transient overlays — tooltips, toasts, menus, dropdowns, flyouts and popovers — are **Frost** (`.cr-frost`), at Meridian's direction (R15e): a surface that opens over content is an intermediate panel, not a compact control, and its reading content sits on Haze inside it. Larger persistent components retain their structural material. Native OS popup internals are platform-owned; use an actual accessible custom component when full Crystal popup rendering is required.
77
+ Small display elements that sit on content (labels, tags, badges and keyboard caps) use `.cr-resin-haze`. This is a reusable composition of existing materials, not a seventh material. Transient overlays (tooltips, toasts, menus, dropdowns, flyouts and popovers) are **Frost** (`.cr-frost`), at Meridian's direction (R15e). A surface that opens over content is an intermediate panel rather than a compact control, and its reading content sits on Haze inside it. Larger persistent components retain their structural material. Native OS popup internals are platform-owned; use an actual accessible custom component when full Crystal popup rendering is required.
78
78
 
79
79
  Selected controls carry correct ARIA state and label weight; a circular badge marks activity or information, never selection. Disabled controls retain legible content but cannot activate. Opaque and forced-color modes replace decorative optics while preserving control boundaries. Motion uses material deformation and changing light, with crisp foreground text.
80
80
 
81
81
  ### Every component names its surface
82
82
 
83
- The catalogue gives every one of its components a **surface** — the material composition it is made of — from the closed vocabulary in `tokens/surfaces.json`, and each surface is one recipe in `assets/crystal.css`. The build refuses a component naming a surface with no recipe, so the catalogue cannot specify a material Crystal has not published. The vocabulary is listed, with counts, at the top of the [catalogue](catalogue.html#surfaces). Four of its entries arrived in 2.2.0 because a consumer had reached them and found nothing:
83
+ The catalogue gives every one of its components a **surface**, which is the material composition it is made of, from the closed vocabulary in `tokens/surfaces.json`. Each surface is one recipe in `assets/crystal.css`. The build refuses a component naming a surface with no recipe, so the catalogue cannot specify a material Crystal has not published. The vocabulary is listed, with counts, at the top of the [catalogue](catalogue.html#surfaces). Four of its entries arrived in 2.2.0, because a consumer had reached for them and not found them:
84
84
 
85
85
  | Surface | Recipe | What it is |
86
86
  |---|---|---|
87
- | Navigation entry | `.cr-nav-item`, `.stacked` for a rail | Furniture on the panel beneath it: no material of its own, pill hit area, 44px target, selection by label weight (650 → 800), and current location by a 6px primary dot on `aria-current` only — never on `aria-selected` or `aria-pressed`, which are selection. The dot is flat (no material, no elevation) and sits in the entry's inline-start padding, so the label does not move. Lifted from this site's own side menu, which this page has always named as the reference implementation of selection; the dot is what the catalogue added (D-22). |
88
- | Bare control | `.cr-bare` | A control inside a surface that already has a coat — a disclosure chevron, a chip's remove button, a sort header, a stepper's arrows, a dismiss button. Crystal paints every `<button>` by element in five layers; this removes all five and keeps the target and the focus ring. |
87
+ | Navigation entry | `.cr-nav-item`, `.stacked` for a rail | Furniture on the panel beneath it: no material of its own, pill hit area, 44px target, selection by label weight (650 to 800), and current location by a 6px primary dot on `aria-current` only. The dot never appears on `aria-selected` or `aria-pressed`, which are selection. The dot is flat (no material, no elevation) and sits in the entry's inline-start padding, so the label does not move. The recipe is lifted from this site's own side menu, which this page names as the reference implementation of selection. The catalogue added the dot (D-22). |
88
+ | Bare control | `.cr-bare` | A control inside a surface that already has a coat: a disclosure chevron, a chip's remove button, a sort header, a stepper's arrows or a dismiss button. Crystal paints every `<button>` by element in five layers; this removes all five and keeps the target and the focus ring. |
89
89
  | Drag handle | `.cr-drag-handle` | A bare control with a grip and a lift while `aria-grabbed` or `data-dragging` is set. Pointer capture, the keyboard alternative and drop validation are the product's. |
90
90
  | Resin panel | `.cr-resin.panel` | The Resin plane with the content radius instead of the pill, for a floating window or a wide control bar. |
91
91
 
@@ -94,12 +94,23 @@ Five more arrived in 2.3.0, each from a ruling of 29 September 2026 on something
94
94
  | Surface | Recipe | What it is |
95
95
  |---|---|---|
96
96
  | Group | `.cr-group`, `.vertical` to stack | A new surface in the vocabulary. A button group and a split button are one Resin plane whose controls touch: one pill outside, the interior corners square against their neighbours, a hairline in `--cr-edge` between. The children keep their fill and give up their own elevation and diffusion, because the plane is the group's. A dock spaces its controls apart; a group does not. |
97
- | Dock controls that are not buttons | `.cr-dock` | The dock now reaches `[role=tab]` (selected by `aria-selected`), a `label` holding a radio (selected by `:checked`, its focus ring drawn on the label) and a link (current by `aria-current`), with the dock button's values. Every selector is inside `:where()`, so nothing a consumer already sits against changes specificity. |
98
- | Dialog body | `.cr-dialog-body`, with `.cr-scroll-frost` | The dialog's surface does not scroll; its body does, so a tall dialog keeps its title in view and takes the edge fade without dissolving its own fill. Give the body `tabindex="0"` and a name when it scrolls, so a keyboard can reach and scroll it. A dialog written without a body scrolls its surface as before. `position: fixed` now applies to a native `dialog.cr-dialog` only, which the browser centres; on any other element the host positions the surface. |
97
+ | Dock controls that are not buttons | `.cr-dock` | The dock reaches `[role=tab]` (selected by `aria-selected`), a `label` holding a radio (selected by `:checked`, its focus ring drawn on the label) and a link (current by `aria-current`), with the dock button's values. Every selector is inside `:where()`, so nothing a consumer already sits against changes specificity. |
98
+ | Dialog body | `.cr-dialog-body`, with `.cr-scroll-frost` | The dialog's surface does not scroll; its body does, so a tall dialog keeps its title in view and takes the edge fade without dissolving its own fill. Give the body `tabindex="0"` and a name when it scrolls, so a keyboard can reach and scroll it. A dialog written without a body still scrolls its surface. `position: fixed` applies to a native `dialog.cr-dialog` only, which the browser centres; on any other element the host positions the surface. |
99
99
  | Recessed overlay | `.cr-haze.overlay` | A menu, popover or listbox opened inside a pane that is already lifted. On the page a transient overlay is Frost; inside a Haze dialog or a Frost panel it recesses into Haze, and plain Haze has no edge. This is a flat Haze fill with the `--cr-edge` rim and the content shadow, and no feather. |
100
- | Count | `.cr-resin-haze.count` | The compact display sized for a count: a 20px circle that grows to a pill with its digits, filled to its own edge, with no block padding. The tag's 8px Haze inset and 17px block padding made a count badge 55px tall. |
100
+ | Count | `.cr-resin-haze.count` | The compact display sized for a count: a 20px circle that grows to a pill with its digits, filled to its own edge, with no block padding. With the tag's 8px Haze inset and 17px block padding a count badge is 55px tall. |
101
101
 
102
- A native switch is a checkbox with a track — `<input type="checkbox" role="switch">` — styled by element like the checkbox and radio: the track reads `--cr-switch-track-width` and `-height`, the thumb is the opaque surface, and the on state is the primary-soft pair.
102
+ The media and text recipes of 2.4.0 add no surface. Each is a selector on a surface the vocabulary already has, so no platform gains a material; it gains the geometry. Each links to its specimen [below](#media-and-text).
103
+
104
+ | Recipe | Surface | What it is |
105
+ |---|---|---|
106
+ | [Media stage](#specimen-media-stage) `.cr-media` | none of its own | The picture's frame: the content radius, a `--cr-surface-alt` letterbox, and the aspect ratio the product sets in `--cr-media-aspect` (unset keeps the media's own; `16 / 9`, `4 / 3`, `1`, `9 / 16`), so the page does not jump when the first frame decodes. `--cr-media-fit` is `contain`, so nothing is cropped unless the product asks for `cover`. In full screen the radius goes to 0. |
107
+ | [Transport](#specimen-media-stage) `.cr-resin.transport` in `.cr-media-bar` | Resin plane | A Resin pill with 4px block and 12px inline padding around the 48px action targets, 58px tall with its rim. The bar is inset 12px from the stage, or the safe area in full screen, so the pill never meets the content radius. The time readouts are tabular, on their own Haze pills, in body ink. Below 420px of player width the bar wraps its trailing controls onto a second row. |
108
+ | [Caption cue](#specimen-media-stage) `.cr-media-caption`, `::cue` | Stone label backing | A cue is a label over a moving picture, so it sits on Stone, above the transport and never under it: 12px above the bar whether or not the bar is shown, so it does not jump when a pointer arrives. `.cr-media-caption` is the feathered backing for a library that renders cues itself; `::cue` gives the browser's own renderer the flat Stone fill, because it accepts no pseudo-element. |
109
+ | [Audio card](#specimen-media-audio) `.cr-haze.cr-media.audio` | Haze reading surface | The audio player has no picture, so the stage becomes a Haze card with the 20px card padding, holding the title, a secondary line and the transport. |
110
+ | [Selection toolbar](#specimen-text-marks) `.cr-frost.bar` | Frost panel | A transient overlay shaped as a row of controls: a pill with 4px padding, for the commonest marks over highlighted text. It is Frost because every transient overlay is (R15e). |
111
+ | [Prose and the editor](#specimen-text-editor) `.cr-prose`, `.cr-editor`, `.cr-editor-toolbar` | Field shell, when editing | One reading vocabulary for a document while it is written and after it is published: 24px between blocks, headings stepping down the type scale, muted list markers, a primary-soft rule on a quotation, checklists of native checkboxes, and marks that each differ in shape as well as colour. A field shell holding an editor becomes a column at the content radius. Its toolbar sits above the text on a fine pointer, and below it on a coarse one, clear of the on-screen keyboard; `.below` asks for that placement on any pointer. |
112
+
113
+ A native switch is a checkbox with a track, `<input type="checkbox" role="switch">`, styled by element like the checkbox and radio. The track reads `--cr-switch-track-width` and `-height`, the thumb is the opaque surface, and the on state is the primary-soft pair.
103
114
 
104
115
  ### Interaction surface geometry
105
116
 
@@ -110,11 +121,11 @@ Toolbars, segmented controls and tab groups share one Resin/Haze surface. Their
110
121
 
111
122
  ## Material definition on small and nested surfaces
112
123
 
113
- 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.
124
+ 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.
114
125
 
115
126
  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.
116
127
 
117
- 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.
128
+ 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.
118
129
 
119
130
 
120
131
  ## Rounded icon set
@@ -132,89 +143,88 @@ Icons next to text are decorative and hidden from assistive technology. Icon-onl
132
143
 
133
144
  ## Focus light and circular state badges
134
145
 
135
- Focus uses an immediate 2px primary-color core at a 3px offset, surrounded by a broadly feathered halo. The halo is four graded layers of the primary color — 46% at 6px / 1px, 30% at 16px / 3px, 17% at 30px / 6px and 8% at 54px / 11px (blur / spread) — so the light falls off smoothly instead of ending on a hard edge. The spreads were halved from 2/6/12/22 at Meridian's request; the blur radii were deliberately left alone, so the ring thins without the falloff flattening.
146
+ Focus uses an immediate 2px primary-color core at a 3px offset, surrounded by a broadly feathered halo. The halo is four graded layers of the primary color: 46% at 6px / 1px, 30% at 16px / 3px, 17% at 30px / 6px and 8% at 54px / 11px (blur / spread). The light falls off smoothly instead of ending on a hard edge. The spreads were halved from 2/6/12/22 at Meridian's request and the blur radii were left unchanged, so the ring thins without the falloff flattening.
136
147
 
137
148
  **A focused control also lifts.** Beneath the halo sit two elevation layers: a directional 8px / 18px (offset / blur) at 30% of the primary color, and a broad 22px / 40px at 27% of the *decorative* color. The directional layer reuses the halo's second feather so the lift reads as the same light source; the broad one is decorative rather than primary so the shadow under a focused control carries the palette's own shadow hue instead of tinting the page purple. Focus changes the elevation shadow's hue without blurring any foreground.
138
149
 
139
- **In dark mode the feather alphas lift**, to 56 / 38 / 22 / 11 against light's 46 / 30 / 17 / 8. A deep canvas swallows the falloff at the lighter values, so the ring reads as a hard edge with nothing around it. Blur, spread and the elevation layers are identical in both modes.
150
+ In dark mode the feather alphas lift, to 56 / 38 / 22 / 11 against light's 46 / 30 / 17 / 8. A deep canvas swallows the falloff at the lighter values, so the ring reads as a hard edge with nothing around it. Blur, spread and the elevation layers are identical in both modes.
140
151
 
141
152
  The four feather colors are published as `--cr-focus-feather-1` through `-4` and the broad shadow as `--cr-focus-shadow`, so a product can retint the falloff without restating the recipe. The single token `--cr-focus-ring` composes all six layers so every focusable surface shares one recipe. The core remains defined for visibility; text and icons are never blurred. Keyboard focus applies to all interactive elements. Text entry lights its Resin shell through `:focus-within`. Motion must neither delay nor remove the focus cue. Forced colors substitute a system Highlight outline and remove decorative shadows.
142
153
 
143
- A `.cr-indicator` is a 20px circle painting an 80% Haze fill on an isolated layer with a 1px feather — Haze rather than Resin, for the reason given under [Indicators](#indicators). Field badges are 24px. Their foreground remains crisp and uses the tested body ink. They sit beside the content, never over text or a native select arrow. These are informational, non-interactive marks, not small click targets.
154
+ A `.cr-indicator` is a 20px circle painting an 80% Haze fill on an isolated layer with a 1px feather. It is Haze rather than Resin, for the reason given under [Indicators](#indicators). Field badges are 24px. Their foreground remains crisp and uses the tested body ink. They sit beside the content, never over text or a native select arrow. These are informational, non-interactive marks and are not click targets.
144
155
 
145
156
  <!-- generated:focus-recipe -->
146
157
 
147
158
  | Layer | Blur | Spread | Role |
148
159
  |---|---|---|---|
149
- | `outline: 2px solid var(--cr-focus-core)` at `outline-offset: 3px` | — | — | The crisp core. Never feathered, and the only part that survives forced colours. |
160
+ | `outline: 2px solid var(--cr-focus-core)` at `outline-offset: 3px` | None | None | The crisp core. Never feathered, and the only part that survives forced colours. |
150
161
  | Halo 1 | 6px | 1px | 46% of the primary colour |
151
162
  | Halo 2 | 16px | 3px | 30% of the primary colour |
152
163
  | Halo 3 | 30px | 6px | 17% of the primary colour |
153
164
  | Halo 4 | 54px | 11px | 8% of the primary colour |
154
- | Elevation 1 | 18px | — | 30% of the primary colour, offset 8px — the directional lift |
155
- | Elevation 2 | 40px | — | 27% of the decorative colour, offset 22px — the broad lift |
165
+ | Elevation 1 | 18px | None | 30% of the primary colour, offset 8px: the directional lift |
166
+ | Elevation 2 | 40px | None | 27% of the decorative colour, offset 22px: the broad lift |
156
167
  <!-- /generated:focus-recipe -->
157
168
 
158
169
  Every layer is read from `--cr-focus-ring` in the library's own exported theme, so this
159
- table cannot disagree with what ships. It used to be read from the preview site's
160
- `assets/controls.css` — a stylesheet the package does not contain — which is how Crystal
161
- came to document a halo it did not export and a lift no consumer received. The core is
162
- never feathered and the offset is never zero: a ring drawn *on* the border is hard to
170
+ table cannot disagree with what ships. The preview site's `assets/controls.css` is a
171
+ stylesheet the package does not contain, and the table must not be read from it. The core
172
+ is never feathered and the offset is never zero: a ring drawn *on* the border is hard to
163
173
  tell from a hover state, and on a pill it reads as a thicker stroke rather than as focus.
164
174
 
165
- A check mark is reserved for validation and information display — the status badges in `.cr-status` and a checkbox's own `:checked` indicator. It never marks a selected, pressed or focused control. Selection instead uses a heavier label weight, which changes no metric that would reflow the group. Round specimen swatches, which cannot carry a weight change, use an inset ring gap. Ordinary prose links retain their link styling. Badges are `aria-hidden`: the real control supplies its accessible name, required/invalid/selected/busy state and error association. The visual symbol never gets appended to the control's text content. Native checkbox/radio indicators and functional labels remain intact. Small controls retain full-sized hit targets. Badges have solid, unblurred alternatives under reduced transparency and forced colors.
175
+ A check mark is reserved for validation and information display: the status badges in `.cr-status` and a checkbox's own `:checked` indicator. It never marks a selected, pressed or focused control. Selection instead uses a heavier label weight, which changes no metric that would reflow the group. Round specimen swatches, which cannot carry a weight change, use an inset ring gap. Ordinary prose links retain their link styling. Badges are `aria-hidden`: the real control supplies its accessible name, required/invalid/selected/busy state and error association. The visual symbol never gets appended to the control's text content. Native checkbox/radio indicators and functional labels remain intact. Small controls retain full-sized hit targets. Badges have solid, unblurred alternatives under reduced transparency and forced colors.
166
176
 
167
177
  ## Geometry
168
178
 
169
- Crystal has exactly two control shapes, and which one applies is determined by what the
170
- control *is*, not by how it looks best in a particular layout.
179
+ Crystal has exactly two control shapes, and what the control is decides which one applies.
180
+ How the control looks in a particular layout does not.
171
181
 
172
182
  **Action controls are pill-shaped.** Buttons, icon buttons, segmented controls, chips,
173
- menu entries, tabs — anything whose job is "do this" or "go here" — use a fully rounded
174
- radius. A pill is unambiguous at any size: it never reads as a card, a field or a
175
- container.
183
+ menu entries and tabs use a fully rounded radius, as does anything else whose job is
184
+ "do this" or "go here". A pill is unambiguous at any size: it never reads as a card, a
185
+ field or a container.
176
186
 
177
- **Card-shaped buttons keep the content radius.** A control that is really a tappable
178
- *object* — a project tile, a palette swatch card, a library item — keeps `--cr-radius`
179
- (28px by default). These are the exception and they are recognisable: the user is choosing
180
- a thing, not triggering an action.
187
+ **Card-shaped buttons keep the content radius.** A control that is a tappable object (a
188
+ project tile, a palette swatch card or a library item) keeps `--cr-radius` (28px by
189
+ default). These are the exception and they are recognisable, because the user is choosing
190
+ a thing and is not triggering an action.
181
191
 
182
- There is no third option. A button with an 8px or 12px radius is neither shape and is a
183
- defect, not a variant.
192
+ There is no third shape: a button with an 8px or 12px radius is neither shape and is a
193
+ defect.
184
194
 
185
195
  <div class="sample-row" markdown="1">
186
196
  <button class="cr-button" type="button">Pill action</button>
187
197
  <button class="cr-control" type="button">Pill control</button>
188
198
  </div>
189
199
 
190
- The pill radius is a token, not a literal: `component.action.radius` resolves through
191
- `semantic.shape.pill`. A component that writes `border-radius:999px` directly works and
192
- silently opts itself out of every future change to the shape language. See
200
+ The pill radius is a token: `component.action.radius` resolves through
201
+ `semantic.shape.pill`. A component that writes `border-radius:999px` directly renders
202
+ correctly and does not follow any later change to the shape language. See
193
203
  [Tokens](tokens.html).
194
204
 
195
205
  ## Focus
196
206
 
197
- Focus is a **crisp 2px primary core at 3px offset, inside a four-layer feathered halo**.
198
- Six layers in total, and each one is doing a job:
207
+ Focus is a crisp 2px primary core at 3px offset, inside a four-layer feathered halo.
208
+ There are six layers in total, and each has a role:
199
209
 
200
210
  | Layer | Role |
201
211
  | --- | --- |
202
- | `outline: 2px solid var(--cr-focus-core)` at `outline-offset: 3px` | The crisp core. This is what proves focus at a glance and what survives forced colours. |
212
+ | `outline: 2px solid var(--cr-focus-core)` at `outline-offset: 3px` | The crisp core. It shows focus at a glance and it survives forced colours. |
203
213
  | `inset 0 2px 1px var(--cr-rim)` | Keeps the control's own top edge readable inside the ring. |
204
214
  | 4 × feathered primary glows at 6/1, 16/3, 30/6 and 54/11 | The halo. Increasing blur at decreasing opacity, so the ring dissolves outward rather than ending on a hard edge. |
205
215
 
206
- Each pair is blur radius / spread. The spread values were halved in September 2026; the blur radii were deliberately left alone, because halving both produces a tighter ring with a harder edge, which is a different thing from a thinner one.
216
+ Each pair is blur radius / spread. The spread values were halved in September 2026 and the blur radii were left unchanged. Halving both produces a tighter ring with a harder edge, which is different from a thinner ring.
207
217
 
208
- The core is never feathered. The offset is never zero — a ring drawn *on* the border is
209
- hard to distinguish from a hover state, and on a pill it reads as a thicker stroke rather
210
- than as focus.
218
+ The core is never feathered. The offset is never zero, because a ring drawn *on* the
219
+ border is hard to distinguish from a hover state, and on a pill it reads as a thicker
220
+ stroke rather than as focus.
211
221
 
212
222
  Tab to the entries in the side menu on this page to see the complete recipe on a real
213
223
  control.
214
224
 
215
225
  Focus is applied through `:focus-visible`, never `:focus`, so pointer users do not get a
216
226
  ring they did not ask for. Any rule that resets `box-shadow` on a control must exclude the
217
- focused state, or it silently reduces the recipe to a bare outline:
227
+ focused state, or it reduces the recipe to a bare outline:
218
228
 
219
229
  ```css
220
230
  /* Correct: the resting state only. */
@@ -236,31 +246,30 @@ Selection is expressed with **label weight**:
236
246
  The side menu on this page is the reference implementation.
237
247
 
238
248
  Nothing is drawn beside the label to mark it. A leading mark is drawn inside the
239
- control, so it offsets the very label it is meant to mark and the selected item stops
240
- lining up with the others. The obligation such a mark would serve — that selection
241
- never rests on colour alone — is already met by weight, which is typographic rather
242
- than chromatic and survives every palette, dark mode and colour vision difference.
249
+ control, so it offsets the label it is meant to mark and the selected item stops lining
250
+ up with the others. Selection must never rest on colour alone, and weight already meets
251
+ that obligation: it is typographic rather than chromatic, so it survives every palette,
252
+ dark mode and colour vision difference.
243
253
 
244
- Why not a check: a check mark is a *statement about a value* — this field validated, this
245
- item is complete, this option is confirmed. If it also means "this is the current tab",
254
+ A check mark is a statement about a value: this field validated, this item is complete,
255
+ this option is confirmed. If it also means "this is the current tab",
246
256
  then a list containing both validated items and a current item becomes unreadable, and a
247
257
  screen reader's "checked" state stops corresponding to anything the user can act on.
248
258
 
249
- Selection colour is never the only signal. A weight change is typographic, so it
250
- survives the palette being changed, the mode being dark, and colour vision differences.
251
- This is WCAG 1.4.1 applied as a design rule rather than as a post-hoc check.
259
+ Selection colour is never the only signal. This is WCAG 1.4.1 applied as a design rule
260
+ rather than as a post-hoc check.
252
261
 
253
262
  ### Selection in forced colours
254
263
 
255
- A filled selected row is a defect in forced-colors mode — see
264
+ A filled selected row is a defect in forced-colors mode. See
256
265
  [forced colours](accessibility.html#forced-colours) for the reason and the correct
257
- recipe. In short: selection becomes a `Highlight` ring, never a fill.
266
+ recipe. Selection becomes a `Highlight` ring, never a fill.
258
267
 
259
268
  ## Indicators
260
269
 
261
- An indicator — the moving pill behind a selected segment, the dock's active marker — is
262
- **Haze, not Resin**. It sits above a surface that is frequently already translucent, and a
263
- Resin indicator would be the nested-Resin failure by another name.
270
+ An indicator (the moving pill behind a selected segment, or the dock's active marker) is
271
+ Haze, not Resin. It sits above a surface that is frequently already translucent, and a
272
+ Resin indicator would be the nested-Resin failure.
264
273
 
265
274
  ```css
266
275
  .cr-indicator{
@@ -276,6 +285,73 @@ Resin indicator would be the nested-Resin failure by another name.
276
285
 
277
286
  The feather is on the `::before` layer alone, so the label above it stays crisp.
278
287
 
288
+ ## Media and text
289
+
290
+ These specimens are static: they show each recipe, and the behaviour (playback, captions, editing commands) is the engine's and the platform library's.
291
+
292
+ <div id="specimen-media-stage" class="cr-media" style="--cr-media-aspect: 16 / 9; max-width: 560px; margin-block: 16px">
293
+ <div class="cr-media-caption"><span>The harbour at dusk.</span></div>
294
+ <div class="cr-media-bar">
295
+ <div class="cr-resin transport" role="group" aria-label="Transport specimen">
296
+ <button type="button" class="cr-bare" aria-pressed="false">Play</button>
297
+ <time>0:00</time>
298
+ <input type="range" min="0" max="8" value="3" aria-label="Seek" style="flex: 1; min-width: 0">
299
+ <time>0:08</time>
300
+ <button type="button" class="cr-bare">Settings</button>
301
+ </div>
302
+ </div>
303
+ </div>
304
+
305
+ The stage at 16:9 with no picture loaded, which is its letterbox, the caption cue on Stone above the transport, and the transport inset 12px from the stage.
306
+
307
+ <div id="specimen-media-audio" class="cr-haze cr-media audio" style="max-width: 560px; margin-block: 16px">
308
+ <div><p style="margin: 0; font-weight: 700">Episode 4: The long way round</p><p style="margin: 0; color: var(--cr-muted)">Harbour stories</p></div>
309
+ <div class="cr-media-bar">
310
+ <div class="cr-resin transport" role="group" aria-label="Audio transport specimen">
311
+ <button type="button" class="cr-bare" aria-pressed="false">Play</button>
312
+ <time>0:00</time>
313
+ <input type="range" min="0" max="8" value="0" aria-label="Seek Episode 4" style="flex: 1; min-width: 0">
314
+ <time>0:08</time>
315
+ </div>
316
+ </div>
317
+ </div>
318
+
319
+ The audio card: Haze, with the card padding, holding the title and the transport.
320
+
321
+ <div id="specimen-text-editor" class="cr-field-shell" style="max-width: 560px; margin-block: 16px">
322
+ <div class="cr-editor-toolbar" role="toolbar" aria-label="Formatting specimen">
323
+ <button type="button" class="cr-bare">Heading</button>
324
+ <span role="separator" aria-orientation="vertical"></span>
325
+ <button type="button" class="cr-bare" aria-label="Bold" aria-pressed="true"><b>B</b></button>
326
+ <button type="button" class="cr-bare" aria-label="Italic" aria-pressed="false"><i>I</i></button>
327
+ <button type="button" class="cr-bare" aria-label="Underline" aria-pressed="false"><u>U</u></button>
328
+ </div>
329
+ <div class="cr-editor" role="textbox" aria-multiline="true" aria-readonly="true" aria-label="Editor specimen">
330
+ <h3>Before the meeting</h3>
331
+ <ul class="checklist">
332
+ <li><label><input type="checkbox" checked aria-label="Send the minutes"></label><p>Send the minutes</p></li>
333
+ <li><label><input type="checkbox" aria-label="Confirm the venue"></label><p>Confirm the venue</p></li>
334
+ </ul>
335
+ <p>The <strong>pilot boat</strong> budget is <u>under review</u>, the fee is <s>£40</s> £45, and the depth at low tide is <del>3.9 m</del> <ins>4.2 m</ins>. Press <kbd>Alt</kbd> + <kbd>F10</kbd> for the toolbar.</p>
336
+ <blockquote><p>A harbour is only as good as the water in it.</p></blockquote>
337
+ </div>
338
+ </div>
339
+
340
+ The editor: a field shell holding the toolbar and the document. The checklist's mark is the native checkbox's own state, the one place a check means checked. A finished item recedes to the muted ink and is not struck through. An insertion is underlined and a deletion struck through, so neither rests on colour alone.
341
+
342
+ <div id="specimen-text-marks" style="display: grid; gap: 12px; justify-items: start; max-width: 560px; margin-block: 16px">
343
+ <div class="cr-frost bar" role="toolbar" aria-label="Selection toolbar specimen">
344
+ <button type="button" class="cr-bare" aria-label="Bold" aria-pressed="true"><b>B</b></button>
345
+ <button type="button" class="cr-bare" aria-label="Italic" aria-pressed="false"><i>I</i></button>
346
+ <button type="button" class="cr-bare">Link</button>
347
+ </div>
348
+ <div class="cr-haze cr-editor" style="padding: 16px" role="textbox" aria-multiline="true" aria-readonly="true" aria-label="Highlight specimen">
349
+ <p>A <mark>highlighted phrase</mark> beside plain text. Select across both to see the selection.</p>
350
+ </div>
351
+ </div>
352
+
353
+ **A highlight and a selection differ (D-34).** A highlight is `mark`, the primary-soft pair, as prose renders it. The editor's selection is a 28% primary tint under unchanged ink, so a highlighted word that is then selected still looks selected. The highlight measures 6.06:1 or better and the selection 7.63:1 or better in every palette and mode. A highlighted word that is then selected takes the action pair, primary with on-primary ink, 4.74:1 or better: the 28% tint over the highlight fell to 3.74:1 in Harbor (D-39).
354
+
279
355
  ## See it working
280
356
 
281
357
  The [Playground](../playground.html#components) renders these controls live, and the side
package/docs/icons.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Crystal's icon set is one grid: a 24px view box, 1.8px strokes, round caps and joins, and `currentColor` so every icon inherits a tested foreground colour.
4
4
 
5
- Icon files carry no stroke width, cap, join or colour of their own. Those come from the stylesheet, so the contract lives in one place and cannot drift across a thousand files. An icon that carries its own stroke is a defect, not a variant.
5
+ Icon files carry no stroke width, cap, join or colour of their own. Those come from the stylesheet, so the contract lives in one place and cannot drift across a thousand files. An icon that carries its own stroke is a defect.
6
6
 
7
7
  Thirteen symbols are original Crystal work and live in the sprite at `assets/icons.svg`: `crystal`, `layers`, `document`, `directions`, `workspace`, `conversation`, `library`, `check`, `attention`, `alert`, `info`, `sparkle` and `chevron`. They are authoritative and are never replaced by a sourced icon of the same name. The remainder are derived from Lucide under the ISC License and vendored into `assets/icons/`; see [asset notices](../reference/ASSET-NOTICES.md).
8
8
 
@@ -26,6 +26,12 @@ Icons beside text are decorative and hidden from assistive technology. An icon-o
26
26
 
27
27
  <script src="../assets/icons.js" defer></script>
28
28
 
29
+ ## Icons the vocabularies require
30
+
31
+ The set is an evenly spaced slice of Lucide's, so an icon a Crystal vocabulary needs can fall outside it. `tools/build-icons.cjs` keeps a named list of required icons whatever the slice picks: today the rich text format vocabulary's `heading-2`, `heading-3`, `heading-4`, `link`, `unlink`, `list`, `list-ordered`, `quote`, `subscript`, `undo` and `redo` (D-35). The manifest lists them under `required`. A library draws these glyphs from the set rather than by hand.
32
+
33
+ Icon identifiers are public contract, so an icon leaves the set only in a major version. The build reports every icon that arrives or leaves against the committed manifest and refuses a removal outside a major release.
34
+
29
35
  ## The sets
30
36
 
31
37
  <!-- generated:icon-counts -->
@@ -33,8 +39,8 @@ Icons beside text are decorative and hidden from assistive technology. An icon-o
33
39
  | Source | Count | Licence |
34
40
  |---|---|---|
35
41
  | crystal | 13 | Original work |
36
- | lucide | 998 | ISC ([notice](../licenses/lucide-LICENSE.txt)) |
37
- | **Total** | **1011** | |
42
+ | lucide | 1009 | ISC ([notice](../licenses/lucide-LICENSE.txt)) |
43
+ | **Total** | **1022** | |
38
44
 
39
45
  One grid: `0 0 24 24` view box, 1.8px strokes, round caps and round joins, and `currentColor` so every icon inherits a tested foreground colour.
40
46