@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.
- package/AGENTS.md +78 -0
- package/README.md +11 -1
- package/dist/component/index.d.ts +1 -1
- package/dist/component/index.d.ts.map +1 -1
- package/dist/component/index.js.map +1 -1
- package/dist/component/tag/index.d.ts +5 -2
- package/dist/component/tag/index.d.ts.map +1 -1
- package/dist/component/tag/index.js +2 -2
- package/dist/component/tag/index.js.map +1 -1
- package/dist/component/tag/style.d.ts +2 -1
- package/dist/component/tag/style.d.ts.map +1 -1
- package/dist/component/tag/style.js +21 -7
- package/dist/component/tag/style.js.map +1 -1
- package/dist/theme/theme.d.ts +5 -0
- package/dist/theme/theme.d.ts.map +1 -1
- package/dist/theme/theme.js +13 -1
- package/dist/theme/theme.js.map +1 -1
- package/docs/component/card-divider.md +67 -0
- package/docs/component/card-row.md +58 -0
- package/docs/component/card.md +82 -0
- package/docs/component/collapsible-section.md +57 -0
- package/docs/component/empty-state.md +49 -0
- package/docs/component/meta-line.md +60 -0
- package/docs/component/metadata-list.md +60 -0
- package/docs/component/nav-desktop.md +62 -0
- package/docs/component/nav-mobile.md +82 -0
- package/docs/component/page.md +81 -0
- package/docs/component/progress-indicator.md +53 -0
- package/docs/component/tag.md +69 -0
- package/docs/component/theme-setting.md +58 -0
- package/docs/component/top-fade.md +60 -0
- package/docs/control/back-button.md +55 -0
- package/docs/control/button.md +78 -0
- package/docs/control/chips-input.md +77 -0
- package/docs/control/confirm-modal.md +68 -0
- package/docs/control/date-time-input.md +56 -0
- package/docs/control/field-list.md +66 -0
- package/docs/control/number-input.md +62 -0
- package/docs/control/page-actions-bar.md +64 -0
- package/docs/control/page-actions-menu.md +65 -0
- package/docs/control/page-footer-actions.md +69 -0
- package/docs/control/popover.md +74 -0
- package/docs/control/segmented-control.md +73 -0
- package/docs/control/select.md +86 -0
- package/docs/control/switch.md +73 -0
- package/docs/control/text-area.md +52 -0
- package/docs/control/text-input.md +73 -0
- package/docs/control/use-modal-dialog.md +76 -0
- package/docs/corners.md +68 -0
- package/docs/hooks.md +104 -0
- package/docs/icon.md +102 -0
- package/docs/patterns.md +116 -0
- package/docs/philosophy.md +91 -0
- package/docs/theme.md +96 -0
- package/docs/toast.md +85 -0
- package/docs/tokens.md +95 -0
- package/package.json +7 -1
- package/src/component/index.ts +1 -1
- package/src/component/tag/index.tsx +7 -2
- package/src/component/tag/style.ts +27 -7
- 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)).
|
package/docs/corners.md
ADDED
|
@@ -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.
|
package/docs/patterns.md
ADDED
|
@@ -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: {}`).
|