@ahrowe/ui 0.29.0 → 0.30.0

package/dist/types/common/colorPicker/toHex.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Normalises any CSS colour the browser understands into hex, which is the only form
+ * ColorPicker's own arithmetic can take. Without it every non-hex value — `transparent`,
+ * `rgba(...)`, and above all `oklch(...)`, which a whole theme may be written in — silently
+ * became the picker's default blue: a swatch confidently showing a colour nothing asked for.
+ *
+ * The canvas 2D context is the browser's own colour parser. Under jsdom there is none, so
+ * this returns `undefined` and callers keep their previous fallback — meaning the widened
+ * behaviour is only observable in a real browser, and only `*.browser.test.ts` can cover it.
+ */
+export declare function toHex(value: string | undefined): string | undefined;

package/dist/types/common/themeProvider/theme.types.d.ts

@@ -16,6 +16,8 @@ export interface ThemeVariables {
     '--lighter-blue'?: string;
     '--black'?: string;
     '--primary-color'?: string;
+    /** Optional gradient layered over --primary-color on large filled surfaces (Button, Chip, ProgressBar, Switch, Slider, Pagination, OptionPicker, Badge). --primary-color stays the solid and stays required: borders, outlines, strokes, shadows and text read it, and a gradient is invalid in all of them. Unset means a flat --primary-color everywhere. */
+    '--primary-gradient'?: string;
     '--primary-accent'?: string;
     '--primary-lighter'?: string;
     '--accent-color'?: string;
@@ -33,6 +35,8 @@ export interface ThemeVariables {
     '--background-accent-dark'?: string;
     '--background-accent-light'?: string;
     '--background-modal'?: string;
+    /** Pale surface behind a checkbox and similar low-emphasis fills. */
+    '--light-background-color'?: string;
     '--success-color'?: string;
     '--success-lighter'?: string;
     '--error-color'?: string;
@@ -51,6 +55,8 @@ export interface ThemeVariables {
     '--header-font-weight'?: string;
     '--default-font'?: string;
     '--themed-font'?: string;
+    /** Font for code and stack traces. Falls back to `monospace`. */
+    '--monospace-font'?: string;
     '--disabled-input-color'?: string;
     '--disabled-font-color'?: string;
     '--input-background'?: string;
@@ -59,12 +65,16 @@ export interface ThemeVariables {
     '--input-label-resting-color'?: string;
     '--input-label-floating-color'?: string;
     '--search-input-color'?: string;
+    /** Colour of an input's error message. */
+    '--error-font-color'?: string;
     '--default-border-radius'?: string;
     '--padding-sides'?: string;
     '--margin-top'?: string;
     '--spacing-s'?: string;
     '--spacing-m'?: string;
     '--spacing-l'?: string;
+    /** Falls back to 4px. */
+    '--spacing-xs'?: string;
     /** Avatar corner radius. Falls back to --default-border-radius when unset. */
     '--avatar-radius'?: string;
     /** Default-style button background. Falls back to transparent when unset. */
@@ -83,9 +93,9 @@ export interface ThemeVariables {
     '--slider-range-color'?: string;
     /** Slider thumb colour. Falls back to --primary-color. */
     '--slider-thumb-color'?: string;
-    /** Slider thumb diameter. Falls back to 18px (also settable per instance via the `size` prop). */
+    /** Slider thumb diameter. Falls back to 1.125x --default-font-size, i.e. 18px at a 16px base (also settable per instance via the `size` prop). */
     '--slider-thumb-size'?: string;
-    /** Slider track thickness. Falls back to 6px. */
+    /** Slider track thickness. Falls back to 0.375x --default-font-size, i.e. 6px at a 16px base. */
     '--slider-track-height'?: string;
     /** Step marker diameter. Falls back to 40px. */
     '--stepper-marker-size'?: string;
@@ -115,7 +125,7 @@ export interface ThemeVariables {
     '--timer-progress-color'?: string;
     /** Timer ring colour once inside the urgent threshold. Falls back to --error-color. */
     '--timer-urgent-color'?: string;
-    /** Timer ring diameter. Falls back to 160px (also settable per instance via the `size` prop). */
+    /** Timer ring diameter. Falls back to 10em, i.e. 160px at a 16px base (also settable per instance via the `size` prop). */
     '--timer-size'?: string;
     /** Timer ring stroke thickness. Falls back to 10px (also settable per instance via `strokeWidth`). */
     '--timer-stroke-width'?: string;
@@ -123,11 +133,103 @@ export interface ThemeVariables {
     '--timer-text-color'?: string;
     /** Timer label (below the readout) text colour. Falls back to --text-dark. */
     '--timer-label-color'?: string;
+    /** Ripple shown as the timer runs out. Falls back to --timer-progress-color. */
+    '--timer-ripple-color'?: string;
+    /** Tooltip bubble and details badge. Falls back to an inverse of the page: --text-color mixed 82% into --background. */
+    '--tooltip-background'?: string;
+    /** Text on that bubble. Falls back to --background. */
+    '--tooltip-color'?: string;
+    /** Size of the checkmark box. Falls back to 1.375em, i.e. 22px at a 16px base. */
+    '--checkbox-size'?: string;
+    /** Gap between the box and its label. Falls back to 0.5em, i.e. 8px at a 16px base. */
+    '--checkbox-gap'?: string;
+    /** Size of the inline colour swatch. Falls back to 2em, i.e. 32px at a 16px base. */
+    '--swatch-size'?: string;
+    /** Diameter of a radio. Falls back to 1.125em, i.e. 18px at a 16px base. */
+    '--radio-size'?: string;
+    /** Gap between a radio and its label. Falls back to 0.625em, i.e. 10px at a 16px base. */
+    '--radio-gap'?: string;
+    /** Diameter of the main button. Falls back to 56px. */
+    '--fab-size'?: string;
+    /** Diameter of a speed-dial entry's button. Falls back to 40px. */
+    '--fab-mini-size'?: string;
+    /** Icon box inside either. Falls back to 18px, and does not follow --fab-size. */
+    '--fab-icon-size'?: string;
+    /** Dot colour. Falls back to --primary-color. */
+    '--timeline-dot-color'?: string;
+    /** Ring drawn around a dot, separating it from the line. Falls back to --background. */
+    '--timeline-dot-border'?: string;
+    /** Dot diameter. Falls back to 14px. */
+    '--timeline-dot-size'?: string;
+    /** Diameter of a dot carrying an icon. Falls back to 28px. */
+    '--timeline-icon-dot-size'?: string;
+    /** Connector colour. Falls back to --border-color. */
+    '--timeline-line-color'?: string;
+    /** Connector thickness. Falls back to 2px. */
+    '--timeline-line-thickness'?: string;
+    /** Gap between the dot column and the content. Falls back to 16px. */
+    '--timeline-gap'?: string;
+    /** Vertical gap between items. Falls back to 20px. */
+    '--timeline-item-gap'?: string;
+    /** Row height. Falls back to 32px. */
+    '--tree-node-height'?: string;
+    /** Selected row background. Falls back to --primary-color. */
+    '--tree-selected-background'?: string;
+    /** Selected row text. Falls back to --text-on-primary. */
+    '--tree-selected-color'?: string;
+    /** Page button size. Falls back to 36px. */
+    '--pagination-size'?: string;
+    /** Gap between page buttons. Falls back to 4px. */
+    '--pagination-gap'?: string;
+    /** Current page background. Falls back to --primary-color. */
+    '--pagination-active-background'?: string;
+    /** Current page text. Falls back to --text-on-primary. */
+    '--pagination-active-color'?: string;
+    /** Filled symbol. Falls back to --primary-color. */
+    '--rating-filled-color'?: string;
+    /** Empty symbol. Falls back to --background-accent-light. */
+    '--rating-empty-color'?: string;
+    /** Symbol size. Falls back to 1.25x --default-font-size, i.e. 20px at a 16px base. */
+    '--rating-size'?: string;
+    /** Minimum height of the control. Falls back to `calc(1.25em + 14px)`. */
+    '--multi-select-min-height'?: string;
+    /** Maximum height of the open option panel. Falls back to 260px. */
+    '--multi-select-panel-height'?: string;
     /** Width a column collapses to once it has no cards (see `collapseEmptyColumns`). Falls back to 140px. */
     '--kanban-empty-column-width'?: string;
     '--option-picker-padding'?: string;
     /** Track (unfilled) background colour. Falls back to --background-accent. */
     '--progress-bar-track-color'?: string;
+    /** Canvas behind the plan. Falls back to --background. */
+    '--plan-canvas-background'?: string;
+    /** Grid lines, drawn at low opacity. Falls back to --text-color. */
+    '--plan-grid-color'?: string;
+    /** The storey below, traced under the current one. Falls back to --text-dark. */
+    '--plan-underlay-color'?: string;
+    /** Room floor. Falls back to --background-accent. */
+    '--plan-room-fill'?: string;
+    /** Room floor under the pointer. Falls back to --background-accent-light. */
+    '--plan-room-fill-hover'?: string;
+    /** Edge of the walls bounding a selected room. Falls back to --primary-color. */
+    '--plan-room-edge-selected'?: string;
+    /** Body of those same walls. Falls back to --primary-lighter. */
+    '--plan-room-edge-selected-fill'?: string;
+    /** Wall body. Falls back to --text-color mixed 58% into the canvas. */
+    '--plan-wall-fill'?: string;
+    /** Wall edge, its caps and the jamb faces. Falls back to --text-color mixed 38% in. */
+    '--plan-wall-outline'?: string;
+    /** Wall corner treatment, any `stroke-linejoin` value. Falls back to `round`. */
+    '--plan-wall-join'?: string;
+    /** How far a mitred corner may run, when --plan-wall-join is `miter`. Falls back to `4`. */
+    '--plan-wall-miter-limit'?: string;
+    /** Door leaf and swing arc. Falls back to --text-dark. */
+    '--plan-door-color'?: string;
+    /** Window pane line. Falls back to --info-color. */
+    '--plan-window-color'?: string;
+    /** RoomDrawer's snap construction lines. Falls back to --info-color. */
+    '--plan-guide-color'?: string;
+    /** RoomDrawer's ruler. Falls back to --primary-color. */
+    '--plan-measure-color'?: string;
     [key: string]: string | undefined;
 }
 export interface Theme {

package/dist/types/common/themeProvider/themeVariablesContext.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The nearest ThemeProvider's resolved variables, for content that renders outside its DOM
+ * subtree. Theme variables reach a component by CSS inheritance, which a portal breaks: a
+ * `BodyEnd` child lands wherever `#bodyEnd` happens to be, so it picks up whatever provider
+ * wraps *that* node rather than the one it was written under.
+ *
+ * Deliberately its own module rather than a member of `themeProvider.tsx`: BodyEnd needs the
+ * context and nothing else, and importing the component for it would pull the whole
+ * ThemeProvider into every bundle that uses a portal.
+ */
+export declare const ThemeVariablesContext: import('react').Context<Record<string, string> | null>;

package/dist/types/common/utils/activationKey.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+/**
+ * Whether a keydown is a click-equivalent activation of the element the handler sits on.
+ *
+ * The target check is the important half: keydown bubbles, so without it a Space typed into a
+ * nested input activates the container and, once the container calls `preventDefault()`, never
+ * reaches the input at all.
+ */
+export declare function isSelfActivation(event: React.KeyboardEvent): boolean;

package/docs/Accordion.md

@@ -41,3 +41,7 @@ import { Accordion, AccordionStyleType } from '@ahrowe/ui';
 | `id` | `string` | Passed back in `onHeaderClicked` |
 
 **Slots:** `root` `header` `title` `icon` `body` `bodyInner`
+
+## Sizing
+
+The header's font, padding and chevron follow `--default-font-size`, as does the body's padding. There is no fixed height: the header is that padding plus one line of text, so a larger base font simply makes it taller.

package/docs/Alert.md

@@ -64,3 +64,7 @@ import { faRocket } from '@fortawesome/free-solid-svg-icons';
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Alert: { hideIcon: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
 **Slots:** `root` `icon` `content` `title` `description` `closeButton`
+
+## Sizing
+
+Every length in an alert is `em`, so the padding, the icon, the close button and the accent bar keep their ratios to the body copy at any base font.

package/docs/BodyEnd.md

@@ -30,3 +30,6 @@ import { BodyEnd } from '@ahrowe/ui';
 | `children` | `ReactNode` | Content rendered into `#bodyEnd` |
 
 **Note:** Returns `null` silently if `#bodyEnd` doesn't exist in the DOM.
+
+**Theming crosses the portal.** Children keep the variables of the nearest `ThemeProvider` they were *written* under, not the one that happens to wrap `#bodyEnd`. BodyEnd applies them through a `display: contents` wrapper, which generates no box — positioning, stacking and clipping are unchanged — while custom properties still inherit. Variables that theme leaves unset fall through to whatever wraps `#bodyEnd`, the same cascade the children would have seen rendered in place. With no `ThemeProvider` above, no wrapper is added at all.
+

package/docs/Button.md

@@ -94,3 +94,9 @@ const theme: Theme = {
 
 **Sizing in a flex row:** a Button never shrinks below its own content (`min-width: min-content`),
 so an icon is never cut off by a flexible sibling. A multi-word label still wraps above that floor.
+
+## Sizing
+
+A Button is sized by its font. `--default-font-size` is the base, and `Small` and `Large` are multiples of it (0.75x and 1.25x), so a theme with a smaller base font gets proportionally smaller controls everywhere. Padding and the icon gap are in `em`, so the whole box grows with the label rather than a large button wearing a default button's padding.
+
+`ButtonSize.Icon` is the exception: it inherits the surrounding text size and has no padding at all, because the caller sets the box.

package/docs/Card.md

@@ -76,3 +76,9 @@ All sub-components are optional — use only what you need. Stacked sub-componen
 |------|------|-------------|
 | `actions` | `CardAction[]` | Array of `{ id, label, styleType, onClick }` renders Buttons |
 | `children` | `ReactNode` | Custom content instead of `actions` |
+
+## Sizing
+
+Card is spaced by its font: the padding, the header's gap and thumbnail, the gap between title and subtitle, and the action row all scale with the theme's text size. The title is `1.125em` — 18px at a 16px base — rather than a fixed size, so it stays proportional to the body text beneath it.
+
+`CardMedia` bleeds to the card's edges with a negative margin that has to stay equal to the padding, so change the two together.

package/docs/Checkbox.md

@@ -38,3 +38,11 @@ const agreedValidator = new FormValidator(false, [Validators.required()]);
 | `cursorDefault` | `boolean` | Use default cursor instead of pointer |
 
 **Slots:** `icon` `checkmark` `label`
+
+## Sizing
+
+The control is sized by its font, so it stays in proportion with the label it sits next to. `--checkbox-size` overrides the box and `--checkbox-gap` the space to the label; they fall back to `1.375em` and `0.5em`, i.e. 22px and 8px at a 16px base. The border and the tick's padding are `em` too, so nothing has to be retuned when the box changes.
+
+**Checked and unchecked are the same size.** The fill is the box's own background rather than an oversized tick laid over it, so the two states occupy identical space. `background` sets that fill, and applies to the border as well.
+
+The `width` and `height` props still win where they are given, for a checkbox that must match a fixed layout rather than the text around it.

package/docs/ColorPicker.md

@@ -34,9 +34,19 @@ import { ColorPicker } from '@ahrowe/ui';
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `value` | `string` | Current hex value (e.g. `'#ff0000'`) |
+| `value` | `string` | Current colour. Any CSS colour the browser understands — `'#ff0000'`, `'#f00'`, `'red'`, `'rgb(255 0 0)'`, `'oklch(0.8 0.11 85)'`, `'transparent'` — normalised to hex on the way in |
 | `onChange` | `(hex: string) => void` | Called with new hex on change |
 | `showInput` | `boolean` | Show hex text input |
 | `inline` | `boolean` | Render picker inline instead of as a popover |
 
 An eyedropper button is shown automatically next to the hex input on browsers that support the native `EyeDropper` API (Chromium-based desktop/Android browsers). It lets the user sample a colour from anywhere on screen, not just within the page. It's hidden entirely on unsupported browsers (Firefox, Safari, iOS) — no prop needed.
+
+**Anything in, hex out.** `value` takes any CSS colour and `onChange` always emits hex (`#rrggbb`, or `#rrggbbaa` when the colour is not fully opaque), so a round trip through the picker normalises the notation. A value the browser cannot parse at all falls back to the component's default colour rather than throwing.
+
+Parsing uses the browser's own colour engine, which means it needs a DOM with a canvas. Under jsdom every non-hex value falls back to the default instead — worth knowing when a test asserts on a colour that went in as `rgb()`.
+
+## Sizing
+
+The inline swatch tracks the theme's text size, since it sits beside a label: `--swatch-size` falls back to `2em`, i.e. 32px at a 16px base, and the gap, the hex overlay and the transparency checkerboard scale with it.
+
+The picker panel deliberately does not. It is a floating control surface with its own fixed layout — a saturation area, sliders and a hex field — and it holds together at a large base font rather than needing to grow with it.

package/docs/Fab.md

@@ -41,3 +41,19 @@ import { faPlus, faPen, faCamera } from '@fortawesome/free-solid-svg-icons';
 | `closeMenuOnEntryClicked` | `boolean` | Auto-close menu after selection |
 | `onClick` | `() => void` | Simple click handler (no speed dial) |
 | `children` | `ReactNode` | FAB icon content |
+
+## Sizing
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--fab-size` | `56px` |
+| `--fab-mini-size` | `40px` |
+| `--fab-icon-size` | `18px` |
+
+**Deliberately not tied to `--default-font-size`**, unlike Button. A FAB is a touch target holding an icon: its size is set by fingers rather than by reading comfort, it contains no text to stay in proportion with, and it floats over the page — so growing it with the text scale would only occlude more content. Couple them yourself if that is what you want:
+
+```css
+--fab-size: calc(var(--default-font-size) * 3.5);
+```
+
+`--fab-icon-size` is independent of `--fab-size`, so enlarging the button does not enlarge the glyph; set both. It applies to the speed-dial entries as well as the main button.

package/docs/Flip.md

@@ -67,7 +67,7 @@ import { Tilt, Flip } from '@ahrowe/ui';
 
 **Motion:** the flip always animates over `flipDuration`, whether triggered by a click, a controlled prop change, or the ref API. Under `prefers-reduced-motion: reduce`, it flips instantly instead. `onFlipEnd` fires once the flip settles on its new face — after the transition completes normally, or synchronously under reduced motion, since no transition runs to wait for.
 
-**Keyboard accessibility:** when `flipOnClick` is set, the root gets `role="button"`, `tabIndex={0}`, and `aria-pressed` reflecting the current flip state, and Enter/Space both toggle the flip the same way a click does. None of this is applied when `flipOnClick` is `false`, since the element isn't interactive.
+**Keyboard accessibility:** when `flipOnClick` is set, the root gets `role="button"`, `tabIndex={0}`, and `aria-pressed` reflecting the current flip state, and Enter/Space both toggle the flip the same way a click does, as long as the key was pressed on the root itself so a nested input or button keeps its own keys. None of this is applied when `flipOnClick` is `false`, since the element isn't interactive.
 
 **Key props:**
 

package/docs/IconPicker.md

@@ -57,3 +57,11 @@ interface IconPickerItem {
 | `isRequired` | `boolean` | |
 
 **Slots:** `root` `label` `itemContainer` `item`
+
+## Selected state
+
+A selected icon sits on `--primary-color` and draws itself in `--text-on-primary`. It used to inherit the page's `--text-color`, which meant the same selected state came out white on a dark theme and near-black on a light one.
+
+## Sizing
+
+Each icon's circular background is `1.5em`, so it stays proportional to the `1em` glyph inside it, as do the padding and the grid gaps.

package/docs/Input.md

@@ -124,3 +124,15 @@ The stored value is the formatted one, spaces included, so strip them before a l
 | `customInput` | `ReactElement` | Element rendered in place of the internal `<input>`, cloned with all of Input's props. The escape hatch for a mask library; note `autoFocus` and `autoResize` stop working, since Input cannot attach its ref |
 
 **Slots:** `label` `container` `input` `suffix` `upperRightLabel` `fieldset`
+
+## Browser autofill
+
+`autoComplete` is the plain HTML attribute and is passed straight through — use `'one-time-code'`, `'new-password'`, `'street-address'` and the rest as you would on a bare `<input>`. Input does **not** set it: autofill and password managers are usability and accessibility features, and a plain field has no suggestion list of its own for them to collide with.
+
+The combobox components — `InputDropdown`, `SearchInput`, `MultiSelect`, `DatePicker`, `TimeInput` — always set `autocomplete="off"` and do not take the prop, because the browser's dropdown would otherwise open on top of the list they render themselves.
+
+**The floating label knows about autofill.** Chrome fills a field on page load by writing the DOM value directly, without firing anything React can observe — so the component's value stayed empty and the label sat on top of the autofilled text. Input detects it through a no-op animation bound to `:-webkit-autofill`, whose `animationstart` is the only notification the browser gives, and floats the label from that as well as from its value.
+
+**Autofilled fields stay on the theme.** Chrome paints `:-webkit-autofill` with its own background and text colour, overriding `background` and `color` outright, which turned a filled field pale blue with near-black text on a dark theme. Input clips that background to the text instead of covering it: the page cannot win on colour, but it can say where a background paints, and `-webkit-text-fill-color` then beats the text colour. The field itself is transparent, so what shows through is whatever is genuinely behind it — inside a Modal, a Card, or a surface of your own — and nothing has to be told what that is.
+
+A custom `--input-background` is covered by the same mechanism, because the container paints it and the transparent field reveals it. Setting a background on the field itself with the `background` shorthand — `styles={{ input: { background: '…' } }}` — resets `background-clip` along with it, and an autofilled field there falls back to Chrome's own colours; `background-color` does not.

package/docs/OtpInput.md

@@ -90,3 +90,7 @@ const codeValidator = new FormValidator('', [Validators.required(), Validators.m
 | `autoFocus` | `boolean` | Focuses the first empty box (or the first box) on mount |
 
 **Slots:** `root` `label` `inputs` `input` `separator`
+
+## Sizing
+
+The code boxes, the digit inside them, the gaps and the separator all scale with the theme's text, so the field stays in proportion with its label.

package/docs/RadioGroup.md

@@ -76,3 +76,9 @@ interface RadioOption {
 **Global defaults:** adopts `ConfigProvider` — e.g. `defaultProps={{ RadioGroup: { orientation: RadioGroupOrientation.Horizontal } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
 **Slots:** `root` `option` `radio` `dot` `label` `description`
+
+## Sizing
+
+The group is sized by its font, so the radios, the spacing between options and the gap to each label all scale with the text. `--radio-size` and `--radio-gap` override the circle and the label spacing; they fall back to `1.125em` and `0.625em`, i.e. 18px and 10px at a 16px base. The dot is always half the circle.
+
+The `size` prop still wins where it is given, for a radio that must match a fixed layout rather than the text around it.

package/docs/Rating.md

@@ -66,7 +66,12 @@ import { faHeart } from '@fortawesome/free-solid-svg-icons';
 |----------|---------------|
 | `--rating-filled-color` | `var(--primary-color)` |
 | `--rating-empty-color` | `var(--background-accent-light)` |
+| `--rating-size` | `1.25x --default-font-size`, i.e. 20px at a 16px base |
 
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Rating: { allowHalf: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
 **Slots:** `root` `item` `iconEmpty` `iconFilled`
+
+## Sizing
+
+The symbols, the gap between them and the partial-fill clip are all `em` against `--rating-size`, so setting it alone resizes the whole control.

package/docs/RoomDrawer.md

@@ -323,26 +323,34 @@ ref.current?.loadJson(await file.text());
 
 ## Theming
 
-All colours come from theme variables. These control the plan itself, and each falls back to a general theme colour when unset:
+All colours come from theme variables. These control the plan itself, and each falls back to a general theme colour when unset. They are declared on `ThemeVariables`, so a `Theme` gets them with autocomplete:
 
 | Variable | Falls back to |
 |----------|---------------|
 | `--plan-canvas-background` | `var(--background)` |
 | `--plan-grid-color` | `var(--text-color)` at low opacity |
+| `--plan-underlay-color` | `var(--text-dark)` at low opacity |
 | `--plan-room-fill` | `var(--background-accent)` |
 | `--plan-room-fill-hover` | `var(--background-accent-light)` |
 | `--plan-room-edge-selected` / `--plan-room-edge-selected-fill` | `var(--primary-color)` / `var(--primary-lighter)` |
-| `--plan-wall-fill` | `var(--text-dark)` |
-| `--plan-wall-outline` | `var(--text-color)` |
+| `--plan-wall-fill` | `var(--text-color)` mixed 58% into the canvas |
+| `--plan-wall-outline` | `var(--text-color)` mixed 38% into the canvas |
+| `--plan-wall-join` | `round` (see below) |
 | `--plan-wall-miter-limit` | `4` (see below) |
 | `--plan-door-color` | `var(--text-dark)` |
 | `--plan-window-color` | `var(--info-color)` |
+| `--plan-guide-color` | `var(--info-color)` |
+| `--plan-measure-color` | `var(--primary-color)` |
 
-**`--plan-wall-miter-limit`** is how sharp a corner may get before it is cut flat rather than run to a point. A mitred join extends to `1 / sin(angle / 2)` times the wall thickness, so it grows without bound as the angle closes: at 10 degrees that is eleven times the wall's own thickness, which reads as a spike fired out of the corner. The default of `4` keeps a true mitred point down to about 29 degrees and caps it at twice the wall's own thickness; sharper than that the corner is cut flat instead. Acute rooms bottom out around 45 degrees in practice and anything under 30 is not a room, so the corners that keep their point are the ones a building actually has. Raise it if you are drawing something genuinely needle-shaped and want the point kept. It governs the corners at a junction too, on the rare occasion one needs filling: where three or more walls meet, the corners between them are normally closed already, except when every wall at the node points into the same half-plane.
+**Walls are drawn as mass, not as ink.** Both wall tones are mixed towards the canvas rather than set to the text colour, so a wall reads as a solid body sitting on the floor and its edge as a soft rim rather than a drafted hairline. The pair must stay two distinct values: the outline pass is only visible where the fill pass does not cover it. The jamb faces at an opening take the *body* tone, since at a doorway they are the only thing standing in for the wall.
+
+**`--plan-wall-join`** is the corner treatment, `round` by default: the outer corners of the building come out softened, and an acute corner cannot throw a mitre spike out of the junction at all. Set it to `miter` for the drafting corner, and `--plan-wall-miter-limit` then governs how far that spike may run. The selection highlight always uses whichever join the walls use, because it is drawn over the same geometry and a different join would leave crescents of wall showing round the corners.
+
+**`--plan-wall-miter-limit`** applies when `--plan-wall-join` is `miter`. It is how sharp a corner may get before it is cut flat rather than run to a point. A mitred join extends to `1 / sin(angle / 2)` times the wall thickness, so it grows without bound as the angle closes: at 10 degrees that is eleven times the wall's own thickness, which reads as a spike fired out of the corner. The default of `4` keeps a true mitred point down to about 29 degrees and caps it at twice the wall's own thickness; sharper than that the corner is cut flat instead. Acute rooms bottom out around 45 degrees in practice and anything under 30 is not a room, so the corners that keep their point are the ones a building actually has. Raise it if you are drawing something genuinely needle-shaped and want the point kept. It governs the corners at a junction too, on the rare occasion one needs filling: where three or more walls meet, the corners between them are normally closed already, except when every wall at the node points into the same half-plane.
 
 **Hover tints the room's floor; selection colours the walls that bound it.** They answer different questions, so they get different channels and can be read at the same time without being confused. Hover is fleeting and asks *which room is under the pointer*, where a faint fill is instant and unambiguous — a wall is not, being shared between the rooms on either side of it. Selection is state you then work inside, where a wash over the room would bury its doors and its label.
 
-The selection highlight is built from **the same geometry as the walls themselves** and drawn in the same two passes, so it inherits their mitred corners and their gaps at openings: a door in the boundary stays a doorway rather than being painted over, and the wall keeps a crisp edge instead of turning into a flat slab. Where two selected rooms share a wall it is drawn once, so it never comes out twice as strong as its neighbours. The room fill carries `data-state="selected" | "hovered"` if you want to style either state further.
+The selection highlight is built from **the same geometry as the walls themselves** and drawn in the same two passes, so it inherits their corners and their gaps at openings: a door in the boundary stays a doorway rather than being painted over, and the wall keeps a crisp edge instead of turning into a flat slab. Where two selected rooms share a wall it is drawn once, so it never comes out twice as strong as its neighbours. The room fill carries `data-state="selected" | "hovered"` if you want to style either state further.
 
 ## Accessibility
 

package/docs/RoomViewer.md

@@ -54,6 +54,10 @@ A plan holds a stack of storeys and the viewer shows one at a time, with a tab p
 
 Drag to pan, wheel or pinch to zoom, and the controls in the corner zoom and fit. The plan fits itself to the viewport on mount, and refits when the floor or the canvas size changes — **until the viewer pans or zooms**, after which the view is theirs and the component stops moving it. `pannable={false}` freezes it.
 
+## Theming the plan
+
+Walls are drawn as mass rather than as ink: the body is `var(--text-color)` mixed 58% into the canvas, its edge the same colour at 38%, and the corners are rounded. Override with `--plan-wall-fill`, `--plan-wall-outline` and `--plan-wall-join: miter`. The full list of plan variables is in [RoomDrawer.md](RoomDrawer.md#theming), and both components read the same ones.
+
 ## Key props
 
 | Prop | Type | Description |

package/docs/Slider.md

@@ -92,8 +92,8 @@ const [value, setValue] = useState(40);
 | `--slider-track-color` | `var(--background-accent-light)` |
 | `--slider-range-color` | `var(--primary-color)` |
 | `--slider-thumb-color` | `var(--primary-color)` |
-| `--slider-thumb-size` | `18px` (also settable per instance via `size`) |
-| `--slider-track-height` | `6px` |
+| `--slider-thumb-size` | `1.125x --default-font-size`, i.e. 18px at a 16px base (also settable per instance via `size`) |
+| `--slider-track-height` | `0.375x --default-font-size`, i.e. 6px at a 16px base |
 
 **Range mode:** set `range` for two thumbs and `[from, to]` pairs.
 
@@ -123,3 +123,7 @@ different things that happen to share a word. The slot means the same in both mo
 announces the limit the thumb actually has. Both thumbs are tabbable and take the same keys.
 
 **Slots:** `root` `track` `range` `thumb` `mark` `markLabel` `value`
+
+## Sizing
+
+The thumb and track scale with the theme's text, so the control stays in proportion with the value and mark labels beside it — those are sized from `--text-small-font-size` and already grew. `--slider-thumb-size` and `--slider-track-height` override them, and the `size` prop still wins where it is given.

package/docs/ThemeProvider.md

@@ -2,7 +2,7 @@
 
 **When to use:** Required wrapper for the entire component library. Injects all CSS custom properties as inline styles so every component inside can use theme variables. Place it at or near the root of your app.
 
-**Keywords:** theming, dark mode
+**Keywords:** theming, dark mode, gradient
 
 **Import:** `import { ThemeProvider } from '@ahrowe/ui'`  
 **Types:** `import type { Theme, ThemeVariables } from '@ahrowe/ui'`
@@ -65,6 +65,7 @@ interface Theme {
 | Variable | Purpose |
 |----------|---------|
 | `--primary-color` / `--primary-lighter` / `--primary-accent` | Brand colours |
+| `--primary-gradient` | Optional gradient layered over `--primary-color` on large filled surfaces (see [Gradient primary](#gradient-primary)) |
 | `--background` | Page/surface background |
 | `--background-accent` / `--background-accent-light` | Raised surfaces, cards |
 | `--text-color` / `--text-dark` | Primary and secondary text |
@@ -89,3 +90,90 @@ interface Theme {
 **Note:** Without `ThemeProvider`, all CSS variables are undefined and components will be unstyled.
 
 **Base typography:** The wrapper also sets `font-family`, `font-size`, `font-weight`, and `color` from the theme's `--default-font`, `--default-font-size`, `--default-font-weight`, and `--text-color`, so everything inside — including content portaled into a `#bodyEnd` placed within the provider — inherits the theme's base text style without each component having to set it.
+
+## Gradient primary
+
+Set `--primary-gradient` next to `--primary-color` to give the brand a gradient:
+
+```ts
+const brandTheme: Theme = {
+  id: 'brand',
+  variables: {
+    '--primary-color': '#8a4bd6',
+    '--primary-gradient': 'linear-gradient(135deg, #6d4bd6 0%, #a24bd6 55%, #4b7ed6 100%)',
+    '--text-on-primary': '#ffffff',
+  },
+};
+```
+
+`--primary-color` stays required and stays a solid colour. A CSS gradient is an image, not a colour,
+so it is invalid in every property that expects one: borders, outlines, SVG strokes, shadows,
+`color`, `color-mix()`. Putting a gradient into `--primary-color` would break those silently, with no
+error and no way to feature-detect it. `--primary-gradient` is therefore additive: it paints over the
+solid on filled surfaces large enough to show a ramp, and everything else keeps the solid.
+
+Surfaces that honour it:
+
+| Component | Surface |
+|-----------|---------|
+| `Button` | primary style |
+| `Chip` | primary style |
+| `ProgressBar` | fill |
+| `Switch` | checked track |
+| `Slider` | filled range |
+| `Pagination` | active page |
+| `OptionPicker` | selected option |
+| `Badge` | primary style, except the `dot` variant |
+| `Alert` | default-style accent border |
+| `Toast` | default-style accent border |
+| `TabHeader` | active tab indicator |
+
+Everything else stays flat: focus rings, outlines, icons, primary-coloured text, and small marks
+such as the `Timeline` dot, the `Checkbox` tick and the `RadioGroup` dot. Focus rings in particular
+stay a solid `--focus-border-color`, because an indicator needs one predictable contrast ratio
+against whatever it sits on, not a ramp that is only high-contrast at one end.
+
+Pick a `--primary-color` that reads as the same brand next to the gradient, since the two sit side
+by side on a component such as an active `Pagination` item, which has a gradient fill inside a solid
+border.
+
+Two things to check when choosing the stops:
+
+- **Contrast.** `--text-on-primary` is one colour sitting on the whole ramp, so keep the stops within
+  a similar lightness. A gradient running light to dark fails contrast at one end.
+- **Element-sized ramps.** Each surface paints its own full gradient, so a wide `Button` and a narrow
+  one show different slices, and a `ProgressBar` ramp shifts as the value grows.
+- **Seams in grouped controls.** Where two primary buttons sit against each other, in a `ButtonGroup`
+  or a `SplitButton`, each segment paints a full ramp, so the end of one meets the start of the next
+  at the seam. A gradient with a vertical axis has no seam to show, since both segments are the same
+  height and stretch together:
+
+  ```
+  linear-gradient(180deg, #8d5ce8 0%, #5a37b8 100%)   /* one control, no seam */
+  linear-gradient(90deg, #6d4bd6 0%, #4b7ed6 100%)    /* visible seam at each segment boundary */
+  ```
+
+  If you want a horizontal or diagonal ramp anyway, flatten the grouped case on its own:
+
+  ```css
+  .myToolbar [role='group'] {
+    --primary-gradient: none;
+  }
+  ```
+
+To turn the gradient off for part of the app, or for a component whose fill you have overridden
+through its own variable (`--slider-range-color`, `--pagination-active-background`), set it back to
+`none` on that subtree:
+
+```css
+.myPanel {
+  --primary-gradient: none;
+}
+```
+
+## Nested providers and portals
+
+Providers nest: an inner one overrides the variables it declares and inherits the rest, so a differently-themed panel inside a themed app works without restating the whole theme.
+
+A portal breaks that by default, because theme variables travel by CSS inheritance and a portal escapes the subtree. Anything rendered through `BodyEnd` — `Tooltip`, `Dropdown`, `InputDropdown`, `ColorPicker`, `FloatingMenu`, `Popover`, `Modal`, `Toast` — therefore carries the nearest provider's variables with it, so an open panel matches the panel that opened it rather than whatever wraps `#bodyEnd`.
+

package/docs/Timer.md

@@ -131,7 +131,7 @@ function Example() {
 | `--timer-progress-color` | `var(--primary-color)` |
 | `--timer-urgent-color` | `var(--error-color)` |
 | `--timer-ripple-color` | `var(--timer-progress-color)` (which itself falls back to `var(--primary-color)`) |
-| `--timer-size` | `160px` (also settable per instance via `size`) |
+| `--timer-size` | `10em`, i.e. 160px at a 16px base (also settable per instance via `size`) |
 | `--timer-stroke-width` | `10px` (also settable per instance via `strokeWidth`) |
 | `--timer-text-color` | `var(--text-color)` |
 | `--timer-label-color` | `var(--text-dark)` |
@@ -139,3 +139,9 @@ function Example() {
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Timer: { adjustSeconds: 60, playSoundOnComplete: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
 **Slots:** `root` `ringWrapper` `ringSvg` `ringTrack` `ringProgress` `ripples` `ripple` `display` `time` `label` `controls` `addButton` `removeButton` `pauseButton` `cancelButton`
+
+## Sizing
+
+The ring follows the theme's text size, because the readout inside it does: `--timer-size` falls back to `10em`, i.e. 160px at a 16px base, and the gaps and padding around it are `em` too. The `size` prop still wins where it is given.
+
+`--timer-stroke-width` is the exception and stays in viewBox units. It already scales with the ring, and it has to match the `strokeWidth` prop, which the component subtracts from the circle's radius so the stroke fits inside the viewBox.

package/docs/Toast.md

@@ -74,3 +74,9 @@ showToast('Done', {
 **ToastType:** `'default'` `'info'` `'success'` `'error'` `'warn'`
 
 **Slots:** `root` `icon` `content` `closeButton` `progressBar`
+
+## Sizing
+
+A toast is sized and spaced by its font: the padding, the gap, the body copy, the icon, the close button, the variant accent bar and the progress bar all scale with the theme's text, as does the gap between stacked toasts.
+
+Its `min-width` and `max-width` are `em` rather than pixels, so they bound the *measure* — roughly how many characters fit on a line — instead of a fixed width that would grow cramped as the text got larger.

package/docs/Tooltip.md

@@ -41,3 +41,18 @@ import { Tooltip } from '@ahrowe/ui';
 | `onClick` | `() => void` | Click handler on the icon |
 
 The bubble is rendered through a portal and tracks its trigger's position directly, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists) — no `position: relative` wrapper is required. It flips to the opposite side automatically when there's no room in its preferred direction, and hides (without losing state) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view.
+
+**Theming:** these are theme variables (typed on `ThemeVariables`). Set them theme-wide via `ThemeProvider`'s `variables`, or per instance via `style`, without fighting specificity. Each falls back to a built-in default when unset:
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--tooltip-background` | `var(--text-color)` mixed 82% into `var(--background)` |
+| `--tooltip-color` | `var(--background)` |
+
+The default bubble is an **inverse of the page** rather than a fixed colour: it comes out dark on a light theme and light on a dark one, so it always separates from whatever it floats over. Both the arrow and the `details` badge follow `--tooltip-background`, so overriding it recolours the whole tooltip. The `error` variant is styled from the semantic error colours (`--error-lighter`, `--error-color`, `--error-border-color`) and ignores these two.
+
+## Sizing
+
+The bubble, its arrow, the `details` badge and the error variant all scale with the theme's text. The bubble's `max-width` is `em`, so it bounds a line measure rather than a pixel count as the text grows.
+
+The badge derives its size from `--default-font-size` directly rather than from `em`. It renders inline wherever you put it, so an `em` would measure the surrounding text instead of the theme; the bubble can use `em` because it is portaled to `#bodyEnd` and always lands on the theme's own size.