shelving 1.322.0 → 1.322.2

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 (316) hide show
  1. package/docs/api/APIProvider.md +2 -2
  2. package/docs/api/CachedAPIProvider.md +6 -8
  3. package/docs/api/ClientAPIProvider.md +5 -5
  4. package/docs/api/DebugAPIProvider.md +3 -5
  5. package/docs/api/HydratingAPIProvider.md +2 -2
  6. package/docs/api/JSONAPIProvider.md +3 -5
  7. package/docs/api/LoggingAPIProvider.md +7 -9
  8. package/docs/api/MockAPIProvider.md +4 -4
  9. package/docs/api/MockEndpointAPIProvider.md +5 -7
  10. package/docs/api/ThroughAPIProvider.md +15 -10
  11. package/docs/api/ValidationAPIProvider.md +3 -5
  12. package/docs/api/XMLAPIProvider.md +3 -3
  13. package/docs/api.md +48 -44
  14. package/docs/bun.md +9 -9
  15. package/docs/db/DBProvider.md +6 -6
  16. package/docs/db/MemoryDBProvider.md +3 -3
  17. package/docs/db/PostgresProvider.md +6 -4
  18. package/docs/db/SQLProvider.md +6 -3
  19. package/docs/db/SQLiteProvider.md +9 -4
  20. package/docs/db/StorageDBProvider.md +2 -2
  21. package/docs/db/ThroughDBProvider.md +6 -6
  22. package/docs/db/UndoDBProvider.md +2 -2
  23. package/docs/db.md +32 -32
  24. package/docs/error/NetworkError.md +5 -5
  25. package/docs/error/RequestError.md +4 -4
  26. package/docs/error/RequiredError.md +2 -2
  27. package/docs/error/ResponseError.md +1 -1
  28. package/docs/error/UnexpectedError.md +1 -1
  29. package/docs/error/UnsupportedError.md +3 -3
  30. package/docs/error/ValueError.md +2 -2
  31. package/docs/error.md +20 -19
  32. package/docs/extract.md +14 -14
  33. package/docs/firebase.md +6 -6
  34. package/docs/guides/building-with-shelving.md +113 -85
  35. package/docs/guides/styleguide.md +29 -29
  36. package/docs/index.md +3 -2
  37. package/docs/llms-full.txt +2541 -2295
  38. package/docs/markup.md +15 -17
  39. package/docs/react/createAPIContext.md +12 -12
  40. package/docs/react/createDBContext.md +21 -15
  41. package/docs/react/useInstance.md +2 -2
  42. package/docs/react/useLazy.md +1 -1
  43. package/docs/react/useMap.md +10 -6
  44. package/docs/react/useReduce.md +2 -2
  45. package/docs/react/useSequence.md +2 -2
  46. package/docs/react/useStore.md +10 -10
  47. package/docs/react.md +22 -16
  48. package/docs/schema/ArraySchema.md +6 -6
  49. package/docs/schema/BooleanSchema.md +5 -5
  50. package/docs/schema/ChoiceSchema.md +1 -1
  51. package/docs/schema/CurrencyAmountSchema.md +2 -2
  52. package/docs/schema/DataSchema.md +5 -5
  53. package/docs/schema/NullableSchema.md +4 -4
  54. package/docs/schema/NumberSchema.md +4 -4
  55. package/docs/schema/OptionalSchema.md +1 -1
  56. package/docs/schema/StringSchema.md +7 -7
  57. package/docs/schema.md +21 -21
  58. package/docs/sequence/DeferredSequence.md +1 -1
  59. package/docs/sequence/InspectSequence.md +8 -6
  60. package/docs/sequence/LazySequence.md +3 -3
  61. package/docs/sequence/Sequence.md +6 -6
  62. package/docs/sequence/ThroughSequence.md +4 -2
  63. package/docs/sequence.md +3 -3
  64. package/docs/store/ArrayStore.md +6 -6
  65. package/docs/store/BooleanStore.md +2 -2
  66. package/docs/store/BusyStore.md +1 -1
  67. package/docs/store/DataStore.md +5 -5
  68. package/docs/store/DictionaryStore.md +4 -4
  69. package/docs/store/FetchStore.md +6 -6
  70. package/docs/store/PathStore.md +4 -4
  71. package/docs/store/PayloadFetchStore.md +1 -5
  72. package/docs/store/Store.md +8 -6
  73. package/docs/store/URLStore.md +5 -5
  74. package/docs/store.md +15 -15
  75. package/docs/test.md +6 -6
  76. package/docs/ui/App.md +99 -69
  77. package/docs/ui/AppLayout.md +35 -26
  78. package/docs/ui/BackButton.md +13 -11
  79. package/docs/ui/Button.md +73 -64
  80. package/docs/ui/Card.md +23 -22
  81. package/docs/ui/Catcher.md +3 -3
  82. package/docs/ui/ClassProps.md +1 -1
  83. package/docs/ui/Code.md +11 -11
  84. package/docs/ui/CollapseTransition.md +5 -5
  85. package/docs/ui/Deleted.md +6 -6
  86. package/docs/ui/Details.md +13 -13
  87. package/docs/ui/Dialog.md +42 -28
  88. package/docs/ui/Dialogs.md +4 -0
  89. package/docs/ui/DocumentationButtons.md +2 -2
  90. package/docs/ui/DocumentationCard.md +2 -2
  91. package/docs/ui/DocumentationFrame.md +4 -4
  92. package/docs/ui/DocumentationLive.md +11 -11
  93. package/docs/ui/DocumentationPage.md +3 -3
  94. package/docs/ui/Emphasis.md +4 -4
  95. package/docs/ui/Empty.md +2 -2
  96. package/docs/ui/FadeTransition.md +9 -9
  97. package/docs/ui/Field.md +14 -14
  98. package/docs/ui/FixedLayout.md +27 -25
  99. package/docs/ui/Form.md +41 -39
  100. package/docs/ui/FormStore.md +6 -2
  101. package/docs/ui/Grid.md +21 -9
  102. package/docs/ui/HTML.md +10 -8
  103. package/docs/ui/Head.md +2 -3
  104. package/docs/ui/Heading.md +12 -12
  105. package/docs/ui/HorizontalTransition.md +10 -10
  106. package/docs/ui/Icon.md +4 -4
  107. package/docs/ui/ImageInput.md +12 -12
  108. package/docs/ui/Inserted.md +6 -6
  109. package/docs/ui/Link.md +11 -11
  110. package/docs/ui/List.md +7 -7
  111. package/docs/ui/Loading.md +6 -6
  112. package/docs/ui/Mark.md +11 -9
  113. package/docs/ui/Markup.md +4 -4
  114. package/docs/ui/Menu.md +24 -24
  115. package/docs/ui/MenuItem.md +29 -29
  116. package/docs/ui/Modal.md +57 -45
  117. package/docs/ui/Navigation.md +28 -26
  118. package/docs/ui/NavigationStore.md +18 -18
  119. package/docs/ui/Notice.md +15 -15
  120. package/docs/ui/Notices.md +17 -17
  121. package/docs/ui/Page.md +13 -13
  122. package/docs/ui/Panel.md +8 -8
  123. package/docs/ui/Paragraph.md +5 -5
  124. package/docs/ui/Progress.md +11 -11
  125. package/docs/ui/Prose.md +6 -6
  126. package/docs/ui/QueryRadiosInput.md +2 -2
  127. package/docs/ui/RouteCache.md +27 -27
  128. package/docs/ui/Router.md +70 -61
  129. package/docs/ui/SchemaInput.md +20 -20
  130. package/docs/ui/Scroll.md +16 -16
  131. package/docs/ui/Section.md +13 -10
  132. package/docs/ui/SidebarLayout.md +27 -27
  133. package/docs/ui/Small.md +4 -4
  134. package/docs/ui/Span.md +3 -1
  135. package/docs/ui/StackButton.md +13 -7
  136. package/docs/ui/Strong.md +4 -4
  137. package/docs/ui/Subheading.md +12 -12
  138. package/docs/ui/TINT_CLASS.md +11 -11
  139. package/docs/ui/Table.md +40 -29
  140. package/docs/ui/Tag.md +15 -15
  141. package/docs/ui/Title.md +13 -13
  142. package/docs/ui/Transition.md +22 -22
  143. package/docs/ui/TreeApp.md +8 -8
  144. package/docs/ui/TreeMarkup.md +2 -2
  145. package/docs/ui/TreeMenu.md +3 -3
  146. package/docs/ui/TreeSidebar.md +1 -1
  147. package/docs/ui/VerticalTransition.md +8 -8
  148. package/docs/ui/getClass.md +10 -10
  149. package/docs/ui/getColorClass.md +23 -23
  150. package/docs/ui/getDurationClass.md +5 -5
  151. package/docs/ui/getGridClass.md +2 -2
  152. package/docs/ui/getHeightClass.md +4 -4
  153. package/docs/ui/getRadiusClass.md +9 -9
  154. package/docs/ui/getShadowClass.md +6 -6
  155. package/docs/ui/getSpaceClass.md +13 -13
  156. package/docs/ui/getStrokeClass.md +6 -6
  157. package/docs/ui/getTypographyClass.md +38 -38
  158. package/docs/ui/getWidthClass.md +4 -4
  159. package/docs/ui/notify.md +11 -11
  160. package/docs/ui/requireContext.md +1 -1
  161. package/docs/ui.md +4 -4
  162. package/docs/util/array.md +35 -29
  163. package/docs/util/async.md +2 -2
  164. package/docs/util/base64.md +7 -7
  165. package/docs/util/boolean.md +10 -10
  166. package/docs/util/buffer.md +5 -5
  167. package/docs/util/bytes.md +9 -9
  168. package/docs/util/class.md +10 -6
  169. package/docs/util/color.md +13 -13
  170. package/docs/util/constants.md +2 -2
  171. package/docs/util/crypto.md +1 -1
  172. package/docs/util/currency.md +2 -2
  173. package/docs/util/data.md +18 -18
  174. package/docs/util/date.md +22 -22
  175. package/docs/util/debug/debug.md +12 -12
  176. package/docs/util/dictionary.md +21 -18
  177. package/docs/util/diff.md +6 -6
  178. package/docs/util/dispose/dispose.md +5 -5
  179. package/docs/util/duration.md +9 -9
  180. package/docs/util/element.md +1 -1
  181. package/docs/util/entity.md +6 -6
  182. package/docs/util/entry.md +21 -8
  183. package/docs/util/env.md +2 -2
  184. package/docs/util/equal.md +16 -16
  185. package/docs/util/error.md +4 -4
  186. package/docs/util/file.md +8 -8
  187. package/docs/util/filter.md +9 -5
  188. package/docs/util/format.md +18 -18
  189. package/docs/util/function.md +4 -4
  190. package/docs/util/geo.md +13 -13
  191. package/docs/util/hash.md +3 -3
  192. package/docs/util/http.md +1 -1
  193. package/docs/util/hydrate/hydrate.md +7 -4
  194. package/docs/util/item.md +4 -4
  195. package/docs/util/iterate.md +11 -11
  196. package/docs/util/jwt.md +1 -6
  197. package/docs/util/link.md +5 -5
  198. package/docs/util/map.md +17 -11
  199. package/docs/util/merge.md +2 -5
  200. package/docs/util/null.md +20 -10
  201. package/docs/util/number.md +16 -16
  202. package/docs/util/object.md +25 -22
  203. package/docs/util/path.md +17 -17
  204. package/docs/util/query.md +23 -25
  205. package/docs/util/random.md +7 -7
  206. package/docs/util/regexp.md +16 -16
  207. package/docs/util/sequence.md +16 -10
  208. package/docs/util/serialise/serialise.md +6 -6
  209. package/docs/util/set.md +10 -10
  210. package/docs/util/sort.md +10 -11
  211. package/docs/util/source.md +11 -7
  212. package/docs/util/start.md +8 -8
  213. package/docs/util/string.md +14 -14
  214. package/docs/util/template.md +3 -3
  215. package/docs/util/timeout.md +5 -5
  216. package/docs/util/transform.md +6 -6
  217. package/docs/util/tree.md +13 -13
  218. package/docs/util/undefined.md +3 -3
  219. package/docs/util/units.md +15 -15
  220. package/docs/util/update.md +16 -16
  221. package/docs/util/uri.md +12 -12
  222. package/docs/util/url.md +11 -11
  223. package/docs/util/uuid.md +3 -3
  224. package/docs/util/validate.md +14 -9
  225. package/package.json +3 -3
  226. package/skills/shelving/SKILL.md +1 -0
  227. package/ui/README.md +4 -4
  228. package/ui/app/App.md +99 -69
  229. package/ui/block/Card.md +23 -22
  230. package/ui/block/Details.md +13 -13
  231. package/ui/block/Grid.md +21 -9
  232. package/ui/block/Heading.md +12 -12
  233. package/ui/block/List.md +7 -7
  234. package/ui/block/Panel.md +8 -8
  235. package/ui/block/Paragraph.md +5 -5
  236. package/ui/block/Prose.md +6 -6
  237. package/ui/block/Section.md +13 -10
  238. package/ui/block/Subheading.md +12 -12
  239. package/ui/block/Title.md +13 -13
  240. package/ui/button/Button.md +73 -64
  241. package/ui/dialog/Dialog.md +42 -28
  242. package/ui/dialog/Dialogs.d.ts +4 -0
  243. package/ui/dialog/Dialogs.js +4 -0
  244. package/ui/dialog/Dialogs.tsx +4 -0
  245. package/ui/dialog/Modal.md +57 -45
  246. package/ui/docs/DocumentationButtons.md +2 -2
  247. package/ui/docs/DocumentationCard.md +2 -2
  248. package/ui/docs/DocumentationFrame.md +4 -4
  249. package/ui/docs/DocumentationLive.md +11 -11
  250. package/ui/docs/DocumentationPage.md +3 -3
  251. package/ui/form/Field.md +14 -14
  252. package/ui/form/Form.md +41 -39
  253. package/ui/form/FormStore.md +6 -2
  254. package/ui/form/Progress.md +11 -11
  255. package/ui/inline/Code.md +11 -11
  256. package/ui/inline/Deleted.md +6 -6
  257. package/ui/inline/Emphasis.md +4 -4
  258. package/ui/inline/Inserted.md +6 -6
  259. package/ui/inline/Link.md +11 -11
  260. package/ui/inline/Mark.md +11 -9
  261. package/ui/inline/Small.md +4 -4
  262. package/ui/inline/Span.md +3 -1
  263. package/ui/inline/Strong.md +4 -4
  264. package/ui/input/ImageInput.md +12 -12
  265. package/ui/input/QueryRadiosInput.md +2 -2
  266. package/ui/input/SchemaInput.md +20 -20
  267. package/ui/layout/AppLayout.md +35 -26
  268. package/ui/layout/AppLayout.module.css +3 -16
  269. package/ui/layout/FixedLayout.md +27 -25
  270. package/ui/layout/SidebarLayout.md +27 -27
  271. package/ui/layout/SidebarLayout.module.css +1 -0
  272. package/ui/menu/Menu.md +24 -24
  273. package/ui/menu/MenuItem.md +29 -29
  274. package/ui/misc/Catcher.md +3 -3
  275. package/ui/misc/Icon.md +4 -4
  276. package/ui/misc/Loading.md +6 -6
  277. package/ui/misc/Markup.md +4 -4
  278. package/ui/misc/Tag.md +15 -15
  279. package/ui/notice/Empty.md +2 -2
  280. package/ui/notice/Notice.md +15 -15
  281. package/ui/notice/Notices.md +17 -17
  282. package/ui/page/HTML.md +10 -8
  283. package/ui/page/Head.md +2 -3
  284. package/ui/page/Page.md +13 -13
  285. package/ui/router/BackButton.md +13 -11
  286. package/ui/router/Navigation.md +28 -26
  287. package/ui/router/NavigationStore.md +18 -18
  288. package/ui/router/RouteCache.md +27 -27
  289. package/ui/router/Router.md +70 -61
  290. package/ui/router/StackButton.md +13 -7
  291. package/ui/style/Scroll.md +16 -16
  292. package/ui/style/TINT_CLASS.md +11 -11
  293. package/ui/style/getColorClass.md +23 -23
  294. package/ui/style/getDurationClass.md +5 -5
  295. package/ui/style/getGridClass.md +2 -2
  296. package/ui/style/getHeightClass.md +4 -4
  297. package/ui/style/getRadiusClass.md +9 -9
  298. package/ui/style/getShadowClass.md +6 -6
  299. package/ui/style/getSpaceClass.md +13 -13
  300. package/ui/style/getStrokeClass.md +6 -6
  301. package/ui/style/getTypographyClass.md +38 -38
  302. package/ui/style/getWidthClass.md +4 -4
  303. package/ui/table/Table.md +40 -30
  304. package/ui/transition/CollapseTransition.md +5 -5
  305. package/ui/transition/FadeTransition.md +9 -9
  306. package/ui/transition/HorizontalTransition.md +10 -10
  307. package/ui/transition/Transition.md +22 -22
  308. package/ui/transition/VerticalTransition.md +8 -8
  309. package/ui/tree/TreeApp.md +8 -8
  310. package/ui/tree/TreeMarkup.md +2 -2
  311. package/ui/tree/TreeMenu.md +3 -3
  312. package/ui/tree/TreeSidebar.md +1 -1
  313. package/ui/util/ClassProps.md +1 -1
  314. package/ui/util/getClass.md +10 -10
  315. package/ui/util/notify.md +11 -11
  316. package/ui/util/requireContext.md +1 -1
@@ -21,11 +21,11 @@ The entry point for a tree-based documentation site. Given a `TreeElement` from
21
21
  - Only directories and files (plus `kind: "module"` symbols) appear in the navigation — code symbols are kept off the sidebar but still get their own pages.
22
22
  - Every renderer is overridable. Each dispatch layer is a `[Mapping, Mapper]` pair built by `createMapper()`; wrap the app (or any subtree) in the matching `*Mapping` component to swap a renderer for one element type without touching anything else:
23
23
 
24
- | Mapping pair | Overrides |
25
- |---|---|
24
+ | Mapping pair | Overrides |
25
+ | -------------------------------------- | ------------------------------------------------- |
26
26
  | `TreePageMapping` / `TreeRouterMapper` | Full-page renderer (dispatched by `<TreeRouter>`) |
27
- | `TreeMenuMapping` / `TreeMenuMapper` | Sidebar menu item |
28
- | `TreeCardMapping` / `TreeCardMapper` | Card in a listing |
27
+ | `TreeMenuMapping` / `TreeMenuMapper` | Sidebar menu item |
28
+ | `TreeCardMapping` / `TreeCardMapper` | Card in a listing |
29
29
 
30
30
  ## Usage
31
31
 
@@ -35,7 +35,7 @@ The entry point for a tree-based documentation site. Given a `TreeElement` from
35
35
  import { TreeApp } from "shelving/ui";
36
36
 
37
37
  // `tree` is a TreeElement returned by DirectoryExtractor (see /extract).
38
- <TreeApp tree={tree} />
38
+ <TreeApp tree={tree} />;
39
39
  ```
40
40
 
41
41
  That single line produces a complete documentation site.
@@ -45,7 +45,7 @@ That single line produces a complete documentation site.
45
45
  Extra `routes` are merged before the tree routes, so they take precedence on conflicts.
46
46
 
47
47
  ```tsx
48
- <TreeApp tree={tree} routes={{ "/changelog": ChangelogPage }} />
48
+ <TreeApp tree={tree} routes={{ "/changelog": ChangelogPage }} />;
49
49
  ```
50
50
 
51
51
  ### Overriding a renderer
@@ -56,8 +56,8 @@ Wrap the app (or any subtree) in a `*Mapping` component to replace the renderer
56
56
  import { TreeApp, TreePageMapping } from "shelving/ui";
57
57
 
58
58
  <TreePageMapping mapping={{ "tree-element": MyTreePage }}>
59
- <TreeApp tree={tree} />
60
- </TreePageMapping>
59
+ <TreeApp tree={tree} />
60
+ </TreePageMapping>;
61
61
  ```
62
62
 
63
63
  The same pattern works for `TreeMenuMapping` (sidebar items) and `TreeCardMapping` (cards inside directory listings).
@@ -27,8 +27,8 @@ import { TreeMarkup } from "shelving/ui";
27
27
 
28
28
  // Inline code spans link automatically: `BooleanSchema` → /schema/BooleanSchema.
29
29
  <Prose>
30
- <TreeMarkup>{element.props.content}</TreeMarkup>
31
- </Prose>
30
+ <TreeMarkup>{element.props.content}</TreeMarkup>
31
+ </Prose>;
32
32
  ```
33
33
 
34
34
 
@@ -26,7 +26,7 @@ import { TreeMenu } from "shelving/ui";
26
26
  import { useTreeMap } from "shelving/ui";
27
27
 
28
28
  // Just the navigation menu from the flattened root's children.
29
- <TreeMenu tree={useTreeMap().get("/")} />
29
+ <TreeMenu tree={useTreeMap().get("/")} />;
30
30
  ```
31
31
 
32
32
  Override the menu-item renderer for one element type:
@@ -35,8 +35,8 @@ Override the menu-item renderer for one element type:
35
35
  import { TreeApp, TreeMenuMapping } from "shelving/ui";
36
36
 
37
37
  <TreeMenuMapping mapping={{ "tree-element": MyMenuItem }}>
38
- <TreeApp tree={tree} />
39
- </TreeMenuMapping>
38
+ <TreeApp tree={tree} />
39
+ </TreeMenuMapping>;
40
40
  ```
41
41
 
42
42
 
@@ -28,7 +28,7 @@ The default sidebar for a tree-based site: a "home" link, a search-as-you-type f
28
28
  import { TreeSidebar } from "shelving/ui";
29
29
 
30
30
  // A home link + children menu combined — the default sidebar.
31
- <TreeSidebar />
31
+ <TreeSidebar />;
32
32
  ```
33
33
 
34
34
 
@@ -34,8 +34,8 @@ A direction-aware `<Transition>` preset that slides its children vertically —
34
34
  import { VerticalTransition } from "shelving/ui";
35
35
 
36
36
  <VerticalTransition>
37
- <Router routes={ROUTES}/>
38
- </VerticalTransition>
37
+ <Router routes={ROUTES} />
38
+ </VerticalTransition>;
39
39
  ```
40
40
 
41
41
  ## Use the class without the component
@@ -47,16 +47,16 @@ import { ViewTransition } from "react";
47
47
  import { SLIDE_DOWN_TRANSITION_CLASS } from "shelving/ui";
48
48
 
49
49
  <ViewTransition enter={SLIDE_DOWN_TRANSITION_CLASS} exit={SLIDE_DOWN_TRANSITION_CLASS}>
50
- <div className="panel">…</div>
51
- </ViewTransition>
50
+ <div className="panel">…</div>
51
+ </ViewTransition>;
52
52
  ```
53
53
 
54
54
  ## Styling
55
55
 
56
- | Variable | Styles | Default |
57
- |---|---|---|
58
- | `--vertical-transition-size` | Slide distance for the enter/leave keyframes. A percentage is of the element's own height. | `100%` |
59
- | `--vertical-transition-duration` | Duration of the slide keyframes | `var(--duration-normal)` |
56
+ | Variable | Styles | Default |
57
+ | -------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------ |
58
+ | `--vertical-transition-size` | Slide distance for the enter/leave keyframes. A percentage is of the element's own height. | `100%` |
59
+ | `--vertical-transition-duration` | Duration of the slide keyframes | `var(--duration-normal)` |
60
60
 
61
61
  **Global tokens it reads** — `--duration-normal`.
62
62
 
@@ -42,16 +42,16 @@ import { getClass, getModuleClass, getTypographyClass } from "shelving/ui";
42
42
  import BUTTON_CSS from "./Button.module.css";
43
43
 
44
44
  export function Button({ children, ...variants }: ButtonProps): ReactElement {
45
- return (
46
- <button
47
- className={getClass(
48
- getModuleClass(BUTTON_CSS, "button", variants), //
49
- getTypographyClass(variants),
50
- )}
51
- >
52
- {children}
53
- </button>
54
- );
45
+ return (
46
+ <button
47
+ className={getClass(
48
+ getModuleClass(BUTTON_CSS, "button", variants), //
49
+ getTypographyClass(variants),
50
+ )}
51
+ >
52
+ {children}
53
+ </button>
54
+ );
55
55
  }
56
56
  ```
57
57
 
@@ -19,36 +19,36 @@ The following `:root` variables are defined by this module and can be overridden
19
19
 
20
20
  ### Palette
21
21
 
22
- | Variable | Default | Notes |
23
- |---|---|---|
24
- | `--color-gray` | `oklch(60% 0.01 240)` | Neutral anchor — also the default tint when nothing moves it. |
25
- | `--color-red` | `oklch(62% 0.2 30)` | |
26
- | `--color-orange` | `oklch(74% 0.157 60)` | |
27
- | `--color-yellow` | `oklch(86% 0.16 92)` | |
28
- | `--color-green` | `oklch(72% 0.185 130)` | |
29
- | `--color-aqua` | `oklch(72% 0.121 185)` | |
30
- | `--color-blue` | `oklch(57% 0.216 260)` | |
31
- | `--color-purple` | `oklch(58% 0.25 300)` | |
32
- | `--color-pink` | `oklch(68% 0.239 350)` | |
22
+ | Variable | Default | Notes |
23
+ | ---------------- | ---------------------- | ------------------------------------------------------------- |
24
+ | `--color-gray` | `oklch(60% 0.01 240)` | Neutral anchor — also the default tint when nothing moves it. |
25
+ | `--color-red` | `oklch(62% 0.2 30)` | |
26
+ | `--color-orange` | `oklch(74% 0.157 60)` | |
27
+ | `--color-yellow` | `oklch(86% 0.16 92)` | |
28
+ | `--color-green` | `oklch(72% 0.185 130)` | |
29
+ | `--color-aqua` | `oklch(72% 0.121 185)` | |
30
+ | `--color-blue` | `oklch(57% 0.216 260)` | |
31
+ | `--color-purple` | `oklch(58% 0.25 300)` | |
32
+ | `--color-pink` | `oklch(68% 0.239 350)` | |
33
33
 
34
34
  ### Semantic
35
35
 
36
- | Variable | Default | Used for |
37
- |---|---|---|
38
- | `--color-link` | `var(--color-blue)` | Link colour. |
39
- | `--color-focus` | `var(--color-blue)` | Focus outlines. |
40
- | `--color-success` | `var(--color-green)` | `status="success"`. |
41
- | `--color-warning` | `var(--color-orange)` | `status="warning"`. |
42
- | `--color-failure` | `var(--color-red)` | `status="error"` / `status="danger"`. |
43
- | `--color-backdrop` | `#0006` | The backdrop that dims the page behind `<Dialog>` and an open `<SidebarLayout>` drawer. |
36
+ | Variable | Default | Used for |
37
+ | ------------------ | --------------------- | --------------------------------------------------------------------------------------- |
38
+ | `--color-link` | `var(--color-blue)` | Link colour. |
39
+ | `--color-focus` | `var(--color-blue)` | Focus outlines. |
40
+ | `--color-success` | `var(--color-green)` | `status="success"`. |
41
+ | `--color-warning` | `var(--color-orange)` | `status="warning"`. |
42
+ | `--color-failure` | `var(--color-red)` | `status="error"` / `status="danger"`. |
43
+ | `--color-backdrop` | `#0006` | The backdrop that dims the page behind `<Dialog>` and an open `<SidebarLayout>` drawer. |
44
44
 
45
45
  ### Brand
46
46
 
47
- | Variable | Default | Used for |
48
- |---|---|---|
49
- | `--color-primary` | `var(--color-blue)` | `color="primary"`. |
47
+ | Variable | Default | Used for |
48
+ | ------------------- | --------------------- | -------------------- |
49
+ | `--color-primary` | `var(--color-blue)` | `color="primary"`. |
50
50
  | `--color-secondary` | `var(--color-purple)` | `color="secondary"`. |
51
- | `--color-tertiary` | `var(--color-pink)` | `color="tertiary"`. |
51
+ | `--color-tertiary` | `var(--color-pink)` | `color="tertiary"`. |
52
52
 
53
53
 
54
54
  ## Signatures
@@ -11,11 +11,11 @@ This module's main job is to **define and document the transition/animation timi
11
11
 
12
12
  The following `:root` variables are defined by this module and can be overridden in a theme file to adjust default styling across the whole app.
13
13
 
14
- | Variable | Default | Used for |
15
- |---|---|---|
16
- | `--duration-fast` | `150ms` | Snappy UI feedback — hovers, small toggles. |
17
- | `--duration-normal` | `300ms` | Default transitions. |
18
- | `--duration-slow` | `600ms` | Deliberate, large movements. |
14
+ | Variable | Default | Used for |
15
+ | ------------------- | ------- | ------------------------------------------- |
16
+ | `--duration-fast` | `150ms` | Snappy UI feedback — hovers, small toggles. |
17
+ | `--duration-normal` | `300ms` | Default transitions. |
18
+ | `--duration-slow` | `600ms` | Deliberate, large movements. |
19
19
 
20
20
 
21
21
  ## Signatures
@@ -22,8 +22,8 @@ The grid variant props lay out a component's children in equal-width columns —
22
22
 
23
23
  ## Styling
24
24
 
25
- | Variable | Styles | Default |
26
- |---|---|---|
25
+ | Variable | Styles | Default |
26
+ | ------------ | ---------------------------------------- | --------------------------- |
27
27
  | `--grid-gap` | Space between cells when no `gap` is set | `var(--space-small)` (12px) |
28
28
 
29
29
  **Global tokens it reads:** `--space-small`, plus the `--space-*` token of the `gap` variant.
@@ -28,10 +28,10 @@ A log-in screen, in the middle of a layout's scroll box:
28
28
 
29
29
  ```tsx
30
30
  <Page title="Log in">
31
- <Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
32
- <LoginForm />
33
- </Block>
34
- </Page>
31
+ <Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
32
+ <LoginForm />
33
+ </Block>
34
+ </Page>;
35
35
  ```
36
36
 
37
37
 
@@ -11,15 +11,15 @@ This module's main job is to **define and document the corner-radius design toke
11
11
 
12
12
  The following `:root` variables are defined by this module and can be overridden in a theme file to adjust default styling across the whole app. Every step derives from `--radius-normal`, so changing that one value reflows the whole ramp.
13
13
 
14
- | Variable | Default | Notes |
15
- |---|---|---|
16
- | `--radius-xxsmall` | `calc(var(--radius-normal) * 0.25)` | 4px |
17
- | `--radius-xsmall` | `calc(var(--radius-normal) * 0.5)` | 8px |
18
- | `--radius-small` | `calc(var(--radius-normal) * 0.75)` | 12px |
19
- | `--radius-normal` | `1rem` | 16px — Base radius (the root of the scale) |
20
- | `--radius-large` | `calc(var(--radius-normal) * 1.5)` | 24px |
21
- | `--radius-xlarge` | `calc(var(--radius-normal) * 2)` | 32px |
22
- | `--radius-xxlarge` | `calc(var(--radius-normal) * 3)` | 48px |
14
+ | Variable | Default | Notes |
15
+ | ------------------ | ----------------------------------- | ------------------------------------------ |
16
+ | `--radius-xxsmall` | `calc(var(--radius-normal) * 0.25)` | 4px |
17
+ | `--radius-xsmall` | `calc(var(--radius-normal) * 0.5)` | 8px |
18
+ | `--radius-small` | `calc(var(--radius-normal) * 0.75)` | 12px |
19
+ | `--radius-normal` | `1rem` | 16px — Base radius (the root of the scale) |
20
+ | `--radius-large` | `calc(var(--radius-normal) * 1.5)` | 24px |
21
+ | `--radius-xlarge` | `calc(var(--radius-normal) * 2)` | 32px |
22
+ | `--radius-xxlarge` | `calc(var(--radius-normal) * 3)` | 48px |
23
23
 
24
24
 
25
25
  ## Signatures
@@ -11,12 +11,12 @@ This module's main job is to **define and document the elevation drop-shadow des
11
11
 
12
12
  The following `:root` variables are defined by this module and can be overridden in a theme file to adjust default styling across the whole app. The scale is [Tailwind's](https://tailwindcss.com/docs/box-shadow) `shadow-md`, `shadow-lg` and `shadow-xl` with half the Y offset, so a sliver of shadow always shows at the top. Each shadow has two layers of `--shadow-color`. Both layers have a negative spread, so no dark line shows under the bottom edge.
13
13
 
14
- | Variable | Default | Used by |
15
- |---|---|---|
16
- | `--shadow-color` | `#0003` (20% black) | Every layer of every shadow below. |
17
- | `--shadow-small` | `0 2px 6px -1px`, `0 1px 4px -2px` | `<Popover>` |
18
- | `--shadow-normal` | `0 5px 15px -3px`, `0 2px 6px -4px` | Floating `<Notices>` |
19
- | `--shadow-large` | `0 10px 25px -5px`, `0 4px 10px -6px` | `<Modal>`, the open `<SidebarLayout>` drawer |
14
+ | Variable | Default | Used by |
15
+ | ----------------- | ------------------------------------- | -------------------------------------------- |
16
+ | `--shadow-color` | `#0003` (20% black) | Every layer of every shadow below. |
17
+ | `--shadow-small` | `0 2px 6px -1px`, `0 1px 4px -2px` | `<Popover>` |
18
+ | `--shadow-normal` | `0 5px 15px -3px`, `0 2px 6px -4px` | Floating `<Notices>` |
19
+ | `--shadow-large` | `0 10px 25px -5px`, `0 4px 10px -6px` | `<Modal>`, the open `<SidebarLayout>` drawer |
20
20
 
21
21
  The table shows the values in pixels. The source uses `rem`.
22
22
 
@@ -19,22 +19,22 @@ The following `:root` variables are defined by this module and can be overridden
19
19
 
20
20
  ### Scale
21
21
 
22
- | Variable | Default | Notes |
23
- |---|---|---|
24
- | `--space-xxsmall` | `var(--space-normal) * 0.25` | 4px |
25
- | `--space-xsmall` | `var(--space-normal) * 0.5` | 8px |
26
- | `--space-small` | `var(--space-normal) * 0.75` | 12px |
27
- | `--space-normal` | 1rem | 16px - base spacing unit (the root of the scale). |
28
- | `--space-large` | `var(--space-normal) * 1.5` | 24px |
29
- | `--space-xlarge` | `var(--space-normal) * 2` | 32px |
30
- | `--space-xxlarge` | `var(--space-normal) * 3` | 48px |
22
+ | Variable | Default | Notes |
23
+ | ----------------- | ---------------------------- | ------------------------------------------------- |
24
+ | `--space-xxsmall` | `var(--space-normal) * 0.25` | 4px |
25
+ | `--space-xsmall` | `var(--space-normal) * 0.5` | 8px |
26
+ | `--space-small` | `var(--space-normal) * 0.75` | 12px |
27
+ | `--space-normal` | 1rem | 16px - base spacing unit (the root of the scale). |
28
+ | `--space-large` | `var(--space-normal) * 1.5` | 24px |
29
+ | `--space-xlarge` | `var(--space-normal) * 2` | 32px |
30
+ | `--space-xxlarge` | `var(--space-normal) * 3` | 48px |
31
31
 
32
32
  ### Semantic
33
33
 
34
- | Variable | Default | Used for |
35
- |---|---|---|
36
- | `--space-section` | `2rem` | Top margin for titles / headings / section blocks. |
37
- | `--space-paragraph` | `var(--space-normal)` | Default block-space for most prose elements. |
34
+ | Variable | Default | Used for |
35
+ | ------------------- | --------------------- | -------------------------------------------------- |
36
+ | `--space-section` | `2rem` | Top margin for titles / headings / section blocks. |
37
+ | `--space-paragraph` | `var(--space-normal)` | Default block-space for most prose elements. |
38
38
 
39
39
 
40
40
  ## Signatures
@@ -11,12 +11,12 @@ This module's main job is to **define and document the border-thickness design t
11
11
 
12
12
  The following `:root` variables are defined by this module and can be overridden in a theme file to adjust default styling across the whole app.
13
13
 
14
- | Variable | Default | Used for |
15
- |---|---|---|
16
- | `--stroke` | `2px` | Base border thickness — the root of the scale. |
17
- | `--stroke-normal` | `calc(var(--stroke) * 1)` | Default borders. |
18
- | `--stroke-thick` | `calc(var(--stroke) * 1.5)` | Heavier borders. |
19
- | `--stroke-focus` | `var(--stroke-thick)` | Focus-outline thickness. |
14
+ | Variable | Default | Used for |
15
+ | ----------------- | --------------------------- | ---------------------------------------------- |
16
+ | `--stroke` | `2px` | Base border thickness — the root of the scale. |
17
+ | `--stroke-normal` | `calc(var(--stroke) * 1)` | Default borders. |
18
+ | `--stroke-thick` | `calc(var(--stroke) * 1.5)` | Heavier borders. |
19
+ | `--stroke-focus` | `var(--stroke-thick)` | Focus-outline thickness. |
20
20
 
21
21
 
22
22
  ## Signatures
@@ -21,57 +21,57 @@ The following `:root` variables are defined by this module and can be overridden
21
21
 
22
22
  ### Faces
23
23
 
24
- | Variable | Default | Notes |
25
- |---|---|---|
26
- | `--font-sans` | `system-ui` | Default UI face. |
27
- | `--font-monospace` | `ui-monospace, "SF Mono", "Consolas", "Menlo", monospace` | Code face. |
28
- | `--font-serif` | `"Palatino", "Garamond", serif` | Serif face. |
29
- | `--font-title` | `var(--font-sans)` | Headings and titles. |
30
- | `--font-body` | `var(--font-sans)` | Body baseline. |
31
- | `--font-label` | `var(--font-sans)` | Labels. |
32
- | `--font-code` | `var(--font-monospace)` | Code and preformatted text. |
24
+ | Variable | Default | Notes |
25
+ | ------------------ | --------------------------------------------------------- | --------------------------- |
26
+ | `--font-sans` | `system-ui` | Default UI face. |
27
+ | `--font-monospace` | `ui-monospace, "SF Mono", "Consolas", "Menlo", monospace` | Code face. |
28
+ | `--font-serif` | `"Palatino", "Garamond", serif` | Serif face. |
29
+ | `--font-title` | `var(--font-sans)` | Headings and titles. |
30
+ | `--font-body` | `var(--font-sans)` | Body baseline. |
31
+ | `--font-label` | `var(--font-sans)` | Labels. |
32
+ | `--font-code` | `var(--font-monospace)` | Code and preformatted text. |
33
33
 
34
34
  ### Weights
35
35
 
36
- | Variable | Default | Used for |
37
- |---|---|---|
38
- | `--weight-normal` | `400` | Body text. |
39
- | `--weight-strong` | `700` | Bold / emphasis. |
40
- | `--weight-title` | `var(--weight-strong)` | Headings and titles. |
41
- | `--weight-body` | `var(--weight-normal)` | Body baseline. |
42
- | `--weight-label` | `var(--weight-strong)` | Labels (`<Label>`, table/definition headers). |
43
- | `--weight-code` | `500` | Monospace / code. |
36
+ | Variable | Default | Used for |
37
+ | ----------------- | ---------------------- | --------------------------------------------- |
38
+ | `--weight-normal` | `400` | Body text. |
39
+ | `--weight-strong` | `700` | Bold / emphasis. |
40
+ | `--weight-title` | `var(--weight-strong)` | Headings and titles. |
41
+ | `--weight-body` | `var(--weight-normal)` | Body baseline. |
42
+ | `--weight-label` | `var(--weight-strong)` | Labels (`<Label>`, table/definition headers). |
43
+ | `--weight-code` | `500` | Monospace / code. |
44
44
 
45
45
  ### Sizes
46
46
 
47
- | Variable | Default | Notes |
48
- |---|---|---|
49
- | `--size-scale` | `1.25` | Ratio between steps. |
50
- | `--size-normal` | `1rem` | Base size — the root of the modular scale. |
47
+ | Variable | Default | Notes |
48
+ | ------------------------------------ | ------------------------------------------------------ | ----------------------------------------------------- |
49
+ | `--size-scale` | `1.25` | Ratio between steps. |
50
+ | `--size-normal` | `1rem` | Base size — the root of the modular scale. |
51
51
  | `--size-xxsmall` … `--size-xxxlarge` | `calc(var(--size-normal) * pow(var(--size-scale), n))` | Each step is the base scaled by a power of the ratio. |
52
- | `--size-1x` … `--size-10x` | `calc(var(--size-normal) * n)` | Direct multiples of normal size. |
53
- | `--size-icon` | `1.5rem` | Icon box size. |
54
- | `--size-label` | `var(--size-small)` | Label text size. |
55
- | `--size-smaller` | `0.875em` | Relative (em) shrink — e.g. inline `<Small>`. |
56
- | `--size-larger` | `1.5em` | Relative grow. |
57
- | `--size-xlarger` | `2.5em` | Relative grow. |
58
- | `--size-xxlarger` | `5em` | Relative grow. |
52
+ | `--size-1x` … `--size-10x` | `calc(var(--size-normal) * n)` | Direct multiples of normal size. |
53
+ | `--size-icon` | `1.5rem` | Icon box size. |
54
+ | `--size-label` | `var(--size-small)` | Label text size. |
55
+ | `--size-smaller` | `0.875em` | Relative (em) shrink — e.g. inline `<Small>`. |
56
+ | `--size-larger` | `1.5em` | Relative grow. |
57
+ | `--size-xlarger` | `2.5em` | Relative grow. |
58
+ | `--size-xxlarger` | `5em` | Relative grow. |
59
59
 
60
60
  ### Line height
61
61
 
62
- | Variable | Default | Used for |
63
- |---|---|---|
64
- | `--leading` | `clamp(1.05em, calc(1em + 0.5rem), 1.5em)` | Default line height; paired with every font-size variant and the body baseline. |
65
- | `--leading-normal` | `1.5` | Plain unitless line height for dense blocks. |
62
+ | Variable | Default | Used for |
63
+ | ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
64
+ | `--leading` | `clamp(1.05em, calc(1em + 0.5rem), 1.5em)` | Default line height; paired with every font-size variant and the body baseline. |
65
+ | `--leading-normal` | `1.5` | Plain unitless line height for dense blocks. |
66
66
 
67
67
  ### Case
68
68
 
69
- | Variable | Default | Used for |
70
- |---|---|---|
71
- | `--case-title` | `none` | `text-transform` for titles and headings. |
72
- | `--case-body` | `none` | `text-transform` for body text and the body baseline. |
73
- | `--case-label` | `uppercase` | `text-transform` for labels and tags. |
74
- | `--case-code` | `none` | `text-transform` for code and preformatted text. |
69
+ | Variable | Default | Used for |
70
+ | -------------- | ----------- | ----------------------------------------------------- |
71
+ | `--case-title` | `none` | `text-transform` for titles and headings. |
72
+ | `--case-body` | `none` | `text-transform` for body text and the body baseline. |
73
+ | `--case-label` | `uppercase` | `text-transform` for labels and tags. |
74
+ | `--case-code` | `none` | `text-transform` for code and preformatted text. |
75
75
 
76
76
 
77
77
  ## Signatures
@@ -26,11 +26,11 @@ The `width` variant prop sets a component's inline-size — `<Card width="narrow
26
26
 
27
27
  The following `:root` variables are defined by this module and can be overridden in a theme file to adjust default styling across the whole app.
28
28
 
29
- | Variable | Default | Used for |
30
- |---|---|---
29
+ | Variable | Default | Used for |
30
+ | ---------------- | ------- | ---------------------------------------------------------- |
31
31
  | `--width-narrow` | `36rem` | Focused single-purpose column, e.g. forms and login pages. |
32
- | `--width-normal` | `48rem` | Standard content column. |
33
- | `--width-wide` | `80rem` | Full dashboard-style content. |
32
+ | `--width-normal` | `48rem` | Standard content column. |
33
+ | `--width-wide` | `80rem` | Full dashboard-style content. |
34
34
 
35
35
 
36
36
  ## Signatures
package/docs/ui/notify.md CHANGED
@@ -15,15 +15,15 @@ Dispatches a `notice` event so the global `<Notices>` list can display it. This
15
15
  - The event bubbles, so any ancestor subscribed with `subscribeNotices()` receives it; it defaults to dispatching on `window`.
16
16
  - A family of helpers builds on `notify`:
17
17
 
18
- | Function | What it does |
19
- |---|---|
20
- | `notify(message, status?, el?)` | Dispatch a notice event (defaults to `window`) |
21
- | `notifySuccess(message, el?)` | Shorthand for a `"success"` notice |
22
- | `notifyError(message, el?)` | Shorthand for an `"error"` notice |
23
- | `notifyThrown(thrown, el?)` | Extract a message from a caught value and dispatch an error |
24
- | `callNotified(callback, ...args)` | Run a callback; dispatch success or error automatically |
25
- | `awaitNotified(promise)` | Same for an already-pending promise |
26
- | `subscribeNotices(callback, el?)` | Listen for notice events; returns an unsubscribe function |
18
+ | Function | What it does |
19
+ | --------------------------------- | ----------------------------------------------------------- |
20
+ | `notify(message, status?, el?)` | Dispatch a notice event (defaults to `window`) |
21
+ | `notifySuccess(message, el?)` | Shorthand for a `"success"` notice |
22
+ | `notifyError(message, el?)` | Shorthand for an `"error"` notice |
23
+ | `notifyThrown(thrown, el?)` | Extract a message from a caught value and dispatch an error |
24
+ | `callNotified(callback, ...args)` | Run a callback; dispatch success or error automatically |
25
+ | `awaitNotified(promise)` | Same for an already-pending promise |
26
+ | `subscribeNotices(callback, el?)` | Listen for notice events; returns an unsubscribe function |
27
27
 
28
28
  ## Usage
29
29
 
@@ -39,8 +39,8 @@ import { callNotified } from "shelving/ui";
39
39
 
40
40
  // Return a string for success; throw for error.
41
41
  callNotified(async () => {
42
- await saveData();
43
- return "Saved!";
42
+ await saveData();
43
+ return "Saved!";
44
44
  });
45
45
  ```
46
46
 
@@ -22,7 +22,7 @@ Reads a React context and throws `RequiredError` if the value is `null` or `unde
22
22
  import { requireContext } from "shelving/ui";
23
23
 
24
24
  function requireNavigation(): NavigationStore {
25
- return requireContext(NavigationContext, requireNavigation);
25
+ return requireContext(NavigationContext, requireNavigation);
26
26
  }
27
27
  ```
28
28
 
package/docs/ui.md CHANGED
@@ -13,8 +13,8 @@ The `ui` module exists so an app never hand-rolls the same form field, card, or
13
13
 
14
14
  A few conventions run through every component:
15
15
 
16
- - **Styling props are for one-off overrides.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`, `width="narrow"`) and boolean props for on/off variants (`<Button plain>`, `<Title center>`, `<Flex wrap>`). Each maps to a class in a CSS Module. Reach for them when a component needs to look different in *one place* — the way the docs site tints its accents purple — not as the way to dress a whole app. You never pass `style`.
17
- - **`className` is the escape hatch.** Most components accept an optional `className`, merged *after* the classes the component computes for itself, so an app class reliably wins over the library's `@layer components` rules. It takes any `Classes` value — a string, an array, or a dictionary of `true` flags — and lands on the component's own root element. Use it for a composed one-off treatment that tokens and per-property hooks can't express (an animation, a bespoke gradient); tokens and hooks stay the primary theming surface. Formatting-only components (`<When>`, `<Prose>`, `<Scroll>`), the `*Layout` components, and `<Dialog>` deliberately don't take one — write a new layout, or style the content inside. See `ClassProps`.
16
+ - **Styling props are for one-off overrides.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`, `width="narrow"`) and boolean props for on/off variants (`<Button plain>`, `<Title center>`, `<Flex wrap>`). Each maps to a class in a CSS Module. Reach for them when a component needs to look different in _one place_ — the way the docs site tints its accents purple — not as the way to dress a whole app. You never pass `style`.
17
+ - **`className` is the escape hatch.** Most components accept an optional `className`, merged _after_ the classes the component computes for itself, so an app class reliably wins over the library's `@layer components` rules. It takes any `Classes` value — a string, an array, or a dictionary of `true` flags — and lands on the component's own root element. Use it for a composed one-off treatment that tokens and per-property hooks can't express (an animation, a bespoke gradient); tokens and hooks stay the primary theming surface. Formatting-only components (`<When>`, `<Prose>`, `<Scroll>`), the `*Layout` components, and `<Dialog>` deliberately don't take one — write a new layout, or style the content inside. See `ClassProps`.
18
18
  - **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like `<Card>`, `<Section>`, `<Button>`, and `<Tag>` rather than shipping their own styling.
19
19
  - **Sentence case.** Titles, headings, and button labels capitalise only the first word.
20
20
  - **Theme with CSS.** An app-wide custom look is a CSS file, not a wall of props. Write a `theme.css` that overrides the base design-token variables (and, where needed, per-component hooks) at `:root`, and import it after the library styles. The recommended workflow is to spend time tuning those variables to match your design — see [Theming](#theming) below.
@@ -25,7 +25,7 @@ The styling system lives in `style/` and has four moving parts: design tokens, t
25
25
 
26
26
  **Design tokens.** Every design-token constant is defined at `:root`, split across the themed token modules in `style/` — each module owns one domain, documents the variables it defines, and is the page a theme author overrides. `style/layers.css` is the cascade-layer anchor; every `*.module.css` `@import`s it plus the specific token modules it references, so the tokens and the layer order reach every component regardless of bundle order. The domains are: colours (`getColorClass()`), typography — font size, weight, family, and case (`getTypographyClass()`), spacing (`getSpaceClass()`), widths (`getWidthClass()`), radii (`getRadiusClass()`), strokes (`getStrokeClass()`), shadows (`getShadowClass()`), and durations (`getDurationClass()`). Each also defines the semantic aliases a theme usually targets (`--color-primary`, `--color-link`, `--space-paragraph`, …). Components read tokens via `var(--token)`.
27
27
 
28
- **The tint scale.** All colour flows from one anchor variable, `--tint-50`, from which a 21-step ladder is computed and *recomputed* under `TINT_CLASS` — the heart of how `color=` and `status=` retint a whole subtree. The ladder, the recompute trick, the painting conventions, and the theming guide all live on the `TINT_CLASS` page.
28
+ **The tint scale.** All colour flows from one anchor variable, `--tint-50`, from which a 21-step ladder is computed and _recomputed_ under `TINT_CLASS` — the heart of how `color=` and `status=` retint a whole subtree. The ladder, the recompute trick, the painting conventions, and the theming guide all live on the `TINT_CLASS` page.
29
29
 
30
30
  **Cascade layers.** Styles are ordered by `@layer`, lowest to highest priority: `defaults` (`:root` tokens, the tint ladder, body baseline) → `components` (the bulk of the CSS: `.card`, `.button`, …) → `variants` (cross-cutting opt-in modifiers, which always beat components) → `overrides` (top-priority structural fixes like `:first-child` / `:last-child` margin collapses). Unlayered rules beat all layered rules, so a theme should set tokens at `:root` or wrap its rules in `@layer`.
31
31
 
@@ -54,7 +54,7 @@ Each base token lives in a themed module that documents the variables it defines
54
54
  - `space` · `width` — layout spacing and widths (`--space-*`, `--width-*`).
55
55
  - `radius` · `stroke` · `shadow` · `duration` — surface tokens (`--radius-*`, `--stroke-*`, `--shadow-*`, `--duration-*`).
56
56
 
57
- The **tint ladder** is the one exception that doesn't follow the override-a-variable pattern: its 21 steps are *recomputed* from a single anchor inside every tinted scope, so you move the anchor (via `color=` / `status=`) rather than overriding individual steps. See `TINT_CLASS` for the full theming guide, and each component's **Styling** section for its per-property hooks.
57
+ The **tint ladder** is the one exception that doesn't follow the override-a-variable pattern: its 21 steps are _recomputed_ from a single anchor inside every tinted scope, so you move the anchor (via `color=` / `status=`) rather than overriding individual steps. See `TINT_CLASS` for the full theming guide, and each component's **Styling** section for its per-property hooks.
58
58
 
59
59
  ## Finding your way around
60
60