@korzun/design 0.0.2 → 0.0.4

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 (61) hide show
  1. package/AGENTS.md +78 -0
  2. package/README.md +11 -1
  3. package/dist/component/index.d.ts +1 -1
  4. package/dist/component/index.d.ts.map +1 -1
  5. package/dist/component/index.js.map +1 -1
  6. package/dist/component/tag/index.d.ts +5 -2
  7. package/dist/component/tag/index.d.ts.map +1 -1
  8. package/dist/component/tag/index.js +2 -2
  9. package/dist/component/tag/index.js.map +1 -1
  10. package/dist/component/tag/style.d.ts +2 -1
  11. package/dist/component/tag/style.d.ts.map +1 -1
  12. package/dist/component/tag/style.js +21 -7
  13. package/dist/component/tag/style.js.map +1 -1
  14. package/dist/theme/theme.d.ts +5 -0
  15. package/dist/theme/theme.d.ts.map +1 -1
  16. package/dist/theme/theme.js +13 -1
  17. package/dist/theme/theme.js.map +1 -1
  18. package/docs/component/card-divider.md +67 -0
  19. package/docs/component/card-row.md +58 -0
  20. package/docs/component/card.md +82 -0
  21. package/docs/component/collapsible-section.md +57 -0
  22. package/docs/component/empty-state.md +49 -0
  23. package/docs/component/meta-line.md +60 -0
  24. package/docs/component/metadata-list.md +60 -0
  25. package/docs/component/nav-desktop.md +62 -0
  26. package/docs/component/nav-mobile.md +82 -0
  27. package/docs/component/page.md +81 -0
  28. package/docs/component/progress-indicator.md +53 -0
  29. package/docs/component/tag.md +69 -0
  30. package/docs/component/theme-setting.md +58 -0
  31. package/docs/component/top-fade.md +60 -0
  32. package/docs/control/back-button.md +55 -0
  33. package/docs/control/button.md +78 -0
  34. package/docs/control/chips-input.md +77 -0
  35. package/docs/control/confirm-modal.md +68 -0
  36. package/docs/control/date-time-input.md +56 -0
  37. package/docs/control/field-list.md +66 -0
  38. package/docs/control/number-input.md +62 -0
  39. package/docs/control/page-actions-bar.md +64 -0
  40. package/docs/control/page-actions-menu.md +65 -0
  41. package/docs/control/page-footer-actions.md +69 -0
  42. package/docs/control/popover.md +74 -0
  43. package/docs/control/segmented-control.md +73 -0
  44. package/docs/control/select.md +86 -0
  45. package/docs/control/switch.md +73 -0
  46. package/docs/control/text-area.md +52 -0
  47. package/docs/control/text-input.md +73 -0
  48. package/docs/control/use-modal-dialog.md +76 -0
  49. package/docs/corners.md +68 -0
  50. package/docs/hooks.md +104 -0
  51. package/docs/icon.md +102 -0
  52. package/docs/patterns.md +116 -0
  53. package/docs/philosophy.md +91 -0
  54. package/docs/theme.md +96 -0
  55. package/docs/toast.md +85 -0
  56. package/docs/tokens.md +95 -0
  57. package/package.json +7 -1
  58. package/src/component/index.ts +1 -1
  59. package/src/component/tag/index.tsx +7 -2
  60. package/src/component/tag/style.ts +27 -7
  61. package/src/theme/theme.ts +16 -1
@@ -0,0 +1,76 @@
1
+ # useModalDialog
2
+
3
+ `import { useModalDialog } from '@korzun/design/control'`
4
+
5
+ A hook that drives a native `<dialog>` from an `isOpen` boolean: it calls
6
+ `showModal()` / `close()` for you and routes Escape and backdrop clicks to
7
+ `onDismiss`. It is the base for every modal in the library (`ConfirmModal`
8
+ uses it). There is no general `Dialog` component; build custom modals with
9
+ this hook plus the `theme.recipe.modal.*` styles.
10
+
11
+ Use something else for: a plain yes/no confirmation (`ConfirmModal`), a
12
+ dropdown or non-modal floating layer (`Popover`).
13
+
14
+ ## Signature
15
+
16
+ ```ts
17
+ function useModalDialog(
18
+ isOpen: boolean,
19
+ onDismiss: () => void,
20
+ canDismiss?: boolean, // default true
21
+ ): RefObject<HTMLDialogElement | null>;
22
+ ```
23
+
24
+ | Argument | Type | Default | Notes |
25
+ |---|---|---|---|
26
+ | `isOpen` | `boolean` | (required) | The single source of truth. `true` calls `showModal()`, `false` calls `close()`. |
27
+ | `onDismiss` | `() => void` | (required) | Called on Escape and on a backdrop click. **It does not close anything itself**: set your `isOpen` state to `false` in it. Receives no event. |
28
+ | `canDismiss` | `boolean` | `true` | When `false`, Escape and backdrop clicks are swallowed. Pass `!loading` (or `countdown === 0`) so an in-flight request can't be escaped. |
29
+
30
+ Returns a ref to attach to the `<dialog>`.
31
+
32
+ ## Behaviour to know
33
+
34
+ - Escape fires the dialog's `cancel` event; the hook always calls
35
+ `preventDefault()` so the browser never closes the dialog behind React's back.
36
+ - A backdrop click counts only when **both** mousedown and mouseup land on the
37
+ `<dialog>` element itself (its content lives in a child). Dragging a text
38
+ selection out of an input onto the backdrop does not dismiss.
39
+ - The `<dialog>` must stay mounted. Rendering it conditionally (`{isOpen && <dialog…>}`)
40
+ breaks `showModal()`; its children also stay mounted while closed, so reset
41
+ any form state yourself when reopening.
42
+ - Never call `showModal()` / `close()` yourself.
43
+
44
+ ## Example
45
+
46
+ ```tsx
47
+ const ref = useModalDialog(isOpen, onClose, !saving);
48
+
49
+ <dialog ref={ref} className={styles.dialog} onClick={(e) => e.stopPropagation()}>
50
+ <div className={styles.header}>Edit progress</div>
51
+ <div className={styles.body}>…</div>
52
+ <div className={styles.footer}>
53
+ <Button type="text" radius="modal" disabled={saving} onClick={onClose}>Cancel</Button>
54
+ <Button type="primary" radius="modal" loading={saving} onClick={save}>Save</Button>
55
+ </div>
56
+ </dialog>
57
+
58
+ // style.ts
59
+ dialog: { ...theme.recipe.modal.dialog }, // radius.lg: the dialog sits on the page
60
+ header: { ...theme.recipe.modal.header },
61
+ body: { padding: `0 ${theme.space.xxl} ${theme.space.xxl}` },
62
+ footer: { ...theme.recipe.modal.footer },
63
+ ```
64
+
65
+ ## Do / don't
66
+
67
+ - Do pass `canDismiss={!loading}` and also disable the Cancel button while
68
+ loading, so every exit is gated the same way.
69
+ - Do keep the `onClick={(e) => e.stopPropagation()}` on the `<dialog>` when it
70
+ is rendered inside a clickable ancestor (a card row); it only stops bubbling,
71
+ dismissal is the hook's job.
72
+ - Do use `radius="modal"` on Buttons inside, and `md` corners for any inset
73
+ surface inside (see [corners](../corners.md)).
74
+ - Don't put a `Select` or `ChipsInput` in a modal without testing it: their
75
+ dropdowns portal to `document.body`, outside the dialog's top layer (see
76
+ [popover](popover.md)).
@@ -0,0 +1,68 @@
1
+ # Corners
2
+
3
+ Corner radius tracks **depth**, not size. Surfaces on the page background have
4
+ the roundest corners. Each surface nested inside another gets a squarer,
5
+ concentric corner, so the inner curve follows the outer one.
6
+
7
+ ## Tokens
8
+
9
+ | Token | Value | Use |
10
+ |---|---|---|
11
+ | `theme.radius.lg` | 16px | Surfaces on the page background |
12
+ | `theme.radius.md` | 8px | One level in: inside a card or modal; also floating layers |
13
+ | `theme.radius.sm` | 4px | Two levels in: inside an input, inset box, row, or menu |
14
+ | `theme.radius.pill` | 999px | Capsules: nav bar, a Switch with no nearby corner |
15
+ | `theme.radius.circle` | 50% | Round glass buttons |
16
+
17
+ ## The rule
18
+
19
+ Find where the element sits, then read its radius from this table:
20
+
21
+ | Where the element sits | Radius | Examples |
22
+ |---|---|---|
23
+ | On the page background | `lg` | `Card`, modal dialog (`recipe.modal.dialog`), a standalone `Button` (default `radius`), `<Select surface="page">` |
24
+ | Inside a card or modal | `md` | inputs (`recipe.input`), `Button radius="card"` / `"modal"`, `Tag`, shaded rows, inset boxes |
25
+ | Inside one of those | `sm` | a chip inside an input, `Button radius="inset"` inside an inset box, a menu item, a Switch track in a shaded row |
26
+ | Flush with its parent (zero inset, edges touch) | the parent's radius | an unlabelled Select's trigger, an input filling its row |
27
+ | Inset 4px or less from its parent | `calc(parent − inset)` | a Switch thumb 2px inside a 4px track is 2px |
28
+ | A small control with no nearby corner | `pill` / `circle` | a Switch in a full-width card header |
29
+ | A floating layer (popover, menu, dropdown, toast) | `md`, plus `shadow.hoverLift` or `recipe.glass` | its items are `sm` |
30
+
31
+ **Step down one token per level** (`lg` → `md` → `sm`). Do not subtract the
32
+ padding: a Card has 13px of inset, but the inputs inside it are `md` (8px), not
33
+ 16 − 13 = 3px. Exact subtraction applies only to tight insets of 4px or less.
34
+
35
+ ## Picking the prop
36
+
37
+ Components take the radius as the **surface they sit on**, not as a size:
38
+
39
+ | Component | Prop | Values |
40
+ |---|---|---|
41
+ | `Button` | `radius` | `background` (lg, the default), `card` (md), `modal` (md), `inset` (sm) |
42
+ | `Select` | `surface` | `page` (lg), `card` (md) |
43
+ | `Switch` | `radius` | `inset` (sm track), `pill` |
44
+
45
+ - Every `Button` inside a `Card` (body or footer) gets `radius="card"`. Leaving
46
+ it out gives a 16px button inside a 16px card: a bug.
47
+ - Every `Button` in a modal footer gets `radius="modal"`.
48
+ - `type="link"` buttons have no padding or background, so radius doesn't apply.
49
+
50
+ ## In your own styles
51
+
52
+ ```ts
53
+ const useStyles = createUseStyles((theme: Theme) => ({
54
+ panel: { ...theme.recipe.card.shell }, // already lg
55
+ inset: {
56
+ backgroundColor: theme.color.bg.cardHeader,
57
+ borderRadius: theme.radius.md, // one level in
58
+ padding: theme.space.md,
59
+ },
60
+ chip: { borderRadius: theme.radius.sm }, // two levels in
61
+ knob: { borderRadius: `calc(${theme.radius.sm} - 2px)` }, // 2px inset
62
+ }));
63
+ ```
64
+
65
+ - Never write a literal `borderRadius` (`'12px'`, `'50%'`). The only
66
+ non-token form allowed is `calc(theme.radius.X - Npx)` for tight insets.
67
+ - Known off-scale values in the library (don't copy them): `CardRow` uses
68
+ `12px`, and `Card size="small"` uses `9px`.
package/docs/hooks.md ADDED
@@ -0,0 +1,104 @@
1
+ # Hooks
2
+
3
+ `import { isStandalone, useMinimizeOnScroll, usePullToRefresh } from '@korzun/design/hooks'`
4
+
5
+ Mobile-chrome behaviour shared by the layout components: detecting the
6
+ installed app, minimizing bottom chrome on scroll, and pull-to-refresh. All
7
+ three read the **window** scroller; they do nothing for content scrolling in an
8
+ inner `overflow: auto` element.
9
+
10
+ ## `isStandalone()`
11
+
12
+ ```ts
13
+ isStandalone(): boolean
14
+ ```
15
+
16
+ True when running as an installed PWA (added to the home screen):
17
+ `(display-mode: standalone)` matches, or iOS Safari's
18
+ `navigator.standalone === true`. Not a hook; a plain function, safe to call
19
+ during render because the status can't change within a session. It touches
20
+ `window`, so don't call it during server rendering.
21
+
22
+ Use it to gate chrome that only makes sense when installed: `TopFade` and a
23
+ pull-to-refresh indicator.
24
+
25
+ ## `useMinimizeOnScroll({ resetKey })`
26
+
27
+ ```ts
28
+ useMinimizeOnScroll({ resetKey }: { resetKey: string }): MinimizeOnScroll
29
+ type MinimizeOnScroll = { minimized: boolean; expand: () => void }
30
+ ```
31
+
32
+ iOS-tab-bar behaviour for bottom chrome. `NavMobile` already uses it; call it
33
+ yourself only for other chrome.
34
+
35
+ - Minimizes when one scroll frame moves **down** at `>= MINIMIZE_SPEED`
36
+ (`0.8` px/ms). Speed, not distance: slow reading never minimizes.
37
+ - Expands after scrolling **up** `EXPAND_AFTER` (`12`) px back from the furthest-down point
38
+ reached since minimizing, on reaching the top, or when you call `expand()`.
39
+ - Only user-driven scrolls count: it ignores scrolling until a `touchstart` or
40
+ `wheel` is seen after `resetKey` last changed (so scroll restoration doesn't
41
+ minimize it). Changing `resetKey` also expands. Pass the route's
42
+ `useLocation().key`.
43
+ - iOS rubber-band overscroll (top and bottom) is clamped out.
44
+
45
+ ## `usePullToRefresh(onRefresh, { enabled })`
46
+
47
+ ```ts
48
+ usePullToRefresh(onRefresh: () => Promise<unknown>, options?: { enabled?: boolean }): PullState
49
+ type PullPhase = 'idle' | 'pulling' | 'armed' | 'refreshing'
50
+ type PullState = { phase: PullPhase; offset: number }
51
+ ```
52
+
53
+ Pull-down-to-refresh for the standalone app, which has no browser gesture. It
54
+ **draws nothing**; you render an indicator from the returned state.
55
+
56
+ - Measures the page's own rubber-band overscroll past the top while a finger is
57
+ down (`-window.scrollY`), so it works only where the browser rubber-bands
58
+ (iOS). It never cancels a touch.
59
+ - `offset`: px of pull, capped at `PULL_THRESHOLD * 1.5` (105). `pulling` below
60
+ `PULL_THRESHOLD` (`70`), `armed` at or above it.
61
+ - Releasing while armed calls `onRefresh` and holds `refreshing` with `offset`
62
+ pinned at `PULL_THRESHOLD` until the promise settles (resolve **or** reject),
63
+ then returns to `idle`. Release short of the threshold returns to `idle`.
64
+ - Ignored: touches starting inside an open `<dialog>`, overscroll with no finger
65
+ down, new pulls while refreshing, and everything when `enabled: false`
66
+ (default `true`).
67
+ - `onRefresh` is read through a ref; an inline closure is fine.
68
+ - **`onRefresh` must return a promise.** A function returning `undefined`
69
+ throws on `.then` and leaves the phase stuck at `refreshing`. Use an `async`
70
+ function.
71
+
72
+ ## Examples
73
+
74
+ ```tsx
75
+ // An indicator for the installed app, mounted once in the layout.
76
+ export const PullToRefreshIndicator = () => {
77
+ const client = useApolloClient();
78
+ const refresh = useCallback(
79
+ () => client.refetchQueries({ include: 'active' }).then(() => undefined, () => undefined),
80
+ [client]
81
+ );
82
+ const { phase, offset } = usePullToRefresh(refresh);
83
+ const style = {
84
+ transform: `translateY(${offset}px)`,
85
+ opacity: Math.min(1, offset / PULL_THRESHOLD),
86
+ };
87
+ return (
88
+ <div style={style}>
89
+ {phase === 'refreshing'
90
+ ? <SpinnerIcon role="status" aria-label="Refreshing" className={styles.spinner} />
91
+ : <ChevronIcon aria-hidden className={phase === 'armed' ? styles.up : styles.down} />}
92
+ </div>
93
+ );
94
+ };
95
+
96
+ {isStandalone() && <PullToRefreshIndicator />}
97
+ ```
98
+
99
+ ## Do / don't
100
+
101
+ - Do gate pull-to-refresh UI on `isStandalone()`; browser tabs have their own.
102
+ - Do return a promise from `onRefresh` that settles even on failure.
103
+ - Don't call `useMinimizeOnScroll` for the bar `NavMobile` already manages.
104
+ - Don't expect any of these to track a nested scroll container.
package/docs/icon.md ADDED
@@ -0,0 +1,102 @@
1
+ # Icons
2
+
3
+ `import { SearchIcon, type IconProps } from '@korzun/design/icon'`
4
+
5
+ Inline SVG icon components, mostly from [Tabler](https://tabler.io/icons) on a
6
+ 24×24 view box. Each one paints in `currentColor`, so it takes the text colour
7
+ of wherever it sits, in both themes, including hover and selected states.
8
+
9
+ Use something else for: a determinate progress mark (`ProgressIndicator`), a
10
+ loading state on a button (`Button`'s `loading`, which draws the spinner for
11
+ you).
12
+
13
+ ## Props (`IconProps`)
14
+
15
+ | Prop | Type | Default | Notes |
16
+ |---|---|---|---|
17
+ | `width` / `height` | `number` | `24` / `24` | Pixels. Set both. A `className` with CSS `width`/`height` overrides them. |
18
+ | `className` | `string` | `''` | On the `<svg>`. Use for size, colour (`color: …`) or animation. |
19
+ | `aria-hidden` | `boolean \| 'true' \| 'false'` | | **Not set by default.** Pass `aria-hidden` for a decorative icon next to text. |
20
+ | `aria-label` / `role` | `string` | | For a meaningful standalone icon: `role="img" aria-label="Warning"` (or `role="status"` for a loading spinner). |
21
+ | `stroke` | `string` | `'currentColor'` | Stroke icons only. |
22
+ | `strokeWidth` | `number` | `2` | Stroke icons only. |
23
+ | `fill` | `string` | `'none'` stroke / `'currentColor'` filled | Ignored by `SpinnerIcon` and the emoji icons. |
24
+
25
+ `defaultStrokeIconProps` and `defaultFilledIconProps` are exported for building
26
+ your own icon with the same defaults.
27
+
28
+ ## Sizing and colour
29
+
30
+ - Size with `width`/`height` props (`<HomeIcon width={14} height={14} />`), or
31
+ with `height: '1em', width: '1em'` in a class so it scales with the text
32
+ (this is what `Button` does for `prefix`/`suffix`).
33
+ - Colour by setting `color` on the icon or any ancestor. Don't pass `stroke` or
34
+ `fill` colours; they bypass the theme.
35
+
36
+ ## Passing icons to other components
37
+
38
+ Components take the icon **component**, never an element:
39
+
40
+ ```tsx
41
+ <Button prefix={SearchIcon}>Search</Button> // ComponentType<IconProps>
42
+ <ConfirmModal icon={AlertOctagonIcon} danger … />
43
+ const item: NavItem = { to: '/', label: 'Home', Icon: HomeIcon, active };
44
+ options={[{ value: 'grid', label: 'Grid', Icon: BooksIcon }]} // SegmentedControl
45
+ ```
46
+
47
+ ## Every icon
48
+
49
+ | Export | Kind | Depicts |
50
+ |---|---|---|
51
+ | `AdjustmentsHorizontalIcon` | stroke | Three horizontal sliders (general settings, filters). |
52
+ | `AlertOctagonIcon` | filled | Octagon with `!` (danger/warning; confirm modals). |
53
+ | `BookIcon` | stroke | A single book (Tabler `book-2`). |
54
+ | `BooksIcon` | stroke | Books standing on a shelf. |
55
+ | `CheckIcon` | filled | A check mark (success). |
56
+ | `ChevronCircleIcon` | stroke | Right chevron in a circle (Card's collapse toggle). |
57
+ | `ChevronIcon` | stroke | Right-pointing chevron; rotate it via `className` for other directions. |
58
+ | `CircleXIcon` | filled | X in a filled circle (clear, error). |
59
+ | `ClockIcon` | stroke | Clock face (time, pending). |
60
+ | `DeviceIcon` | stroke | A tablet / e-reader (Tabler `device-tablet`). |
61
+ | `HandLoveYouIcon` | emoji | 🤟 silhouette (rating 5, "Love"). |
62
+ | `HandOkIcon` | emoji | 👌 silhouette (rating 2, "Okay"). |
63
+ | `HandPeaceIcon` | emoji | ✌️ silhouette (rating 3, "Nice"). |
64
+ | `HandsClapIcon` | emoji | 👏 silhouette (rating 4, "Great"). |
65
+ | `HomeIcon` | stroke | A house. |
66
+ | `InfoCircleIcon` | filled | `i` in a filled circle (info). |
67
+ | `KeyIcon` | stroke | A key (passwords, credentials). |
68
+ | `ListCheckIcon` | stroke | Checklist (requests, tasks). |
69
+ | `MoreIcon` | stroke | Three horizontal dots (overflow menu). |
70
+ | `RowRemoveIcon` | stroke | A table row with an X under it (remove row). |
71
+ | `SearchIcon` | stroke | Magnifying glass. |
72
+ | `SettingsIcon` | stroke | Gear. |
73
+ | `SpinnerIcon` | stroke | A quarter arc. **Does not spin by itself**: add `theme.recipe.spinner` in a class. |
74
+ | `ThumbDownIcon` | emoji | 👎 silhouette (rating 1, "Bad"). |
75
+ | `UploadIcon` | stroke | Arrow up out of a tray. |
76
+ | `UserIcon` | stroke | One person. |
77
+ | `UsersIcon` | stroke | Two people. |
78
+ | `XIcon` | stroke | An X (close, dismiss, error toast). |
79
+
80
+ Filled icons ignore `stroke`/`strokeWidth`. Emoji icons draw the platform's
81
+ colour-emoji glyph as an alpha mask over `currentColor`, so they recolour like
82
+ the others but their exact shape depends on the OS emoji font; they ignore
83
+ `fill`, `stroke` and `strokeWidth`.
84
+
85
+ ## Examples
86
+
87
+ ```tsx
88
+ // Decorative, inline with text.
89
+ <CheckIcon width={15} height={15} aria-hidden className={styles.checkIcon} />
90
+ Book is valid
91
+
92
+ // A spinning loader with an accessible name.
93
+ const useStyle = createUseStyles((theme: Theme) => ({ spinner: theme.recipe.spinner }));
94
+ <SpinnerIcon role="status" aria-label="Loading" className={styles.spinner} />
95
+ ```
96
+
97
+ ## Do / don't
98
+
99
+ - Do pass `aria-hidden` when the icon sits next to a text label.
100
+ - Do give a standalone meaningful icon `role` and `aria-label`.
101
+ - Don't pass `<Icon />` elements where a component is expected.
102
+ - Don't import from icon file paths; only `@korzun/design/icon` is exported.
@@ -0,0 +1,116 @@
1
+ # Patterns
2
+
3
+ How screens are put together from the library, as Bookplate does it.
4
+
5
+ ## A screen
6
+
7
+ A screen is a `Page` holding a vertical stack of `Card`s, one card per feature.
8
+ Page-level buttons sit between the cards with no `radius` prop, because they are
9
+ on the page background.
10
+
11
+ ```tsx
12
+ import { Page, Card, ThemeSetting } from '@korzun/design/component';
13
+ import { Button, Switch } from '@korzun/design/control';
14
+
15
+ export const SettingsPage = () => (
16
+ <Page back="/" documentTitle="Settings">
17
+ <ThemeSetting />
18
+ <Card title="Notifications">
19
+ <Switch name="digest" label="Email digests" checked={digest} onChange={setDigest} />
20
+ </Card>
21
+ <Button danger onClick={logOut}>Log out</Button>
22
+ </Page>
23
+ );
24
+ ```
25
+
26
+ ## A form in a card
27
+
28
+ - Fields go in the card body, in a column with `gap: theme.space.md`. Keep each
29
+ input's default `horizontal` layout (label and control on one shaded row).
30
+ - Every field needs a `name`. It is required, and it is the key passed to
31
+ `onValidChange`.
32
+ - The submit button goes in the `footer`: `type="primary"`, `radius="card"`,
33
+ `submit`, and `form` set to the id of the `<form>` in the body.
34
+
35
+ ```tsx
36
+ <Card
37
+ title="Change password"
38
+ footer={
39
+ <Button type="primary" radius="card" submit form="change-password">Save</Button>
40
+ }
41
+ >
42
+ <form id="change-password" className={styles.fields} action={save}>
43
+ <TextInput name="current" label="Current" password value={current} onChange={setCurrent} />
44
+ <TextInput name="next" label="New" password value={next} onChange={setNext} />
45
+ </form>
46
+ </Card>
47
+ ```
48
+
49
+ ## A confirmation
50
+
51
+ Use `ConfirmModal` for yes/no confirmations. Pass `loading` while the request
52
+ is in flight; it disables Cancel and blocks Escape and backdrop dismissal.
53
+
54
+ ```tsx
55
+ <ConfirmModal
56
+ isOpen={confirming}
57
+ title="Delete book?"
58
+ confirmText="Delete"
59
+ danger
60
+ loading={deleting}
61
+ onCancel={() => setConfirming(false)}
62
+ onConfirm={remove}
63
+ >
64
+ This can't be undone.
65
+ </ConfirmModal>
66
+ ```
67
+
68
+ ## A custom modal
69
+
70
+ There is no general `Dialog` component yet. Build one on `useModalDialog` and
71
+ the modal recipes:
72
+
73
+ ```tsx
74
+ const ref = useModalDialog(isOpen, onClose, !saving); // canDismiss = !saving
75
+ return (
76
+ <dialog ref={ref} className={styles.dialog} onClick={(e) => e.stopPropagation()}>
77
+ <div className={styles.header}>Edit progress</div>
78
+ <div className={styles.body}>…</div>
79
+ <div className={styles.footer}>
80
+ <Button type="text" radius="modal" onClick={onClose} disabled={saving}>Cancel</Button>
81
+ <Button type="primary" radius="modal" loading={saving} onClick={save}>Save</Button>
82
+ </div>
83
+ </dialog>
84
+ );
85
+ // style.ts:
86
+ // dialog: { ...theme.recipe.modal.dialog }, header: { ...theme.recipe.modal.header },
87
+ // body: { padding: `0 ${theme.space.xxl} ${theme.space.xxl}` },
88
+ // footer: { ...theme.recipe.modal.footer }
89
+ ```
90
+
91
+ - `useModalDialog` owns open and close. Never call `showModal()` or `close()`
92
+ yourself, and never render the `<dialog>` conditionally: it must stay mounted.
93
+ - Escape and backdrop clicks call `onDismiss`, unless `canDismiss` is false.
94
+
95
+ ## Notifications
96
+
97
+ `const toast = useToast()` inside `ToastProvider`. See [toast](toast.md).
98
+
99
+ ## Overriding a library style
100
+
101
+ Pass `className` (only some components accept it; each module doc says so) and
102
+ win specificity with `'&&'`:
103
+
104
+ ```ts
105
+ searchButton: { '&&': { borderRadius: theme.radius.md } },
106
+ ```
107
+
108
+ Never use `!important`, and never target the library's internal class names.
109
+
110
+ ## Layout and text
111
+
112
+ There are no `Stack`, `Text`, or `Heading` components yet. Write a small
113
+ `createUseStyles` rule using tokens: `display: 'flex'`, `gap: theme.space.*`,
114
+ `fontSize: theme.fontSize.*`, `fontWeight: theme.fontWeight.*`,
115
+ `color: theme.color.text.*`. Don't use inline `style={{…}}` objects with
116
+ literal values.
@@ -0,0 +1,91 @@
1
+ # Design philosophy
2
+
3
+ These are the rules the code already enforces, extracted from the source comments at extraction time. Nothing here is aspirational: each rule names the file whose comment states it and the code that carries it out.
4
+
5
+ ## One modal width
6
+
7
+ **Rule:** Give every dialog the same width by taking it from `layout.modalWidth`.
8
+
9
+ **Why:** `src/theme/theme.ts` says "modalWidth: one width for every dialog so modals read as a single system", and `recipe.modal.dialog` reads "One shared width for every modal; the maxWidth keeps it inside a narrow viewport (the auto side-margins then center it)". `layout.modalWidth` is `500px`, and `recipe.modal.dialog` (used by `src/control/confirm-modal/style.ts`) sets `width` to it and caps it at `calc(100vw - space.xxl * 2)`.
10
+
11
+ ## Stacked shadows, not blur, on cards and buttons
12
+
13
+ **Rule:** Lift cards and buttons with a hard offset shadow (`0px 2px 0px <colour>`), not a blurred one.
14
+
15
+ **Why:** `src/theme/theme.ts` defines `shadow.cardStack`, `shadow.dangerStack` and `shadow.brandStack` as `0px 2px 0px` with a translucent colour, and `recipe.card.shell` and the button types in `src/control/button/style.ts` use them. Blurred shadows are kept for glass chrome (`shadow.glass`, `shadow.glassActive`, via `recipe.glass` and `recipe.glassHighlight`) and for floating surfaces, which take `shadow.hoverLift`: the toast (`src/toast/style.ts`) and the select and chips-input dropdowns (`src/control/select/style.ts`, `src/control/chips-input/style.ts`). `shadow.card` (`0 1px 3px`) is also blurred; it is defined in `src/theme/theme.ts` but no consumer outside it was found. In dark mode the stacks switch to `applyTransparency('#000', 0.4)`.
16
+
17
+ ## Translucent hover scrims
18
+
19
+ **Rule:** Paint hover state with a translucent scrim (`color.bg.hover`), never an opaque grey.
20
+
21
+ **Why:** `src/theme/theme.ts` (`color.bg.hover`, light mode): "A translucent scrim, not an opaque grey: hover has to read on whatever surface it lands on. The old '#f0f0f0' was lighter than the modal footer (gray[100]) it was painted over, so hovering a text button there produced no visible change at all." Light mode is black at 0.07 opacity, dark mode white at 0.12. `src/control/button/style.ts` and `src/control/action-menu-list/style.ts` both use it.
22
+
23
+ ## A 16px floor on mobile form controls
24
+
25
+ **Rule:** Keep the font size of every input, textarea and select at 16px on mobile.
26
+
27
+ **Why:** `src/theme/global-styles.ts`: "iOS Safari auto-zooms when a form control with a font-size below 16px is focused. Enforce a 16px floor on mobile so focusing an input never zooms." Controls whose class-level font size out-specifies that global rule restore the floor themselves: `recipe.input` in `src/theme/theme.ts` ("Restore the 16px floor on mobile: this class-level font-size otherwise out-specifies the global `input` rule") and `src/control/chips-input/style.ts`.
28
+
29
+ ## Glass chrome with a solid fallback
30
+
31
+ **Rule:** Build floating chrome from `recipe.glass`, which must degrade to a near-opaque fill where backdrop blur is unavailable.
32
+
33
+ **Why:** `recipe.glass` in `src/theme/theme.ts` blurs and saturates the backdrop with `color.bg.glass`, and inside `@supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px)))` swaps the background to `color.bg.glassFallback` (0.92 opacity against 0.6 for the glass itself). `src/control/action-menu-list/style.ts`, `src/control/page-actions-menu/style.ts` and `src/control/back-button/style.ts` spread it. `recipe.glassHighlight` is the pressed or active counterpart, used by `src/component/nav-mobile/style.ts`.
34
+
35
+ ## The `track` token must read against both `page` and `card`
36
+
37
+ **Rule:** Keep `color.bg.track` distinguishable from `color.bg.page` and from `color.bg.card` in both themes.
38
+
39
+ **Why:** `src/theme/theme.ts` documents `bg.track` as "The rail behind a segmented control's sliding lens. Its own token, not `cardHeader`, because it must read against BOTH `page` and `card` — and in dark mode those sit on either side of `cardHeader`, which left the rail invisible on the page." In light mode it is `gray[100]`; in dark mode it is `#2C2D31`, "A step LIGHTER than the page, not darker", because the dark palette puts `page` above `card` and recessing the track has nowhere to go. `src/control/segmented-control/style.ts` paints it.
40
+
41
+ ## Recipes are spreadable fragments, not components
42
+
43
+ **Rule:** Express shared styling as a `Recipe` object that styles spread (`...theme.recipe.glass`), not as a component.
44
+
45
+ **Why:** `src/theme/theme.ts`: "Recipes are JSS-spreadable fragments. Loose typing lets them include pseudo-selectors (`&:hover`) and nested rules without fighting JSS's TS surface." The `Recipe` type is deliberately loose for the same reason. `recipe.input`, `focusRing`, `label`, `spinner`, `glass`, `glassHighlight`, `modal.*` and `card.*` are all plain objects, and consumers such as `src/control/button/style.ts` spread them (`...theme.recipe.focusRing`).
46
+
47
+ ## Measured layout numbers live in tokens
48
+
49
+ **Rule:** Put a measured layout number in `theme.layout` (or `theme.size`) and read it from there.
50
+
51
+ **Why:** `src/theme/theme.ts` on `layout`: "Intrinsic sizes of chrome that other elements must lay out around. These are measured, not derived (the element's real height comes from its content), so they need on-device tuning — keep the single source of truth here." `navHeightMobile` is read by `src/component/page/style.ts` and `src/toast/style.ts`, and `controlHeight` by the text, number, select and date-time inputs. Exception to know about: `src/component/page/style.ts` keeps its own measured `minHeight: '2.25rem'` on `headerRow`, commented "MEASURED, not derived, and the one number to tune here", and `src/control/chips-input/style.ts` uses the same `2.25rem` for its roomier default. Those two have not been promoted to tokens.
52
+
53
+ ## Form controls share one height
54
+
55
+ **Rule:** Give single-line inputs, selects and chips the same height from `layout.controlHeight`.
56
+
57
+ **Why:** `src/theme/theme.ts`: "controlHeight: the shared single-line height for inputs/select/chips (~33px) so form controls line up on one row. Single source of truth." `layout.controlHeight` is `2.0625rem`, and `src/control/text-input/style.ts`, `number-input`, `select` and `date-time-input` set `height` to it. `chips-input` uses it only in its `dense` mode.
58
+
59
+ ## Pin floating controls with sticky positioning, not scroll listeners
60
+
61
+ **Rule:** Hold floating mobile controls in a `position: sticky` row at `layout.floatingControlTopBase`; do not drive a fixed element's `top` from scroll events.
62
+
63
+ **Why:** `src/component/page/style.ts` (`controlsRow`): "STICKY, not fixed: it starts in the page's flow … scrolls up with the page like everything else, and pins at `floatingControlTopBase` once it gets there." The old approach, a `position: fixed` row with a scroll listener rewriting `top`, "lags the compositor on iOS and jitters for the whole ride; sticky positioning is the same motion, done by the scroller itself." `floatingControlTopBase` in `src/theme/theme.ts` is also the one token that is a position rather than a size.
64
+
65
+ ## Page content clears the floating mobile nav through one token
66
+
67
+ **Rule:** Anything that must rest above the floating mobile nav adds `layout.navHeightMobile` to its offset instead of hard-coding the nav's height.
68
+
69
+ **Why:** `src/theme/theme.ts`: "The floating mobile nav capsule is ~96px tall on-device … page padding and bottom-docked toasts both clear it via this token." `src/component/page/style.ts` (`bottomNav`) pads the last row by it "so the last row can always be scrolled above both the nav and Safari's expanded URL bar", and `src/toast/style.ts` rests mobile toasts at `calc(navHeightMobile + space.md + env(safe-area-inset-bottom))`.
70
+
71
+ ## Toasts slide up from behind the nav
72
+
73
+ **Rule:** Stack mobile toasts one layer below the nav (`zIndex.sticky - 1`), so they emerge from behind it rather than covering it.
74
+
75
+ **Why:** `src/toast/style.ts`: "Rest just above the floating bottom nav (plus the home-indicator inset). Sit one layer below the nav so toasts slide up from behind it, not over it." On mobile the code sets `zIndex: theme.zIndex.sticky - 1`; the desktop container uses `theme.zIndex.toast`.
76
+
77
+ ## Safe-area insets are spent once, by whatever is topmost
78
+
79
+ **Rule:** Add `env(safe-area-inset-top)` once, at the topmost element, and let anything below it reuse the inset through `--page-top-inset`.
80
+
81
+ **Why:** `src/component/page/style.ts`: "The inset belongs to whatever is topmost. When that is this `<main>` the fallback applies; when the admin's library-switcher band sits above it, the band has already spent the inset and sets `--page-top-inset` to zero on everything after it." Counting it twice left a status-bar-sized hole in the installed app only, "because in a Safari tab the inset is zero, which is how it went unnoticed." The page's top padding is `calc(space.xxxxxl + var(--page-top-inset, env(safe-area-inset-top)))`. The modal recipe applies the same insets to its mobile margins.
82
+
83
+ ## Un-tokenized literals are declared, not hidden
84
+
85
+ **Rule:** When a style keeps a literal that is off the token scale, say so in a comment at the top of the file and on the line.
86
+
87
+ **Why:** `src/control/button/style.ts` opens with "A small handful of literals stay un-tokenized in this file by design", listing `'#FFF'` (focus-ring border on colored backgrounds), `'0.5em'` (a gap that scales with the button's own font size) and `'0.80rem'` (button-specific size, "off the global fontSize scale"). The `0.80rem` line repeats the note in place.
88
+
89
+ ## Not found in the code
90
+
91
+ - **Ink-on-paper register over glossy chrome.** Searched `src/` for gradients and glossy treatments. The only gradient is a `linear-gradient` mask in `src/component/top-fade/style.ts`, which is a blur fade, not paint. The statement itself lives in Bookplate's `brand/README.md` ("a gradient reads as glossy app-store chrome, which is the opposite of the idea"), where it governs the logo kit (solid ink tiles, `currentColor` marks), and that kit is not part of this package. The flat, hard-edged look the principle implies is covered by the stacked-shadow rule above, so it is not written separately.
package/docs/theme.md ADDED
@@ -0,0 +1,96 @@
1
+ # Theme
2
+
3
+ `import { ThemeProvider, useTheme, createUseStyles, type Theme } from '@korzun/design/theme'`
4
+
5
+ Every visual value comes from the theme. App styles use `createUseStyles` (the
6
+ same function react-jss exports, re-exported here) with a typed `theme`
7
+ argument. Don't add another CSS-in-JS library, and don't write literal colours,
8
+ spacing, font sizes, or radii.
9
+
10
+ ## Setup
11
+
12
+ ```tsx
13
+ <ThemeProvider identity={userId /* or null when signed out */}>
14
+ <ToastProvider>{app}</ToastProvider>
15
+ </ThemeProvider>
16
+ ```
17
+
18
+ - `identity?: string | null` (default `null`) scopes the saved light/dark/auto
19
+ choice to `localStorage['theme-setting:<identity>']`. With `null`, nothing is
20
+ stored and the mode is `auto`.
21
+ - `ThemeProvider` renders `GlobalStyles`: the page background, the body font,
22
+ a 16px input floor on iOS, scroll lock while a `<dialog>` is open, and the
23
+ `theme-rotation` and `theme-slide-*` keyframes. Don't render
24
+ `GlobalStyles` yourself.
25
+ - `useThemeSetting()` returns `[setting, setSetting]` (`'light' | 'dark' |
26
+ 'auto'`). The `ThemeSetting` component is a ready-made picker for it.
27
+ - `useTheme()` returns the current `Theme` object, for values needed outside a
28
+ stylesheet.
29
+ - `lightTheme` / `darkTheme` are the two concrete themes (for tests).
30
+
31
+ ## Writing styles
32
+
33
+ ```ts
34
+ // style.ts, next to the component
35
+ import { createUseStyles, type Theme } from '@korzun/design/theme';
36
+ import { applyTransparency } from '@korzun/design';
37
+
38
+ export const useStyle = createUseStyles((theme: Theme) => ({
39
+ root: {
40
+ display: 'flex',
41
+ flexDirection: 'column',
42
+ gap: theme.space.md,
43
+ color: theme.color.text.primary,
44
+ },
45
+ hint: { fontSize: theme.fontSize.sm, color: theme.color.text.muted },
46
+ highlight: { backgroundColor: applyTransparency(theme.color.brand.default, 0.12) },
47
+ [theme.breakpoint.mobile]: { root: { gap: theme.space.sm } },
48
+ }));
49
+ ```
50
+
51
+ - `applyTransparency(color, alpha)` turns a hex or rgb token into an `rgba()`
52
+ string. Use it for tints instead of writing an rgba literal.
53
+ - Media queries: use the `theme.breakpoint.mobile` / `.normal` strings as keys.
54
+
55
+ ## Tokens
56
+
57
+ | Group | Keys | Notes |
58
+ |---|---|---|
59
+ | `color.text` | `primary`, `secondary`, `muted`, `faint`, `description`, `onPrimary`, `onDanger` | `muted` for labels and meta, `faint` for placeholders |
60
+ | `color.bg` | `page`, `card`, `cardHeader`, `track`, `input`, `footer`, `glass`, `glassFallback`, `glassActive`, `selected`, `hover`, `success`, `placeholder` | `cardHeader` is also the shaded-row and inset-box fill; `hover` is a translucent scrim |
61
+ | `color.border` | `default`, `strong`, `light`, `focus`, `hover`, `danger`, `glass`, `glassActive`, `faint`, `loading`, `success`, `section` | Cards and dividers use `strong`; inputs use `default` |
62
+ | `color.brand` | `default`, `hover`, `active`, `light`, `outline`, `loading*`, `linkHover` | The primary action colour |
63
+ | `color.danger` | `default`, `hover`, `active`, `light`, `outline`, `loading*` | Destructive actions and errors |
64
+ | `color.success` | (a string) | There are no warning or info colours yet |
65
+ | `color.chip.<tone>` | `{ text, bg, border }` for `status`, `author`, `series`, `subject`, `book`, `entryType`, `user`, `rating`, `neutral` | Used by `Tag` |
66
+ | `color.overlay` | `backdrop` | Modal backdrop |
67
+ | `color.gray` / `blue` / `red` | primitive scales | Don't use these in app code; use the semantic tokens above |
68
+ | `space` | `xxxs` 0.1rem, `xxs` 0.125, `xs` 0.25, `sm` 0.375, `md` 0.5, `lg` 0.625, `xl` 0.75, `xxl` 1, `xxxl` 1.25, `xxxxl` 1.5, `xxxxxl` 2rem | `md` is the default gap between stacked fields |
69
+ | `radius` | `sm` 4px, `md` 8px, `lg` 16px, `circle`, `pill` | Chosen by nesting depth; see [corners](corners.md) |
70
+ | `fontSize` | `xxs` 0.6rem, `xs` 0.7, `sm` 0.75, `md` 0.875, `lg` 1, `xl` 1.25, `xxl` 1.75rem | Control text is `'0.80rem'`, the one sanctioned literal (already applied by `recipe.input` and Button) |
71
+ | `fontWeight` | `medium` 500, `semibold` 600, `bold` 700, `extrabold` 800 | |
72
+ | `lineHeight` | `tight` 1, `body` 1.3 | |
73
+ | `fontFamily` | `body`, `mono` | |
74
+ | `shadow` | `card`, `cardStack`, `hoverLift`, `dangerStack`, `brandStack`, `glass`, `glassActive` | Floating layers use `hoverLift` |
75
+ | `transition` | `fast`, `medium`, `slide`, `slow`, `spring` | Values like `'0.2s ease-in'` |
76
+ | `zIndex` | `behind`, `base`, `stack.{lo,md,hi}`, `header`, `sticky`, `toast` | |
77
+ | `breakpoint` | `mobile` (≤640px), `normal` | Media query strings |
78
+ | `layout` | `navHeightMobile`, `modalWidth`, `controlHeight`, `floatingControlTopBase` | Measured chrome sizes to lay out around |
79
+ | `size` | `metadataValue` | |
80
+
81
+ ## Recipes
82
+
83
+ Recipes are style fragments that you spread into a rule: `{ ...theme.recipe.input }`.
84
+
85
+ | Recipe | Gives you |
86
+ |---|---|
87
+ | `recipe.input` | Text-input chrome: font, `md` radius, border, hover and focus colours, iOS 16px floor; `&$danger` turns the border red if your sheet declares a `danger: {}` class |
88
+ | `recipe.label` | Field label: semibold, `md`, muted; `&$danger` |
89
+ | `recipe.focusRing` | Transparent 2px outline; set `outlineColor: theme.color.brand.outline` on `'&:focus'` |
90
+ | `recipe.spinner` | 1em rotating box; apply to `SpinnerIcon` |
91
+ | `recipe.glass` / `glassHighlight` | Frosted translucent surface (floating chrome) and its active state |
92
+ | `recipe.card.shell` / `header` / `footer` | The Card surface (`lg`), its header bar, and its footer bar |
93
+ | `recipe.modal.dialog` / `header` / `footer` | A `<dialog>` surface (`lg`, shared width, backdrop), its title, and its button bar |
94
+
95
+ Recipes that use `$name` references need an empty class with that name in the
96
+ same sheet (`danger: {}`).