@crystal-ui/core 2.1.0 → 2.3.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 (38) hide show
  1. package/assets/crystal-theme.css +15 -0
  2. package/assets/crystal.css +652 -12
  3. package/assets/crystal.js +10 -0
  4. package/assets/motion.css +3 -3
  5. package/assets/motion.js +17 -2
  6. package/assets/tokens.js +1 -1
  7. package/docs/accessibility.md +19 -3
  8. package/docs/adoption.md +3 -1
  9. package/docs/catalogue.md +467 -53
  10. package/docs/components.md +36 -9
  11. package/docs/materials.md +12 -4
  12. package/docs/motion-components.md +11 -8
  13. package/docs/motion.md +10 -4
  14. package/docs/tokens.md +3 -2
  15. package/engines.js +13 -2
  16. package/exports/crystal-tokens.kt +2 -1
  17. package/exports/crystal-tokens.swift +2 -1
  18. package/exports/crystal-tokens.ts +2 -1
  19. package/package.json +2 -1
  20. package/tokens/catalogue/01-layout.json +45 -0
  21. package/tokens/catalogue/02-navigation.json +88 -6
  22. package/tokens/catalogue/03-actions.json +42 -2
  23. package/tokens/catalogue/04-inputs.json +359 -5
  24. package/tokens/catalogue/05-data-display.json +185 -21
  25. package/tokens/catalogue/06-feedback.json +75 -6
  26. package/tokens/catalogue/07-overlays.json +52 -5
  27. package/tokens/catalogue/08-typography.json +54 -0
  28. package/tokens/catalogue/09-utility.json +79 -0
  29. package/tokens/catalogue/10-charts.json +89 -1
  30. package/tokens/catalogue/11-media.json +33 -0
  31. package/tokens/catalogue/12-commerce.json +133 -1
  32. package/tokens/catalogue/13-screens.json +77 -0
  33. package/tokens/catalogue/14-blocks.json +101 -0
  34. package/tokens/catalogue.json +1656 -48
  35. package/tokens/crystal.json +3 -2
  36. package/tokens/crystal.tokens.json +7 -2
  37. package/tokens/motion-recipes.json +124 -96
  38. package/tokens/surfaces.json +177 -0
@@ -622,7 +622,7 @@
622
622
  "component": {
623
623
  "action": {
624
624
  "radius": 999,
625
- "minTarget": 44,
625
+ "minTarget": 48,
626
626
  "paddingBlock": 15,
627
627
  "paddingInline": 24,
628
628
  "gap": 9,
@@ -670,7 +670,8 @@
670
670
  },
671
671
  "overlay": {
672
672
  "maxWidth": 480,
673
- "tooltipMaxWidth": 352
673
+ "tooltipMaxWidth": 352,
674
+ "tooltipRadius": 18
674
675
  },
675
676
  "field": {
676
677
  "wellInset": 7
@@ -1723,8 +1723,8 @@
1723
1723
  },
1724
1724
  "minTarget": {
1725
1725
  "$type": "dimension",
1726
- "$value": "44px",
1727
- "$description": "Minimum interactive target"
1726
+ "$value": "48px",
1727
+ "$description": "Minimum interactive target. Above the 44px floor Crystal specifies, which this must never fall below."
1728
1728
  },
1729
1729
  "paddingBlock": {
1730
1730
  "$type": "dimension",
@@ -1885,6 +1885,11 @@
1885
1885
  "$type": "dimension",
1886
1886
  "$value": "352px",
1887
1887
  "$description": "About sixty characters: a tooltip longer than this is documentation"
1888
+ },
1889
+ "tooltipRadius": {
1890
+ "$type": "dimension",
1891
+ "$value": "18px",
1892
+ "$description": "A tooltip's corner radius. Smaller than the content radius the other overlays share, because a tooltip is a compact panel of one or two lines."
1888
1893
  }
1889
1894
  },
1890
1895
  "field": {
@@ -1577,56 +1577,6 @@
1577
1577
  }
1578
1578
  }
1579
1579
  },
1580
- {
1581
- "id": "reaction",
1582
- "category": "Content",
1583
- "label": "Reaction response",
1584
- "duration": 680,
1585
- "engine": "Motion",
1586
- "keyframes": [
1587
- {
1588
- "transform": "scale(0.9155,1.0923) rotate(-4deg)",
1589
- "offset": 0
1590
- },
1591
- {
1592
- "transform": "scale(1.1193,0.8934) rotate(3deg)",
1593
- "offset": 0.3333333333333333
1594
- },
1595
- {
1596
- "transform": "scale(0.9658,1.0355) rotate(-1deg)",
1597
- "offset": 0.6666666666666666
1598
- },
1599
- {
1600
- "transform": "scale(1) rotate(0)",
1601
- "offset": 1
1602
- }
1603
- ],
1604
- "use": "Toggle the real reaction state and count before the response.",
1605
- "reduced": "Apply the semantic state immediately; omit decorative movement.",
1606
- "material": "resin",
1607
- "signature": "coalesce",
1608
- "spring": {
1609
- "stiffness": 307.72,
1610
- "damping": 21.752,
1611
- "mass": 1,
1612
- "dampingRatio": 0.62,
1613
- "platform": {
1614
- "swiftUI": {
1615
- "response": 0.3582,
1616
- "dampingFraction": 0.62
1617
- },
1618
- "compose": {
1619
- "dampingRatio": 0.62,
1620
- "stiffness": 307.72
1621
- },
1622
- "web": {
1623
- "stiffness": 307.72,
1624
- "damping": 21.752,
1625
- "mass": 1
1626
- }
1627
- }
1628
- }
1629
- },
1630
1580
  {
1631
1581
  "id": "toast-in",
1632
1582
  "category": "Feedback",
@@ -1842,52 +1792,6 @@
1842
1792
  }
1843
1793
  }
1844
1794
  },
1845
- {
1846
- "id": "busy",
1847
- "category": "Feedback",
1848
- "label": "Finite busy cue",
1849
- "duration": 680,
1850
- "engine": "GSAP",
1851
- "keyframes": [
1852
- {
1853
- "opacity": 0.45,
1854
- "offset": 0
1855
- },
1856
- {
1857
- "opacity": 1,
1858
- "offset": 0.5
1859
- },
1860
- {
1861
- "opacity": 0.45,
1862
- "offset": 1
1863
- }
1864
- ],
1865
- "use": "One cycle for an actual pending operation; keep a static busy label if it lasts longer.",
1866
- "reduced": "Apply the semantic state immediately; omit decorative movement.",
1867
- "material": "stone",
1868
- "signature": "feather",
1869
- "spring": {
1870
- "stiffness": 134.9372,
1871
- "damping": 21.3739,
1872
- "mass": 1,
1873
- "dampingRatio": 0.92,
1874
- "platform": {
1875
- "swiftUI": {
1876
- "response": 0.5409,
1877
- "dampingFraction": 0.92
1878
- },
1879
- "compose": {
1880
- "dampingRatio": 0.92,
1881
- "stiffness": 134.9372
1882
- },
1883
- "web": {
1884
- "stiffness": 134.9372,
1885
- "damping": 21.3739,
1886
- "mass": 1
1887
- }
1888
- }
1889
- }
1890
- },
1891
1795
  {
1892
1796
  "id": "skeleton-resolve",
1893
1797
  "category": "Feedback",
@@ -2568,10 +2472,134 @@
2568
2472
  }
2569
2473
  }
2570
2474
  }
2475
+ },
2476
+ {
2477
+ "id": "activity-turn",
2478
+ "category": "Feedback",
2479
+ "label": "Indeterminate arc",
2480
+ "duration": 1200,
2481
+ "engine": "Motion",
2482
+ "loop": true,
2483
+ "direction": "normal",
2484
+ "easing": "linear",
2485
+ "keyframes": [
2486
+ {
2487
+ "transform": "rotate(0deg)",
2488
+ "offset": 0
2489
+ },
2490
+ {
2491
+ "transform": "rotate(360deg)",
2492
+ "offset": 1
2493
+ }
2494
+ ],
2495
+ "use": "A loader, or an indeterminate progress ring, while an operation is genuinely pending — and only then. Starts when the work starts and stops when it resolves. One period for every continuous indicator, so two in one view never tick against each other.",
2496
+ "reduced": "Static: the whole track visible and nothing turning. Never a partial arc, which reports a measurement nobody took.",
2497
+ "material": "stone",
2498
+ "signature": "feather"
2499
+ },
2500
+ {
2501
+ "id": "activity-travel",
2502
+ "category": "Feedback",
2503
+ "label": "Indeterminate bar",
2504
+ "duration": 1200,
2505
+ "engine": "Motion",
2506
+ "loop": true,
2507
+ "direction": "normal",
2508
+ "easing": "linear",
2509
+ "keyframes": [
2510
+ {
2511
+ "transform": "translateX(-100%)",
2512
+ "offset": 0
2513
+ },
2514
+ {
2515
+ "transform": "translateX(100%)",
2516
+ "offset": 1
2517
+ }
2518
+ ],
2519
+ "travelException": "A travelling segment crosses its own track, and the track is its bound; the travel is a fraction of the track rather than a distance on the page.",
2520
+ "use": "Indeterminate linear progress while an operation is genuinely pending, stopping when it resolves or becomes measurable.",
2521
+ "reduced": "Static: the whole track visible. A segment frozen part of the way along reports a measurement nobody took.",
2522
+ "material": "stone",
2523
+ "signature": "feather"
2524
+ },
2525
+ {
2526
+ "id": "skeleton-sweep",
2527
+ "category": "Content",
2528
+ "label": "Luminance sweep",
2529
+ "duration": 1200,
2530
+ "engine": "Motion",
2531
+ "loop": true,
2532
+ "direction": "normal",
2533
+ "easing": "linear",
2534
+ "keyframes": [
2535
+ {
2536
+ "backgroundPosition": "200% 0",
2537
+ "offset": 0
2538
+ },
2539
+ {
2540
+ "backgroundPosition": "-200% 0",
2541
+ "offset": 1
2542
+ }
2543
+ ],
2544
+ "use": "A skeleton while its content is genuinely loading, on the Haze fill and never on the text that replaces it. Ends with skeleton-resolve.",
2545
+ "reduced": "Static Haze fill.",
2546
+ "material": "haze",
2547
+ "signature": "feather"
2548
+ },
2549
+ {
2550
+ "id": "mark-in",
2551
+ "category": "Content",
2552
+ "label": "Mark arriving",
2553
+ "duration": 500,
2554
+ "engine": "Motion",
2555
+ "keyframes": [
2556
+ {
2557
+ "transform": "scaleY(0)",
2558
+ "opacity": 0,
2559
+ "offset": 0
2560
+ },
2561
+ {
2562
+ "transform": "scaleY(1)",
2563
+ "opacity": 1,
2564
+ "offset": 1
2565
+ }
2566
+ ],
2567
+ "overshoot": "never",
2568
+ "stagger": {
2569
+ "step": 24,
2570
+ "maxMarks": 24
2571
+ },
2572
+ "use": "A data mark — a bar, a series, a segment — growing from its baseline when a chart first appears, and not when its data later changes. transform-origin is the baseline. Staggered by index up to 24 marks; past that every mark arrives together, because a sequence nobody can count is decoration.",
2573
+ "reduced": "Marks appear in place at their values.",
2574
+ "material": "haze",
2575
+ "signature": "feather",
2576
+ "spring": {
2577
+ "stiffness": 644.657,
2578
+ "damping": 50.7802,
2579
+ "mass": 1,
2580
+ "dampingRatio": 1,
2581
+ "platform": {
2582
+ "swiftUI": {
2583
+ "response": 0.2475,
2584
+ "dampingFraction": 1
2585
+ },
2586
+ "compose": {
2587
+ "dampingRatio": 1,
2588
+ "stiffness": 644.657
2589
+ },
2590
+ "web": {
2591
+ "stiffness": 644.657,
2592
+ "damping": 50.7802,
2593
+ "mass": 1
2594
+ }
2595
+ }
2596
+ }
2571
2597
  }
2572
2598
  ],
2573
2599
  "travelPolicy": "5–30px ordinary, 50px guidance; justified large transitions may exceed it. Haze and Stone paint moves locally while text stays fixed.",
2574
2600
  "springPolicy": "Every recipe carries a spring fitted to its authored duration, which remains the authority. Damping ratio is chosen by signature: inertia and coalesce overshoot because momentum is their material claim, feather and caustic do not because a soft edge that bounces is wrong. Disabling springs must reproduce the keyframes exactly.",
2601
+ "continuousPolicy": "A continuous recipe is the one kind of motion that repeats, and it is not ambient: it reports work that is genuinely pending, runs only while that work is pending, and stops when it resolves. Nothing loops at rest. Every continuous recipe travels linearly at one period, motion.flow, so no two indicators in a view tick against each other, and none carries a spring, because a loop has no rest position to settle to. Reduced motion removes it and leaves the whole track or fill in place — never a partial segment, which would report a measurement nobody took.",
2602
+ "staggerPolicy": "A recipe that animates many marks at once may declare a stagger: a step between consecutive marks and a ceiling on how many are staggered. Past the ceiling every mark arrives together. The whole staggered sequence stays within the recipe's duration ceiling, and a recipe that shows data declares overshoot never and is critically damped — a mark that overshoots its value has shown a number that is not true.",
2575
2603
  "incompressibility": "Deformations conserve volume: every scale(sx, sy) satisfies sx*sy = 1 within 0.005. Corrected by dividing both axes by the square root of the area, which preserves each deformation's aspect ratio exactly and removes only the compressibility error. Enforced by tools/validate-motion.cjs.",
2576
2604
  "ambientPolicy": "Ambient motion is what a surface does at rest. It is a capability tier, not a default: a platform declares support, and a surface opts in. Two rules are absolute. Ambient runs on the rim and the fill and never on a surface the user is reading, for the same reason Resin lenses at its edge rather than rippling through its middle. And it is the first motion that prefers-reduced-motion removes — WCAG 2.2.2 requires that anything moving for more than five seconds can be stopped, and an ambient loop never stops on its own. Where a platform cannot honour it, ambient degrades to a static surface with no other change."
2577
2605
  }
@@ -0,0 +1,177 @@
1
+ {
2
+ "$description": "Crystal's surface vocabulary: the closed set of material compositions a component may be made of, and the crystal.css recipe that implements each. Every catalogue entry names one or more of these in its `surface` field. tools/build-catalogue.cjs refuses an entry naming a surface not listed here, and refuses a surface whose `class` does not exist in core/assets/crystal.css — so a component cannot be specified in a material Crystal has not published a recipe for.",
3
+ "$rule": "The vocabulary is small on purpose. A component that seems to need a new surface almost always needs one of these on a different element; a new entry here is a new material composition for every platform library, and is added with a recipe, a fallback for reduced transparency and forced colours, a contract row in docs/components.md and a changelog entry — never alone.",
4
+ "surfaces": [
5
+ {
6
+ "id": "plastic",
7
+ "name": "Plastic foundation",
8
+ "materials": ["Plastic"],
9
+ "class": ".cr-plastic",
10
+ "use": "The root scene or window. One contextual, opaque foundation per view; never a component."
11
+ },
12
+ {
13
+ "id": "frost",
14
+ "name": "Frost panel",
15
+ "materials": ["Frost"],
16
+ "class": ".cr-frost",
17
+ "use": "Intermediate task frames and every transient surface that opens over content: side panels, drawers, sheets, app bars, and — at Meridian's direction (R15e) — menus, popovers, tooltips and toasts. Reading content inside it sits on Haze."
18
+ },
19
+ {
20
+ "id": "haze",
21
+ "name": "Haze reading surface",
22
+ "materials": ["Haze"],
23
+ "class": ".cr-haze",
24
+ "use": "Anything read: cards, rows, panels, wells, forms, messages, decisions. 80% fill, 1.95px feather on an isolated paint layer, crisp foreground. `.cr-well` is the same recipe recessed into a Frost or Resin frame. `.cr-haze.overlay` is the recessed overlay: a transient overlay opened inside a pane that is already lifted, drawn as a flat Haze fill with the `--cr-edge` rim and the content shadow, so it can be told from the pane it sits in.",
25
+ "also": [".cr-haze.overlay"]
26
+ },
27
+ {
28
+ "id": "resin",
29
+ "name": "Resin plane",
30
+ "materials": ["Resin"],
31
+ "class": ".cr-resin",
32
+ "use": "One floating Resin plane with no reading fill of its own, pill-shaped unless it is a panel: a player's transport bar, a pinned element, a Resin handle over imagery or between regions. Controls inside it lose their own backdrop filter — Resin never contains Resin. A plane whose controls are labels to be read holds a Haze fill as well, and is a dock."
33
+ },
34
+ {
35
+ "id": "resin-panel",
36
+ "name": "Resin panel",
37
+ "materials": ["Resin"],
38
+ "class": ".cr-resin.panel",
39
+ "use": "The Resin plane with the content radius instead of the pill, for a floating control plane that is a rectangle: a floating window, a media control bar wider than it is tall. Same fill, rim, blur and float shadow; only the geometry changes."
40
+ },
41
+ {
42
+ "id": "control",
43
+ "name": "Resin control",
44
+ "materials": ["Resin", "Haze"],
45
+ "class": ".cr-button",
46
+ "also": [".cr-control", "button", "a.cr-button"],
47
+ "use": "An action: a Resin shell with the 8px-inset Haze reading pad and the optical sheen. Pill geometry. `.primary` tints the pad, `.quiet` removes it, `.danger` adds the destructive boundary. Selected state is the primary pad plus label weight 800."
48
+ },
49
+ {
50
+ "id": "field",
51
+ "name": "Field shell",
52
+ "materials": ["Resin", "Haze"],
53
+ "class": ".cr-field-shell",
54
+ "use": "The Resin surround of a native text entry, with the Haze well the value is read on and the circular field-state badge. The native control keeps its functional boundary and semantics."
55
+ },
56
+ {
57
+ "id": "compact",
58
+ "name": "Compact display",
59
+ "materials": ["Resin", "Haze"],
60
+ "class": ".cr-resin-haze",
61
+ "also": [".cr-tag", ".cr-resin-haze.count"],
62
+ "use": "Small information displays that sit on content: tags, badges, labels, keyboard caps. A Resin shell with the inset Haze pad, 18px radius. Not for anything that opens — transient overlays are Frost. `.count` is the size for a count: a 20px circle that grows to a pill, filled to its own edge, with no block padding."
63
+ },
64
+ {
65
+ "id": "stone",
66
+ "name": "Stone label backing",
67
+ "materials": ["Stone"],
68
+ "class": ".cr-stone",
69
+ "use": "A label over an unknown or moving backdrop — a caption on media, a status bar over a scene. 55% light / 60% dark fill, feathered like Haze, crisp text."
70
+ },
71
+ {
72
+ "id": "mirage",
73
+ "name": "Mirage scrim",
74
+ "materials": ["Mirage"],
75
+ "class": ".cr-mirage",
76
+ "also": [".cr-dialog::backdrop"],
77
+ "use": "The chromatic diffusion of the real scene behind a modal. Never a content surface; the decision surface above it is Haze."
78
+ },
79
+ {
80
+ "id": "dialog",
81
+ "name": "Dialog",
82
+ "materials": ["Haze", "Mirage"],
83
+ "class": ".cr-dialog",
84
+ "use": "A Haze decision surface over a Mirage scrim, with the float shadow. Modality, focus and dismissal are the product's. The surface does not scroll: `.cr-dialog-body`, worn with `.cr-scroll-frost`, scrolls inside it, so the title stays in view and the edge fade does not dissolve the surface. `position: fixed` is for a native `<dialog>`; on any other element the host positions it.",
85
+ "also": [".cr-dialog-body"]
86
+ },
87
+ {
88
+ "id": "indicator",
89
+ "name": "Indicator",
90
+ "materials": ["Haze"],
91
+ "class": ".cr-indicator",
92
+ "use": "A 20px informational circle painting Haze on an isolated layer, or the moving pill behind a selected segment. Haze rather than Resin, because it sits on a surface that is often already translucent. Never a selection mark."
93
+ },
94
+ {
95
+ "id": "status",
96
+ "name": "Status badge",
97
+ "materials": ["Resin", "Haze"],
98
+ "class": ".cr-status",
99
+ "use": "The semantic ink and surface pair behind a symbol, with words beside it. Status colours are independent of the palette and are never redefined by it."
100
+ },
101
+ {
102
+ "id": "bubble",
103
+ "name": "Authored bubble",
104
+ "materials": ["Haze"],
105
+ "class": ".cr-bubble",
106
+ "use": "A Haze message surface with a directional tight corner. `.own` uses the palette's own-content pair."
107
+ },
108
+ {
109
+ "id": "table",
110
+ "name": "Table",
111
+ "materials": ["Resin", "Haze"],
112
+ "class": ".cr-table-scroll",
113
+ "also": [".cr-table"],
114
+ "use": "A Resin shell with an inset Haze fill holding the table, with the primary-soft header and the Resin scrollbar. Rows are read on the Haze; sort and selection are announced, and selection is label weight."
115
+ },
116
+ {
117
+ "id": "dock",
118
+ "name": "Dock",
119
+ "materials": ["Resin", "Haze"],
120
+ "class": ".cr-dock",
121
+ "also": [".cr-dock-inner"],
122
+ "use": "A Resin plane holding labelled controls on one Haze fill, so every label reads on the same protected ground: a dock of destinations, and the strips that group controls the same way — tab strips, segmented controls, toolbars, command and action bars. The controls inside are transparent; the current or selected one takes weight 800 and the primary fill, whether it is a dock's destination, a tab or a segment. The controls may be buttons, tabs (`[role=tab]`, selected by `aria-selected`), radio labels (selected by `:checked`) or links (current by `aria-current`); only buttons were reached before 2.3.0."
123
+ },
124
+ {
125
+ "id": "group",
126
+ "name": "Group",
127
+ "materials": ["Resin", "Haze"],
128
+ "class": ".cr-group",
129
+ "also": [".cr-group.vertical"],
130
+ "use": "A Resin plane whose controls touch: button groups and split buttons. The silhouette is one pill, the interior corners square off against their neighbours, and a hairline in `--cr-edge` separates them. The children keep their fill and give up their own elevation and diffusion, because the plane is the group's. `.vertical` stacks them. Not a dock: a dock spaces its controls apart on its Haze fill."
131
+ },
132
+ {
133
+ "id": "nav-item",
134
+ "name": "Navigation entry",
135
+ "materials": ["Plastic"],
136
+ "class": ".cr-nav-item",
137
+ "use": "An entry in side navigation, a rail or a tree of destinations. It has no material of its own — it is furniture on the panel beneath it — and carries selection by label weight alone. Pill hit area, 44px target. `.stacked` puts the icon above the label for a rail. Adopted from the documentation site's side menu, which docs/components.md names as the reference implementation of selection."
138
+ },
139
+ {
140
+ "id": "bare",
141
+ "name": "Bare control",
142
+ "materials": [],
143
+ "class": ".cr-bare",
144
+ "use": "A control that must not wear the Resin coat because it sits inside a surface that already has one: a disclosure chevron, a chip's remove button, a sort header, a stepper's arrows, a dismiss button on a toast. Crystal paints every button by element, so bare means subtracting the fill, the shadow, the backdrop filter and both pseudo-layers — this class does all four. The focus ring and the target floor stay."
145
+ },
146
+ {
147
+ "id": "drag-handle",
148
+ "name": "Drag handle",
149
+ "materials": [],
150
+ "class": ".cr-drag-handle",
151
+ "use": "A bare control with a grip glyph and a lift while dragging. Keyboard drag is the product's; the handle only says it can be grabbed and when it has been."
152
+ },
153
+ {
154
+ "id": "choice",
155
+ "name": "Selection control",
156
+ "materials": ["Resin"],
157
+ "class": "input:is([type=checkbox],[type=radio])",
158
+ "also": ["input[type=checkbox][role=switch]", "input[type=range]"],
159
+ "use": "Native checkbox, radio, switch and range, styled by element: a Resin box, circle or track with a contained mark, and the marked glass thumb. Semantics stay native."
160
+ },
161
+ {
162
+ "id": "native",
163
+ "name": "Native control furniture",
164
+ "materials": [],
165
+ "class": "select option",
166
+ "also": ["input[type=file]::file-selector-button"],
167
+ "use": "Parts of native controls the browser draws and Crystal tints: select options, the file button. Platform-owned popups keep platform drawing."
168
+ },
169
+ {
170
+ "id": "none",
171
+ "name": "No surface of its own",
172
+ "materials": [],
173
+ "class": null,
174
+ "use": "Layout, typography, behaviour and drawing components that inherit whatever they sit on. A chart's marks, a divider, a provider. Nothing to paint and nothing to wear."
175
+ }
176
+ ]
177
+ }