@crystal-ui/core 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +82 -23
  2. package/assets/core/preferences.d.ts +4 -4
  3. package/assets/core/preferences.js +4 -4
  4. package/assets/core/presets.d.ts +4 -3
  5. package/assets/core/presets.js +24 -18
  6. package/assets/core/spring.js +9 -10
  7. package/assets/core/state.js +7 -7
  8. package/assets/crystal.css +784 -284
  9. package/assets/crystal.d.ts +3 -3
  10. package/assets/crystal.js +100 -123
  11. package/assets/icons/heading-2.svg +1 -0
  12. package/assets/icons/heading-3.svg +1 -0
  13. package/assets/icons/heading-4.svg +1 -0
  14. package/assets/icons/link.svg +1 -0
  15. package/assets/icons/list-ordered.svg +1 -0
  16. package/assets/icons/list.svg +1 -0
  17. package/assets/icons/manifest.json +81 -2
  18. package/assets/icons/quote.svg +1 -0
  19. package/assets/icons/redo.svg +1 -0
  20. package/assets/icons/subscript.svg +1 -0
  21. package/assets/icons/undo.svg +1 -0
  22. package/assets/icons/unlink.svg +1 -0
  23. package/assets/motion.js +13 -12
  24. package/docs/accessibility.md +50 -54
  25. package/docs/adoption.md +33 -19
  26. package/docs/catalogue.md +113 -108
  27. package/docs/colors.md +67 -73
  28. package/docs/components.md +142 -66
  29. package/docs/icons.md +9 -3
  30. package/docs/materials.md +129 -117
  31. package/docs/motion-components.md +15 -15
  32. package/docs/motion.md +156 -158
  33. package/docs/principles.md +12 -12
  34. package/docs/tokens.md +129 -130
  35. package/engines.js +3 -3
  36. package/package.json +11 -3
  37. package/tokens/catalogue/01-layout.json +1 -1
  38. package/tokens/catalogue/02-navigation.json +4 -4
  39. package/tokens/catalogue/03-actions.json +2 -1
  40. package/tokens/catalogue/04-inputs.json +30 -22
  41. package/tokens/catalogue/05-data-display.json +9 -14
  42. package/tokens/catalogue/06-feedback.json +8 -6
  43. package/tokens/catalogue/07-overlays.json +4 -4
  44. package/tokens/catalogue/08-typography.json +12 -8
  45. package/tokens/catalogue/09-utility.json +1 -1
  46. package/tokens/catalogue/10-charts.json +7 -7
  47. package/tokens/catalogue/11-media.json +33 -20
  48. package/tokens/catalogue/12-commerce.json +4 -4
  49. package/tokens/catalogue/13-screens.json +2 -3
  50. package/tokens/catalogue/14-blocks.json +3 -3
  51. package/tokens/catalogue.json +176 -116
  52. package/tokens/crystal.tokens.json +6 -6
  53. package/tokens/motion-recipes.json +6 -6
  54. package/tokens/surface-recipes.json +3452 -0
  55. package/tokens/surfaces.json +48 -17
package/README.md CHANGED
@@ -1,37 +1,96 @@
1
- # Crystal design system
1
+ # @crystal-ui/core
2
2
 
3
- Open [the interactive playground](index.html). This package is Meridian Digital's Crystal design system: a product-neutral visual language with five bolder palettes, the original Harbor mapping, light/dark modes, real local adjustments and CSS/JSON exports.
3
+ Crystal is Meridian's design system. This package is the library: design tokens,
4
+ the material stylesheets, a token resolver, a headless state core, motion recipes,
5
+ icons, shaders and the specification.
4
6
 
5
- ## Visual acceptance baseline
7
+ It is framework independent. It is the base that platform component libraries are
8
+ built on, and it is not a component framework or a native renderer itself.
6
9
 
7
- The [approved Crystal material studies](reference/approved-crystal/README.md) are the visual standard for all future work. Unexplained divergence is a defect, not an acceptable style variation. Capture the affected UI before and after any visual change, in both light and dark and at narrow widths, and compare it against those studies; passing token and contrast checks alone do not establish visual correctness.
10
+ ```sh
11
+ npm install @crystal-ui/core
12
+ ```
8
13
 
9
- ## Defining hierarchy
14
+ ## Using the stylesheets
10
15
 
11
- **Plastic → Frost → Resin**, from back to front. Product palettes vary; this material order is Crystal’s shared identity. Haze reading wells sit within that hierarchy.
16
+ Load the theme first, then the primitives.
12
17
 
13
- ## Recommended defaults
18
+ ```js
19
+ import '@crystal-ui/core/theme';
20
+ import '@crystal-ui/core/css';
21
+ ```
14
22
 
15
- Color atmosphere **90%**, Frost base tint **35%**, elevation **125%**, and corner radius **28px**. Resin stays at **20%** fill opacity. Haze uses **80%** fill with a **1.95px** feathered perimeter and crisp text. See the [material specification](docs/materials.html#recommended-defaults) for recipes and fallback behavior.
23
+ ```html
24
+ <section class="cr-plastic">
25
+ <section class="cr-frost">
26
+ <article class="cr-haze">Readable product content</article>
27
+ </section>
28
+ <nav class="cr-resin" aria-label="Product navigation">
29
+ <!-- The product's navigation controls -->
30
+ </nav>
31
+ </section>
32
+ ```
16
33
 
17
- Stone retains 55% light / 60% dark opacity and shares Haze’s 1.95px feather. Mirage is the modal scrim. All six are explicit materials in the canonical catalog.
34
+ Set `data-crystal-mode="dark"` or `"light"` on the root element to choose a mode.
35
+ The generated theme is the Prism palette in both modes. The resolver produces a
36
+ theme for any of the six palettes and any settings within the documented ranges.
18
37
 
19
- ## Included
38
+ ## Materials
20
39
 
21
- - Preserved original specification and token files with a SHA-256 provenance manifest.
22
- - Eight editable specification chapters covering identity, typography/layout, color, materials/elevation, components/patterns, accessibility, adoption, material motion and component motion.
23
- - Six full light/dark palettes, independent functional statuses, configurable atmosphere/tint/elevation/radius/density/font and reduced transparency.
24
- - Three local product scenes; working dialog, token inspection, local name editing, preference persistence and downloads.
25
- - Framework-independent CSS primitives and a dependency-free JavaScript token resolver/exporter. This is not a complete production component framework or native renderer.
26
- - A dedicated [motion playground](motion.html) with six replayable material motions with 5–30px ordinary travel, up to 50px ordinary expressive depth, with documented exceptions for larger compositions, in-place Haze/Stone ripples, liquid light, moving feathered edges and directional Mirage entrances/exits, working scene/dialog transitions, saved animation speed across the preview (0.25–2×, five-second cap) and independent reduced-motion preferences.
27
- - Motion 13.4.0 and GSAP 3.15.0 installed and bundled locally, with 54 component recipes, live component studies and real-engine browser contract checks. See [component motion](docs/motion-components.html).
28
- - Resin/Haze interaction surfaces and compact information shells, including tooltips, toasts, labels, tags and temporary menus.
29
- - Rebuild/validation tooling and actual verification results, separately labeled from product adoption requirements.
40
+ The material order is **Plastic → Frost → Resin**, from back to front. Products
41
+ change the palette. They do not change this order.
30
42
 
31
- The original source proposal and application remain unchanged. Company branding is intentionally not invented; Crystal is the shared design-system name, and products supply their own names and marks.
43
+ | Material | What it is |
44
+ |---|---|
45
+ | Plastic | The opaque foundation, tinted by the palette. |
46
+ | Frost | The intermediate panel: 40px blur, tint and fine grain. |
47
+ | Resin | The floating control plane: 20px blur, a fixed 20% fill and a defined rim. |
48
+ | Haze | The reading surface: an 80% fill with a 1.95px feathered edge and crisp text. |
49
+ | Stone | Label backing: 55% in light mode, 60% in dark, feathered like Haze. |
50
+ | Mirage | The scrim behind a modal. |
32
51
 
33
- ## Open locally
52
+ Recommended defaults: colour atmosphere 90%, Frost base tint 35%, elevation 125%,
53
+ corner radius 28px. Feathering applies to an isolated paint layer only. Text,
54
+ icons, hit areas and focus rings are never blurred.
34
55
 
35
- Run `python3 tools/serve.py` from this folder and visit `http://127.0.0.1:4321/`. Direct file opening is not browser-verified. The preview has no backend and makes no required external asset requests. External reference links open their named documentation sites.
56
+ ## What the package exports
36
57
 
37
- See [adoption](docs/adoption.html), [verification](validation/report.html), and [asset notices](reference/ASSET-NOTICES.md). The packaged ZIP is published as a release asset rather than kept in the repository; it contains the complete usable directory without local dependency environments. Rebuild it locally with `python3 tools/package.py`. No framework installation is needed to view it.
58
+ | Import | Contents |
59
+ |---|---|
60
+ | `@crystal-ui/core` | The generated token export for TypeScript. Swift and Kotlin exports are in `exports/`. |
61
+ | `@crystal-ui/core/tokens` | The token source, in W3C DTCG format. |
62
+ | `@crystal-ui/core/flat` | The flat token file, with the runtime defaults and the palette list. |
63
+ | `@crystal-ui/core/css` | `crystal.css`: the materials, the control surface and the component recipes. |
64
+ | `@crystal-ui/core/theme` | The generated default theme. |
65
+ | `@crystal-ui/core/resolver` | The token resolver, contrast calculation, and CSS and JSON export. |
66
+ | `@crystal-ui/core/core/state` | State derivation for indicators, fields and ranges. |
67
+ | `@crystal-ui/core/core/preferences` | Preference clamping and duration resolution. |
68
+ | `@crystal-ui/core/core/spring` | Spring physics: sampling, settling time and overshoot. |
69
+ | `@crystal-ui/core/core/presets` | Keyframes for the material motion presets, computed from tokens. |
70
+ | `@crystal-ui/core/motion-recipes` | The 59 motion recipes, each with its spring and per-platform values. |
71
+ | `@crystal-ui/core/engines` | The Motion and GSAP engine entry. |
72
+ | `@crystal-ui/core/icons` | The icon manifest. There are 1022 icons on a 24px grid. |
73
+ | `@crystal-ui/core/shaders/*` | The optical layer's shader sources and their manifest. |
74
+ | `@crystal-ui/core/catalogue` | The component catalogue: 284 components in 14 categories. |
75
+ | `@crystal-ui/core/surfaces` | The 23 surfaces a component can be made of, each with its recipe. |
76
+ | `@crystal-ui/core/docs/*` | The eleven specification chapters, as Markdown. |
77
+
78
+ `motion` and `gsap` are dependencies of this package. A consumer bundles them as
79
+ it prefers.
80
+
81
+ ## Specification
82
+
83
+ The chapters in `docs/` are the specification. Start with `principles.md`,
84
+ `materials.md` and `components.md`. `adoption.md` covers how a product or a
85
+ library takes Crystal on, and `catalogue.md` lists every component with its
86
+ surface, states, semantics and motion.
87
+
88
+ The rendered site, the interactive playground and the verification evidence are
89
+ in [crystal-preview](https://github.com/boomerbowser/crystal-preview). The
90
+ approved material studies there are the visual standard. A rendering that departs
91
+ from them without an approved reason is a defect, and passing token and contrast
92
+ checks does not establish that a rendering is correct.
93
+
94
+ ## Licences
95
+
96
+ Third-party licences are in `licenses/`.
@@ -1,9 +1,9 @@
1
1
  /* Types for Crystal's headless preference core.
2
2
  *
3
- * Hand-written because the implementation is hand-written: these are source
4
- * types, not generated ones. They exist because CONTRACT §1 tells libraries to
5
- * import this module, and an untyped import makes every consumer re-describe
6
- * the same shape — which is the divergence the section is about.
3
+ * These are source types, written by hand like the implementation. Nothing
4
+ * generates them. They exist because CONTRACT §1 tells libraries to import
5
+ * this module, and an untyped import makes every consumer describe the same
6
+ * shape again, which is the divergence that section is about.
7
7
  */
8
8
 
9
9
  export interface CrystalRange { min: number; max: number; }
@@ -1,9 +1,9 @@
1
1
  /* Crystal headless core: preferences and motion resolution.
2
2
  *
3
- * Pure functions. The clamps and the duration ceiling are contract, not
4
- * defensive coding: a product that lets a preference drift outside these ranges
5
- * is no longer rendering Crystal, and an animation that runs past the ceiling
6
- * breaks the responsiveness the motion specification promises.
3
+ * Pure functions. The clamps and the duration ceiling are part of the contract.
4
+ * A product that lets a preference drift outside these ranges is no longer
5
+ * rendering Crystal, and an animation that runs past the ceiling breaks the
6
+ * responsiveness the motion specification promises.
7
7
  */
8
8
  (function (root, factory) {
9
9
  const api = factory();
@@ -2,7 +2,7 @@
2
2
  *
3
3
  * A preset is the movement a material makes entering or leaving. Its geometry is
4
4
  * computed from travel, depth and feather tokens rather than stored, so a token
5
- * change moves every preset at once — which is why a library must call this
5
+ * change moves every preset at once. A library must therefore call this module
6
6
  * rather than copy the keyframes it produces.
7
7
  */
8
8
 
@@ -17,8 +17,9 @@ export interface CrystalPresetMeasurements {
17
17
  travel: number;
18
18
  /** Resolved depth distance in px, from `travel-depth`. */
19
19
  depth: number;
20
- /** A dismissal that fades rather than falls: a dialog, a Haze card, a Stone
21
- * backing — anything anchored to the page rather than floating above it. */
20
+ /** A dismissal that fades rather than falls. It applies to anything anchored
21
+ * to the page rather than floating above it: a dialog, a Haze card, a Stone
22
+ * backing. */
22
23
  anchored?: boolean;
23
24
  /** Where a Mirage wash flows from. */
24
25
  from?: CrystalFlowDirection;
@@ -1,22 +1,28 @@
1
1
  /* Crystal headless core: the motion presets.
2
2
  *
3
- * A preset is the movement a *material* makes when it enters or leaves — Plastic
4
- * rising, Frost coming toward the viewer, Resin flowing in, Mirage washing across
5
- * the scene, and the shared dismissal. Unlike a recipe, a preset is not a stored
6
- * keyframe list: its geometry is computed from the travel, depth and feather
7
- * tokens, so changing a travel token changes every preset at once.
3
+ * A preset is a material's signature movement: Plastic rising, Frost coming
4
+ * toward the viewer, Resin flowing in, Haze and Stone moving their feathered
5
+ * edges, Mirage washing across the scene, and the shared dismissal. A recipe is
6
+ * a stored keyframe list. A preset's geometry is computed from the travel, depth
7
+ * and feather tokens, so changing a travel token changes every preset at once.
8
+ *
9
+ * In 2.x only `mirage`, `mirage-out` and `dismiss` are entrances and exits: the
10
+ * catalogue assigns them to the dialog and its scrim. `plastic`, `frost`,
11
+ * `resin`, `haze` and `stone` are studies, which the motion chapter shows and
12
+ * no catalogue entry assigns. Which surface enters with which preset is decided
13
+ * per surface in 3.0 (D-31).
8
14
  *
9
15
  * Pure functions. No DOM access, no globals, no side effects: the caller measures
10
- * its own environment and passes the numbers in. That is what lets the web
11
- * runtime, a React library, a SwiftUI view and a Compose composable all produce
12
- * the same movement instead of four implementations that drift — which CONTRACT
13
- * §1 names as the reason to reuse the resolver's arithmetic rather than
14
- * reimplement it.
16
+ * its own environment and passes the numbers in. The web runtime, a React
17
+ * library, a SwiftUI view and a Compose composable therefore all produce the
18
+ * same movement, where four separate implementations drift. CONTRACT §1 names
19
+ * that as the reason to reuse the resolver's arithmetic rather than reimplement
20
+ * it.
15
21
  *
16
- * What is deliberately NOT here: the decorative paint layers the web runtime adds
17
- * on top — animated box-shadow, border-radius and background-position. Those
18
- * cannot be composited, so each of them repaints every frame, and they are also
19
- * unportable. A platform that wants them adds them itself; the movement below is
22
+ * The decorative paint layers the web runtime adds on top (animated box-shadow,
23
+ * border-radius and background-position) are left out of this module. They
24
+ * cannot be composited, so each of them repaints every frame, and they are not
25
+ * portable. A platform that wants them adds them itself. The movement below is
20
26
  * the contract.
21
27
  */
22
28
  (function (root, factory) {
@@ -66,7 +72,7 @@
66
72
  * @param {number} measured.travel resolved travel distance in px
67
73
  * @param {number} measured.depth resolved depth distance in px
68
74
  * @param {boolean} [measured.anchored] a dismissal that fades rather than falls,
69
- * which is what a surface anchored to the page does — a dialog, a Haze
75
+ * which is what a surface anchored to the page does: a dialog, a Haze
70
76
  * card, a Stone backing. An unanchored dismissal drops away.
71
77
  * @param {string} [measured.from] flow direction for Mirage: left, right, top, bottom
72
78
  * @param {boolean} [measured.softFlow] true when the host can register a custom
@@ -128,10 +134,10 @@
128
134
  { transform: `translateY(${travel}px)`, opacity: 0 },
129
135
  ];
130
136
  }
131
- /* `haze` and `stone` have no component movement of their own: their material
137
+ /* `haze` and `stone` have no component movement of their own. Their material
132
138
  signature is the feathered paint shifting while the text stays fixed, which
133
- is a paint-layer effect the caller adds. Returning no keyframes is the
134
- correct answer, not a gap. */
139
+ is a paint-layer effect the caller adds, so returning no keyframes is
140
+ correct. */
135
141
 
136
142
  return result;
137
143
  }
@@ -6,11 +6,10 @@
6
6
  * duration and a bézier, for two reasons. The first is behavioural: a timed
7
7
  * curve cannot be interrupted meaningfully, because it has no notion of where
8
8
  * the thing currently is or how fast it is going. Press a control while it is
9
- * still settling and a curve restarts from a new zero, which is why timed
10
- * motion feels brittle under real use. A spring resumes from its current state
11
- * because its current state is all it needs.
9
+ * still settling and a curve restarts from a new zero, which makes timed
10
+ * motion feel brittle in use. A spring resumes from its current state.
12
11
  *
13
- * The second is portability, which is the reason it lives in the core. A
12
+ * The second is portability, which is why it lives in the core. A
14
13
  * cubic-bézier is a web primitive. Stiffness, damping and mass map directly
15
14
  * onto SwiftUI's spring(response:dampingFraction:), Compose's
16
15
  * spring(dampingRatio:stiffness:) and every serious animation runtime, so a
@@ -57,9 +56,9 @@
57
56
  displacement 1 with zero initial velocity. Returns 0 at t=0 and approaches
58
57
  1 as the spring settles, so it can be read directly as animation progress.
59
58
 
60
- The three damping regimes are genuinely different closed-form solutions,
61
- not one formula with a parameter; conflating them produces NaN at exactly
62
- critical damping, which is the case a designer is most likely to pick. */
59
+ The three damping regimes have different closed-form solutions. Applying
60
+ one formula to all three produces NaN at exactly critical damping, which
61
+ is the case a designer is most likely to pick. */
63
62
  function sampleSpring(spec, tSeconds) {
64
63
  const { stiffness, damping, mass } = normaliseSpring(spec);
65
64
  const t = Math.max(0, Number(tSeconds) || 0);
@@ -98,9 +97,9 @@
98
97
  return MAX_SETTLE_MS;
99
98
  }
100
99
 
101
- /* Does this spring pass its target before settling? Underdamped springs do;
102
- it is the overshoot that reads as momentum, and its absence that makes
103
- critically damped motion feel mechanical. */
100
+ /* True when the spring passes its target before settling, which underdamped
101
+ springs do. The overshoot reads as momentum, and without it critically
102
+ damped motion feels mechanical. */
104
103
  function overshoots(spec) {
105
104
  return dampingRatio(spec) < 1;
106
105
  }
@@ -2,9 +2,9 @@
2
2
  *
3
3
  * Pure functions. No DOM access, no globals, no side effects. A web page, a
4
4
  * React component, a SwiftUI view and a Compose composable all need the same
5
- * answers to "which mark does this control show" and "how full is this range";
6
- * deriving that here is what lets libraries share behaviour instead of
7
- * reimplementing it and drifting.
5
+ * answers to "which mark does this control show" and "how full is this range".
6
+ * Deriving them here lets libraries share behaviour instead of reimplementing
7
+ * it and drifting.
8
8
  *
9
9
  * Usable as a plain <script> (attaches to CrystalCore) or via require().
10
10
  */
@@ -18,8 +18,8 @@
18
18
  /* Indicator precedence. Activity outranks location, which outranks selection:
19
19
  a control that is busy should say so before it says where you are, and a
20
20
  control that is the current page should say that before it says it is
21
- selected. A check mark is deliberately absent — it means validated or
22
- informational, never "this one is selected". */
21
+ selected. The order has no check mark, because a check mark means validated
22
+ or informational, never "this one is selected". */
23
23
  const INDICATOR_ORDER = ['busy', 'current', 'selection'];
24
24
 
25
25
  function resolveIndicator(flags) {
@@ -40,8 +40,8 @@
40
40
  return 'idle';
41
41
  }
42
42
 
43
- /* Range fill, clamped to 0-100. A zero-width range is a legitimate state
44
- (a single-value slider), not an error, and must not divide by zero. */
43
+ /* Range fill, clamped between 0 and 100. A zero-width range is a legitimate
44
+ state (a single-value slider) and must not divide by zero. */
45
45
  function rangeProgress(range) {
46
46
  const r = range || {};
47
47
  const min = Number(r.min);