@korzun/design 0.0.3 → 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 +8 -0
- 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 +4 -1
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: {}`).
|
package/docs/toast.md
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Toast
|
|
2
|
+
|
|
3
|
+
`import { ToastProvider, useToast } from '@korzun/design/toast'`
|
|
4
|
+
|
|
5
|
+
Short, transient confirmations and errors ("Password changed", "Failed to reset
|
|
6
|
+
password") that appear in a corner, stay four seconds, and slide away. Mount
|
|
7
|
+
`ToastProvider` once; call the function `useToast()` returns from anywhere
|
|
8
|
+
below it.
|
|
9
|
+
|
|
10
|
+
Use something else for: an error that must stay until the user acts (inline
|
|
11
|
+
text near the field, or `EmptyState danger` for a failed load), a question
|
|
12
|
+
needing an answer (`ConfirmModal`).
|
|
13
|
+
|
|
14
|
+
## `ToastProvider`
|
|
15
|
+
|
|
16
|
+
| Prop | Type | Default | Notes |
|
|
17
|
+
|---|---|---|---|
|
|
18
|
+
| `children` | `ReactNode` | required | The app. |
|
|
19
|
+
| `maxToasts` | `number` | `3` | When a new toast would exceed this, the oldest starts its exit animation. |
|
|
20
|
+
|
|
21
|
+
Placement:
|
|
22
|
+
|
|
23
|
+
- **Inside `ThemeProvider`** (toasts are styled from the theme) and above every
|
|
24
|
+
component that calls `useToast`. Bookplate nests it innermost among its app
|
|
25
|
+
providers, around the router.
|
|
26
|
+
- It renders its container itself; you don't place anything in the layout.
|
|
27
|
+
Desktop: bottom-right, `space.xxxxl` from the edges. Mobile: full width just
|
|
28
|
+
above the floating `NavMobile` (and below it in z-order, so toasts slide up
|
|
29
|
+
from behind the bar).
|
|
30
|
+
- The container is a `popover="manual"` element shown while any toast is up,
|
|
31
|
+
so toasts appear **above an open modal `<dialog>`** too.
|
|
32
|
+
|
|
33
|
+
## `useToast()`
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
useToast(): (message: string, type: 'success' | 'error' | 'info') => void
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Returns the **function itself** (not an object): `const showToast = useToast()`.
|
|
40
|
+
|
|
41
|
+
| Argument | Notes |
|
|
42
|
+
|---|---|
|
|
43
|
+
| `message` | Plain string. No elements, no actions, no links. |
|
|
44
|
+
| `type` | `'success'`: green check. `'error'`: red X, announced `aria-live="assertive"`. `'info'`: brand-blue info icon. Success and info are `polite`. Required; there is no default. |
|
|
45
|
+
|
|
46
|
+
## Surprising behaviour
|
|
47
|
+
|
|
48
|
+
- **Without a `ToastProvider` above it, `showToast` silently does nothing**
|
|
49
|
+
(the default context is a no-op). No error is thrown.
|
|
50
|
+
- Duration is fixed at 4000ms; there is no per-toast duration, no close
|
|
51
|
+
button, and no tap-to-dismiss.
|
|
52
|
+
- Toasts have `radius.md` (a floating layer) per [corners](corners.md).
|
|
53
|
+
|
|
54
|
+
## Examples
|
|
55
|
+
|
|
56
|
+
```tsx
|
|
57
|
+
// App root.
|
|
58
|
+
<ThemeProvider identity={username}>
|
|
59
|
+
<ToastProvider>
|
|
60
|
+
<AppRouter />
|
|
61
|
+
</ToastProvider>
|
|
62
|
+
</ThemeProvider>
|
|
63
|
+
|
|
64
|
+
// A component reporting a mutation's outcome.
|
|
65
|
+
const showToast = useToast();
|
|
66
|
+
const save = async () => {
|
|
67
|
+
try {
|
|
68
|
+
const result = await changePassword(input);
|
|
69
|
+
if (!result.ok) {
|
|
70
|
+
showToast(result.message, 'error');
|
|
71
|
+
return;
|
|
72
|
+
}
|
|
73
|
+
showToast('Password changed', 'success');
|
|
74
|
+
} catch (err) {
|
|
75
|
+
showToast(err instanceof Error ? err.message : 'Password change failed', 'error');
|
|
76
|
+
}
|
|
77
|
+
};
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Do / don't
|
|
81
|
+
|
|
82
|
+
- Do mount exactly one `ToastProvider`, inside `ThemeProvider`.
|
|
83
|
+
- Do keep messages to one short sentence; nothing truncates a long one.
|
|
84
|
+
- Don't destructure: `const { showToast } = useToast()` is wrong.
|
|
85
|
+
- Don't use a toast for the only copy of an error the user must fix.
|
package/docs/tokens.md
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Tokens
|
|
2
|
+
|
|
3
|
+
Every token lives in `src/theme/theme.ts`. The `Theme` interface declares the groups; `lightTheme` and `darkTheme` are both built by `buildTheme(mode)` and share every key, differing only in values. Consumers read tokens with `useTheme()` or inside `createUseStyles((theme: Theme) => ...)`. The groups below follow the order of the `Theme` type; the key lists are taken from it.
|
|
4
|
+
|
|
5
|
+
The top-level `colorScheme` key holds the mode, `'light'` or `'dark'` (type `ThemeMode`), and is also the only non-group key of the type.
|
|
6
|
+
|
|
7
|
+
## color
|
|
8
|
+
|
|
9
|
+
Surfaces, text, borders and state colours, mode-aware. Keys are grouped as follows.
|
|
10
|
+
|
|
11
|
+
- `color.gray`: primitive palette, steps `50 100 150 200 300 400 500 600 700 900`. Identical in both modes.
|
|
12
|
+
- `color.blue`: primitive palette, steps `50 100 200 300 400 500 600 700 800`. Identical in both modes.
|
|
13
|
+
- `color.red`: primitive palette, steps `50 100 300 400 500 600 700`. Identical in both modes.
|
|
14
|
+
- `color.text`: `primary secondary muted faint onPrimary onDanger description`
|
|
15
|
+
- `color.bg`: `page card cardHeader track input footer glass glassFallback glassActive selected hover success placeholder`. `track` must read against both `page` and `card`; `hover` is a translucent scrim; `glass*` feed `recipe.glass`.
|
|
16
|
+
- `color.border`: `default strong light focus hover danger glass glassActive faint loading success section`
|
|
17
|
+
- `color.success`: a single value.
|
|
18
|
+
- `color.brand`: `default hover active light outline loading loadingHover loadingActive linkHover`
|
|
19
|
+
- `color.danger`: `default hover active light outline loading loadingHover loadingActive`
|
|
20
|
+
- `color.overlay`: `backdrop`
|
|
21
|
+
- `color.chip`: eight tinted label colourways, each `{ text, bg, border }`: `status author series subject book entryType user rating`. See Slated for curation.
|
|
22
|
+
|
|
23
|
+
## space
|
|
24
|
+
|
|
25
|
+
The spacing scale, in `rem`: `xxxs xxs xs sm md lg xl xxl xxxl xxxxl xxxxxl` (`0.1rem` up to `2rem`).
|
|
26
|
+
|
|
27
|
+
## radius
|
|
28
|
+
|
|
29
|
+
Corner radii: `sm md lg circle pill` (`4px`, `8px`, `16px`, `50%`, `999px`).
|
|
30
|
+
|
|
31
|
+
## size
|
|
32
|
+
|
|
33
|
+
Fixed component sizes that are not part of the spacing scale. One key: `metadataValue`. See Slated for curation.
|
|
34
|
+
|
|
35
|
+
## layout
|
|
36
|
+
|
|
37
|
+
Intrinsic sizes of chrome that other elements must lay out around. They are measured, not derived, so they are tuned on a device and kept in one place. Keys: `navHeightMobile` (the floating mobile nav, `96px`), `modalWidth` (the one width for every dialog, `500px`), `controlHeight` (the shared single-line control height, `2.0625rem`), and `floatingControlTopBase`, a position rather than a size: the `top` at which the mobile back button and actions menu pin, `max(space.xxxl, env(safe-area-inset-top) + space.xxxxl)`.
|
|
38
|
+
|
|
39
|
+
## fontSize
|
|
40
|
+
|
|
41
|
+
The type scale: `xxs xs sm md lg xl xxl` (`0.6rem` up to `1.75rem`).
|
|
42
|
+
|
|
43
|
+
## fontFamily
|
|
44
|
+
|
|
45
|
+
Two stacks: `body` (`system-ui, sans-serif`) and `mono`.
|
|
46
|
+
|
|
47
|
+
## fontWeight
|
|
48
|
+
|
|
49
|
+
Numeric weights: `medium semibold bold extrabold` (500, 600, 700, 800).
|
|
50
|
+
|
|
51
|
+
## lineHeight
|
|
52
|
+
|
|
53
|
+
Two values: `tight` (1) and `body` (1.3).
|
|
54
|
+
|
|
55
|
+
## shadow
|
|
56
|
+
|
|
57
|
+
Mode-aware elevation. `card` is a soft one-pixel shadow (defined, with no consumer outside the theme); `cardStack`, `dangerStack` and `brandStack` are the hard `0px 2px 0px` offset shadows for cards and buttons; `hoverLift` is the elevation of floating surfaces (the toast and the select and chips-input dropdowns); `glass` and `glassActive` belong to `recipe.glass` and `recipe.glassHighlight`. Keys: `card cardStack hoverLift dangerStack brandStack glass glassActive`.
|
|
58
|
+
|
|
59
|
+
## transition
|
|
60
|
+
|
|
61
|
+
Shorthand durations and easings: `fast medium slide slow spring`.
|
|
62
|
+
|
|
63
|
+
## zIndex
|
|
64
|
+
|
|
65
|
+
Stacking layers: `behind base stack header sticky toast`, where `stack` is a nested `{ lo, md, hi }` (1, 2, 3). Values run from `-1` (`behind`) to `9999` (`toast`).
|
|
66
|
+
|
|
67
|
+
## breakpoint
|
|
68
|
+
|
|
69
|
+
Media-query strings, ready to use as JSS keys: `mobile` (`@media (max-width: 640px)`) and `normal` (`@media (min-width: 641px)`).
|
|
70
|
+
|
|
71
|
+
## recipe
|
|
72
|
+
|
|
73
|
+
JSS-spreadable style fragments (`...theme.recipe.x`), not components.
|
|
74
|
+
|
|
75
|
+
- `recipe.input`: the base text-field look (border, radius, hover and focus colours, 16px font on mobile).
|
|
76
|
+
- `recipe.focusRing`: a transparent 2px outline that controls recolour on focus.
|
|
77
|
+
- `recipe.label`: form label text, with a `$danger` variant.
|
|
78
|
+
- `recipe.spinner`: a 1em rotating indicator using the `theme-rotation` keyframes.
|
|
79
|
+
- `recipe.glass`: frosted, blurred chrome with a solid fallback where backdrop blur is unsupported.
|
|
80
|
+
- `recipe.glassHighlight`: the active or pressed fill that sits on top of glass.
|
|
81
|
+
- `recipe.modal.dialog`: the shared dialog shell (one width, backdrop, mobile margins and safe-area insets).
|
|
82
|
+
- `recipe.modal.header`: dialog title row.
|
|
83
|
+
- `recipe.modal.footer`: dialog action row.
|
|
84
|
+
- `recipe.card.shell`: card container with border, radius and `shadow.cardStack`.
|
|
85
|
+
- `recipe.card.header`: card title bar.
|
|
86
|
+
- `recipe.card.footer`: card action row.
|
|
87
|
+
|
|
88
|
+
## Slated for curation
|
|
89
|
+
|
|
90
|
+
Both groups below move into the package byte-for-byte in 0.0.1 and are due for a decision before the API settles.
|
|
91
|
+
|
|
92
|
+
- `color.chip.*`: eight colourways (`status author series subject book entryType user rating`) named after Bookplate's metadata chips, not after a general role.
|
|
93
|
+
- `size.metadataValue`: `15rem`, a width named after Bookplate's metadata display.
|
|
94
|
+
|
|
95
|
+
No other token name or comment in `src/theme/theme.ts` is clearly Bookplate-specific. Two comments mention app internals (`floatingControlTopBase` refers to the admin picker and `router/nav-layout-style`), but the tokens themselves are generic.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@korzun/design",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.4",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"repository": {
|
|
@@ -12,6 +12,9 @@
|
|
|
12
12
|
"url": "https://github.com/Korzun/korzun-design/issues"
|
|
13
13
|
},
|
|
14
14
|
"files": [
|
|
15
|
+
"AGENTS.md",
|
|
16
|
+
"docs",
|
|
17
|
+
"!docs/superpowers",
|
|
15
18
|
"dist",
|
|
16
19
|
"src",
|
|
17
20
|
"!src/**/*.test.*",
|