@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.
- 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 +784 -284
- 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/README.md
CHANGED
|
@@ -1,37 +1,96 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @crystal-ui/core
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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
|
-
|
|
10
|
+
```sh
|
|
11
|
+
npm install @crystal-ui/core
|
|
12
|
+
```
|
|
8
13
|
|
|
9
|
-
##
|
|
14
|
+
## Using the stylesheets
|
|
10
15
|
|
|
11
|
-
|
|
16
|
+
Load the theme first, then the primitives.
|
|
12
17
|
|
|
13
|
-
|
|
18
|
+
```js
|
|
19
|
+
import '@crystal-ui/core/theme';
|
|
20
|
+
import '@crystal-ui/core/css';
|
|
21
|
+
```
|
|
14
22
|
|
|
15
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
38
|
+
## Materials
|
|
20
39
|
|
|
21
|
-
|
|
22
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
56
|
+
## What the package exports
|
|
36
57
|
|
|
37
|
-
|
|
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
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
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
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
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();
|
package/assets/core/presets.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
21
|
-
*
|
|
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;
|
package/assets/core/presets.js
CHANGED
|
@@ -1,22 +1,28 @@
|
|
|
1
1
|
/* Crystal headless core: the motion presets.
|
|
2
2
|
*
|
|
3
|
-
* A preset is
|
|
4
|
-
*
|
|
5
|
-
* the scene, and the shared dismissal.
|
|
6
|
-
* keyframe list
|
|
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.
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
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
|
-
*
|
|
17
|
-
*
|
|
18
|
-
* cannot be composited, so each of them repaints every frame, and they are
|
|
19
|
-
*
|
|
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
|
|
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
|
|
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
|
|
134
|
-
correct
|
|
139
|
+
is a paint-layer effect the caller adds, so returning no keyframes is
|
|
140
|
+
correct. */
|
|
135
141
|
|
|
136
142
|
return result;
|
|
137
143
|
}
|
package/assets/core/spring.js
CHANGED
|
@@ -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
|
|
10
|
-
* motion
|
|
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
|
|
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
|
|
61
|
-
|
|
62
|
-
|
|
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
|
-
/*
|
|
102
|
-
|
|
103
|
-
|
|
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
|
}
|
package/assets/core/state.js
CHANGED
|
@@ -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
|
-
*
|
|
7
|
-
*
|
|
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.
|
|
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
|
|
44
|
-
(a single-value slider)
|
|
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);
|