zabi-components 8.0.0 → 9.0.0

package/CHANGELOG.md

@@ -0,0 +1,2935 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Changelog policy (theme/token surface)
+
+Whenever token or CSS import API surface changes, include:
+- exported path additions/removals/deprecations (`package.json` `exports`)
+- token rename/add/remove (for `--color-*` and `--zabi-*`)
+- mapping rule updates (for example dark semantic mapping)
+- migration guidance when compatibility aliases remain temporarily
+
+## [Unreleased]
+
+### Fixed
+
+- **BottomTabBar**: a tab's side padding is 2px (was 4px), so a five-tab bar keeps a label like "Kalender" whole at 320px.
+- **Toaster**: a stack that scrolls keeps the newest toast in view when its words arrive after it is shown and it grows. It was pushed below the end of the stack.
+
+## [9.0.0] - 2026-10-13
+
+9.0.0 is a new look and a larger set. Bars, sheets, menus and toasts are glass materials, the light page is
+near-white, dark mode is drawn on the neutral ramp, and solid controls have a soft gradient. The shell is
+redesigned: flush bars that turn to glass over content, a large `AppBar` title, an `AppShell` `navigation` slot
+with `AppNavigation`. New components include `Chip` and `ChipGroup`, `Block`, `Stat`, `PickerField`, `CodeField`,
+`SpeechBubble`, the SVG charts (`LineChart`, `BarChart`, `PieChart`, `Sparkline`) and `MapView` (from
+`zabi-components/map`, with `maplibre-gl` as an optional peer). It is a major because of what an app shows
+without a code change, not because of its API: nothing from 8.1.0 was removed or renamed, and every `exports`
+path, prop, variant and token is still there.
+
+The work was built as 32 local preview builds, none published to npm. Their sections below are the full record:
+every addition, every changed default and, where one exists, the line that restores the 8.1 look.
+
+### Upgrade notes
+
+Coming from 8.1.0, these are visible without a code change. The section named in brackets has the detail and
+the line that restores 8.1.
+
+**Appearance, light and dark**
+
+- The default typeface is the platform's UI face, and transitions use `--ease-standard` (alpha.1).
+- The light page is near-white (`--color-surface-base` is `--zabi-base-50`), a default `Card` has a 1px edge and
+  no shadow, status tints are a step lighter and shadows are softer (alpha.1).
+- Primary, accent and danger buttons, the `FloatingActionButton` and the on `Toggle` have a soft gradient. The
+  outline button has a 3:1 edge. The off `Toggle` is a light tint, and its knob is 3:1 on the track (alpha.2,
+  alpha.26).
+- `SegmentedControl` selects with a neutral thumb, and its indicator and the one in `Tabs` slide. `List` rows
+  are divided by a hairline, and a subtle `Badge` has no visible border (alpha.2).
+- `BottomSheet`, `Drawer`, `Modal`, the `Dropdown` menu, the `Select` list, `Tooltip` and every toast are frosted
+  glass. `Tooltip` has no arrow by default. `data-materials="opaque"` turns the glass off (alpha.2).
+- `AppBar`, `BottomTabBar`, `StickyActionBar` and `TopNavbar` are the page colour at rest and glass once content
+  is under them. `--color-surface-chrome` is the page colour. The active tab has no outline, and the sidebar
+  and the top navbar are restyled (alpha.3).
+- Dark surfaces are steps of the neutral ramp, the primary and danger buttons keep their hue in dark under a
+  white label (`createTheme({ darkPrimary: 'mirror' })` gives the 8.1 fills), and dark status tints are
+  low-chroma (alpha.4).
+- In dark, a form field is a translucent well and a flat `Card` is a translucent layer (alpha.6).
+
+**Layout and behaviour**
+
+- A `bg-*` or `border-*` class on a bar no longer changes its surface: the fill is painted on the material's
+  layer (alpha.3).
+- The `AppShell` footer lies over the scroller, so content passes under the tab bar (alpha.3).
+- `Collapsible` with the default trigger is a native `<details>` with a `<summary>`, not a `<button>`
+  (alpha.5).
+- `Input type="password"` has the show/hide button by default (`revealable={false}` removes it), and `Textarea`
+  has no resize grip on a touch screen (alpha.6).
+- A `Select` in a sheet with up to six options and no search gets a sheet as tall as its list
+  (`sheetFit={false}` restores the half sheet) (alpha.8).
+- A `RadioGroup` option's `description` is no longer part of the radio's name, and `Skeleton` is still under
+  reduced motion (alpha.12).
+- `TopNavbar` opens its links in a bottom sheet below `collapseAt` (alpha.16).
+- Toasts: a mouse holds the timer only once it has moved over the toast, a pushed id replaces the showing
+  toast in place, and a touch swipe dismisses (alpha.18).
+- `Button` is capped at its container's width and hyphenates a label that does not fit (alpha.32).
+
+**Themes**
+
+- `createTheme` checks the material pairs it used to skip, so a theme can get a contrast warning it did not
+  get in 8.1.0. Links follow an overridden primary (alpha.2, alpha.4).
+- The theme snapshot only gained names: no published token was removed.
+
+### Fixed since alpha.32
+
+Found by the first full browser run on 9.0.
+
+- A secondary `Button` or `IconButton` on a brand block (`on-brand`, `Card tone="brand"`, a brand `AppBar`) in
+  dark: its wash was the dark theme's white one, under the block's white label, which left the label at
+  4.1:1. On a brand block the wash is now the dark one in both modes (5.7:1). A surface inside the block gets
+  the theme's wash back.
+- A brand block inside an accent block, or an accent block inside a brand block, with or without a card
+  between them, took its own label colour as its fill: white text on white. The inversion of a solid fill
+  inside a block no longer applies to an element that is a block itself.
+
+### Not verified
+
+The preview builds were tested lightly on purpose (type and design checks, unit tests in jsdom, the package
+build). Not done by anyone: a real phone, Safari, Firefox, a screen reader, an accessibility review. `MapView`
+has never been drawn against a real map: its tests use a stand-in for MapLibre.
+
+## [9.0.0-alpha.32] - 2026-10-13
+
+A thirty-second local preview build of the 9.0 direction, not published to npm. No token, prop, variant,
+string key, export or data attribute of alpha.31 is removed or renamed. Nothing in it has been rendered in a
+browser: type and design checks, unit tests in jsdom, the package build.
+
+### Added
+
+- `MapView`, from a new entry `zabi-components/map`: a map on MapLibre GL JS with markers from a list (Z-137,
+  D262). `maplibre-gl` is an optional peer dependency (`>=5.0.0`, built against 6.14.0): the app installs it, and
+  the component loads it with `import("maplibre-gl")` when it is mounted in a browser. No other entry of the
+  package exports the map, so importing anything else brings none of it. The library's stylesheet is not needed.
+  - `points` (`id`, `lng`, `lat`, `label`, `checked`), `styleLight` and `styleDark` (URL or object; the dark one
+    is drawn while `data-theme` on `<html>` is dark, or `auto` on a dark system, and a change keeps the position
+    and the markers), `onpointpress(point, index)`, `onclusterpress(points)`, `clusterLabel(points)`.
+  - Markers are buttons with a 44px tap area in px, in the order of `points`. Markers whose tap areas overlap are
+    one count marker, which sits at the place of its first point in the tab order and keeps its element (and the
+    focus) while others join or leave it. A marker reached with Tab outside the view is jumped into view.
+  - `fitMaxZoom` (default 16), `bind:center`, `bind:zoom`, `onmove`, and the methods `fit()`,
+    `showPoint(id, { inset, zoom })` and `showPlace(place, { inset, zoom })` through `bind:this`. Every move is a
+    jump. With `center` and `zoom` given at the start the map opens there and is not fitted.
+  - `viewer`: a dot at a position the page hands in; the map jumps to it. The component never asks the browser.
+  - `bind:status` / `onstatus`: `loading`, `ready`, `library-error`, `tiles-error`. `tiles-error` is told when the
+    style cannot be fetched, or tiles failed and none has arrived; a tile that arrives later takes it back.
+  - `attribution` (string or snippet); without it the words of the style's own attribution, as plain text. Always
+    shown, bottom left. `strings`: `label`, `cluster(count)`, `viewer`. `mapViewSupported()` answers whether the
+    browser has WebGL without loading the library.
+  - Not in `ZabiStringsProvider` yet: the words come through `strings`. A drag that starts on a marker does not
+    pan the map.
+- `Textarea`: `count`, `countFrom` and `countText` show a character count under the field when it has a
+  `maxlength`: "12 / 2000" by default, at the end of the line the hint is on, part of the field's description and
+  not a live region. `TextareaCount` is exported (Z-125, D254).
+- `Toggle`: `description`, a line under the label and inside it, so a tap on it toggles. It is tied to the switch
+  with `aria-describedby`, after any ids passed in, and does not join the name (Z-126, D255).
+- `Checkbox`: `description`, as `Radio` has. `Checkbox` and `Radio`: `controlPosition="end"` puts the control
+  last in the row, which then fills its width; the markup order is unchanged (Z-128, D256).
+- `ImageUpload`: `multiple`, `maxFiles` and `onfiles(files)`. With `multiple` the chooser and a drop take several
+  files and hand them over together, in order; the component keeps none (no preview, `value` not set,
+  `onfileselect` not called). `onfilereject` has a third reason, `"count"`, only with `maxFiles` (Z-130, D258).
+- `PhotoViewer`: `onloaderror(photo, index)`, once per address that fails, and `onretry(photo, index)`, called
+  when "Try again" is pressed; a promise it returns is waited for, with the button busy, before the image is
+  asked for again. `PhotoGrid`: `onloaderror(photo, index)` for a thumbnail (Z-132, D259).
+- `PhotoGrid`: a photo's `status` (`uploading`, with an optional `progress` from 0 to 1, or `error`) is drawn on
+  its tile and said in its name; `onretry(photo, index)` puts a "Try again" button on a failed one. New strings
+  with defaults: `uploading`, `uploadFailed`, `retryUpload(name)`. `PhotoStatus` is exported (Z-133, D260).
+- `PhotoViewer`: a photo's `credit` is a second, quieter line under the caption, outside what "More" folds. The
+  dialog is described by the caption and the credit after the photo's name and place (Z-135, D261).
+
+### Fixed
+
+- `Button`: never wider than its container (`max-inline-size: 100%`, as `Badge`), and a word that alone does not fit is hyphenated by
+  the page's language (`hyphens-auto`). A label that already wraps may now be hyphenated at a line's end
+  (Z-129, D257).
+- `Checkbox`, `Radio`, `RadioGroup`: the input's touch target is 44px in px, centred on the box. In rem it grew
+  with the text: 88px at 200%, past the screen's edge from a box at the end of a row (Z-128, D256).
+- `PhotoGrid`: nothing leaves the add tile at large text. The label is cut at two lines (the name keeps the whole
+  text) and the plus is drawn only where the tile has room for it above two lines (Z-136, D260).
+- `PhotoViewer`: when the control that had the focus is taken out (an action that goes with its photo, with or
+  without a confirm dialog between) and the focus is left on `<body>`, Close takes it (Z-134, D261).
+
+### Notes
+
+- `Collapsible` is not for a "show all" under a list; a `Button` with `aria-expanded` and `aria-controls` under
+  the list is the intended way (Z-127, D263).
+- `PhotoViewer` does not take the browser's Back: a history entry made by a component conflicts with the app's
+  router. Open it from the router's own state, as SvelteKit's shallow routing does (Z-131, D263).
+
+## [9.0.0-alpha.31] - 2026-10-11
+
+A thirty-first local preview build of the 9.0 direction, not published to npm. No token, prop, variant,
+string key, export or data attribute of alpha.30 is removed or renamed.
+
+### Fixed
+
+- `Input`: a placeholder longer than the field ends in an ellipsis (`placeholder-shown:text-ellipsis`), not half way
+  through a letter. A typed value is unchanged: it still scrolls with the caret. A placeholder that fits looks the
+  same. Fields built on `Input` (`ColorPicker`, the search field of `Select`, `SidebarPanel` and
+  `SidebarNavigation`) get it too (Z-124, D252).
+
+## [9.0.0-alpha.30] - 2026-10-11
+
+A thirtieth local preview build of the 9.0 direction, not published to npm. No token, prop, variant,
+string key, export or data attribute of alpha.29 is removed or renamed.
+
+### Added
+
+- `Skeleton`: every piece carries `data-skeleton` (its variant; a line of a `lines` paragraph is `text`, beside the
+  existing `data-skeleton-line`), in every branch: announced, `decorative`, and inside a `SkeletonGroup`. A
+  paragraph's wrapper has `data-skeleton-paragraph`. The `animate-pulse` class stays on the pieces (Z-123, D251).
+- `Skeleton` and `SkeletonGroup` pass other `div` attributes (`id`, `data-testid`, `style`, `aria-*`) to their
+  root element. `role`, `aria-busy`, `aria-hidden` and `data-skeleton` are not overridden. `SkeletonGroup` has
+  `data-skeleton-group`.
+
+## [9.0.0-alpha.29] - 2026-10-10
+
+A twenty-ninth local preview build of the 9.0 direction, not published to npm. No token, prop, variant,
+string key, export or data attribute of alpha.28 is removed or renamed.
+
+### Fixed
+
+- `Select`: an option in the list that opens has the pointer cursor, as a `DropdownItem` has; a disabled option
+  keeps `not-allowed`.
+- `ActionPanel` as a button (`onclick`, no `href`) has the pointer cursor.
+
+## [9.0.0-alpha.28] - 2026-10-10
+
+A twenty-eighth local preview build of the 9.0 direction, not published to npm. No token, prop, variant,
+string key, export or data attribute of alpha.27 is removed or renamed.
+
+### Added
+
+- `AppBar`: the row carries `data-title-empty` when the bar has no `title`.
+
+### Fixed
+
+- `AppBar` with no `title` and a wide `leading`: the empty title part no longer asks for 72px, so it no longer
+  sends the bar to `data-title-row="own"` and takes a row of its own (the bar was 12px taller). A bar with
+  nothing to show as a title stays on one row whatever room is left, on the server and before it is measured
+  as well; `leading` is still cut to the room beside the back control and the actions. A bar with a title is
+  unchanged.
+
+## [9.0.0-alpha.27] - 2026-10-10
+
+A twenty-seventh local preview build of the 9.0 direction, not published to npm. Loose ends. No token,
+prop, variant, string key, export or data attribute of alpha.26 is removed or renamed.
+
+### Added
+
+- `zabi-components/atoms` now also exports `Toast`, `Tooltip`, `Progress`, `Skeleton`, `SkeletonGroup`,
+  `CodeBlock`, `FeatureCard`, `OptimizedImage`, `DEFAULT_SKELETON_STRINGS` and the type `SkeletonStrings`,
+  which the root entry already had.
+- Bottom sheets (`BottomSheet`, `SlideUp`): content with `touch-action: none`, or `pan-x` alone, under the
+  finger keeps its own gesture (a map, a canvas, a drawing pad); no `data-sheet-no-drag` is needed.
+  `data-sheet-no-drag` still works.
+
+### Changed
+
+- Bottom sheets: the axis of a swipe in the content is decided once per gesture, after 8px. A swipe that
+  begins sideways stays sideways and never moves the sheet, even if it later turns down. A downward swipe
+  of under 8px no longer starts a drag. The grip is unchanged.
+
+### Fixed
+
+- `Drawer`: the overlay root is `overflow-clip`, not `overflow-hidden`, as the bottom sheet's already was
+  (WebKit scrolled a hidden root to a focused control while the panel was still off screen).
+
+## [9.0.0-alpha.26] - 2026-10-10
+
+A twenty-sixth local preview build of the 9.0 direction, not published to npm. Three rulings from the
+owner (2026-10-10). No token, prop, variant, string key, export or data attribute of alpha.25 is removed or
+renamed. One default colour changes on purpose: the `Toggle` knob (below). Run on this build: the type and
+design checks, the unit suite, the package build and a scratch install; no browser.
+
+### Changed
+
+- `Toggle`: the default knob is now 3:1 or more on its track in every enabled state, light and dark
+  (WCAG 1.4.11). Before, the knob was the card colour: 1.27:1 on the off track in light and 1.57:1 in dark, and
+  1.74:1 to 3.39:1 on the primary fill in dark. Now off is `--color-toggle-knob` (light base-500: 3.81:1 on the resting
+  track, 3.53:1 hovered, 3.27:1 pressed; dark base-700: 7.07:1, 6.13:1, 5.23:1) and on is
+  `--color-toggle-knob-checked` (the primary fill's label colour: 4.86:1, 6.76:1, 9.44:1 on the fill at rest,
+  hovered, pressed). The off track's edge is unchanged (4.63:1 on the page and 4.83:1 on a card in light).
+  `--color-toggle-thumb` still wins when set; `--color-toggle-thumb-checked`, declared nowhere, sets the
+  on knob alone. The knob pairs are in the contrast guard. (Z-121, D240)
+
+### Fixed
+
+- `Checkbox`, `Radio`: the box is centred on the row again and the row keeps its height and touch target, as
+  before alpha.25; the first-line alignment and `pointer-coarse:py-3` of alpha.25 are withdrawn. The box
+  still does not shrink (`shrink-0`). (Z-119, D241)
+- Forced colours: a busy button `Card` (`loading`) has `GrayText` text and a dashed `GrayText` edge, and the
+  `Toaster` time bar's track has a `CanvasText` edge. Nothing changes outside `forced-colors: active`.
+  (D242)
+
+## [9.0.0-alpha.25] - 2026-10-10
+
+A twenty-fifth local preview build of the 9.0 direction, not published to npm. Five entries
+from the app team (Z-117 to Z-121). No token, prop, variant, string key, export or data attribute of
+alpha.24 is removed or renamed; new props, tokens and string keys are optional. Run on this build: the
+type and design checks, the unit suite, the package build and a scratch install; no browser.
+
+### Added
+
+- `TimeField` `openAt` (`HH:mm`): where an empty field's columns stand when the sheet opens. Nothing is
+  chosen and `value` stays empty. Without it the columns stand at now, on the minute step. (Z-117, D235)
+- `TimeField` string key `chosenTime` ("Chosen time"): the sheet says the time Done will set, beside
+  Done, so it is on the screen even when a column is scrolled away from it (Z-118, D236).
+- `--color-toggle-thumb`, declared nowhere: the `Toggle` knob's colour. Unset, the knob is the card colour as
+  before (Z-121, D239).
+
+### Fixed
+
+- `Checkbox`, `Radio`: the box no longer shrinks when the label wraps (`shrink-0` always), and sits by the
+  first line of a label that wraps (Z-119, D237).
+- `AppBar`: the parts of the row are measured as laid out (up to the next pixel) and not by `offsetWidth`,
+  so actions with a fractional width no longer wrap to a row of their own (Z-120, D238).
+
+## [9.0.0-alpha.24] - 2026-10-10
+
+A twenty-fourth local preview build of the 9.0 direction, not published to npm. Two entries
+from the app team (Z-115, Z-116). No token, prop, variant, string key, export or data attribute of
+alpha.23 is removed or renamed; nothing changes outside `forced-colors: active`. Run on this
+build: the type and design checks, the unit suite, the package build and a scratch install; no browser.
+
+### Fixed
+
+- Forced colours (Windows contrast themes): `Toggle` has a 1px `ButtonText` edge on the track, a thumb
+  in `ButtonText`; on is a `Highlight` track with a `HighlightText` thumb; disabled is `GrayText`
+  (Z-115, D232).
+- Forced colours: a ticked `Checkbox`, `Radio` and `RadioGroup` option is a `Highlight` box with a
+  `HighlightText` tick or dot, an unticked one an edge in `ButtonText`, a disabled one `GrayText`
+  (Z-116, D233).
+- Forced colours: `Slider` has a `Highlight` fill on a `Canvas` track with a `ButtonText` edge, and the
+  `Toaster` time bar is `Highlight` (D234).
+
+## [9.0.0-alpha.23] - 2026-10-09
+
+A twenty-third local preview build of the 9.0 direction, not published to npm. One entry
+from the app team (Z-114). No token, prop, variant, string key, export or data attribute of
+alpha.22 is removed or renamed. Run on this build: the type and design checks, the unit
+suite, the package build and a scratch install; no browser.
+
+### Fixed
+
+- `Checkbox`, `Radio` and `RadioGroup`: the edge of an unticked box is `--color-control-border` (3:1 on
+  every surface, both themes) and not the fixed step `base-400`, which was 2.5:1 in light and 1.9 to 2.3:1
+  in dark. In a brand or accent block it follows the block's on-colour too (Z-114, D231).
+
+## [9.0.0-alpha.22] - 2026-10-09
+
+A twenty-second local preview build of the 9.0 direction, not published to npm. Six entries
+from the app team (Z-108 to Z-113). No token, prop, variant, string key, export or data attribute of
+alpha.21 is removed or renamed. Run on this build: the type and design checks, the unit
+suite, the package build and a scratch install; no browser.
+
+### Added
+
+- `Card` `loading` (with `type`): `aria-busy` and `aria-disabled`, the press swallowed, the pressed look held,
+  size and Tab stop kept (Z-108, D225).
+- `BottomTabBar` `pending`: the tab just pressed takes the mark while `aria-current="page"` stays on `active`
+  until it changes; the pending link has `aria-busy` (Z-109, D226).
+- `.z-fixed`, beside `.z-sticky` and the other layer classes (Z-113, D230).
+
+### Fixed
+
+- `Button` in forced colours: the variants drawn by a fill (`primary`, `accent`, `secondary`, `danger`,
+  `tonal`) get a 1px `ButtonBorder` edge there, and a disabled or loading button a `GrayText` one (Z-110, D227).
+- `Stepper` inside a `SkeletonGroup` no longer renders its own `role="status"` (Z-111, D228).
+- `Skeleton`: the variant's width and height are written at zero specificity (`:where()`), so any size
+  class at the call site wins, including a size name of the app's own (Z-112, D229).
+
+## [9.0.0-alpha.21] - 2026-10-08
+
+A twenty-first local preview build of the 9.0 direction, not published to npm. One entry
+from the app team (Z-107). No token, prop, variant, string key, export or data attribute of
+alpha.20 is removed or renamed. Run on this build: the type and design checks, the unit
+suite, the package build and a scratch install; no browser.
+
+### Fixed
+
+- `BottomSheet`, `SlideUp` (and so `Select`, `Dropdown` and `TopNavbar` sheets, `TimeField`, `DateField`): a
+  swipe down that starts on a box inside the content that scrolls by itself (the hours and minutes of
+  `TimeField`, the list of a `Select`, a long text area) no longer moves the sheet; the box keeps the
+  gesture, at its top too, and nothing is handed over mid-gesture (Z-107, D224). The sheet still follows
+  a swipe from the grip, the header, the content outside such a box when the content is at its top.
+  Default change: a swipe down on a scrolling box at its top used to close the sheet and now does not.
+
+### Added
+
+- `data-sheet-no-drag` is read for a touch in the content as well as in the header: anything carrying
+  it, or inside it, and every `<input type="range">`, keeps its drag from the sheet. `TimeField`'s
+  columns, `ColorPicker`'s colour map and the handle of `SortableList` carry it.
+
+## [9.0.0-alpha.20] - 2026-10-08
+
+A twentieth local preview build of the 9.0 direction, not published to npm. Two
+entries from the app team, the first time the snackbar was drawn in a browser
+(Z-105, Z-106). No token, prop, variant, string key or export of alpha.19 is removed
+or renamed. Run on this build: the type and design checks, the unit suite, the package
+build and a scratch install; no browser.
+### Added
+
+- `Toaster` `timeLine?: boolean` and `pushToast` / `ToastItem` `timeLine?: boolean`: whether the thin
+  bar along the bottom of a timed toast is drawn. Unset, it is drawn as before, except under a
+  confirmation in the snackbar that has nothing to press (timed, no action, `closable: false`),
+  where it is now left out. `false` leaves it out, `true` draws it; a toast's own value wins over the
+  Toaster's. The bar has `data-toast-timeline`; the sentence for a screen reader about the time left stays.
+- A unit test that fails on a Tailwind class put together at run time (`max-sm:${x}`, `w-[${px}px]`).
+### Changed
+
+- `Toaster mode="auto"`: the clip that makes the toast come out from behind the docked edge was a
+  class assembled at run time (`max-sm:` + the rule), which is in no stylesheet, so below 640px the
+  toast slid in over the tab bar. It is written out whole now. Nothing to change in an app; an app
+  that carried the class itself as a stand-in can remove it.
+- A snackbar confirmation with nothing to press no longer has the time bar (see Added); pass
+  `timeLine` to bring it back.
+
+## [9.0.0-alpha.19] - 2026-10-08
+
+A nineteenth local preview build of the 9.0 direction, not published to npm. One
+entry from the app team (Z-104), about `CodeField`; no token, prop, variant,
+string key or export of alpha.18 is removed or renamed. One default changes where
+it was a defect, under Changed. Run on this build: the type and design checks,
+the unit suite, the package build and a scratch install; no browser.
+### Added
+
+- `CodeField` `groups?: number | number[]`: draws the boxes in groups with a wider gap
+  (`groups={4}` on 8 places is 4 and 4, `groups={[3, 3, 4]}` is explicit). Only the drawing:
+  one input, one value, `one-time-code`, the post and a paste of "1234 5678" or "1234-5678" are
+  unchanged, and a screen reader still hears one field. A row that cannot fit wraps between groups.
+- `CodeField` `size?: "sm" | "md" | "lg"` (default `"md"`, today's look): `sm` is a compact row, 44px tall.
+- Export of the type `CodeFieldSize`.
+
+### Changed
+
+- `CodeField` boxes no longer shrink below 1.15em of their own digit, so a digit is never wider than
+  its box at large text or a narrow screen (it overlapped the box edges at 200% text with eight
+  places); where the boxes would have been narrower the row now wraps (between groups when `groups`
+  is set). At 100% text nothing changes up to 9 places at 320px (10 at 360px); a longer code that is not grouped now wraps there instead of drawing slivers. A tap in the gap between boxes or on a second row now
+  puts the caret at the nearest box.
+
+## [9.0.0-alpha.18] - 2026-10-08
+
+An eighteenth local preview build of the 9.0 direction, not published to npm. It
+makes the toast work on a phone (the app team's Z-097 to Z-103). No token, prop,
+variant, string key or export of alpha.17 is removed or renamed, and a `Toaster`
+with no new prop looks and behaves as before, except for the four defect fixes
+under Changed. Run on this build: the type and design checks, the unit suite,
+the package build and a scratch install; no browser, no screen reader.
+### Added
+
+- `Toaster` `mode?: "stack" | "snackbar" | "auto"` (default `"stack"`, type `ToasterMode`): the
+  snackbar is one row of 52px (two lines at most), one at a time, its action beside its text, set
+  directly above what is docked at the bottom and sliding out from behind that edge on
+  `--ease-standard` (no overshoot, no movement under reduced motion). `"auto"` is the snackbar below
+  640px and the stack from there up.
+- `Toaster` `max` (how many show; the oldest timed toast leaves, never an error, one with an action or
+  a persistent one; 1 in the snackbar), `avoid` (a CSS selector for what the stack must not lie on)
+  and `swipeToDismiss` (default `true`).
+- The toaster finds a `BottomTabBar` or `StickyActionBar` (`data-bar-edge="bottom"`), a
+  `FloatingActionButton` and a dirty `UnsavedChangesBar` (new `data-toast-clear`) that lie under the
+  stack and sits above the highest, at any width.
+- `pushToast` and `ToastItem`: `closable?: boolean` (default `true`); `false` leaves the close button
+  out of a short timed toast, which then has no control and takes no taps. `pushToast` takes `id?`.
+### Changed
+
+- A mouse holds a toast's timer once it has moved over the toast, not when the toast arrives under a
+  pointer at rest (Z-098: it never closed). `mouseenter` and `pointerenter` alone no longer hold it.
+- A toast pushed with the id of one that is showing replaces it in place and restarts its time
+  (before, a second item with the same id was added, which a keyed list cannot have).
+- A touch or a pen swipe dismisses a toast (sideways; `swipeToDismiss={false}` turns it off). The close
+  button stays. The toast has `touch-action: pan-y`.
+- One line of text is centred on the buttons beside it; text that wraps stays at the top.
+- The words of a toast are put in its `role="status"` / `role="alert"` element about 100 ms after the
+  toast is mounted, so the live region is in the page empty first (Z-102). The server's markup has
+  them at once. Tests that read a toast's text right after `pushToast` need to wait for it.
+
+## [9.0.0-alpha.17] - 2026-10-08
+
+A seventeenth local preview build of the 9.0 direction, not published to npm. It
+finishes the `TopNavbar` sheet of alpha.16; no token, prop, variant or export of
+alpha.16 is removed or renamed, and no default changes. Run on this build: the
+type and design checks, the unit suite, the package build and a scratch install; no
+browser.
+### Changed
+
+- `TopNavbarStrings`: `menuTitle` (alpha.16) and the new `themeHeading` are optional in the
+  interface, with their defaults in `DEFAULT_TOP_NAVBAR_STRINGS` (now `Required<TopNavbarStrings>`).
+  Code that writes out a complete `TopNavbarStrings` object, as it could before alpha.16, type-checks
+  again; this repairs the note on alpha.16 that said it did not.
+- `TopNavbar` sheet: it grows with its content up to the full screen below the status bar, where
+  alpha.16 stopped at half of it, so eight links and the two sections below them do not scroll in
+  a short box. Choosing a theme or an accent does not close the sheet.
+### Added
+
+- `BottomSheet` `fitMax?: "half" | "full"` (default `"half"`): with `fit`, how tall the sheet may
+  grow before its content scrolls. Without it nothing changes.
+
+## [9.0.0-alpha.16] - 2026-10-08
+
+A sixteenth local preview build of the 9.0 direction, not published to npm. One
+behaviour change in `TopNavbar`, which you can turn off with one attribute; no
+token, prop, variant or export of alpha.15 is removed or renamed. Run on this
+build: the type and design checks, the unit suite, the package build and a
+scratch install; no browser.
+### Changed
+
+- `TopNavbar`: below `collapseAt` the menu button opens the links in a bottom sheet (`BottomSheet`,
+  `fit`) instead of the panel under the bar. The sheet is a modal dialog: focus moves in and back
+  to the button, Escape, the backdrop, the close button and a swipe down close it, the page behind
+  is locked, it is named by the new string `menuTitle` ("Menu"), and its links sit in a `nav` named
+  by `ariaLabel` (else `menuTitle`). Rows are full width and 44px; `actions`, the theme toggle, the
+  current-page mark and the new-tab note are as in the panel; a followed link, a `currentPath`
+  change and a wider screen close it. The menu button gets `aria-haspopup="dialog"`, and the bar no
+  longer takes the glass while the menu is open. **Opt out:** `menu="inline"` is the panel of
+  alpha.15 and earlier, unchanged. Without script the phone menu is as inert as before.
+- `TopNavbar` sheet, below the links: the `actions` and the theme choice have a section of their
+  own at the full width of the sheet. The built-in theme toggle is a segmented control there
+  (light / dark, or system / light / dark with `themeModes="three"`, 44px on a touch screen, words
+  from `themeLabels`, heading from the new string `themeHeading`, "Theme"); it writes the page
+  as `ThemeToggle` does, which stays as it was in the bar. Actions are laid out in a column at
+  full width. The docs site's `BrandSwitcher` is a labelled group of large rows in the sheet and
+  the small button in the bar.
+- `BottomSheet`: the slide-in is on the standard curve (`--ease-standard`) with no overshoot;
+  snapping between snap points and settling a drag keep `--ease-spring`.
+### Added
+
+- `getTopNavbarPlace()` and type `TopNavbarPlace` (`"bar" | "menu"`): a control in `TopNavbar`'s
+  `actions` calls it while it initialises to know whether it is in the bar or the sheet; the
+  snippet gets no argument. `"bar"` outside a bar and in `menu="inline"`.
+- `TopNavbar` `menu?: "sheet" | "inline"` (default `"sheet"`), exported type `TopNavbarMenu`, strings
+  `menuTitle` and `themeHeading` in `TopNavbarStrings` (code that writes out a complete
+  `TopNavbarStrings` object needs the new keys; `strings` itself is partial). Stories for both modes, catalog entry, docs, `?menu=inline`
+  on the chaos-lab page.
+
+## [9.0.0-alpha.15] - 2026-10-08
+
+A fifteenth local preview build of the 9.0 direction, not published to npm. One
+addition to `AppShell`, `AppShellHeaderPart`; no token, prop, variant or export of
+alpha.14 is removed or renamed, and no default changes. Run on this build: the type
+and design checks, the unit suite, the package build and a scratch install; no
+browser.
+### Added
+
+- `AppShellHeaderPart`: the consumer chooses what stays at the top. Put several in `AppShell`'s
+  `header` snippet, each with `sticky` (default `true`) or `sticky={false}` to scroll away with
+  the content: the bar can leave while a filter row stays, or a large title can go while the bar
+  and the tabs stay. Plain `position: sticky` in the scroller's flow, no scroll listener; the
+  stuck parts stack under one another in document order (a part that scrolls away in between
+  does not leave a gap), and the shell reports only what is stuck as `--app-shell-top-inset` and
+  `scroll-padding-top`. One glass surface and one hairline under the lowest stuck part; the
+  status bar is covered by whatever is topmost, also after the first part has gone. Stuck parts
+  may cover 40% of the scroller at most, the lower ones then scroll (`data-released`). A header
+  without parts and `AppBar collapseOnScroll` / `largeTitle` behave as before. `AppBar` now
+  carries `data-appbar`. Types: `AppShellHeaderPartProps`. Story, catalog entry and demo toggle.
+
+## [9.0.0-alpha.14] - 2026-10-08
+
+A fourteenth local preview build of the 9.0 direction, not published to npm. One
+entry from the app team (Z-096), a new component `CodeField`; no token, prop,
+variant or export of alpha.13 is removed or renamed, and no default changes. Run
+on this build: the type and design checks, the unit suite, the package build and
+a scratch install; no browser.
+### Added
+
+- `CodeField`: a field for a verification or one-time code (Z-096). One real `<input>`
+  (`autocomplete="one-time-code"`, `inputmode="numeric"`) under boxes drawn and hidden from
+  assistive technology, so the iPhone and Android code suggestion, paste of a whole code
+  ("123 456" and "123-456" too, with the caret anywhere) and one accessible name work, and the
+  form posts the code by `name` with scripts off, where the input is a plain bordered field.
+  `length` (1 to 12, default 6), `value` (bindable), `mode` (`numeric` default, `alphanumeric`),
+  `label` / `labelHidden`, `hint`, `error`, `variant` + `message`, `required`, `disabled`,
+  `readonly`, `oncomplete(value)` and `strings`; the words (`codeField.label`,
+  `codeField.description`) come from `ZabiStringsProvider`. Exports: `CodeField`,
+  `DEFAULT_CODE_FIELD_STRINGS`, types `CodeFieldProps`, `CodeFieldMode`, `CodeFieldStrings`.
+
+## [9.0.0-alpha.13] - 2026-10-07
+
+A thirteenth local preview build of the 9.0 direction, not published to npm. Two
+entries from the app team (Z-094, Z-095), both about `Skeleton`; no token, prop,
+variant or export of alpha.12 is removed or renamed, and no default changes: a
+lone `Skeleton` is the same status named "Loading…". Run on this build: the type
+and design checks, the unit suite, the package build and a scratch install; no
+browser.
+### Added
+
+- `SkeletonGroup`: one `role="status"` with the loading label for the `Skeleton` pieces
+  inside it, which are hidden from assistive tech, so a screen of eight pieces is announced
+  once. `Skeleton` takes `decorative` (no role, no label, `aria-hidden`) for a piece beside
+  a status of your own, and `strings` (`label`); the label reads the provider's
+  `skeleton.label` before the English "Loading…", and `aria-label` still wins. A lone
+  `Skeleton` is unchanged. (Z-094)
+- `Skeleton` takes `tone="on-color"`: the surface's label colour at 24% (`bg-skeleton-on-color`,
+  in `@layer utilities`), for the `on-brand`, `on-accent` and `on-fill` blocks and a `Card` with
+  `tone`, in light and dark; `--zabi-skeleton-fill` replaces it. The default `tone="neutral"` is
+  `bg-neutral-subtle` as before. And `lines` (1 to 20, text variant): one placeholder with that many
+  lines and a shorter last line (60%); `width` and `class` apply to the paragraph, `height` to each
+  line, and it is one status like a lone piece. (Z-095)
+
+## [9.0.0-alpha.12] - 2026-10-07
+
+A twelfth local preview build of the 9.0 direction, not published to npm. Five
+entries from the app team (Z-089 to Z-093); no token, prop, variant or export of
+alpha.11 is removed or renamed. Two defaults change what a consumer gets: a
+`RadioGroup` option with a description is named by its label alone, and a
+one-line option is centred in its row. Run on this build: the type and design
+checks, the unit suite, the package build and a scratch install; no browser.
+
+### Added
+
+- `Chip` takes `loading` on its button forms (`type="submit"`, `"button"` and the toggle):
+  `aria-busy` and `aria-disabled`, a spinner over the label, the press swallowed, the
+  width and the focus kept, as `Button`'s. A link and a `checkbox` / `radio` chip ignore it. (Z-091)
+- `Checkbox` and `Radio` take `error`, `variant`, `message` and `hint`, drawn under the
+  label as on `Input`: an error is an alert, sets `aria-invalid` on a checkbox and is
+  tied to the input with `aria-describedby` (after the hint). `Toggle` is unchanged. (Z-090)
+
+### Fixed
+
+- `Skeleton` no longer pulses under `prefers-reduced-motion`: it is a still fill
+  (`motion-reduce:animate-none`). A `motion-reduce:animate-pulse` class on the
+  skeleton brings the pulse back. (Z-093)
+- `RadioGroup`: an option's `description` is no longer part of the radio's name; it is
+  `aria-hidden` and tied to the radio with `aria-describedby`, as `Radio`'s. A one-line
+  option is centred in its row (44px on touch) and its circle loses `mt-0.5`; a row
+  with a description keeps the radio at the top. A radio found by its two-sentence
+  name is now found by its label. (Z-092)
+- `Select` no longer outgrows its container: a width class (`w-48`) in a narrower
+  column is capped at the column (`.select-container { max-width: 100% }`, in the
+  components layer, so a `max-w-*` class of your own still wins). (Z-089)
+
+## [9.0.0-alpha.11] - 2026-10-07
+
+An eleventh local preview build of the 9.0 direction, not published to npm. One
+fix for the app team's report Z-088; no token, prop, variant or export of
+alpha.10 is removed or renamed. Run on this build: the type and design checks,
+the unit suite, the package build and a scratch install, and one run in
+Playwright's WebKit (an iPhone 15 profile, not iOS Safari).
+
+### Fixed
+
+- `BottomSheet` no longer rises to the top of the screen as it opens on WebKit,
+  and no longer rests 32px above the bottom edge. The overlay root was
+  `overflow: hidden`, a scroll container, and WebKit scrolled it to the focused
+  grip while the panel was still below the screen; it is now `overflow: clip`.
+  The slide's own spring (a 15px overshoot at half) is unchanged. To restore the
+  old root: `overflow-hidden` for `overflow-clip` on the root in
+  `BottomSheet.svelte`.
+
+## [9.0.0-alpha.10] - 2026-10-07
+
+A tenth local preview build of the 9.0 direction, not published to npm. One
+addition for the app team's request Z-087; no token, prop, variant or export of
+alpha.9 is removed or renamed, and nothing an app shows changes without a
+change to its code. Run on this build: the type and design checks, the unit
+suite, the package build and a scratch install. Not run: Playwright or any
+look in a browser.
+
+### Added
+
+- `Avatar` `children`: a snippet drawn inside the circle in place of `src` and
+  the initials, for an inline SVG that reads the page's tokens. It is
+  presentational; `name` stays the accessible name, and the circle keeps its
+  size.
+- `AvatarGroup` people take `picture?: Snippet`, the same for one person.
+- A list row's `avatarPicture?: Snippet` (`ListItemData`): the same in the
+  row's round; wins over `avatar` and `icon`; decorative unless `avatarAlt`
+  names it.
+
+## [9.0.0-alpha.9] - 2026-10-07
+
+A ninth local preview build of the 9.0 direction, not published to npm. Two
+additions for the app team's request Z-086; no token, prop, variant or export
+of alpha.8 is removed or renamed, and nothing an app shows changes without a
+change to its code. Run on this build: the type and design checks, the unit
+suite, the package build and a scratch install. Not run: Playwright or any
+look in a browser.
+
+### Added
+
+- `RadioGroup` `chosenRing` (default `true`). `chosenRing={false}` leaves the
+  filled radio to show the chosen row: the row's own ring is gone, and keyboard
+  focus keeps its ring.
+- `Radio` `description`: a line under the label, tied to the radio with
+  `aria-describedby`; the label alone names the radio.
+
+## [9.0.0-alpha.8] - 2026-10-07
+
+An eighth local preview build of the 9.0 direction, not published to npm. Four
+additions for the app team's requests Z-082 to Z-085; no token, prop, variant
+or export of alpha.7 is removed or renamed. One default changes what an app
+shows without a change to its code: a `Select` in a sheet with up to six
+options and no search field gets a sheet as tall as its list; `sheetFit={false}`
+restores the half-height sheet. Run on this build: the type and design checks,
+the unit suite, the package build and a scratch install. Not run: Playwright or
+any look in a browser.
+
+### Added
+
+- `Chip type="submit"` (Z-082; D185): a button chip that posts its form with `name` and `value`, and does not toggle; `selected` is the app's and is drawn as on a toggle and said with `aria-pressed`. `type="button"` is the same without the submit. Without a `type` a chip is the toggle button it was.
+- `Select` options take `lang` (Z-083; D186): set on the option's row, on the trigger's text while it is chosen and on the native `<option>`.
+- `Select sheetFit`, `Dropdown sheetFit` and `BottomSheet fit` (Z-084; D187): a sheet as tall as its content, up to half the screen, with one resting height.
+- `Card type="submit" | "button" | "reset"` with `name`, `value`, `form` and `disabled` (Z-085; D188): the whole card is one `<button>`, drawn and pressed as a link card is, with the 44px minimum. With `href` it is still a link.
+
+### Changed
+
+- A `Select` shown in a sheet, with up to six options and `searchable={false}`, now gets a sheet as tall as its list instead of half the screen (Z-084; D187). Restore the half sheet with `sheetFit={false}`.
+
+## [9.0.0-alpha.7] - 2026-10-07
+
+A seventh local preview build of the 9.0 direction, not published to npm. One
+addition on top of alpha.6; no token, prop, variant or export is removed or
+renamed, and with the new properties unset every `Badge` renders as before.
+
+### Added
+
+- `Badge` neutral subtle fill and text (Z-081; D184): `--zabi-badge-neutral-fill` and `--zabi-badge-neutral-text`, declared nowhere and read in front of `--color-neutral-subtle` and `--color-neutral-text`. Set on any ancestor or in the theme, in light and dark, they move the neutral subtle `Badge` (`variant="neutral"` or `"default"`) and nothing else: `Alert variant="neutral"`, `Skeleton`, `AvatarGroup`, `Header` and the other badge variants keep reading the neutral tokens. New classes `bg-badge-neutral` and `text-badge-neutral` (`@layer utilities`), the first listed beside `bg-neutral-subtle` in the colour-block rules, so a badge in `on-brand`, `on-accent`, `on-fill` and `Card tone` is restored as before. Theme output gains only those lines.
+
+## [9.0.0-alpha.6] - 2026-10-07
+
+A sixth local preview build of the 9.0 direction, not published to npm; 8.1.0
+stays the stable version. New: the charts drawn in plain SVG (`LineChart`,
+`BarChart`, `PieChart`, `Sparkline`) and `SpeechBubble`. Extended: `Textarea`
+(`resize`, `autogrow`, `maxRows`), `ImageUpload` (`variant="button"`,
+`maxSize`), `ConfirmDialog` (`cancelVariant`). No token, prop, variant or
+export is removed or renamed. Four things change what an app shows without a
+change to its code, each with the line that restores the earlier look in its
+entry below: a dark form field is a well a step lighter than its surface; a
+dark flat `Card` is a translucent layer; a `Textarea` has no resize grip on a
+touch screen; `Input type="password"` has the show/hide button by default.
+Run on this build: the type and design checks, the unit suite, the theme
+tests, the package build and a scratch install. Not run: Playwright, an
+accessibility pass, any look in a browser at the changes since alpha.5 other
+than the charts.
+
+### Added
+
+- `ImageUpload variant="button"` (Z-076; D183): only the trigger, for a photo that is one choice in a row of others. A `Button` that opens the file chooser (`buttonVariant`, default `secondary`; `buttonSize`, default `md`; its text is `label`, or `children`), with `accept`, `onclick`, `onbrowse`, `onchange`, `onfileselect`, `bind:value`, `disabled`, the error block and the polite announcement as in the dropzone; no drop area, no preview, no Change or Remove. The default `variant="dropzone"` is unchanged.
+- `ImageUpload maxSize` (bytes), in both variants: a larger file, chosen or dropped, is not selected and goes to `onfilereject`, which now gets a second argument, `"type"` or `"size"`. Without `maxSize` nothing changes. The component had no size limit before.
+
+- `Textarea autogrow` and `maxRows` (Z-077; D181): the field grows with its content from `rows` up to `maxRows` rows and scrolls after that (no limit without `maxRows`). It uses `field-sizing: content` where the browser has it and measures the content elsewhere. An autogrow field has no resize grip.
+
+- `ConfirmDialog cancelVariant` (Z-080; D182): the cancel button's `Button` variant, any `ButtonVariant`. The default is `outline`, so nothing changes; `tonal`, `secondary`, `ghost` or `text` for an app that has no outline button. Cancel stays the first control and keeps the initial focus.
+
+- **Charts in plain SVG: `LineChart`, `BarChart`, `PieChart`, `Sparkline`** (Z-004; D156 to D159). The library draws its own charts and has no chart-library dependency; no dependency was added. The three charts are each a `figure` whose `figcaption` is the required `label` (`labelHidden` keeps it for assistive technology only); the drawing is hidden from assistive technology and the same numbers are in a real `table`, off screen unless `showTable`. They take the width of their container and are laid out in real pixels, so text is never scaled; before they are measured (on the server) they are drawn 600 wide and scaled to fit.
+  - `LineChart`: `series` (`{ name, points, color? }[]`; `null` in `points` leaves a gap), `xLabels`, `yMin`, `yMax`, `yFormat` (`'number'`, `'percent'` where 72 is "72 %", or a function), `height` (px, default 240), `legend` (default: on for more than one series), `markers` (default on: a different shape per series, so lines differ by more than colour), `xTitle`, `locale`, `glass`. Pointing at or tapping the plot shows the values at that x label in a pane of the thick material that floats over the plot beside the guide, as a `Tooltip` does; there is no keyboard route to that readout, the table is.
+  - `BarChart`: `data` (`{ label, value, color? }[]`), `color`, `yMax`, `yFormat`, `height`, `showValues` (default on), `categoryTitle`, `valueTitle`, `locale`. One set of upright bars from a zero line; values below zero are drawn downward.
+  - `PieChart`: `data`, `donut`, `center` (a snippet in the middle of the ring), `format`, `size` (px, default 192; shrinks with the container), `legend` (default on: each slice's label, value and share), `categoryTitle`, `valueTitle`, `shareTitle`, `locale`. Slices run clockwise from twelve o'clock in the order given and are parted by a thin cut, so they need no border colour; in a full pie the cut narrows to a point at the centre, so every slice runs to the middle.
+  - `Sparkline` (atom): `points`, `label` (an image by that name; without it, decoration), `color`, `min`, `max`. 5rem by 1.5rem unless `class` says otherwise.
+  - Colours: a series without a `color` takes `--zabi-chart-1` to `--zabi-chart-6` by its place; these are declared nowhere and fall back to steps of the library's own ramps: `--color-action-primary` (what a `Progress` fills with), `--color-accent-500`, `--color-brand-900`, `--color-accent-700`, `--color-base-500`, and for a sixth series a plum mixed from the brand and error ramps. None is a status colour. On the default theme each is 3:1 or more on a card in light and dark and any two differ for a reader who does not see red and green. `color` takes one of `primary`, `accent`, `success`, `warning`, `error`, `info`, `neutral`, or any CSS colour; in a chart that names one, a series without a `color` steps past the series colour nearest to it. In forced colours the marks are drawn in `CanvasText`.
+  - Built from the library's parts: the caption is set like a `Progress` label; a bar is a `Progress` fill stood on end (at most 24px wide, a round far end) and with a `yMax` each bar stands in a `Progress` track up to it, the values in a row over the tracks; grid lines are `--color-border` and the base line `--color-border-strong`; the `PieChart` key is set like `List` rows (name, value, share; parted in `--zabi-list-divider-color`) and takes the width beside the drawing, or the full width under it when the chart itself is narrower than 26rem; `showTable` shows the library's `Table`, numbers at the end of their column; a donut's ring is a third of the radius and takes a `center` snippet (a `Stat` fits); lines are 2px with 8px markers, each in a ring cut out of the lines so it shows whatever is behind the chart (`--zabi-chart-surface` paints the ring instead); a `Sparkline` ends in a dot on its last value. Chart text is 0.75rem with tabular numerals and the value axis is as wide as its widest label as drawn, so both follow the reader's text size.
+  - Glass marks: the slices of a `PieChart` and the bars of a `BarChart` are drawn as glass by default: the series colour, opaque, under the veil of a solid control, with one pixel of light on the top of the rim, a soft sheen under it and a soft shadow. No backdrop blur is involved (an SVG shape takes none), so it reads on a plain card too. Flat fills with reduced transparency, more contrast, forced colours and inside `data-materials="opaque"`. Line markers, key marks and the `Sparkline` dot stay flat.
+  - Glass panel: `glass` on `LineChart`, `BarChart` and `PieChart` stands the chart on a panel of the thick material (off by default: it needs a wash, a tint or a picture behind it, and on a plain card it shows only an edge and a shadow). It is the library's `material-thick`, so reduced transparency, more contrast, forced colours, no `backdrop-filter` and `data-materials="opaque"` make it the opaque surface. Over a solid brand or accent fill some series colours fall under 3:1 on it; THEMING.md has the numbers.
+  - Types `ChartSeries`, `ChartDatum`, `ChartColor`, `ChartColorName`, `ChartFormat` are exported. Not included: stacked or grouped bars, horizontal bars, areas, a second axis, zoom, animation.
+- **`SpeechBubble`** (Z-075; D155): a quotation in a bubble with a drawn tail. A `figure` whose `figcaption` is `label` (a string or a snippet; `labelHidden` keeps it for assistive technology only) and whose content is a `blockquote` with the children as real, selectable text. `side` (`end` default, `start`; follows the text direction) places the tail; `tone` is `ink` (default: the headline colour as fill and the page colour as text, so dark in light and light in dark) or `paper` (the two swapped, for a bubble on a filled block). `decoration` is a snippet drawn on the top corner of the tail's side. Four custom properties declared nowhere, set on the component or any ancestor: `--zabi-bubble-fill` and `--zabi-bubble-text` (win over `tone`), `--zabi-bubble-radius` (any `border-radius` value, the eight-value form included; default `1.5rem`) and `--zabi-bubble-tilt` (turns the fill and tail, not the text; default `0deg`). The tail is an inline SVG in the fill colour, sized in rem; tail, fill and decoration are hidden from assistive technology; in forced colours the bubble is a 2px outline and the tail is not drawn. The type is `text-lg font-medium` on the figure and can be replaced through `class`. Not included: a copy action and a speaker slot.
+
+### Changed
+
+- `Textarea` has no resize grip on a touch screen (Z-077; D181). New prop `resize`: `auto` (default: the browser's vertical grip with a mouse or trackpad, none where the pointer is coarse), `vertical`, `none`. On a phone the grip was 16px in the field's corner and dragging it scrolled the page. Desktop is unchanged. The earlier behaviour everywhere: `resize="vertical"`. A `resize-*` class passed in `class` still wins.
+
+- **In dark, a form field is a well of its own, not the page colour inside an edge** (Z-078; D180). `--color-input` in dark is a translucent step of the neutral ramp (base-50 at 7%; `-hover` 10%, `-focus` 7%, `-active` 15%) instead of the page step, so `Input`, `Textarea`, `Select`, `DateField`, `TimeField` and `PickerField` are a little lighter than whatever they sit on: 1.20:1 off the page, 1.22:1 off a card, 1.23:1 off a sheet on the default theme, with no rule per surface. Light is unchanged. The field edge (`--color-input-border`) is unchanged and stays 3:1 against the surface outside the field; against the lifted fill inside it is 3.05:1 on the page, 2.79:1 on a card and 2.50:1 on a sheet. The dark placeholder is a shade lighter (`#ababb3`, was `#a1a1aa`) to keep 4.5:1 on the lifted fill; on a pressed field in a sheet it is 4.08:1. New tokens, additive: `--color-input-solid`, `-solid-hover`, `-solid-focus`, `-solid-active`, the opaque field a colour block (`.on-brand`, `.on-accent`, `.on-fill`) uses, where a translucent fill would sit on the block's colour. New guard pairs in `check:contrast` and in `createTheme`'s check, dark only, laid over the page, a card and the overlay: the well against its surface (1.15:1), value and placeholder on every field state, the hover and pressed steps, the edge on the fill. `--color-surface-inset`, `--color-input-disabled` and the progress track are unchanged. Restore the earlier dark field: `overrides: { dark: { '--color-input': 'var(--color-surface-inset)', '--color-input-hover': 'var(--color-base-200)', '--color-input-focus': 'var(--color-base-150)', '--color-input-active': 'color-mix(in srgb, var(--zabi-base-50) 10%, var(--color-surface-inset))', '--color-input-placeholder': 'var(--color-base-600)' } }`.
+
+- `Input type="password"` has the show/hide button by default (`revealable` now defaults to `true`). Pass `revealable={false}` for a password field without it. Other types are unaffected.
+
+- In dark, `Card variant="flat"` is a translucent, slightly lighter layer (the neutral ramp's base-50 at 7%, hover 11%, pressed 15%) instead of the opaque card fill, so flat cards nested in each other, in a default card, an elevated card or a sheet each read a step lighter and stay visible. Light is unchanged: a light flat card computes to the same fill as before. New tokens `--color-card-flat`, `--color-card-flat-hover`, `--color-card-flat-active` (utilities `bg-card-flat`, `hover:bg-card-flat-hover`, `active:bg-card-flat-active`), settable through `createTheme` `overrides`. To keep the opaque dark fill: `overrides: { dark: { '--color-card-flat': 'var(--color-card)' } }`, and the same for `-hover` and `-active` (`var(--color-card-hover)`, `var(--color-card-active)`).
+
+### Fixed
+
+- `BottomSheet`: the panel's height no longer transitions while the sheet slides in (Z-079). The height transition is for snapping and for settling a drag; during the slide-in a late change of height rode the spring and moved the content after it had arrived. It is switched on when the slide has ended (at once under reduced motion). The slide itself and the snaps keep the spring.
+
+- `Input type="search"` with a clear button of its own in `trailing` no longer also shows the browser's clear cross in Chrome and Safari. A search field without `trailing` keeps the browser's.
+
+## [9.0.0-alpha.5] - 2026-10-07
+
+A fifth local preview build of the 9.0 direction, not published to npm; 8.1.0
+stays the stable version. It is the components the consuming app asked for.
+New: `Chip` and `ChipGroup` (a link, a toggle button or a real radio or
+checkbox input under one tonal selected style, in a wrap or a one-row layout
+that scrolls sideways), `Block` (the full-width colour section), `Stat`,
+`PickerField` (a field-shaped trigger for an app's own sheet). Extended: `Card`
+is linkable (`href`) and takes a `tone` or a custom `fill`; `Collapsible` is a
+native `<details>` and opens without scripts; `Progress` gets a 16px size, a
+segmented form and a track edge token; `Rating` a compact score, 40px stars
+and a soft empty state; `Heading` a display variant on a display typeface
+token; `Checkbox`, `Radio` and `Toggle` a `leading` snippet; `Alert` an edge
+that can be turned off and a brand variant; `DateField` and `TimeField` a
+`locale` with the library's own display and picker over the native input.
+No token, prop, variant or export is removed or renamed. Four things change
+what a consumer sees or gets without a code change, each listed under Changed
+or Fixed with what restores it where something does: the default
+`Collapsible` trigger is a `<summary>` instead of a `<button>`; a solid
+control in a colour block's own colour is inverted inside that block; a
+`Stepper` bar's upcoming segments are filled with the progress track; and the
+floating `BottomTabBar` is 72px tall with equal insets. Built quickly and
+tested lightly on purpose: the type and design checks, the unit run, the theme
+tests, the package build and a scratch install were run on it, and the new
+components' stories were looked at once in Storybook with headless Chromium in
+light and dark at phone and desktop widths (two things were fixed from that
+look). No browser suite was run, there was no accessibility or QA review, and
+nothing was tried on a real phone, in Safari or Firefox, without scripts in a
+real browser, at 200% text, right-to-left, in forced colours, or with a
+keyboard or a screen reader.
+
+### Added
+
+- **Chip tokens** (Z-051): `--color-chip`, `-hover`, `-active`, `-text` (a quiet neutral fill without an edge: `base-200` / `300` / `350` in light, `--zabi-base-750` / `700` / `650` in dark, the label is the headline colour) and `--color-chip-selected`, `-hover`, `-active`, `-text`, which default to the tonal role (`--color-action-tonal*`), so an app that themes tonal gets matching chips. Classes `bg-chip`, `hover:bg-chip-hover`, `active:bg-chip-active`, `text-chip-text`, `bg-chip-selected`, `hover:bg-chip-selected-hover`, `active:bg-chip-selected-active`, `text-chip-selected-text`. Label pairs guarded at 4.5:1 on all fills in both modes, in the library and in `createTheme`.
+- **`--color-card-tint`** (`bg-card-tint`; Z-055): the brand tint as a surface for content. `brand-100` in light, the brand at 8% over the card in dark. Text roles and the link are guarded on it at 4.5:1, the focus ring, the field edge and the outline-button edge at 3:1.
+- **`.on-fill`** (Z-055): the on-colour scope for a fill the app chooses. Like `.on-brand`, with the label colour taken from `--zabi-on-fill` (fallback `currentColor`): text roles, links, edges and focus rings inside take it, and a surface inside (a Card, a field, a Chip) gets the theme's roles back. The library cannot check the contrast of a colour picked at run time.
+- **`--color-progress-track-border`** (`border-progress-track-border`; Z-049): the edge of the Progress track, by default the field edge as before. `createTheme` writes `transparent` for a mode in which an overridden `--color-progress-track` itself reaches 3:1 against the page and the card and the app did not set the edge; an edge the app sets itself is never moved.
+- **`--font-family-display`** (`font-display`; Z-058): a second typeface as a token; follows `--font-family-heading` until set. `cn` knows `font-heading` and `font-display` as font families.
+- **`Checkbox`, `Radio` and `Toggle` take a `leading` snippet** (Z-060; D145): drawn inside the one `<label>`, between the control and the label text (an avatar in an attendee list), so a press on it toggles the control. The accessible name stays the `label` string; give a leading image an empty alt. Without `leading` the markup is unchanged.
+- **`Chip`** (Z-051; D144): one pill, four forms. With `href` it is a link (`selected` sets `aria-current`, `current` picks its value) and works without scripts; with `type="checkbox"` or `type="radio"` it is a real input inside a label, which submits in a form without scripts and whose selected look follows the native `:checked`, so a choice made before hydration shows at once and is kept; otherwise it is a toggle button with `aria-pressed`. One selected style in every form and both modes: the tonal fill and label (`--color-chip-selected*`) and a semibold label, no outline and no solid fill; a system-colour outline in forced colours. Props: `selected` (bindable), `size` (`sm` 28px, `md` 32px, `lg` 40px; a 44px target on coarse pointers without growing the box), `leading`, `checkmark` (a check while selected; on for a checkbox and a toggle button, off for a link and a radio), `disabled`, `name`, `value`, `required`, `form`, `onchange`. A repeat press on the selected radio chip does nothing; a checkbox or toggle chip turns off.
+- **`ChipGroup`** (Z-051, Z-059; D144): `layout="wrap"` (default) or `layout="row"`, one line that scrolls sideways without a scrollbar, with the chosen chip brought into view on load (only the row scrolls; `scrollSelectedIntoView={false}` turns it off) and an edge cue, `edge="fade"` (default: a mask on a side that has more chips beyond it, so it works on any background; none on the server or before hydration) or `edge="none"`. `label` (or `aria-label` / `aria-labelledby`) names the group, `showLabel` shows it. With `type="radio"` or `type="checkbox"`, `name` and `value` (bindable; a string, or an array for checkboxes) the chips inside are inputs that take only a `value`. A `ChipGroup` inside a `ChipGroup` is a named sub-group in the same row or wrap, with a wider gap (24px) between sub-groups.
+- **`Progress size="xl"`** (16px) and **`Progress segmented`** (Z-049; D147): `segmented` draws `max` separate segments with `value` of them filled, for a count such as 4 of 19 (`max` a whole number from 2 to 24; any other `max` draws the continuous bar and warns in a dev build). Still one `role="progressbar"`, with `aria-valuetext` from the new string `progress.valueText(value, max)` ("4 of 19"; set it once in `ZabiStringsProvider` or per instance with `strings`), and with `label` the read-out is that text instead of the percent.
+- **`Card href`** (Z-042; D146): the card itself is an `<a>` (with `target`, `rel`), so the whole card is the link and it works without scripts: focus ring on the card edge, hover and pressed states, a 44px minimum, the content keeps the body colour. A link card must not hold other interactive elements.
+- **`Card tone`, `fill` and `onFill`** (Z-055; D146): `tone="neutral"` (default, unchanged), `"tint"` (`--color-card-tint`), `"brand"` (the primary fill with the `on-brand` scope) or `"accent"`; `fill` with `onFill` is a colour the app chooses with its label colour (the new `on-fill` scope; the app holds that pair to 4.5:1, the library cannot check it). A toned card has no border and no shadow (unless `variant="elevated"`). Text, links, outline and ghost buttons, edges and focus rings inside take the fill's label colour; a neutral Card, a field or an Alert inside is a surface with the theme's colours again. An interactive toned card shows hover and pressed as a veil of its own text colour.
+- **`Block`** (Z-055; D146): the full-width, square-cornered colour section, with the same `tone`, `fill` and `onFill`, `padding` (`none`, `sm`, `md`, `lg`) and `as` (`div`, `section`, `header`, `footer`, `article`, `aside`). It does not break out of a padded parent by itself: place it outside the padded container or give it a negative inline margin through `class`.
+- **`Rating compact`** (Z-054, Z-066; D149): a score for a list, not a control: one filled star and the number ("4,0", through `formatValue`), from the real `value` and `max`, as one image with one accessible name ("4 of 5 stars", the readonly string). It implies `readonly`. Sizes `sm` (14px), `md` (16px), `lg` (20px), `xl` (28px star, 30px number) and `display` (40px star, 48px number in the display face).
+- **`Rating size="xl"`** (40px stars, for a large input) and **`Rating empty="soft"`** (Z-054; D149): an empty star as a soft filled shape with no outline, in `--zabi-rating-off-fill` (falls back to `--color-control-track`; declared nowhere, set it on any ancestor). The soft fill is below 3:1 against the page by default, so it suits a rating with a visible label and value; in forced colours it is an outline. The default stays `empty="outline"`.
+- **`Stat`** (Z-058; D150): a figure with a label. `value`, `label`, `unit` (after the value, smaller, on the same baseline: `value="4" unit="av 19"`), `size` (`sm` 24px, `md` 36px, `lg` 48px), `align`, `labelPosition` (`below`, `above`), or children for a figure that needs markup. The value is in the display face with tabular figures; plain text in reading order, no role.
+- **`Heading variant="display"`** (Z-058; D150): the display face (`--font-family-display`) with its own steps: 60px (48px below `sm`), 48 (36), 36 (30), 30, 24 and 20px by `size ?? level`, balanced wrapping. Its weight and tracking are two custom properties declared nowhere, shared with `Stat`: `--zabi-display-weight` (default 700) and `--zabi-display-tracking` (default -0.02em). So a second typeface is three properties on any ancestor and no CSS rule. `variant="heading"` (default) is unchanged.
+- **`Alert bordered`, `--zabi-alert-border-width` and `Alert variant="brand"`** (Z-072; D152). `bordered={false}` makes the edge transparent (the box keeps its size); the edge's width reads `--zabi-alert-border-width` (default `1px`, declared nowhere), so `--zabi-alert-border-width: 0px` on `:root` or any ancestor removes the edge from every Alert under it with no prop. `variant="brand"` is the theme's brand tint (`--color-action-primary-subtle`, edge `--color-action-primary-border`, icon in the link colour), with `role="status"`. `variant="neutral"` already existed. The default Alert is unchanged.
+- **`PickerField`** (Z-071; D151): a field-shaped trigger that opens whatever the app gives it (its own sheet with search, a page). It looks and measures like a `Select` of the same `size`, with `label`, `hint`, `error` (and `variant` / `message`) wired as on the other fields, `value` (the text of what is chosen), `placeholder`, a `leading` snippet, children for a rich value, and a chevron. It is a `<button aria-haspopup="dialog">` named by the label and the value (`haspopup`, `expanded` and `controls` set the ARIA attributes), `bind:element` hands the app the trigger to return focus to, and `name` with `formValue` submit the chosen id through a hidden input. With `href` it is a link, for a picker that is a page and works without scripts.
+- **`DateField` and `TimeField` take a `locale`** (Z-053; D153). Without it nothing changes. With it, the server and the page before hydration still render the native `<input type="date|time">` (the fallback without scripts; it submits as before). Once the page runs, the native input stays as the form control, out of sight, and a field-shaped button takes its place in the same box, showing the value in the app's locale through `Intl.DateTimeFormat` ("10 nov. 2026", "18:30", never the browser's own format), with `format` (the `Intl` options, for "tis 6 okt") and `placeholder`. Pressing it opens the library's picker in a `BottomSheet` titled by the label: the `Calendar` for a date (choosing a day sets the value, closes and returns focus; `min` and `max` are honoured), and two listbox columns, hours and minutes, for a time (hours labelled as the locale writes them, minutes every `step`, 5 minutes without one, a value off the step kept as its own option; Done commits). Clear is offered when the field is not `required`. `picker="native"` keeps the locale display and opens the platform's picker with `showPicker()` instead (and a `step` under a minute does the same); where that is refused the native input comes back. `input` and `change` fire on the native input for a value set by the picker, and a `required` empty field moves focus to the button instead of showing a bubble on a hidden control. New strings `dateField` and `timeField` (`clear`, `done`, `hours`, `minutes`, `chooseDate`, `chooseTime`) through `ZabiStringsProvider` or `strings`. The sheet is used at every width in this build. `PickerField` gains a `trailing` snippet that replaces its chevron.
+
+### Changed
+
+- **`Collapsible` opens without scripts** (Z-041; D143). With the default trigger (`title`) it is now a native `<details>` / `<summary>`: it opens before hydration and for a visitor without scripts, a toggle made before hydration is kept, find-in-page opens it, and a single-open `CollapsibleGroup` gives its panels a shared `name` so the browser keeps them exclusive too. Markup change: the default trigger is a `<summary>` (it keeps `id`, `data-collapsible-trigger` and `triggerClass`), not a `<button>` with `aria-expanded`, the heading of `headingLevel` is inside it, and the panel is no longer `hidden` while closed (a form inside a closed panel keeps its values and still submits them, as before). A test that looked for `role="button"` needs the summary instead. A `disabled` panel has `aria-disabled` and leaves the tab order. With a custom `trigger` snippet nothing changes, and that path still needs scripts. No prop is added or removed.
+- **`Progress` reads its track edge from `--color-progress-track-border`** (class `border-progress-track-border`, was the hard-coded `border-input-border`; Z-049). The default value is the same field edge, so nothing moves until the token is set (or `createTheme` sets it to `transparent` for a track that reaches 3:1 on its own).
+- **`Stepper`, bar layout: an upcoming segment is a filled track** (Z-050; D147): fill `--color-progress-track`, edge `--color-progress-track-border`, instead of a hollow `--color-control-border` outline. With the default tokens it looks nearly as it did (the field fill inside the field edge); an app that themes the progress track gets a filled, edgeless track. Restore the 8.1 outline on any ancestor: `--zabi-stepper-upcoming-fill: transparent; --zabi-stepper-upcoming-edge: var(--color-control-border)`.
+- **A solid control in the block's own colour is inverted inside a block** (D148). Inside `.on-brand`, `.on-accent` and `.on-fill` (so inside `Card tone="brand"`, a brand `AppBar`, or a block an app already marks), an element with `bg-action-primary` on a brand block (a primary `Button`, a solid brand `Badge`, a checked `Checkbox`), or with `bg-accent` on an accent block, was the same colour as the block; it now takes the block's label colour as its fill and the block's colour as its text, with hover and pressed mixed from the two, and a filled `Rating` star takes the label colour. A surface inside the block restores the theme's values. Outside a block nothing changes.
+- **`AppBar`: the row's fixed pixel scale is documented** (Z-074) on the `leading` and `actions` props: the row sets `--spacing: 4px`, so content placed there should be sized on it (`size-9`, or `calc(var(--spacing) * 9)`), not in rem, or it grows at 200% text while the bar's own controls do not. No behaviour change.
+
+### Fixed
+
+- **The floating `BottomTabBar` capsule is concentric with its tabs** (D154): the tabs sat 8px inside the capsule at its ends but 4px above and below, under a 28px corner. They now sit the same distance inside on all four sides (the list's gap: 8px, less in a very narrow bar), and the capsule's radius is the tab's 20px plus that distance, so outer radius = inner radius + padding holds at every width. The floating bar is 72px tall (was 64px); `--app-shell-bottom-inset` follows, it is measured. The edge-to-edge bar is unchanged.
+- **`Alert`: the close button's radius follows `--zabi-alert-border-width`**, so it stays concentric with the alert when the edge is set to `0px`.
+- **The active tab's forced-colours outline is the system highlight colour** in `BottomTabBar` and `AppNavigation`: the class `forced-colors:outline-(color:Highlight)` was never emitted (that form is for custom properties), so the outline fell back to the text colour. It is `forced-colors:outline-[color:Highlight]` now. `ring-(color:--color-bar)`, the ring around a tab's count, was checked in the built stylesheet and is emitted.
+- **`TimeField` picker: the chosen minute is in view and the chosen row is legible** (found in the look at this build): the columns centred their chosen row from `offsetTop`, which counts from the sheet, so only the focused hours column was right; and the chosen row's label kept the body colour on the primary fill in light. Both corrected before the build was packed.
+- **Storybook: `Heading / All levels`, `Display` and `Display with own face` render** (they passed a string as a component), and the `Stat` row on a brand block wraps on a phone.
+
+## [9.0.0-alpha.4] - 2026-10-06
+
+A fourth local preview build of the 9.0 visual direction, not published to npm;
+8.1.0 stays the stable version. It is dark mode on its own terms: the dark
+surfaces are steps of the neutral ramp, so a tinted neutral keeps its hue and
+chroma on every level, in two tone steps, with overlays set apart by a rim and
+a shadow instead of by grey; the primary and danger buttons keep their colour
+in dark under a white label; the dark status tints are low-chroma tints of the
+card; and dark sheets, menus and bars show glass again, because the dark
+material dims what is behind it. Light does not change, with one exception:
+the light thick material is 88% instead of 86%. `createTheme` gains
+`darkPrimary`, now checks the material pairs it was silently skipping (a theme
+may get a warning it did not get before), and keeps the ramp's ink in the mode
+an override did not name. AppShell gains `flushTop` and AppBar a fourth tone,
+`inherit`; `cn` merges the named spacing steps. No token, prop, variant or
+export is removed or renamed; `tokens/surface-ladder.js` (not a published
+file) exports steps instead of wash alphas. Several dark defaults change what a
+consumer sees, and each has a line that restores the earlier look. Built
+quickly and tested lightly on purpose: the type and design checks, the unit
+run, the theme tests, the package build and a scratch install were run on it,
+and the shell, Card, Alert, Badge, Button, Progress, Toggle, SegmentedControl,
+Select, Modal and BottomSheet stories were looked at once in Storybook in dark
+and light at phone and desktop widths. No browser suite was run (the library's
+Playwright specs will need updating for the new looks), there was no
+accessibility or QA review, and nothing was tried on a real phone, in Safari or
+Firefox, at 200% text or with a keyboard.
+
+### Added
+
+- **`AppShell flushTop`** (Z-065; D140): without a `header`, the content no longer gets the top safe-area padding, so a colour block at the top of a tab screen runs under the status bar and the content handles the safe area itself (`--app-shell-top-inset` keeps its value; an `AppBar position="static"` in the block pads by it). Default `false`; with a `header` it does nothing.
+- **`AppBar tone="inherit"`** (Z-067; D140): a bar inside a block that is not the primary colour. No fill of its own, never the glass or the hairline, and the title, back control, ghost actions, links, borders and focus rings take the text colour the block gives (the `on-brand` scope with `--color-on-brand: currentColor`). A sticky bar that must cover scrolling content takes its fill from the app: `class="[--color-bar:var(--your-block-colour)]"`. Contrast inside the block is the app's to check. Story: "Design System/Organisms/AppShell (9.0) / Colour Block Under Status Bar".
+
+### Changed
+
+- **Dark surfaces are steps of the neutral ramp** (Z-044; D133, D134). `--color-surface-raised` is `var(--zabi-base-850)` (`#1f1f22`, was a 6.4% white wash, `#262629`), `--color-surface-elevated` and `--color-surface-overlay` are both `var(--zabi-base-800)` (`#27272a`; were `#363638` and `#454547`), `--color-surface-overlay-hover` is `var(--zabi-base-750)` and `--color-surface-inset` (and so `--color-input`) is the page step, `var(--zabi-base-900)`. The page does not move. Two tone steps in all (OKLCH L 21.0, 24.1, 27.4), and with a tinted neutral every surface keeps the ramp's hue and chroma instead of greying as it rises. An overlay is no longer a lighter grey than a card: it is set apart by its rim (`--color-material-rim`, 12% to 14% of `--zabi-base-50`: 1.85:1 on the page, 1.72:1 on a card, 1.56:1 on the overlay) and a stronger dark shadow (`--shadow-opacity` 0.24 to 0.5, `--shadow-opacity-contact` 0.3 to 0.4). What follows the ladder in dark: `--color-border` and `--color-border-weak` are `base-250` (`#333338`: 1.41:1 on the page, 1.31:1 on a card; a quieter hairline than before), `--color-progress-track` is `base-250` (the field is the page colour now), `--color-input-disabled` is `base-75`, `--color-segment-thumb` is `base-400`, `--color-card-active` and `--color-surface-4` are the overlay hover step. Light is unchanged. Restore the 8.1 dark ladder: `overrides: { dark: { '--color-surface-raised': 'color-mix(in srgb, var(--zabi-base-50) 6.4%, var(--zabi-base-900))', '--color-surface-elevated': 'color-mix(in srgb, var(--zabi-base-50) 13.1%, var(--zabi-base-900))', '--color-surface-overlay': 'color-mix(in srgb, var(--zabi-base-50) 19.7%, var(--zabi-base-900))', '--color-surface-inset': 'var(--color-base-150)', '--color-border': 'var(--color-base-200)', '--shadow-opacity': '0.24', '--shadow-opacity-contact': '0.3' } }`.
+- **The primary action keeps the brand hue in dark** (Z-043; D135). The dark primary was the mirrored pale step (`--color-brand-600`, physical step 400) with a dark label; it is now the same physical steps as light, `--color-action-primary: var(--zabi-brand-600)`, `-hover: var(--zabi-brand-700)`, `-active: var(--zabi-brand-800)`, with the light label: `--zabi-on-brand-dark` defaults to `var(--zabi-on-brand)` (white; was `var(--zabi-brand-950)`). White on step 600 is 4.76:1 or more on any ramp; the default fill is 3.65:1 on the dark page, 3.39:1 on a card and 3.07:1 on an overlay. Everything that reads the primary follows: checked Checkbox, Radio and Toggle, the Progress fill, Stepper, the solid brand Badge, the FAB, the brand AppBar. Danger does the same (`--color-action-danger: var(--zabi-error-600)`, 700, 800, label `var(--zabi-error-50)`), so a destructive button is one red in both modes. The focus ring, links, the brand tints, the tonal button and the active navigation fills stay on the mirrored ramp: they are text, rings and tints on a dark surface. With the fill a mid step under a white label, the dark control veil is darken-only as in light (`--gradient-control-top-strength: 0%`, `-bottom-strength: 14%`; were 22% and 6%); the accent keeps 22% and 6% in its own strengths, because its dark fill is still the light step under a dark label. `--color-progress-track` in dark is `base-75` (`#101013`, a well just below the page) so the mid-step fill holds 3:1 on it. Restore 8.1 in one option: `createTheme({ darkPrimary: 'mirror' })` (CLI `--dark-primary mirror`); without the generator, set the three fills to `var(--color-brand-600 | 700 | 800)`, `--zabi-on-brand-dark: var(--zabi-brand-950)` and the two strengths under `.dark`.
+- **`createTheme({ darkPrimary })`** (Z-043): `'brand'` (default, what the library does, nothing extra written) or `'mirror'` (the 8.1 dark fills for primary and danger, the label chosen by the contrast check, the 22% / 6% veil, written under the dark selectors). A `dark` or `both` override of a role wins over both. In dark the label tried first is now white (the ramp's dark end if white fails, so a pale dark primary of the app's own keeps a dark label). With `pin`, a colour that fails in dark falls back to what this option gives, which is step 600 with white by default. An app that overrides `--color-action-primary` for both modes with a semantic step keeps its mirrored dark primary; move the override under `light` to get the brand step in dark.
+- **Four more guarded pairs**: the primary fill and the danger fill against the page and against a card, 3:1, both modes (until now only a pinned colour was held to this).
+- **Dark status tints are low-chroma tints of the card** (Z-057; D136). `--color-success-subtle`, `--color-warning-subtle`, `--color-error-subtle`, `--color-info-subtle`, `--color-energetic-subtle` and `--color-accent-subtle` were the mirrored step 100 (physical 900: the dark error surface was `#660002`); each is now `color-mix(in srgb, var(--zabi-<ramp>-500) 16%, var(--color-surface-raised))`, and the matching `-border` the same mix at 36%. `--color-action-danger-subtle` is the error tint, its hover the mix at 20% and its pressed step at 32%. The hue stays in the icon and the text, which did not move. Light is unchanged. Restore 8.1 per family: `overrides: { dark: { '--color-error-subtle': 'var(--color-error-100)', '--color-error-border': 'var(--color-error-200)' } }`.
+- **Alert's status icon is drawn at stroke 2.5** (was lucide's 2), in both modes, so it holds its weight beside the text.
+- **Dark materials show glass again** (D137). Dark sheets, menus and modals were 98% opaque, because faint text had to hold 4.5:1 over a white backdrop. The dark backdrop filter now also dims what is behind the glass: new token `--material-backdrop-brightness` (`1` in light, an identity; `0.6` in dark), and the three `--material-filter-*` tokens end in `brightness(var(--material-backdrop-brightness))`. The brightest thing behind dark glass is therefore near-white times 0.6, and the contrast guard measures the fill over that dimmed backdrop (material pairs only; every fallback that removes the filter also makes the fill opaque, so the rule is what a browser paints). Dark alphas re-solved on it: `--material-alpha-thin` 66% to 60%, `--material-alpha-regular` (bars) 76% to 68%, `--material-alpha-thick` 98% to 72% (floors 30, 47 and 68). No text role moved and the thick material still carries all five. Restore the 8.1-like opaque dark overlays: `overrides: { dark: { '--material-alpha-thick': '98%', '--material-backdrop-brightness': '1' } }`, or `data-materials="opaque"`.
+- **`createTheme` now checks the material pairs** (D138). The generator's data did not carry `--material-alpha-*`, so every "text on a material" pair was skipped without a word: a theme reported "all 278 role pairs pass" and the same input now checks 354. An app whose text or surface overrides make glass unreadable over the worst backdrop gets a warning it did not get before; the fix is the alpha of that level for that mode, for example `overrides: { light: { '--material-alpha-thin': '68%' } }`. `--material-alpha-*` and `--material-backdrop-brightness` are honoured per mode in the check.
+- **Light `--material-alpha-thick` is 88%** (was 86%), found by that check: with a strongly tinted neutral (`neutralChroma: 0.08`) the caption on a light sheet over a black backdrop was 4.47:1 at 86%. Neutral hues at chroma 0 to 0.1 now pass. Restore: `overrides: { light: { '--material-alpha-thick': '86%' } }`.
+- **The dark half of the surface elevation guard is a new rule** (D134), because the old one (four levels, each 5 to 8 lightness points above the last) described the old design. Now: every dark surface role is declared as one step of the neutral ramp, not a mix; lightness never falls from page to overlay and the card is lighter than the page; at most two tone steps above the page, each 2 to 5 OKLCH L points, the top within 8; the overlay rim reaches 1.5:1 against the page and the card and 1.3:1 against the overlay; the card edge reaches 1.2:1 against the page and the card, as in light. `tokens/surface-ladder.js` exports `SURFACE_STEP` in place of the wash alphas.
+- **The field edge is guarded on the elevated and overlay surfaces too**, in both modes (`--color-input-border` at 3:1; a field in a sheet or a modal). Two more guarded pairs in `createTheme`'s check.
+
+### Fixed
+
+- **`cn` knows the named spacing steps** (Z-064): `xs`, `sm`, `md`, `lg`, `xl` and `2xl` (`--spacing-*`) are registered with the class merger as spacing values, so a call-site `p-sm` beats a component's `p-xs`, and the same for margin, gap, inset and the other spacing groups. Until now `p-xs p-sm` kept both classes and the stylesheet order picked the padding. `3xl` is not registered: the library has no `--spacing-3xl`.
+- **`createTheme`: an ink role overridden in one mode keeps the ramp's ink in the other** (Z-061). With `neutralChroma`, a role such as `--color-action-secondary` set under `overrides.light` alone got the library's grey `rgba(250, 250, 250, 0.09)` under the dark selectors; it now gets the tinted `color-mix(in srgb, var(--zabi-base-50) 9%, transparent)` that the option derives, as it does without the override. The same holds the other way: a role set under `overrides.dark` alone keeps the tinted mix in light (it fell back to the library's grey there). Roles: `--color-action-secondary` (and `-hover`, `-active`), `--color-surface-hover`, `--color-surface-active`, `--color-border-overlay`, `--shadow-color`. An app that restated the dark mixes as a workaround can delete them; to keep the old grey in the other mode, set it there.
+
+## [9.0.0-alpha.3] - 2026-10-06
+
+A third local preview build of the 9.0 visual direction, not published to npm;
+8.1.0 stays the stable version. It is the redesign of the shell: AppBar,
+BottomTabBar, StickyActionBar and TopNavbar are flush with the page and turn to
+glass once content scrolls under them; the AppShell footer lies over the
+scroller; the active tab loses its outline; the sidebar and the top navbar have
+one active indicator, sentence-case headings and tighter rows; AppBar gains a
+large title that condenses and a brand tone; IconButton gains a count; and
+AppShell gains a `navigation` slot that is tabs, a rail or a sidebar by
+breakpoint, with `AppNavigation` as its ready-made content. No token, prop,
+variant or export is removed or renamed; several defaults change what a consumer
+sees, and each has a line that restores 8.1 where one exists. Built quickly and
+tested lightly on purpose: the type and design checks, the unit run, the theme
+tests, the package build and a scratch install were run on it, and the new
+shell stories were looked at once in Storybook (light and dark, at phone, tablet
+and desktop widths, at rest and scrolled). No browser suite was run (the
+library's Playwright specs will need updating for the new looks), there was no
+accessibility or QA review, and nothing was tried on a real phone, in Safari or
+Firefox, at 200% text or with a keyboard. Dark mode is still not art-directed.
+
+### Added
+
+- **Bar tokens** (Z-045; D124): `--color-bar` (a bar's fill at rest, default `var(--color-surface-chrome)`), `--color-bar-border` (the hairline a bar shows once content is under it: the headline colour at 10%), `--color-bar-brand` (the fill of an on-brand AppBar, default `var(--color-action-primary)`) and `--color-tabbar-active` (the active tab's pill, default `var(--color-nav-menu-active)`; Z-046). All four are restated in dark and settable through `createTheme` `overrides` per mode. Classes `bg-tabbar-active`, `bg-bar-brand`, `border-bar`. Guarded pairs: the active tab label on its pill, on-brand text on the brand bar, the headline on a bar at rest.
+- **`.material-bar`**: the surface of a bar. A `::before` layer paints `--color-bar` at rest and, when the element has `data-scrolled-under="true"`, the regular material with a 1px `--color-bar-border` hairline on the content side (`data-bar-edge="bottom"` puts it on the top edge). The element itself has no `backdrop-filter`, so a Dropdown or Tooltip in a bar is still placed against the screen. Under the opaque fallbacks a scrolled bar is the page colour with the hairline.
+- **`.material-layer-regular`**: the layer form of the regular material, as `.material-layer-thick` is for the thick one, for a floating bar that holds controls.
+
+- **`BottomTabBarItem.activeIcon`** (Z-046): drawn instead of `icon` on the active tab, typically the filled form. Without it the same icon is drawn with a heavier stroke (2.5) when active; `BottomTabBarIcon` now also accepts `strokeWidth`.
+- **`BottomTabBar floating`** (D126): the bar as a rounded glass capsule inset 12px from the screen edges, always on the regular material. Default `false`.
+- **AppShell `navigation` slot** (D101-S, D130): `navigation?: Snippet<[{ placement: "tabs" | "rail" | "sidebar" }]>` and `navigationPlacement?: "auto" | "tabs" | "rail" | "sidebar"` (default `"auto"`). One navigation, rendered once and first in the DOM, placed by CSS: tabs over the bottom of the screen below 48rem (768px), a rail from 48rem and a sidebar from 64rem (1024px) as a full-height column at the inline start; a forced value applies at every width. The server render is right without scripts. The host carries `data-navigation-placement`; `--app-shell-bottom-inset` counts the tabs (and a `footer`, which then sits directly above them); new `--app-shell-start-inset` is the rail's or sidebar's width (`0px` as tabs), mirrored on `<html>` with the other two. `footer`, `header` and `children` work as before, and a shell without `navigation` renders the markup it always did. Types `AppShellNavigationPlacement`, `AppShellNavigationMode`, `AppShellNavigationContext` and the constants `APP_SHELL_RAIL_MIN_WIDTH`, `APP_SHELL_SIDEBAR_MIN_WIDTH`.
+- **`AppNavigation`** (new organism; D130): the ready-made content for the slot. Takes the `BottomTabBar` item list (`items`, `active`, `label`, `badgeLabel`, `badgeMax`, `floating`) and draws it as a BottomTabBar, an 80px rail (icon in the tab pill over a label) or a 256px sidebar (36px rows, icon before the label, count at the end, one tinted active indicator), by CSS alone; `header` and `footer` snippets go above and below the list in the side forms. Outside a shell it is the tab bar.
+- **Stories**: `Design System/Organisms/AppShell (9.0)` shows the redesigned shell as a phone, a phone with floating tabs, a tablet rail, a desktop sidebar, adaptive, and with a brand bar. The prototype story stays beside it.
+- **`AppBar largeTitle`** (Z-045; D128): the title large (30px bold, capped at 39px, two lines at most) on a second row under the 56px bar. The large row scrolls away with the content, with no scroll-linked animation; the bar stays and shows the title small once the large one has gone under it. The heading element is the large title; the small one is hidden from assistive technology. In an AppShell, `--app-shell-top-inset` is the condensed height. `collapseOnScroll` is ignored with it (a dev build warns). Before the bar is measured, and without scripts, the whole header sticks with the large title in view.
+- **`AppBar tone`** (Z-045; D129): `"default"`, `"transparent"` (no fill at rest, glass once content is under it: for a canvas, an image or a colour block behind the bar) or `"brand"` (`--color-bar-brand` with on-brand text and controls, opaque at rest and scrolled, no hairline, so a brand block directly under the bar joins it). The header carries `data-tone`.
+- **`AppBar position`** (Z-067): `"sticky"` (default) or `"static"` for a bar in the flow of the page, inside a block of the content: it scrolls away with the block and is never glass. `class="static"`, the 8.1 way to say this, is read as `position="static"` (the bar is `relative`, because the material's layer is placed against it).
+- **`IconButton count`, `countLabel`, `countMax`** (Z-056 part 1; D131): a count in the attention colour drawn inside the button's own box, in its upper end corner, so a bar or an `overflow` ancestor cannot cut it. `99+` above `countMax` (default 99); a dot at `xs` and `sm`; nothing for 0 or while loading. The accessible name is the `label`, a comma and `countLabel(count)` (default "3 new").
+- **`scrollEdge`** on AppBar, BottomTabBar, StickyActionBar and TopNavbar (D123): `"auto"` (default: flush at rest, glass and a hairline once content is under the bar), `"always"` or `"never"`. Each bar writes `data-scrolled-under="true|false"` on its root (`"false"` on the server).
+- **`AppShell canvas`** (D125): paints the shell with `bg-canvas` (the page colour with the brand wash) and lets the header bar rest transparent over it. Default `false`.
+- **AppShell scroll state**: `data-scrolled-top` and `data-scrolled-bottom` on the host, and `--app-shell-footer-overlay` on the scroller (the bottom inset when a footer lies over it, else `0px`). `getAppShell()` in `util/app-shell` gives a component inside a shell the same state; `util/scroll-edge` (`watchScrollEdge`) is the helper for a bar on its own.
+
+### Changed (visible in 9.0)
+
+- **Bars are flush with the page and turn to glass when content scrolls under them** (Z-045; D108, D123, D124). AppBar, BottomTabBar, StickyActionBar and TopNavbar are the page colour with no line at rest; once content is under one it takes the regular material and a 1px hairline on the content side. They no longer have a border of their own, so AppBar is 56px (was 57) and BottomTabBar 64px (was 65); an app that hard-coded 57px or 65px should read `--app-shell-top-inset` / `--app-shell-bottom-inset` or use the new numbers. Restore 8.1's look: `scrollEdge="always"` on the bar together with `data-materials="opaque"` on `<html>` and `--color-surface-chrome: var(--color-surface-raised)` (a permanent opaque raised bar with its line).
+- **BottomTabBar: the active tab has no outline** (Z-046; D107, D126). It is marked by the tinted pill (`--color-tabbar-active`), a filled or heavier icon, a semibold label and the active colour; the focus ring shows on `:focus-visible` only. Under forced colours the pill keeps a system-colour outline. The count badge is the attention colour (the solid error fill) with a 2px ring in the bar colour. Restore 8.1: none by token (the outline was the reported defect); `--color-tabbar-active` takes any fill.
+- **Sidebar and TopNavbar restyled** (D127). SidebarNavigation: one active indicator, the tinted fill with the active text colour and a semibold label (the 3px leading bar is gone; forced colours keep an outline); rows are 36px at 14px with 20px icons and 44px on coarse pointers; sections are separated by space, not lines. SidebarNavSection headings are sentence case as written (no `uppercase`, no tracking), 12px medium. SidebarShell reads `--color-surface-chrome` (the page colour) with a weak hairline on the content side and no shadow in the `card` layout. SidebarPanel is a flat card (no shadow or ring; `variant="elevated"` now looks the same as the default) and its selected row uses the same single indicator. TopNavbar links are 14px without tracking, medium, semibold when active. Restore 8.1: none by token or prop.
+- **A `bg-*` or `border-*` class on a bar no longer changes its surface.** The fill and the hairline are painted on the material's layer, not on the bar element, so `class="bg-transparent border-b-0"` on an AppBar (or a `bg-*` on BottomTabBar, StickyActionBar, TopNavbar) has no visible effect. Use `tone="transparent"` or `tone="brand"` on AppBar, or set `--color-bar` on the bar (`class="[--color-bar:transparent]"`, any colour) and `scrollEdge="never"` for no glass and no line.
+- **The AppShell footer lies over the scroller** (D125) instead of taking a row of its own, so content passes under the tab bar. `--app-shell-bottom-inset` has the same meaning and value; the shell now gives the content that much bottom padding and the scroller that much `scroll-padding-bottom`. A floating button at `bottom: calc(var(--app-shell-bottom-inset) + 1rem)` sits where it did. Content that sized itself to the scroller's height (`min-h-full`) is now as tall as the screen minus the header only; its end is still above the footer because of the padding. No restore short of reverting.
+- **StickyActionBar and UnsavedChangesBar in a shell with a footer** stick above the footer (they read `--app-shell-footer-overlay`). **UnsavedChangesBar** is the regular material (rim, highlight, soft shadow) instead of an opaque card with a border and `shadow-lg`; `data-materials="opaque"` makes it opaque.
+- **`--color-surface-chrome` is the page colour** (`var(--color-surface-base)`) in both modes, not the raised surface (D108), so bars and sidebars that read it are flush with the page. The regular material is mixed from it and was re-solved: light 84% (was 80%), dark 76% (unchanged); thin stays 58% / 66%. Restore 8.1: `--color-surface-chrome: var(--color-surface-raised)` (per mode in `overrides`).
+
+## [9.0.0-alpha.2] - 2026-10-06
+
+A second local preview build of the 9.0 visual direction, not published to npm;
+8.1.0 stays the stable version. It adds the first restyled components on top of
+alpha.1's token layer: List and Badge without their double outlines, a sliding
+indicator in Tabs and SegmentedControl, gradient solid buttons with new `tonal`
+and `text` variants and a 56px size, a lighter off Toggle, the seven overlays
+on the thick material and a spring for BottomSheet. Bars, the shell and dark
+mode are not touched yet. No token, prop, variant or export is removed or
+renamed; several defaults change what a consumer sees, and each has a line that
+restores 8.1 where one exists. Built quickly and tested lightly on purpose: the
+type and design checks, the unit run, the theme tests, the package build and a
+scratch install were run on it. NOTHING was rendered: no browser suite, no
+Storybook or visual check in either mode, no accessibility or QA review, so the
+glass, the sliding indicators and the springs have never been seen. Using it is
+the test.
+
+### Added
+
+- **Button `variant="tonal"`** (Z-047): the tonal fill with its brand label, flat, for secondary actions and chosen answers. IconButton has it too.
+- **Button `variant="text"`** (Z-048): a standalone text action in the link colour (the on-colour inside `.on-brand` and `.on-accent`): no underline, a semibold label, the box and 44px touch target of the other variants, `px-2`, a hover and pressed tint. With `href` it is still a boxed action; `variant="link"` with `href` stays the underlined link for a sentence. IconButton shows it as its link look.
+- **Button `size="xl"`** (Z-047): 56px. Button only; `SizeVariant` is unchanged. New type `ButtonSize` (`SizeVariant | "xl"`), exported with `ButtonVariant`. `scripts/check-control-geometry.js` holds it to the same one-line rule as the other sizes.
+- **`--zabi-button-radius` and `--zabi-button-font-weight`** (Z-047) are now read by Button (and the inline link), through `rounded-button`, `font-button` and `font-button-strong`. Defaults are today's corner and a 500 label (600 for `text`).
+- **Control gradient, darken-only in light** (design review: "controls are flat"). `--gradient-control-top-strength` is 0% in light (the fill at the top is the control's own colour, so the label keeps its full contrast and an app's brand colour is not altered) and `--gradient-control-bottom-strength` 14% of `--zabi-base-950` (was 4% / 6%); dark stays 22% / 6%. The veil is for primary, accent and danger: `bg-control-gradient` serves danger too, and danger's label is now a guarded gradient pair. New `--gradient-control-accent-top-strength` and `--gradient-control-accent-bottom-strength` (default: the shared strengths) so one control can differ. The highlight now uses Tailwind's inset-shadow variable (`--tw-inset-shadow`) instead of `--tw-shadow`, so a `shadow-*` class on the same element draws as well. `createTheme` flips a veil to lighten-only in a mode where a dark label would fail the darkened bottom (a light accent), writes 0% if no strength passes, and never moves a strength you set. Restore: `--gradient-control-top-strength: 4%; --gradient-control-bottom-strength: 6%` in light.
+- **Tonal action role** (Z-047): `--color-action-tonal`, `--color-action-tonal-hover`, `--color-action-tonal-active`, `--color-action-tonal-text`; classes `bg-action-tonal` (with its hover and pressed states), `text-action-tonal`. Light is the brand-100 tint with a brand-800 label (8.15, 6.94 and 6.25:1 on rest, hover and pressed); dark the deep tint with the light label (9.48, 6.94, 5.86). `.bg-action-tonal` is a surface inside `.on-brand` and `.on-accent`.
+- **Outline edge, guarded at 3:1** (Z-047): `--color-action-outline-border` and `--color-action-outline-border-hover` (the field edge, 4.63:1 on the light page, 4.83:1 on a card; dark 3.67 and 3.12), classes `border-action-outline` and `hover:border-action-outline-hover`; the block's label colour inside `.on-brand` and `.on-accent`. Restore the old edge: `--color-action-outline-border: var(--color-border); --color-action-outline-border-hover: var(--color-border-medium)`.
+- **Button corner and label weight, apart from fields** (Z-047): `rounded-button` (`--zabi-button-radius`, falling back to `--radius-control`), `font-button` (`--zabi-button-font-weight`, falling back to 500) and `font-button-strong` (600, for the text variant). Declared nowhere, so set them on any ancestor or in `createTheme` `overrides`; a scoped `--radius-control` still flows. Defaults keep today's look.
+- **Toggle off track** that does not read as disabled: `--color-toggle-track` (light base-200, dark base-300), `-hover`, `-active`, and the edge `--color-toggle-track-border` (the field edge: 4.63:1 on the light page, 4.83:1 on a card, dark 3.67 and 3.12). Classes `bg-toggle-track` (with hover and pressed) and `ring-toggle-track` (an inset 1px edge that does not change the switch's size). `--color-control-track*` is untouched; Slider and Progress look as before. Restore: `--color-toggle-track: var(--color-control-track); --color-toggle-track-hover: var(--color-control-track-hover); --color-toggle-track-active: var(--color-control-track-active); --color-toggle-track-border: transparent`.
+- **`SegmentedControl tone`** (Z-052): `"neutral"` (default) or `"primary"`. Neutral draws the selected segment as a thumb: card colour, headline-coloured label, `--shadow-sm` and a 1px edge, on the tinted track. New tokens `--color-segment-thumb` (light: the raised surface; dark: the overlay surface), `--color-segment-thumb-text` and `--color-segment-thumb-border` (the control boundary, held to 3:1 against the track over the page and over a card, with the thumb text held to 4.5:1 on the thumb).
+- **A sliding indicator in Tabs and SegmentedControl.** After mount the selected item's mark (the underline, the pill, the thumb or the primary fill) is one element that moves and resizes to the selected item over `--duration-moderate`: with `--ease-spring` for the pill and the thumb, `--ease-standard` for the underline. It is measured, so it follows resizes, zoomed text (a wrapped SegmentedControl moves the thumb in two dimensions), right-to-left layouts and a scrolling tablist. Server-rendered, before hydration, without ResizeObserver or layout, and under forced colours the selected item draws its own mark as before. No motion under reduced motion.
+- **`Badge variant="brand"`** (Z-056 part 3): the primary brand colour as a badge, subtle (brand tint, link-coloured text) and solid (the primary fill with its label). New token `--color-action-primary-border` (the brand tint's edge), and the guarded pairs `badge subtle · brand` and `badge solid · brand`.
+- **`Badge bordered`** (Z-056 part 2): puts a subtle badge's family edge back. Default `false`.
+- **`--zabi-list-row-border-color`** (default `transparent`) and **`--zabi-list-divider-color`** (default `var(--color-border)`): set on a list or any ancestor.
+- **`.material-layer-thick`** (package 10): the thick material in a form for a container that holds fixed-position content. The fill, backdrop filter, highlight and rim are painted on a `::before` layer behind the content (isolated, `z-index: -1`, same tokens as `.material-thick`, so every fallback applies); the element itself carries only the outer shadow, so it is not the containing block of its `position: fixed` descendants. The element must be positioned and must not scroll its own content. Use it for any panel that can hold a popover; use `.material-thick` for a leaf.
+- **`Tooltip tone`**: `"material"` (default) or `"inverted"`. Typed in `TooltipProps`, documented in the catalog and the story.
+- **Guarded pairs on the thick material**: a Toast's status text (`--color-success-text`, `--color-error-text`, `--color-warning-text`, 4.5:1), the status colours as icons (3:1) and `--color-link` (4.5:1), each over the worst backdrop and over the page, in both modes.
+
+### Changed (visible in 9.0)
+
+- **A soft gradient on primary, accent and danger Buttons and IconButtons, the FloatingActionButton and the on Toggle** (design review: "controls are flat"): a darker bottom and a 1px top highlight over the control's own fill. None when disabled, loading, or a toggled-on IconButton. Restore 8.1: `--gradient-control-bottom-strength: 0%; --shadow-control-highlight: none` (and `--gradient-control-accent-bottom-strength: 0%` if the accent strength was set apart).
+- **The outline Button and IconButton have a 3:1 edge** (Z-047), not the 1.25:1 card edge. Restore 8.1: `--color-action-outline-border: var(--color-border); --color-action-outline-border-hover: var(--color-border-medium)`.
+- **The off Toggle is a light tint with a 1px edge**, no longer the mid-grey that read as disabled; its colour change and the thumb's slide use the motion tokens (`--duration-moderate`, the thumb on the spring easing). Restore 8.1: `--color-toggle-track: var(--color-control-track); --color-toggle-track-hover: var(--color-control-track-hover); --color-toggle-track-active: var(--color-control-track-active); --color-toggle-track-border: transparent`.
+- Button, IconButton and the FloatingActionButton change colour over `--duration-base` instead of a literal 150ms, so reduced motion zeroes it.
+- **`createTheme`: links follow an overridden primary** (Z-048). An app that sets `--color-action-primary` in `overrides` (and not `--color-link`) gets `--color-link` equal to it, and `--color-link-hover` equal to the primary hover if it set one, in each mode the override applies to, as long as no guarded pair fails that did not before; otherwise the ramp's link stays in that mode. An explicit `--color-link` always wins. The library default stays `--color-link: var(--color-brand-700)`. The generator also resolves the control veil pairs now (it skipped them before). Restore: `overrides: { '--color-link': 'var(--color-brand-700)', '--color-link-hover': 'var(--color-brand-800)' }`.
+- **SegmentedControl: the selected segment is a neutral thumb, not a solid primary fill** (Z-052), so the control is no longer louder than the screen's main button. Restore 8.1: `tone="primary"`.
+- **The indicators of Tabs and SegmentedControl slide** between items instead of switching. Restore 8.1: `--duration-moderate: 0s` on the component or an ancestor makes the move instant (the token is shared with other components); reduced motion already has none.
+- **List rows have no border of their own; a hairline divides them.** A row inside the bordered `.list-group` shell (or a bare `<List>`) drew a second outline; now rows keep a transparent 1px border (so height and text do not move) and a 1px `--color-border` divider sits in the gap between rows, none above the first or below the last, hidden next to a selected row (which keeps its fill and `border-action-primary` edge). The `.list-group` shell keeps its one border. Row transitions use the motion tokens. Restore 8.1: `--zabi-list-row-border-color: var(--color-border); --zabi-list-divider-color: transparent;` on the list or any ancestor.
+- **A subtle Badge has no visible border.** The 1px border box stays (same height), drawn transparent. Restore 8.1: `bordered` on the Badge. Solid badges are unchanged.
+- **BottomSheet arrives on a spring.** The slide in, the move between snap points and the settle after a drag use `--ease-spring` over `--duration-slow` (300ms); they were a literal 200ms ease-out. The slide in reads both tokens from the sheet, so a theme that sets them is followed, and falls back to `ease-out` where the tokens cannot be read or the engine rejects a `linear()` easing. A 2rem filler under the panel's bottom edge keeps the overshoot from showing the page. Reduced motion is unchanged (no slide, no transition), and so are drag, snap logic, focus and scroll lock. Restore 8.1: on the sheet or an ancestor, `--ease-spring: var(--ease-out); --duration-slow: 200ms` (both tokens are shared with other components), or `class="duration-200 ease-out"` on the `BottomSheet`.
+- **Overlays are frosted glass** (package 10): BottomSheet, Drawer, Modal, the Dropdown menu, the Select list, the Tooltip bubble and every Toast (and Toaster toast) take the thick material instead of an opaque overlay fill with a border and `shadow-lg`; the material brings its own rim and shadow. Dividers inside a header or footer, row hover and selected fills, and the scrims behind Modal, Drawer and BottomSheet are unchanged. Dark thick is 98% opaque by design for now, so a dark overlay shows almost no glass. In Modal, Drawer and BottomSheet the glass is a layer behind the content: the Drawer panel lost its edge border and the BottomSheet its top and side borders (the rim replaces them), and a Modal's panel no longer scrolls itself: its Card does (`overflow-y-auto` moved from the panel to the Card, `min-h-0` added), and the Card takes the panel's full corner radius. A fixed-position popover inside any of them is placed against the viewport exactly as before, with materials on or off. Restore 8.1: `data-materials="opaque"` on the root or any ancestor (a portaled overlay lives under `body`, so put it on `html` or `body`) gives opaque overlay surfaces. The 8.1 `shadow-lg` and 1px border look itself is not restorable with one token.
+- **The Tooltip bubble is glass with body text and no arrow by default.** The arrow is a second shape on a translucent fill and would show a seam. Restore 8.1: `tone="inverted"` (the dark bubble with its arrow, still reading `--color-tooltip-bg` and `--color-tooltip-fg`).
+- **Toast text uses the status `-text` colour** (`text-success-text`, `text-error-text`, `text-warning-text`) instead of the plain status colour, which is 3.7:1 to 3.9:1 on glass; the border stays the plain colour. The neutral toast draws no second border. A Dropdown danger item uses `text-error-text` for the same reason. Restore 8.1: none by token; the colours are slightly darker in light and lighter in dark.
+- **Overlay motion reads the tokens**: Dropdown fades over `--duration-moderate` with `--ease-standard`, the Modal's slide over `--duration-slow` with `--ease-out`, the Drawer reads `--duration-moderate` and `--ease-out` for its slide, the Select over `--duration-base` and `--duration-moderate`, the Tooltip over `--duration-moderate`. Reduced motion zeroes them.
+
+### Fixed
+
+- **Z-040: the pressed field follows the field.** `--color-input-active` (the
+  pressed Select trigger) is now derived from `--color-input`, so an app that
+  sets the light card colour through `createTheme` `overrides.light` no longer
+  trips "pressed field against the resting field". Light mixes 12% of the ink
+  (`--zabi-base-900`) into the field, dark 10% of the light end
+  (`--zabi-base-50`). On the default theme light moves from `#e4e4e7` to
+  `#e3e3e4` and dark from `#333338` to `#353538`. An app that overrode
+  `--color-input-active` by hand to get past the check can delete that override.
+  Restore: `--color-input-active: var(--color-base-200)` in light,
+  `var(--color-base-250)` in dark. The neutral chroma at the light end is not a
+  new option: set the page per mode (`overrides.light`, `--color-surface-base`),
+  see THEMING.md.
+
+## [9.0.0-alpha.1] - 2026-10-06
+
+A local preview build of the 9.0 visual direction, not published to npm; 8.1.0
+stays the stable version. It holds the token layer only (surfaces, status
+colours, materials, gradients, motion, typeface): no component is restyled yet
+except the default `Card` and the `ImageUpload` hover plate, and dark mode is
+not yet art-directed. No token, prop or export is removed or renamed; values
+move, and each visible change below has a line that restores 8.1. Built quickly
+and tested lightly on purpose: the type and design checks, one unit run, the
+theme tests, the package build and a scratch install were run on it. NOTHING
+was rendered: no browser suite, no Storybook or visual check in either mode, no
+accessibility or QA review. Using it is the test.
+
+### Added
+
+- **Motion tokens.** `--duration-fast|base|moderate|slow` (100, 150, 200, 300ms) and `--ease-standard` (`cubic-bezier(0.2, 0, 0, 1)`), `--ease-out` (Tailwind's own curve) and `--ease-spring` (a lightly damped `linear()` spring with one overshoot, with a cubic-bezier fallback where `linear()` is unsupported). Utilities: `ease-standard`, `ease-out`, `ease-spring`; durations are `duration-(--duration-moderate)` (Tailwind has no `duration-fast` style name for custom properties). Under `prefers-reduced-motion: reduce` the four durations become `0s` and the spring becomes the standard curve, in both modes and over an app's own values (`:root:root`, like the materials fallback), so everything that reads the tokens follows. All are settable through `createTheme` `overrides`.
+- **Materials (frosted glass) for what floats over content.** Tokens `--color-material-thin|regular|thick` (the fills: `--color-surface-chrome` at an alpha for thin and regular, `--color-surface-overlay` for thick), `--material-alpha-thin|regular|thick`, `--material-blur-thin|regular|thick`, `--material-saturate`, `--material-filter-*`, `--color-material-highlight`, `--color-material-rim`, `--shadow-material` and `--shadow-opacity-contact`, and the classes `material-thin`, `material-regular` and `material-thick` (fill, backdrop filter, edge and shadow; they compose with `rounded-*` and `focus-ring`). Highlight, rim and shadow derive from the neutral ramp, so `neutralChroma` tints them. No component uses them yet except the `ImageUpload` hover plate.
+- **Alpha floors in the contrast guard.** Each material is composited over the worst backdrop of the mode (`--zabi-base-950` behind light, `--zabi-base-50` behind dark) and over the page: thin must give its headline 4.5:1, regular its headline, body and label, thick all five text roles, and regular and thick the focus ring 3:1 (a thin control's ring is drawn outside it). Shipped alphas for thin, regular and thick: light 58, 80 and 86, dark 66, 76 and 98, each the smallest whole 2% that passes except light thin, whose floor is lower. Dark thick is close to opaque because captions must hold over a white backdrop; dark is art-directed in a later 9.0 change. `scripts/contrast-pairs.js` has a `behind` form that `createTheme` evaluates too, so an app's generated theme gets the same floor; every material token is settable through `overrides` (`light`, `dark`, `both`).
+- **Fallbacks and `data-materials="opaque"`.** The fills become the opaque surface they are made from, and the blur goes, under `prefers-reduced-transparency: reduce`, `prefers-contrast: more`, `forced-colors: active`, where `backdrop-filter` is unsupported, and where the root or any ancestor has `data-materials="opaque"`. Under forced colors the rim is a `CanvasText` outline. The fallbacks are in the theme files and in `zabi-components-colors.css`.
+- **Gradient tokens and three classes.** Canvas: `--gradient-canvas` (two soft radial washes from brand 300 and accent 300, a `background-image` only), its stops `--color-canvas-wash-brand` and `--color-canvas-wash-accent`, and `--gradient-canvas-strength` (light 55%, dark 25%); the class `bg-canvas` adds `--color-surface-base` under it. The library does not paint it on `body`. Controls: `--gradient-control` and `--gradient-control-accent`, a translucent veil over the control's own `background-color` (so hover and pressed fills still show), with the veil colours `--color-control-gradient-start|end` and `--color-control-gradient-accent-start|end`, strengths `--gradient-control-top-strength` and `--gradient-control-bottom-strength`, and `--shadow-control-highlight` (an inset 1px top edge); classes `bg-control-gradient` and `bg-control-gradient-accent` (the highlight goes through Tailwind's shadow variables, so `focus-ring` still draws). All follow a custom `brand` and `accent` and are settable through `createTheme` `overrides` (`light`, `dark`, `both`). No component uses them yet.
+- **Worst-case rule for gradients.** Contrast is never measured against a gradient. The guard holds the five text roles, `--color-link` (4.5:1), `--color-focus-ring` and `--color-input-border` (3:1) on each canvas wash stop over `--color-surface-base`, and the solid-button label on both veil ends over rest, hover and pressed fills (4.5:1). Solved strengths: canvas light 55 and dark 25 (the prototype used 85 and 45); top veil light 4 and dark 22. `createTheme` evaluates the same pairs.
+- `scripts/check-token-violations.js` fails `backdrop-blur-*` and `backdrop-filter` in `src/components`. The `ImageUpload` hover plate (`bg-surface-overlay/60 backdrop-blur-md`) is now `material-thin`.
+
+### Changed (visible in 9.0)
+
+- **Default typeface is the platform's UI face.** `--font-family-sans` is `ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` plus the emoji faces; `--font-family-heading` still follows it; `--font-family-mono` is `ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace` (it was Monaco, Menlo, Ubuntu Mono). The library and its Storybook no longer load Nunito Sans, so a default install downloads no font. The face now differs by platform (San Francisco, Segoe UI, Roboto) and text widths change, so truncation and wrapping can move. Restore 8.1: load Nunito Sans yourself and set `--font-family-sans: 'Nunito Sans', ui-sans-serif, system-ui, sans-serif` on `:root` after the imports. The docs site keeps Familjen Grotesk for its marketing headings.
+- **Default transition curve.** `transition`, `transition-colors`, `transition-opacity` and the rest, where a component sets no duration of its own, now use `--ease-standard` instead of Tailwind's `cubic-bezier(0.4, 0, 0.2, 1)`; the duration stays 150ms (`--duration-base`). Restore Tailwind's curve: `--default-transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1)` on `:root` after the imports, or `createTheme({ …, overrides: { '--default-transition-timing-function': 'cubic-bezier(0.4, 0, 0.2, 1)' } })`.
+- **Light page and cards.** The light page is now near-white (`--color-surface-base` is `--zabi-base-50`, `#fafafa`; it was `--zabi-base-150`, `#ececee`), and `--color-page` and `--color-background` follow it. A default `Card` now has a 1px `--color-border` edge and no shadow (it used `shadow-sm`, and `hover:shadow-lg` when clickable); it is the same as `variant="outlined"`, which stays. `elevated` and `flat` are unchanged. A clickable card's hover fill is now `--color-card-hover` = base-150 (was base-100) and its pressed fill base-200, and `--color-input-disabled` is base-150 and `--color-background-secondary` base-100, so they still read against the lighter page. Dark does not change.
+- **New token `--color-surface-chrome`** (and the `bg-surface-chrome` utility) for bars and sidebars: `var(--color-surface-raised)` in both modes. The components do not read it yet. In `createTheme`, set it per mode with `overrides: { light: { '--color-surface-chrome': … }, dark: { … } }`.
+- **Restore 8.1.** Page: `createTheme({ …, overrides: { light: { '--color-surface-base': 'var(--zabi-base-150)' } } })`, or `--color-surface-base: var(--zabi-base-150)` in light CSS. Card: there is no `variant` that gives the old shadowed default; pass `class="border-transparent shadow-sm"` to approximate it.
+- **Status colours.** Every `-subtle` fill moves from ramp step 200 to step 100 and every `-border` from 300 to 200 in light (`success`, `warning`, `error`, `energetic`, `accent`, `info`; `--color-action-primary-subtle` and its hover and pressed steps follow, to 100, 200 and 300/200). Neutral's fill is `--color-base-200` (was 250) and its edge `--color-base-250` (was 300). Dark already used 100 and 200 and is only affected by the regenerated ramps below. The `warning`, `citron` (the default `accent` and `energetic`) and `pine` (`success`) ramps are regenerated on the same lightness curve with new hue and chroma, which is breaking by the repo's policy for every `--zabi-warning-*`, `--zabi-citron-*`, `--zabi-accent-*` and `--zabi-pine-*` step. Step 600: warning `#9e6000` to `#a05f00`, citron and accent `#707400` to `#5d7900`, pine `#00805e` to `#00804b`. Contrast ratios are unchanged to within rounding. An app that passes its own `accent` or `brand` to `createTheme` is unaffected, except that its dark mirror of `success`, `warning` and `energetic` follows the new ramps.
+- **Restore 8.1 status colours.** Subtle fills: set `--color-<family>-subtle: var(--color-<ramp>-200)` and `--color-<family>-border: var(--color-<ramp>-300)` (ramp `pine` for success, `iris` for info, `citron` for energetic) in light, and `--color-neutral-subtle: var(--color-base-250)`, `--color-neutral-border: var(--color-base-300)`. Ramps: pass the old colour to `createTheme` (`accent: '#707400'`) or set the old `--zabi-*` steps on `:root`; the 8.1 seeds were warning hue 82, shift -24, chroma 0.165; citron hue 112, chroma 0.135; pine hue 170, chroma 0.115.
+- **Softer, layered shadows.** `--shadow-sm|md|lg|xl` keep their names and are each a tight contact shadow plus a wider soft one. `--shadow-opacity` is now the strength of the wide layer: `0.10` in light (was `0.14`) and `0.24` in dark (was `0.3`); the new `--shadow-opacity-contact` is the contact layer, `0.06` light and `0.3` dark. Restore 8.1: in light `--shadow-opacity: 0.14`, `--shadow-sm: 0 1px 3px 0 rgb(var(--shadow-color) / var(--shadow-opacity)), 0 1px 2px -1px rgb(var(--shadow-color) / var(--shadow-opacity))`, `--shadow-md: 0 4px 6px -1px rgb(var(--shadow-color) / var(--shadow-opacity)), 0 2px 4px -2px rgb(var(--shadow-color) / var(--shadow-opacity))`, `--shadow-lg: 0 10px 15px -3px rgb(var(--shadow-color) / var(--shadow-opacity)), 0 4px 6px -4px rgb(var(--shadow-color) / var(--shadow-opacity))`, `--shadow-xl: 0 20px 25px -5px rgb(var(--shadow-color) / var(--shadow-opacity)), 0 8px 10px -6px rgb(var(--shadow-color) / var(--shadow-opacity))`; in dark the same with `--shadow-opacity: 0.3`.
+- The surface guard (`scripts/check-surface-elevation.js`) now checks the light surfaces by the card edge (`--color-border` at 1.2:1 or more on the page and the card) instead of a lightness ladder; the dark rules are unchanged.
+
+## [8.1.0] - 2026-10-06
+
+8.1.0 adds a theme generator (`zabi-theme`, `createTheme`) and an accent colour,
+a mobile set (AppShell, AppBar, BottomTabBar, BottomSheet, Drawer, Select as a
+sheet, safe areas, 44px touch targets) and more than 25 new components. Form fields,
+focus rings and light-mode surfaces are easier to see, and `strings` and
+`ZabiStringsProvider` replace every built-in English text. Nothing from 8.0.0
+was removed or renamed: every `exports` path, prop and token is still there.
+8.0.1 was never published, so everything in the 8.0.1 section below (valid theme
+files, the three-line Tailwind setup working, ColorPicker on the server,
+Progress named) is part of 8.1.0.
+
+### Upgrade notes
+
+Coming from 8.0.0, these are visible without a code change. Each bullet says
+what to do.
+
+**Appearance**
+
+- **Form field edges are darker.** `--color-input-border` is `base-500` in
+  light and dark (was `base-350` light, `base-300` dark) and
+  `--color-input-border-hover` is `base-550` in light. The edge is guarded at
+  3:1 against the field fill, the page and the card, in both themes. A theme
+  of yours that overrides the edge can now report a pair below 3:1 in the
+  generator check. The dark field edge on the overlay surface (sheets, modals)
+  is about 2:1 against the panel and is not guarded. Nothing to do unless you
+  override the edge.
+- **`Progress` uses new tokens.** The fill is `--color-progress-fill` (default
+  `--color-action-primary`) and the track `--color-progress-track` (default
+  `--color-input`); utilities `bg-progress-fill` and `bg-progress-track`. The
+  fill used to be the hard-coded brand step 600, so a bar changes colour in an
+  app that pins a primary action, and in dark. Fill on track is guarded at
+  3:1. Set the two tokens to keep the old colour.
+- **Light mode has a visible surface ladder, stronger tints and shadows.** See
+  Changed: the page, cards, tinted fills, hover fills, overlay edge and shadow
+  all move. A card is 1.18:1 on the page (was 1.10). Check screenshots; no
+  token was renamed.
+- **Focus rings are one step darker in light and lighter in dark.**
+  `--color-focus` is `brand-600` in both themes (light was `brand-500` at
+  2.99:1 on the page; dark was `brand-500`, 2.91:1 on the overlay; dark is
+  #92a9ff by default). The muted ring in dark is one step lighter
+  (`--color-focus-ring-muted`, `base-600`).
+- **The computed `box-shadow` of a focused element lists five shadows**, not
+  two, because the ring now composes with shadow utilities. A test that reads
+  the ring colour from it should pick the 4px spread.
+- **Dark surfaces are `color-mix()` expressions** over `--zabi-base-*`
+  (`--color-surface-raised`, `-elevated`, `-overlay`). The pixels are the same;
+  `getComputedStyle` reports `color(srgb …)`, not `rgb(…)`, so a test that
+  compares the string needs updating.
+- **Placeholder text is one step stronger** in both themes
+  (`--color-input-placeholder`: #61616a light, #a1a1aa dark; 4.5:1 or more on
+  the resting, hovered, focused and pressed field).
+- **Checked checkboxes and radios use the primary action fill**, with the
+  primary button's text colour on the tick and dot.
+- **Dropdown menus, Select lists, the ColorPicker popover and NavigationMenu
+  panels have 16px corners** (were 8px), and other nested corners are
+  concentric: the Card in a Modal, MediaGrid's check mark, Alert's close
+  button, rows in a `.list-group`, the avatar in SidebarFooter's profile
+  button.
+- **`font-sans` and `font-mono` follow the theme's font tokens**
+  (`--font-family-sans`, `--font-family-mono`), not Tailwind's system stacks.
+  If you used `font-sans` to get the system font, write the stack yourself.
+- **`color-scheme` comes from the theme**: `light` by default and for
+  `data-theme="light"`, `dark` under `.dark` and `data-theme="dark"` (also when
+  both `class="dark"` and `data-theme="light"` are set). Native controls,
+  scrollbars, date pickers and autofill follow the theme. A
+  `<meta name="color-scheme">` tag is not needed, and a `color-scheme` rule of
+  your own must come after the theme import to win.
+
+**Markup, roles and accessible names**
+
+- **A `Select` is found by role `combobox`, not `button`.** Its trigger has
+  `role="combobox"` and reports `aria-invalid`, `aria-required` and
+  `aria-busy`. Its form control is a native `<select name>` (not a hidden
+  input), so code that looked for `input[type=hidden]` must look for the
+  select, and `required` now blocks the form. A form reset returns the Select
+  to the value it was rendered with. Update tests and selectors.
+- **A loading `Button` or `IconButton` is `aria-disabled="true"` and
+  `aria-busy="true"`, not `disabled`.** It keeps keyboard focus and swallows
+  the press. CSS or tests that matched it with `:disabled`, `[disabled]` or a
+  strict `toBeDisabled()` must use `[aria-busy="true"]`.
+- **`ThemeToggle` (two modes) has the constant name "Dark mode"** with
+  `aria-pressed`, not "Switch to dark mode" / "Switch to light mode"; update
+  tests and scripts that find the button by those names. It applies the stored
+  choice when it mounts (`storageKey={null}` turns that off) and no longer
+  writes an inline `color-scheme`.
+- **`NavigationMenu` is a list of links and disclosure buttons**, not a
+  `menubar`: the list has `role="list"` and items carry no menu roles. Screen
+  readers announce it differently; keyboard use is unchanged.
+- **A `List` row with no `href` in a List with no `onclick` is plain content**,
+  not a focusable button with an arrow.
+- **Checkbox and Radio inputs are stretched invisibly over their box** instead
+  of being visually hidden, so `getByRole("checkbox").check()` works.
+- **An unnamed `RadioGroup` submits nothing.** Give it a `name`. (The
+  generated name still groups the radios.)
+- **A disabled `Dropdown` or `Select` option is `aria-disabled`, not
+  `disabled`**: reachable with the arrow keys, announced as disabled, not
+  selectable.
+- A Select list and a Dropdown menu are one Tab stop (roving `tabindex`, 0 or
+  -1). `getFocusableElements` skips `tabindex="-1"`.
+
+**Defaults and behaviour**
+
+- **A binding that starts `undefined` on a bindable prop is now written back
+  as the default** (`""`, `false`, `null`). `let value = $state()` works with
+  `bind:value` everywhere; no bindable prop has a fallback expression any
+  more.
+- **Controls are at least 44px on touch screens** (`pointer: coarse`), so
+  layouts there get taller (a checkbox list at an 8px gap is 52px a row).
+  Nothing changes with a mouse.
+- **Every pressable control shows a `:active` pressed state** that does not
+  depend on hover. Hand-written `:hover` rules apply only under
+  `@media (hover: hover)`, so a tapped button no longer sticks in its hover
+  colour.
+- **`Page` pads for the safe areas by default** (`safeArea`). An app that sets
+  `viewport-fit=cover` and already pads for the insets itself should pass
+  `safeArea={false}`. Without `viewport-fit=cover` the insets are zero and
+  nothing changes.
+- **`Select` opens as a bottom sheet on a phone** (a touch screen narrower than
+  640px; `presentation="auto"`). Pass `presentation="popover"` to keep the
+  pop-over. It fills its container like Input (a Select in a flex row takes the
+  free width; give it a width such as `class="w-48"`, which is honoured now),
+  and a label too long for the trigger wraps instead of being cut.
+  `maxMenuHeight` defaults to `60dvh` (was `60vh`).
+- **`Button` labels wrap.** A label that does not fit goes onto a second line
+  and the button grows (`min-height` instead of a fixed height); in a tight
+  flex row a button may shrink and wrap where it held its width.
+- **Toasts show your message.** A toast with a `message` and no `title` shows
+  the message, not a default heading; only a toast with `detail` can be
+  expanded; the countdown sentence and "Click to stop" are off unless
+  `showCountdown`. A toast with no `duration` closes after 7 s (14 s when its
+  text is 121 to 240 characters, stays when longer); an error toast and a
+  toast with an action stay until dismissed. On touch, `onpausechange` reports
+  `paused` then `running` for a tap. Toasts also sit above the tab bar, the
+  home indicator and the on-screen keyboard, and move while an overlay with a
+  header and footer is open. Mount the Toaster inside `ZabiStringsProvider`
+  when you use it.
+- **`Tooltip` opens on a tap and can be hovered.** A touch or pen press toggles
+  it, and it stays open until a second tap, a tap elsewhere, Escape, a scroll
+  or focus leaving (`touchDuration` defaults to `0`). The pointer can move from
+  the trigger onto the open bubble, so an open tooltip takes presses: keep
+  tooltips clear of other controls. A tooltip that would leave the viewport
+  flips or slides to stay 8px inside, and `data-placement` reports the side
+  used.
+- **`Tabs` with long labels scroll** instead of wrapping onto several lines.
+- **`AppBar` and `BottomTabBar` stay one row** (titles and labels get an
+  ellipsis; the bars are 57px and 65px at any text size). AppBar can be two
+  rows tall when the title would have under 72px beside the controls.
+- **Overlays follow the on-screen keyboard** where it covers the page (Modal,
+  BottomSheet, SlideUp, Drawer), and Modal and SlideUp are at most `90dvh`.
+- **Light-mode `Input`, `Textarea` and `Select` darken their border on hover**
+  and render text at 16px below 640px, so iOS Safari no longer zooms on focus.
+- **`Table` and `PropsTable` sit on the card surface** with an elevated header
+  band; Skeleton and Header's variant chips use `bg-neutral-subtle`.
+- **Inside `on-brand` and `on-accent` blocks** labels, links, borders and quiet
+  buttons change to the block's on-colour; a card inside a block gets the
+  page's colours back. Custom properties named `--zabi-theme-*` appear on a
+  block's parent.
+- **`ImageUpload` no longer forces a 16rem minimum width**, and its `id` names
+  the control (the dropzone button), not the host. Set a width with `class` if
+  you relied on it.
+- **`SidebarAccountPanel`'s `systemMode` default text is "Follows the
+  system".**
+- `UnsavedChangesBar` and `ConfirmDialog` leave focus on the pressed button
+  while busy, where they moved it to their container.
+- `Modal`'s `onclick` as a close signal is deprecated (see Deprecated).
+
+**Theme files and the generator**
+
+- **Dark theme files no longer restate the `--zabi-*` ramps.** `theme-dark`,
+  `theme-dark-only` and the dark part of `colors` only remap roles; the raw
+  palettes are declared once, in the light theme. Import the light theme
+  first: `@import "zabi-components/theme-only"; @import
+  "zabi-components/theme-dark-only";`. 8.0.0's `.dark`-only file carried a
+  copy; a dark file imported on its own now has no ramps. An override of
+  `--zabi-brand-*`, `--zabi-accent-*` or `--zabi-base-*` on `:root` applies in
+  both modes. The dark files are about 13 KB larger, because the block is
+  published for the class and attribute and for the system setting. See
+  `docs/theme-imports.md`.
+- **The generator checks more role pairs than 8.0.0**, so a theme check that
+  passed on 8.0.0 can turn red. `createTheme` and `zabi-theme` resolve every
+  role pair the library's own guard checks (the field edge on fill, page and
+  card; the progress fill on its track; the muted and danger focus rings and
+  the control boundary on all five surface levels; the accent star outline on
+  an inset surface; the focus ring or its offset gap on an accent button; the
+  label on a selected and on a held selected pill tab). A pair below AA (4.5:1
+  text, 3:1 UI parts) is a warning, and fails under `--strict`. The generated
+  values are unchanged; the findings are real for that theme. Fix them with an
+  override (`--set`), for example `--color-focus` and `--color-link-hover` one
+  brand step darker, or use `--pin`.
+- Theme files work with `[data-theme="dark"]`, and with `[data-theme="auto"]`
+  under `prefers-color-scheme: dark`. A page with no class and no attribute is
+  light, as before.
+
+**Package**
+
+- `package.json`: new `./create-theme` export and `zabi-theme` bin; `culori`
+  moved to `dependencies` (the generator uses it at run time);
+  `sideEffects: ["**/*.css"]`; `CHANGELOG.md` shipped in `files`; the `prepare`
+  script renamed `fix:lucide-types` (dev-only, so installing prints no
+  install-scripts notice; run it if your editor needs it). Every component
+  imports icons from `@lucide/svelte/icons/<name>`; import yours that way too.
+  No export, prop, token or file from 8.0.0 was removed or renamed.
+
+### Added
+
+#### Theming and the `zabi-theme` generator
+
+- **`npx zabi-theme --brand "#0026EA"`** writes a CSS file with the full
+  `--zabi-brand-*` ramp; with `--accent` and `--neutral` also the
+  `--zabi-accent-*` ramp and all 21 `--zabi-base-*` steps; `--out` names the
+  file. Import it after `theme-only` and `theme-dark-only` and it covers light
+  and dark. The same is available in code as `createTheme({ brand, accent,
+  neutral })` from `zabi-components/create-theme`, which returns `{ css, tokens,
+  warnings, closest }`. The ramps sit on the library's lightness curve: your
+  colour gives the hue and chroma and is not pinned to a step, so the exact hex
+  may not appear, and the file header names the closest step. The generator
+  picks the text colour for the brand and accent fills.
+- **The generator reports contrast** on stderr, in the file header and in
+  `warnings`; `--strict` exits 1 on a failed pair. `--set <token>=<value>` (or
+  `overrides`) moves a role and is checked too. `overrides` takes a flat map
+  (both modes) or `{ light, dark, both }`; the CLI has `--set-light` and
+  `--set-dark`. A light-only override is restated with the library's own dark
+  value in the dark rules, and the check reads each mode's own value.
+- **`zabi-theme --pin`** (`createTheme({ pin: true })`): the primary action is
+  the exact brand colour in light, with derived hover and pressed states and a
+  label checked at 4.5:1. The focus ring and links take the colour where every
+  guarded pair still passes. Dark keeps the mirrored ramp step unless the colour
+  passes there; the header says which. A failing pair is a warning and the
+  colour is never moved. `--pin-accent` / `pin: { accent: true }` does the same
+  for the solid accent fill.
+- **`neutralChroma`** (CLI `--neutral-chroma`, 0 to 0.1, needs `neutral`): the
+  OKLCH chroma at the neutral ramp's peak, for a clearly tinted neutral. With it
+  the translucent ink roles (`--color-action-secondary` and its hover and
+  pressed steps, `--color-surface-hover`, `-active`, `--color-border-overlay`
+  in light, `--shadow-color`) follow the neutral ramp, and the file restates the
+  dark values under the dark selectors.
+- **A theming guide.** `THEMING.md` is the documented token API: quick start
+  with `zabi-theme`, import order, tables of the tokens an app may set (brand,
+  accent and neutral ramps, the "on" colours, fonts and weights, radius,
+  shadow, z-index) and the roles to read, light, dark and auto, what the
+  generator does and does not do, and what does not follow an override.
+  Renaming or removing a documented token is a breaking change; the token-name
+  snapshot in `npm run test:themes` enforces it. The docs site has a `/theming`
+  page with a brand switcher (`?brand=amber` opens any page in Amber, generated
+  from `#C17B00` and a warm neutral).
+- **One brand override restyles light and dark.** The raw `--zabi-*` ramps are
+  declared once and the dark block only remaps roles; dark surfaces are mixed
+  from the neutral ramp, so warm or tinted greys carry through.
+- **An accent colour.** `--zabi-accent-50` … `950`, `--color-accent-50` …
+  `950`, the roles `--color-accent`, `-hover`, `-active`, `-subtle`, `-border`,
+  `-text`, `--color-on-accent`, and the classes `bg-accent`, `text-accent`,
+  `border-accent` (with working `hover:` and `active:` forms, also
+  `active:bg-info-active` and `hover:bg-nav-menu-active-hover`). The
+  `energetic` tokens are unchanged. `Button` and `IconButton` take
+  `variant="accent"` (solid, own hover and pressed fills, `--color-on-accent`
+  label); `Badge variant="accent"` (subtle and solid); `Rating tone="accent"`.
+- **The text on a fill can be set.** `--zabi-on-brand` (light, white) and
+  `--zabi-on-brand-dark` (dark, `brand-950`) feed `--color-on-brand`, which
+  `--color-action-primary-text` follows; `--zabi-on-accent` and
+  `--zabi-on-accent-dark` do the same for the accent. `Heading` and `Text` take
+  `tone="inherit" | "on-brand" | "on-accent"`; the classes `on-brand` and
+  `on-accent` set a block's text colour and make the focus ring visible on it;
+  `on-surface` marks a surface of your own inside a block.
+  THEMING.md ("Text and controls on a brand or accent block") says which button
+  variants stay legible there. Directly on a block an empty or ticked checkbox,
+  radio or toggle, a filled Rating star and status message text are not legible
+  (put them on a card); a card inside a block needs `:has()`.
+- **Font tokens.** `--font-family-heading` (follows `--font-family-sans` until
+  set; applied to `h1`–`h6` and Heading), `--font-family-mono` (CodeBlock reads
+  it), `--font-weight-regular`, `-normal`, `-medium`, `-semibold`, `-bold`,
+  `--font-sans`, `--font-mono`, `--font-heading`, and a `font-heading` utility.
+- **Dark mode by attribute and by the system setting.** The dark files apply to
+  `.dark`, `[data-theme="dark"]`, and `[data-theme="auto"]` when
+  `prefers-color-scheme` is dark; `[data-theme="light"]` stays light. Following
+  the system is opt-in. Put the class or attribute on `<html>`.
+- **ThemeToggle `modes="three"`** steps through system, light and dark, writes
+  `data-theme` on `<html>`, shows a monitor, sun or moon and names itself
+  "Theme: system. Switch to light"; `labels` (including `labels.darkMode`)
+  replaces the words. `mode` (bindable), `onmodechange` and `storageKey` read or
+  drive the mode, or store it under your own key. It reads `dark`, `light` and
+  `auto`, follows changes made elsewhere, and shows the right icon before it
+  mounts.
+- **Theme helpers** from the package root: `getThemeMode`, `setThemeMode`,
+  `isThemeDark`, `getStoredThemeMode`, `storeThemeMode`, `themeInitScript` and
+  the `ThemeMode` type. `themeInitScript()` returns a script for `<head>` that
+  applies the stored mode before first paint. TopNavbar takes `themeModes`,
+  `themeStorageKey` and `themeLabels`; SidebarAccountPanel takes
+  `themeModes="three"` with `onThemeModeChange`.
+- New tokens: `--color-surface-inset` (`bg-surface-inset`; a recessed well on a
+  card, `base-100` light and `base-150` dark, AA text; dark `--color-input`
+  points at it and keeps its value; do not use `--color-input` for a well, it is
+  white in light), `--color-input-border-hover`, `--color-control-border`
+  (`border-control-border`, `text-control-border`; 3:1 on every surface level;
+  `--color-border-strong` is unchanged and decorative), `--color-focus-ring-muted`
+  (`.focus-ring--muted`), `--color-focus-ring-danger` (the error colour; the
+  on-colour inside a block), `--color-input-active` (`active:bg-input-active`;
+  Select's trigger uses it), `--color-action-primary-subtle-active` and
+  `--color-action-danger-subtle-active` (`active:bg-…`), `--zabi-list-row-radius`
+  (`.list-group` sets it for rows), `--color-progress-fill`,
+  `--color-progress-track`, `--zabi-avatar-ring`, and the documented star
+  colours `--zabi-rating-on`, `--zabi-rating-off`, `--zabi-rating-on-hover`,
+  `--zabi-rating-on-active`, `--zabi-rating-on-edge` (they apply when set on an
+  ancestor or by a class). The contrast guard holds the muted and danger focus
+  rings and the control boundary to 3:1 on all five surface levels, and fails
+  when a focus-ring rule reads a colour that is not in its pair list.
+
+#### New components
+
+- **SortableList** reorders items and leaves their content to you. Each row
+  has a drag handle (mouse and touch), arrow keys, Home and End on the handle,
+  optional move up and down buttons and a polite announcement of the new
+  position. `bind:items`, `onreorder` (item, old and new index),
+  `controls="manual"`, `strings`. Escape cancels a drag; a key that cannot move
+  further says so ("Hero section, already first"); a parent replacing `items`
+  mid-drag cancels it. Clicks on the handle or a move button do not bubble: put
+  them beside a header toggle, never inside another button. Handle and buttons
+  sit 8px apart on touch.
+- **Collapsible**: a trigger wired to the panel it shows and hides, owning ids,
+  `aria-expanded`, `aria-controls` and the panel's name. `title` gives a
+  full-width header button with a chevron (`headingLevel` wraps it in a real
+  heading); a `trigger` snippet hands the wiring to your own `<button>`.
+  `bind:open`, `onopenchange`, `disabled`. Closed content stays in the DOM under
+  `hidden` (`unmountOnClose` removes it). If the panel closes while focus is
+  inside it, focus moves to the trigger. **CollapsibleGroup** makes an
+  accordion: opening one closes the others, or `multiple`; Arrow Up and Down,
+  Home and End move between headers. In a single-open group only the first
+  panel marked open renders open (also on the server, without
+  `onopenchange`); a disabled panel keeps its state.
+- **ConfirmDialog** (on Modal): `title`, `message`, `variant` (`danger`,
+  `warning`, `info`, each with an icon; `danger` uses the danger button),
+  `confirmLabel`, `cancelLabel`. If `onconfirm` returns a promise the dialog
+  shows its loading state and cannot be dismissed until it settles: it closes on
+  success, stays open on failure and passes the error to `onerror`; returning
+  `false` keeps it open. `loading` does the same for your own request tracking;
+  `oncancel` reports how the user backed out; `loadingLabel` (default
+  "Working…") is announced once. Focus starts on Cancel, Enter only activates
+  the focused button, and it renders in `document.body` unless `portal={false}`.
+  It uses `role="alertdialog"`, draws no outline around the whole dialog while
+  loading and sets no `aria-busy` on the panel.
+- **Drawer**: a modal panel from the side. `side` is `left`, `right`, `start` or
+  `end`; `size` is `sm`, `md` or `lg`, never wider than the screen; `title`,
+  `description`, a `footer` snippet; `dismissible`, `onclose({ reason })`,
+  `closeLabel`, `initialFocus`, `portal` (default true). Focus is trapped and
+  returns to the opener, the page does not scroll, the slide is skipped under
+  `prefers-reduced-motion`, it shares the scroll lock with Modal and SlideUp and
+  stacks with them. Its `onkeydown` runs after Escape handling; content with
+  nothing to focus is a Tab stop named by the title; the panel pads for the
+  bottom safe area; the close button takes taps in a 44px area.
+- **MediaGrid**: image and video thumbnails to pick from (the grid only).
+  `getKey`, `getLabel`, `getUrl`; `bind:selected` or, with `multiple`,
+  `bind:selectedKeys`. A single selection moves and is never cleared by a repeat
+  press. `ondelete` shows a delete button named after each item (focus moves to
+  the item that took its place); `getType`, `getPoster`, `loading`, `empty`
+  snippet, `emptyHeadingLevel` (default 3), `minTileSize` (96px), `strings`. One
+  Tab stop; arrow keys move by the columns on screen, Home and End within the
+  row, Delete asks to delete; "Use the arrow keys to move between items." is read
+  when focus enters the grid and shown below it while it has keyboard focus. The delete button sits on the end corner, mirrors
+  in RTL, takes taps in a 44px area and shows a pressed state on touch.
+- **Spinner**: the loading ring on its own. Sizes `xs` to `lg` (12, 14, 16,
+  20px); with a `label` it is a `status`, without one it is decorative; fades
+  instead of spinning under `prefers-reduced-motion`.
+- **Slider**: a native range input in the library's colours. `bind:value`,
+  `min`, `max`, `step`, label, helper or error text, three sizes, `showValue`,
+  `formatValue` (also `aria-valuetext`).
+- **UnsavedChangesBar**: Save and Discard while a form is `dirty`; sticky
+  (`position` `bottom` or `top`); `onsave` may return a promise (saving state;
+  a rejection keeps the bar and calls `onerror`); appearance announced politely;
+  never takes focus; focus returns to the edited field when it goes; `actions`
+  snippet. Warning before the page is left is your app's job.
+- **AppShell**: the phone layout. `header` snippet (AppBar), `<main>` content,
+  `footer` snippet (BottomTabBar), a `dvh` column inside the safe areas. Sets
+  `--app-shell-top-inset` and `--app-shell-bottom-inset` (fallbacks 57px and
+  65px) on itself and on `<html>` while mounted, for overlays in
+  `document.body`. `contentElement="div"` inside a page that already has a
+  `<main>`.
+- **AppBar**: a phone top bar with `title` (`headingLevel`, default 1;
+  `titleLines={2}` allows two lines), back control (`backHref` or `onback`,
+  `backLabel`), `leading` and `actions` snippets (up to two actions),
+  `collapseOnScroll` (stays while focus is inside; no animation under reduced
+  motion). The title always has at least 72px; a `leading` wider than the row is
+  held to the row. Parts carry `data-appbar-part` (`back`, `title`, `actions`);
+  the bar measures itself in the browser, so before hydration the title wraps to
+  the second row. At 180px wide no title shows beside a back control and two
+  actions.
+- **BottomTabBar**: three to five links with an icon above a short label.
+  `items` take `href`, `label`, `icon`, `badge` (read with the label: "Inbox, 3
+  new"; `badgeLabel`, `badgeMax`). `active` is an href or path (`aria-current=
+  "page"`); left out, the bar follows the browser address, so pass
+  `active={page.url.pathname}` on the server. Fixed on its own and in the flow
+  in an AppShell (`position`), clear of the home indicator. Tabs are at least
+  44px with 8px gaps; under 52px wide the labels hide (icon only, label stays
+  the accessible name); tabs go under 44px only when five do not fit. The
+  active tab has a 2px outline in the action colour. With five tabs labels stay
+  11 to 12px at 200% text.
+- **Rating**: one to `max` (default 5) stars, can be empty. `bind:value` is a
+  number or `null`; a radio group named by `label`, each star reads "4 of 5
+  stars"; arrow keys, Home and End; `name` submits it. A repeat press on the
+  selected star never clears it; `clearable` adds a clear button (Delete and
+  Backspace clear too). `readonly` shows a score as one image ("Quiz, 3.5 of 5
+  stars"), with fractions, `showValue`, `formatValue`; it submits nothing. 44px
+  targets at every `size`; `strings`; the empty star uses
+  `--color-control-border`.
+- **SegmentedControl**: two to four choices in one row. `options` (`value`,
+  `label`, `icon`, `disabled`), `bind:value`, `onchange`. A radio group, not
+  tabs: one Tab stop, arrows move and select, `name` submits, a repeat press
+  does nothing. `fullWidth` (default true), labels wrap, 44px tall on touch.
+- **BottomSheet**: a modal panel sliding up from the bottom. Snap points
+  (`snapPoints`, `"half"` and `"full"` by default; `bind:snap`); the grip drags
+  between them or down to close and is a button ("Expand" / "Collapse"). Content
+  scroll wins over dragging unless at its top. `title`, `description`, `footer`,
+  `isOpen`, `dismissible`, `portal`, `initialFocus`, `closeLabel`,
+  `onclose({ reason })` with the extra reason `"swipe"`. Safe areas, no animation
+  under reduced motion, a centred 40rem sheet from `md`. Half and full heights
+  are shares of what the on-screen keyboard leaves. The grip's focus ring is
+  drawn inside its 44px box; a click reaches the grip button, and flicks are
+  timed from the events' own times.
+- **StickyActionBar**: keeps a form's main action in view at the bottom of the
+  screen or scrolling box, rises above the on-screen keyboard, reserves
+  `scroll-padding-bottom`, never takes focus. One per scrolling box; a short
+  form needs `class="flex min-h-full flex-col"`.
+- **FloatingActionButton**: a round 56px primary button. `label` (required, the
+  accessible name), `extended`, `icon`, `href` (a link; a button otherwise),
+  `position` (`bottom-end` default, `bottom-start`, `bottom-center`). Above the
+  tab bar in an AppShell, above the safe area elsewhere; `--fab-bottom-offset`
+  lifts it; it reserves `scroll-padding-bottom` on what scrolls under it.
+- **DateField** and **TimeField**: the browser's date and time inputs in the
+  library's Input. `bind:value` is `YYYY-MM-DD` or 24-hour `HH:mm`, `""` when
+  empty; `label`, `hint`, `error`, `min`, `max`, `step`, `required`, `disabled`,
+  `readonly`, `size`, `name`; work in FormField; ids start with `input-`.
+  **`formatDate` and `formatTime`** (package root) format those strings for a
+  locale (`formatDate("2026-10-06", "sv")` is "6 okt. 2026"), never shift by the
+  time zone, and return `""` for empty or invalid.
+- **Calendar**: one month as an ARIA grid with event dots. `bind:month`
+  (`YYYY-MM`), `bind:selected` (`YYYY-MM-DD` or `null`), `events` (`date`,
+  `label`, `tone`; up to three dots a day), `weekStartsOn` (default Monday),
+  `locale`, `min`, `max`, `isDateDisabled`, `onselect`, `onmonthchange`,
+  `strings`. One Tab stop: arrows by day and week, Home and End within the
+  week, Page Up and Down by month (Shift: year). Days are named in full with
+  state and events and are 44px tall; unavailable days have a line through the
+  number. `locale` translates dates only, so pass `strings` for "today",
+  "selected", "unavailable". Pressing the selected day does nothing.
+- **DropdownItem**: the menu item as a component for a Dropdown's custom
+  `children`; takes its role from the Dropdown and joins the arrow-key order. A
+  DropdownItem with custom children and a description is named by its content
+  alone.
+- **Stepper**: progress through a multi-step form. `steps` (labels or `{ label,
+  description }`), `bind:current` (zero-based), `layout` (auto goes compact below
+  30rem of its own width: it suits about five short labels; compact segments are
+  narrower than 44px from seven steps with `interactive` on 320px), `size`
+  (`sm`, `md`, `lg`), `strings`. Completed steps show a check, the current one
+  its number, upcoming an outline; a navigation landmark with
+  `aria-current="step"`; a step change is announced once. `interactive` makes
+  completed steps buttons. It does not move focus: focus the new heading
+  yourself. In Safari 16 and older it needs a width from its parent in a flex
+  row.
+- **PhotoGrid**: square thumbnails that open a viewer. `photos` (`src`,
+  `thumbSrc`, `alt`, `width`, `height`, `caption`, `id`), `columns` (3, then 4
+  and 5), `max` ("+N" tile), `onopen(index)`, `onadd` ("Add photo" tile),
+  `selectable` (`"single"` or `"multiple"`, `bind:selected`,
+  `bind:selectedKeys`; a single selection is never cleared by a repeat press and
+  each tile gets an Open button). One Tab stop, lazy loading, placeholder and
+  failure fallback. **PhotoViewer**: a full-screen dialog for them, `bind:index`,
+  `bind:isOpen`, caption, counter, up to three `actions` (more in a menu).
+  Swipe or arrows change photo; pinch, double tap, Ctrl+wheel or `+`/`-` zoom;
+  drag pans; swipe down, Escape or the close button close it
+  (`onclose({ reason })`). Focus returns to the tile; the thumbnail shows
+  blurred until the full image loads; neighbours are preloaded; dark in both
+  themes; safe areas. Double tap is timed from the touch events. Previous and
+  Next at the ends keep their plate and dim only the arrow.
+- **Avatar** and **AvatarGroup**: `Avatar` is a round picture falling back to
+  initials (`name`, `src`, `size` `sm` 24, `md` 32, `lg` 48px, `alt`, `alt=""`
+  for decorative, `locale`); initials come from the first and last word, are in
+  the server markup and remain if the picture fails. They are `brand-200` on
+  `brand-700` in the default light theme (the subtle primary pair, 4.5:1).
+  `AvatarGroup` shows `people` overlapped as a list, up to `max` (default 4) and
+  "+3" (`strings.more`), `locale`. Not interactive.
+- **SwipeableListItem**: a row with one or two `actions` revealed by a swipe
+  towards the inline start (touch and stylus; mirrored in RTL); a swipe only
+  reveals, an action runs on press. The same actions are behind a "more"
+  button (`showMoreButton`, on by default; with `false` offer another route).
+  Bindable `open`, `onopenchange`, `strings.actions`; one row open per list.
+- **PullToRefresh**: wraps a list; pulling down at the top calls `onrefresh`
+  (touch only). Bindable `refreshing`, `disabled`, `threshold` (64px),
+  `strings`. A Refresh button shown on keyboard focus does the same; a status
+  region says "Refreshing" then "Updated". A rejected `onrefresh` ends the busy
+  state silently: report the failure in the app. In controlled mode it says
+  "Updated" whenever `refreshing` goes back to false.
+- **`focusToasts()`** moves focus to the newest toast; focus returns when it is
+  dismissed, also from inside an open overlay.
+
+#### Existing components
+
+- **ImageUpload**: `onbrowse` replaces the native chooser and
+  `event.preventDefault()` in `onclick` keeps it closed. A video value (file
+  type, extension, or `previewType`) renders a `<video>` with controls, never
+  autoplaying; a `preview` snippet replaces the preview. `label` and `id` (the
+  dropzone is a native `<button>`); Change and Remove are named from the label
+  ("Change logo") or `changeLabel` and `removeLabel`; the preview takes `alt`.
+  A dropped file is checked against `accept` and rejected through
+  `onfilereject`. Copy props: `browseText`, `changeText`, `removeText`,
+  `errorTitle`, `errorRecovery` (`false` leaves the line out), `selectedText`,
+  `removedText` ("Image selected" / "Image removed" are announced);
+  `actionsPlacement` (`"overlay"` or `"strip"`, strip by default for video).
+- **IconButton**: `xs` size (24px, the minimum target; use `sm` or larger where
+  touch is primary); `pressed` (bindable, `aria-pressed` and a pressed style in
+  every variant; `event.preventDefault()` in `onclick` keeps the state; left
+  undefined it renders no `aria-pressed`); `tone="danger"` on `ghost` or
+  `outline` for a quiet destructive style. `href` on Button and IconButton
+  renders a real link (`target`, `rel`, `download`); a disabled or loading link
+  has no `href` and is `aria-disabled`.
+- **Modal**: `portal` (renders in `document.body`; a theme class set below
+  `<body>` does not reach it); `onclose({ reason: "escape" | "backdrop" |
+  "close-button" })`; `dismissible={false}` (the close button stays focusable,
+  `aria-disabled`; setting `isOpen` still closes); `role="alertdialog"`;
+  `closeLabel` (default "Close"); `fullScreen` (or `"mobile"` below `md`);
+  `initialFocus` (also on SlideUp); typed `aria-describedby`, `aria-busy`,
+  `data-*`, `id`. SlideUp: `closeLabel`, `swipeToClose` (grip, downward swipe,
+  calls `onclick`), a `footer` snippet kept above the keyboard.
+- **Toast and Toaster**: `pushToast` takes `action: { label, onclick,
+  dismissOnClick? }` (a button in the toast, announced with the message, closes
+  after the handler unless `dismissOnClick` is `false`; the countdown pauses
+  while pointer or focus is on it; give it a long `duration` or `0`; the
+  `ToastAction` type is exported); `duration` takes `"short"` (3 s), `"medium"`
+  (7 s), `"long"` (14 s), `"persistent"` or milliseconds, with `defaultDuration`
+  on Toaster (`TOAST_DURATIONS`, `ToastDuration` exported); `strings` for every
+  built-in word (`ToasterStrings`, `DEFAULT_TOASTER_STRINGS`), `aria-label`,
+  `showCountdown`, `onpausechange({ id, paused })`, `data-paused`; `closeLabel`
+  on Toast and Alert; `--toaster-bottom-offset` (72px clears a
+  FloatingActionButton); other attributes pass to the region. A held finger
+  pauses a toast, lifting resumes with at least 3 s left. Toasts do not fly
+  under reduced motion; one with an action stays until dismissed.
+- **Dropdown**: options take `icon`, `tone: "danger"` and `description` (the
+  `DropdownOption` type is exported). `presentation` (`"auto"`, `"popover"`,
+  `"sheet"`; default `"popover"`): in a sheet the same menu opens in a
+  BottomSheet titled by the control's label; `<Dropdown presentation="sheet">`
+  is the library's action sheet (`sheetTitle`, `sheetSnap`, `sheetCloseLabel`,
+  `sheetExpandLabel`, `sheetCollapseLabel`, `fullWidth`, optional
+  `ariaLabelledby`). Menu boxes report `data-resolved-placement`.
+- **Select**: renders a real `<select>` on the server, the working control
+  before hydration and with scripts off; on mount the custom list takes over,
+  and a choice made before is kept and reported once; `presentation="native"`
+  renders only the native select. `presentation` (`"auto"`, `"popover"`,
+  `"sheet"`, `"native"`), `strings` (including `listLabel`;
+  `DEFAULT_SELECT_STRINGS`, `SelectStrings`, `SelectPresentation` exported,
+  also from atoms; the six text props still win). The chosen option has a check
+  mark at the inline end and a fill, and every option carries `aria-selected`.
+  A disabled Select submits its value once hydrated and not before; the inline
+  message of a `required` Select is the browser's, in the browser's language; a
+  label longer than one line is cut in the native select and wraps in the custom
+  one, so the field can grow by a line.
+- **Input, Textarea, Select**: `hint` and `error` (a hint is tied with
+  `aria-describedby`, an error sets the error state and is announced;
+  `variant` + `message` still work and your own `aria-describedby` is merged).
+  Input takes `leading` and `trailing` snippets and, for `type="password"`,
+  `revealable` (`revealLabel`, default "Show password", `aria-pressed`). Input,
+  Textarea, Select, Checkbox, Radio, Toggle and ThemeToggle accept their
+  element's native attributes (`autocomplete`, `inputmode`, `maxlength`,
+  `enterkeyhint`, `data-*`); Table and Text pass other attributes on. Toggle
+  takes `aria-label` and `aria-labelledby` ("Toggle" is only the last fallback).
+  `Checkbox` is exported from the atoms entry.
+- **Table**: `stacked` (or `"sm"`, `"md"`, `"lg"`) lays rows out as label and
+  value pairs and drops the 20rem minimum; put `data-label` on each cell and
+  keep the `<thead>`; `captionHidden` keeps the caption as the accessible name
+  but hides it. A stacked cell keeps several children together on the value
+  side; a cell without `data-label` puts its content there too; an empty cell
+  leaves no blank line.
+- **EmptyState**: `headingLevel` (1–6, default 2); `size="compact"` (tighter,
+  smaller title, a plain `<div>` not a named region; the default is still a
+  `<section>` named by its title).
+- **TopNavbar**: nav items take `external` (default true for absolute URLs);
+  `collapseAt` (`"sm"`, `"md"` default, `"lg"`, `"xl"`; `TopNavbarCollapseAt`
+  exported).
+- **Tabs**: `fullWidth` (for two or three tabs; scrolls when a share is too
+  small for the longest word). The rule under Tabs is `border-border`; a
+  selected pill uses `action-primary-subtle`.
+- **SidebarShell**: `mobile="drawer"` hides the sidebar below `lg` and opens it
+  in a Drawer from the start side: `bind:isOpen`, `trigger` snippet
+  (`aria-expanded` wiring), `drawerTitle`, `closeLabel`, `onclose({ reason })`;
+  it closes when a link is followed and when the screen widens past 1024px;
+  `label` names the scrolling region (default "Navigation links").
+  SidebarNavigation declares and passes these on. Default `mobile="none"`
+  changes nothing.
+- **Page**: `safeArea` (default true) pads left, right and bottom by
+  `env(safe-area-inset-*)`; nothing inside an AppShell or where the insets are
+  zero; your own `px-*` class replaces that side. Needs `viewport-fit=cover`.
+- **Tooltip**: `touchDuration` (default `0`); one open at a time; a tooltip on a
+  disabled button is tied to it with `aria-describedby`. Do not put essential
+  information in a tooltip.
+- **ColorPicker**: the colour map is two native sliders (saturation, lightness)
+  in one Tab stop, working by keyboard (Shift moves ten steps), touch and pen;
+  new strings `area`, `saturation`, `lightness`, `invalidHex`; the hue slider
+  shows its focus ring and is 44px on a coarse pointer.
+- **CodeBlock**: `copyLabel`, `copiedLabel`; "copied" is announced through a
+  status region. **FormField**: `requiredLabel`.
+#### Mobile and touch
+
+- New props for phones: `Page` `safeArea`, `Modal` `fullScreen`, `SlideUp`
+  `swipeToClose` and `footer`, `TopNavbar` `collapseAt`, `Tabs` `fullWidth`,
+  `Tooltip` tap, `Select` and `Dropdown` `presentation`, `SidebarShell`
+  `mobile="drawer"`, `Toaster` `--toaster-bottom-offset`. Components for them:
+  AppShell, AppBar, BottomTabBar, BottomSheet, Drawer, StickyActionBar,
+  FloatingActionButton, SwipeableListItem, PullToRefresh, PhotoViewer. Safe areas
+  need `viewport-fit=cover`.
+
+#### Accessibility
+
+- A focus ring in forced colours: `.focus-ring`, the legacy `.focus-brand` and
+  `.focus-nav`, and the checkbox and radio row draw an outline there. The
+  current page has an outline in forced colours in SidebarNavigation,
+  SidebarPanel and TopNavbar. In forced colours every option of a Select list
+  has the same border and the chosen one is told apart by its check mark only.
+- `docs/ACCESSIBILITY.md` has a "Library conventions" section (where focus goes
+  when a focused control is removed, the shared overlay stack and scroll lock,
+  disabled options, hover-revealed actions, focus in forced colours) and no
+  longer lists fixed issues as open; `docs/KEYBOARD_NAVIGATION.md` describes
+  what the components do.
+
+#### Strings and hydration
+
+- **`ZabiStringsProvider`**: wrap the app in `<ZabiStringsProvider
+  strings={…}>` and every component under it uses those words unless an
+  instance says otherwise. One entry per component with a `strings` object
+  (including `avatarGroup`, `swipeableListItem`, `pullToRefresh`), keyed by prop
+  name for components with single-text props (`toast`, `alert`, `codeBlock`,
+  `imageUpload`, `unsavedChangesBar`), and a `common` group (close, back, expand,
+  collapse, required, showPassword, search, confirm, cancel). Order, later wins:
+  built-in English, provider, the instance's `strings`, its own text props. It
+  is Svelte context (per request on the server, nestable, reaches portalled
+  overlays); Modal, Drawer, SlideUp, BottomSheet, Toaster, Rating and the
+  components above read it; landmark `ariaLabel`s are not covered.
+  `getZabiStrings()`, `DEFAULT_ZABI_COMMON_STRINGS` and the types are exported.
+  No translations ship; the README has a complete Swedish example. Nothing
+  changes outside a provider.
+- **Every built-in text can be replaced**: `strings` on TopNavbar,
+  SidebarFooter, SidebarAccountPanel, SidebarNavigation, SidebarBrandHeader,
+  ColorPicker, ContactForm, PropsTable, ComponentDemo, Select, Toaster, Stepper,
+  Calendar, MediaGrid, SortableList, Rating, PullToRefresh. The README's "Texts
+  and other languages" lists the prop for each component.
+- **A choice made before the page hydrates is kept.** A Checkbox, Radio,
+  RadioGroup, Rating, SegmentedControl or Select changed in the server's markup
+  was set back at hydration; the bound value now follows the native input and
+  the change callback fires once (a form reset still returns to the rendered
+  value). A bound Select value with no matching option is kept and submitted as
+  itself.
+- **No component drops keyboard focus on hydration** (Heading, Text,
+  CardHeader, AppBar's title, EmptyState's heading, Container, AppShell,
+  Collapsible); a guard fails the build if a dynamic element comes back.
+
+#### Package and build
+
+- Exports and package fields are listed under Upgrade notes. `zabi-components/types`
+  matches the components again (see Fixed). `npm run build:css` works in a fresh
+  checkout with no `dist/`.
+- The docs site honours `data-theme`, and Storybook's toolbar Theme control
+  drives its sidebar, toolbar and docs pages. `docs/theme-imports.md` says what
+  to expect when Tailwind and `zabi-components/css` are combined (the compiled
+  stylesheet carries its own copy of each utility, so import order decides: with
+  Tailwind in the app import `theme-only` and `theme-dark-only` instead).
+  `THEME.md` no longer tells apps to import the compiled stylesheet after
+  `theme-only` or to use `theme()` for a colour. `THEME_QUICK_REFERENCE.md`
+  shows the current primary colour and dark mirror; `docs/VARIANTS.md`, the
+  README, the Storybook introduction and the showcase guide cover the new
+  components. The component docs site examples are written in English. The
+  site's catalog sidebar is a drawer below 1024px and its "On this page" list
+  marks the section being read; the site sets `viewport-fit=cover`.
+
+### Changed
+
+- **Light mode has a visible surface ladder.** `--color-surface-base`,
+  `--color-page` and `--color-background-tertiary` move from `base-100` to
+  `base-150`; `--color-surface-elevated` from `base-50` to `base-100`; a card is
+  1.18:1 on the page (was 1.10) and a nested card 1.10:1 (was 1.04).
+  `--color-card-active` and `--color-surface-overlay-hover` are `base-150`.
+- **Light tinted fills read on a white card.** `--color-<family>-subtle` moves
+  from step 100 to 200 and `--color-<family>-border` from 200 to 300 for
+  success, warning, error, energetic and info (1.36:1 on a card, was 1.16);
+  `--color-neutral-subtle` is `base-250`, `--color-neutral-border` `base-300`;
+  `--color-action-primary-subtle` and `-subtle-hover` are `brand-200` and
+  `brand-300`.
+- **Light hover and secondary fills are stronger.** `--color-surface-hover` and
+  `--color-surface-active` are 9% and 15% ink (were 6% and 11%);
+  `--color-action-secondary`, `-hover`, `-active` are 10%, 15%, 20% (were 7%,
+  12%, 17%).
+- **Overlays have an edge in light** (`--color-border-overlay` is a 10% ink tint,
+  was transparent); **light shadows are stronger** (`--shadow-color` `24 24 27`,
+  `--shadow-opacity` 0.14; were `0 0 0` and 0.1).
+- **Light fields and disabled controls follow the new page**:
+  `--color-input-hover` `base-100`, `--color-input-disabled` the page colour,
+  `--color-action-disabled` `base-250`, `--color-action-disabled-border`
+  `base-300`.
+- **Focus tokens**: `--color-focus` is `brand-600` in both themes;
+  `--color-focus-weak`, `-medium`, `-strong` each move one step;
+  `--color-nav-menu-focus` follows `--color-focus`; `.focus-ring--muted` (ghost
+  and link buttons, the AppBar back control, the SortableList handle) reads
+  `--color-focus-ring-muted`, 3.7:1 or more on every surface level (dark was
+  `base-500`, 2.49:1 on elevated, 1.98:1 on overlay). Dark mode otherwise keeps
+  its values: `.dark` restates the values it used to inherit.
+- **Dark mapping**: `--color-action-primary-text` follows `--color-on-brand`;
+  dark `--color-base-*` steps alias the mirrored `--zabi-base-*` step; the dark
+  block holds no raw palette and no hex value.
+- **Menus share one edge and surface**: Dropdown, NavigationMenuContent and the
+  ColorPicker popover use `border-border-overlay` on `bg-surface-overlay` (the
+  ColorPicker popover no longer sits on the inset field colour in dark). Dropdown
+  menus and Select lists use the 16px overlay radius, and Select's search field
+  and options sit 4px closer to the list's edge. ColorPicker's popover and
+  NavigationMenu's panels use the overlay radius.
+- **Nested corners are concentric** where a rounded element sits closer to its
+  container's corner than that corner's radius: the Card in a Modal, the avatar
+  in SidebarFooter's profile button, MediaGrid's check mark (a rounded square)
+  and video badge, Alert's close button, ListItem rows in a `.list-group`.
+- Input, Textarea and Select text is 16px below 640px (also ColorPicker's hex
+  field and the search fields in Select and the sidebars); sizes unchanged from
+  `sm` up and control heights unchanged.
+- **Checked checkboxes and radios use the primary action fill**, tick and dot in
+  the primary button's text colour (was a paler step at 2.8:1 on the light page).
+- Input, Select and Textarea darken their border on hover in light
+  (`--color-input-border-hover`); error, success, warning and disabled fields
+  are unchanged. Select's trigger placeholder uses the placeholder colour.
+- Table and PropsTable sit on the card surface with an elevated header band;
+  Skeleton and Header's variant chips use `bg-neutral-subtle`.
+- Sidebar search fields, the selected panel item, the elevated panel and the
+  profile button use full-strength rings instead of 40–80% alpha ones; dashed
+  empty states keep only their dashed border. SidebarNavigation's search
+  placeholder keeps 4.5:1 on hover.
+- **Controls are 44px on touch** (`@media (pointer: coarse)`): Button, IconButton,
+  Input and the Select trigger at `sm` and `md` (`lg` is 48px already; use it
+  for the main action on a phone), and Slider rows, Checkbox, Radio and Toggle
+  rows, Tabs, Collapsible triggers, Dropdown items, Select options (48px),
+  NavigationMenu, TopNavbar and Sidebar items, SortableList controls and toast
+  buttons. The close buttons of Alert, Toast, Modal, SlideUp and Drawer and the
+  Toggle switch keep their size and take taps in a 44px area. IconButton `xs`
+  stays 24px.
+- **Every pressable control shows a `:active` state**; a disabled Toggle or Tab
+  no longer shows one. A toggled-on ghost, outline, link or danger-tone
+  IconButton shows a pressed fill distinct from hover and 1.25:1 or more from
+  rest. The selected pill Tab's pressed fill is 1.42:1 from rest (was 1.24:1)
+  and its label keeps 4.89:1.
+- SlideUp pads its content for the bottom safe area and is at most `90dvh`
+  (was `90vh`); Modal is at most `90dvh`.
+- **Tabs scroll sideways when they do not fit**, with a fade on the edge that has
+  more, and bring the selected and keyboard-focused tab into view; labels no
+  longer wrap or squeeze.
+- **Toasts**: sit above the tab bar and home indicator (the stack clears
+  `--app-shell-bottom-inset` and the bottom safe area; below `sm` it spans the
+  width with 16px gutters; a `viewport` Toast at the top clears the top safe
+  area and an AppShell header); keep clear of an overlay's footer (16px above
+  it, or at the top when there is no room; a centred desktop Modal changes
+  nothing); take the larger free stretch above the panel or between header and
+  footer, scrolling there, without covering an overlay's title and close button;
+  sit above the on-screen keyboard; `--toaster-bottom-offset` is not added on top
+  of an overlay's footer. Tab moves from an overlay's last control to the toast
+  controls and back, and Escape in a toast returns focus without closing the
+  overlay. Padding, gaps and button targets are in px and the status icon stays
+  20px at enlarged text (a two-sentence toast at 375px and 200% text is at most
+  420px tall, was 594px); buttons wrap under the title when it would get less
+  than 8rem; the stack is capped to the screen and scrolls. The countdown says
+  "1 second", not "1 seconds".
+- **Tooltip**: flips or slides to stay 8px inside the viewport, also with a
+  mouse; below 640px a `left` or `right` tooltip opens above or below; a tap
+  opens it when the finger comes up where it went down, so a scroll that starts
+  on the trigger no longer flashes it; `data-placement` reports the side used.
+- **Overlays stay above the on-screen keyboard** where it covers the page; the
+  focused field is scrolled into view.
+- **Overlay headers stay compact at large text sizes.** In BottomSheet, Modal,
+  Drawer and SlideUp the header's padding, gaps, grip and close button are in px
+  and the title grows to 1.3 times and stops; at 200% text a half-height sheet
+  gives the content 378 of 576px (was 182). Titles break at a hyphen in the
+  page's language and a too-long word no longer sticks out of Drawer or SlideUp.
+- **Select fills its container** and no longer changes width with the chosen
+  option; its trigger is a `combobox` reporting `aria-invalid` (with `error`, the
+  error variant or a failed `required` check), `aria-required` and `aria-busy`;
+  `required` blocks an empty form, shows the browser's message as the error and
+  focuses the trigger; a long label wraps; the form control is a `<select
+  name>`; a reset returns it to its rendered value; it opens as a sheet on a
+  phone; the chevron and the Dropdown panel do not animate under reduced
+  motion; keyboard focus in the native select moves to the trigger at handover;
+  `aria-label` and `aria-labelledby` name the native select too; with several
+  empty required Selects only the form's first invalid control takes focus.
+- **A loading Button or IconButton** is `aria-disabled` and `aria-busy` (see
+  Upgrade notes); a loading link keeps its place in the Tab order. Button labels
+  wrap (`min-height`: 32, 40, 48px; 44px minimum on touch).
+- **A disabled Dropdown option stays focusable** (`aria-disabled`).
+- **A toast with an action stays until dismissed** unless given a `duration`;
+  with no duration a toast closes after 7 s (see Upgrade notes); a message with
+  no title is the toast's text.
+- **ThemeToggle** (two modes) has the name "Dark mode" and applies the stored
+  choice on mount in both modes; it no longer writes an inline `color-scheme`
+  and removes a stale one, so adding or removing `class="dark"` from your own
+  script moves native controls with the tokens.
+- **EmptyState at `size="compact"`** is a plain `<div>`.
+- **ImageUpload** fills its container; `id` names the control; Change and Remove
+  appear on `:focus-visible` (not any focus), wrap and truncate in a narrow
+  container, stay visible on coarse pointers and where hover is unavailable, and
+  sit on an opaque plate so "Change" is readable over any image (it was 2.59:1 in
+  dark over a light image).
+- **`font-sans` and `font-mono` follow the theme.**
+- **A List row with nothing to do is plain content**; a disabled plain ListItem
+  row no longer carries `aria-disabled`.
+- Checkbox and Radio inputs are stretched invisibly over their box.
+- Textarea and Select status messages use the same text colour step as Input's.
+- **Icons are imported one file at a time** from `@lucide/svelte/icons/<name>`,
+  not the `@lucide/svelte` barrel: an app importing one Button from the root
+  compiles 366 modules where it compiled 3,800 (233 from
+  `zabi-components/atoms`). The re-exported icons keep their names.
+- The `viewport` prop on NavigationMenu only sets `isMobile` on the context for
+  your own children; it has no effect of its own, and the docs now say so.
+- **`Toast`/`Alert`/`CodeBlock`/`ImageUpload`/`UnsavedChangesBar`** follow
+  `ZabiStringsProvider`.
+
+### Deprecated
+
+- **Modal's `onclick` is deprecated as a close signal.** It is still called with
+  the event on Escape, a backdrop click and the close button; use `onclose`.
+- In `zabi-components/types`, members that were exported but never existed
+  (`open`, `className`, `position`, Button's `ariaLabel` and icon props) stay as
+  optional and deprecated so existing code keeps compiling.
+
+### Fixed
+
+- **`strings` props and `ZabiStringsProvider`:** a key set to `undefined` keeps
+  the English default instead of blanking the text (`null` and an empty string
+  are still honoured).
+- **`Progress`:** a passed `id` is on the wrapper only (it appeared on the
+  wrapper and the bar); `aria-valuenow` is clamped to 0..`max`; a non-positive
+  or non-finite `max` falls back to 100; new `aria-label` and `aria-labelledby`
+  props name the progressbar.
+- **`ColorPicker`:** Escape closes the popover and returns focus to the swatch
+  (and does not close a Modal around it); opening by keyboard moves focus in;
+  typing a hex redraws the colour map; with a `label`, the hex input and swatch
+  are named by it. Its popover could be placed below the viewport at 320px; a
+  press on a toast no longer closes it.
+- **`Select`:** the popover listbox is named by the field's label (still "Select
+  options" with no label); **`Dropdown`** gets an optional `ariaLabelledby`
+  prop. Arrow keys get past a disabled option. The Select trigger's pressed
+  state shows in light (was the resting fill) and is 1.27:1 against rest in
+  light and 1.31:1 in dark (was 1.10:1). A Select no longer changes its value
+  when the page hydrates. A disabled Select dims its value. Dropdown and Select
+  return focus to the trigger when the menu closes from inside it; focus your
+  own handler moved elsewhere is left alone. A Select list and a Dropdown menu
+  are one Tab stop: Shift+Tab goes to the search field in one step, and a
+  character typed on an option goes to the search field or the matching item.
+  A press on a toast no longer closes an open Select or Dropdown.
+- **`SwipeableListItem`:** a long action label wraps (it was clipped at the start
+  at 200% text), the action area is capped at two thirds of the row, and the
+  "more" button stays 44px at any text size. With `showMoreButton={false}` focus
+  has nowhere to return to after an action.
+- A long Modal title no longer squeezes the close button or runs out of the
+  panel (the title wraps, also inside a single long word; the close button keeps
+  32px).
+- A Tooltip with `strategy="fixed"` no longer covers its trigger when it opens
+  above or to the left; a closed tooltip no longer widens the page; it has an
+  edge in forced colours, is centred correctly in RTL and its arrow points at its
+  trigger in RTL; only one tooltip is open at a time and the pointer can cross a
+  diagonal to its far corner. Escape with a tooltip showing dismisses the
+  tooltip only, not the modal or sheet it sits in.
+- A Dropdown stays on screen: measured before paint, it flips when the preferred
+  side does not fit, slides back when neither does and is capped to the viewport
+  with its own scroll only when it must be (8px margin). `placement` is still
+  the preferred side; a menu that fits is positioned as before. A Dropdown, Select
+  list or NavigationMenu panel is no longer cut off by a scrolling or clipping
+  ancestor such as a Modal's content (the nearest clipping ancestor decides the
+  side; when it fits on neither it is positioned against the viewport; an
+  ancestor with a transform or filter cannot be escaped), and a menu leaves a
+  clipping container only when that puts it on screen. A height-capped Dropdown
+  scrolls inside its rounded panel. Dropdown follows the writing direction
+  (`bottom-start` and `top-start` sit on the start edge, item text aligns to it).
+- NavigationMenu fits a narrow screen: the list wraps onto further rows and a
+  content panel slides back inside the viewport. A press on a toast no longer
+  closes a NavigationMenu panel or the TopNavbar menu.
+- TopNavbar's phone menu closes after a link in it is followed, when
+  `currentPath` changes, on Escape (focus returns to the menu button), on a click
+  or focus move outside the bar and when the screen widens past the breakpoint;
+  a press on a control behind the open menu still reaches it. It is at most as
+  tall as the screen below the bar and scrolls, allows for the top safe area,
+  its links fill the row, and `aria-controls` on the menu button is set only
+  while the menu exists. The menu button stays on screen with a long brand or
+  enlarged text (the brand truncates below the breakpoint).
+- Toasts fit a 320px screen (the 18rem minimum width no longer overflows); the
+  close button takes taps in its full 44px area; `aria-controls` on the expand
+  button is set only while the detail is open; focus no longer falls to the page
+  after "Okay" or "Click to stop" is pressed; dismissing the focused toast moves
+  focus to the next toast or back to where it was; a tap neither sticks nor
+  dismisses; toasts do not fly in or out under `prefers-reduced-motion`.
+- A disabled Checkbox, Radio or RadioGroup row no longer dips, changes fill or
+  shows the pressed fill when pressed or hovered; stacked checkbox and radio
+  rows no longer overlap on touch; the row shows its hover
+  (`--color-surface-hover`, `--color-surface-active`, was a fixed `base-100`).
+  Checkbox shows its loading ring (replacing the tick, fading under reduced
+  motion).
+- Alert's close button shows the library's focus ring and mirrors in RTL.
+- State variants beside a semantic colour class work: the hand-written colour
+  classes sit outside every cascade layer, so `text-description
+  hover:text-headline` never changed on hover. Thirteen such variants the
+  components use are restated by hand (the hover colour of close buttons, the
+  hover border of outline buttons, the disabled text colour of fields and ghost
+  buttons).
+- Accent hover and pressed states work: `hover:bg-accent-hover` and
+  `active:bg-accent-active` did nothing next to `bg-accent`.
+- An overlay opened later is always on top: Modal and SlideUp take a z-index
+  that grows with the number of open overlays, so a modal opened from a portalled
+  one no longer opens behind it; a modal opened while a portalled drawer is open
+  (and the reverse) is drawn on top.
+- Modal and SlideUp keep Tab inside, and still close on Escape, when focus has
+  fallen out of the dialog because the focused control was disabled or removed.
+  A modal or sheet with nothing focusable takes focus itself. Modal, Drawer,
+  SlideUp and BottomSheet no longer take focus from content that focused itself
+  inside the panel as it opened. Focus returns to a replaced element (the one
+  that now has the opener's id) instead of `<body>`. Modal and SlideUp do not
+  slide in under `prefers-reduced-motion`.
+- The focus ring survives a shadow: `.focus-ring` on an element with a `shadow-*`
+  or `ring-*` utility (also `shadow-none`) drew no ring (the SidebarNavigation
+  search field, the selected SidebarPanel row, an interactive Card, any
+  IconButton given a shadow); it now composes. A List no longer clips the focus
+  ring of its rows.
+- Placeholder contrast: placeholder text and the format hint of an empty
+  DateField or TimeField was 3.40:1 on a dark field and 4.40:1 on a hovered light
+  one; see Upgrade notes. A disabled field's placeholder is no stronger than a
+  disabled value.
+- Native controls follow the dark theme under `.dark` as well as `data-theme`
+  (scrollbars, date and time pickers, other native form controls, autofill); a
+  page that sets `color-scheme` on `<html>` keeps its value.
+- Hover colours no longer stick after a tap: the hand-written `:hover` rules in
+  the theme files (`.bg-action-primary:hover` and 41 more) now sit in `@media
+  (hover: hover)`.
+- ImageUpload keeps keyboard focus (to Change after a selection, to the dropzone
+  after Remove, untouched when focus is elsewhere), cancels a file dropped while
+  `disabled`, its actions layer no longer takes clicks meant for the preview, its
+  error message is tied to the Change button when a preview is showing, and a
+  disabled dropzone no longer takes the primary border on hover.
+- ActionPanel shows its hover and pressed states (the fill is drawn over the
+  card). A selected Tabs pill shows its pressed state and a selected List row its
+  selected border. ListItem rows show a hover and a pressed fill.
+  SidebarFooter's avatar ring used a colour token that does not exist and now uses
+  the border colour. A `dark:` variant in Section's accent background, which
+  followed the OS setting and never applied, was removed.
+- ThemeToggle shows the right icon before it mounts (both icons are in the
+  markup and the `dark` class picks one); it works with `data-theme`.
+- ConfirmDialog no longer draws a focus outline around the whole dialog while
+  loading and sets no `aria-busy` on the panel.
+- A Badge with a long label wraps: it is at least 20, 24 or 28px tall, grows when
+  the label wraps and is never wider than its container; a one-line badge is
+  unchanged to the pixel and a wrapped one reads as a rounded rectangle.
+- An AppBar's title is never squeezed out (see AppBar).
+- Keyboard focus is visible in forced colours (see Accessibility).
+- **`zabi-components/types` matches the components again.** Every exported
+  `*Props` interface declares the props its component accepts today: `ModalProps`
+  has `isOpen`, the interfaces have `class`, and the new props are there.
+  `SelectProps.options`, `AlertProps.message` and `TooltipProps.content` are
+  optional, as on the components.
+- A bindable prop bound to `undefined` no longer stops the page from hydrating
+  (RadioGroup threw, and 36 other bindable props could); see Upgrade notes.
+- Button and IconButton (including `variant="accent"`) do not scale when pressed
+  under `prefers-reduced-motion`; built-in loading rings (Button, IconButton,
+  Input, Textarea, ActionPanel, Toggle) fade instead of spinning, Checkbox's
+  ring stops; Toggle's loading ring has its gap back.
+- Input, Textarea and Select no longer point `aria-describedby` at a message that
+  is not rendered.
+- `fullWidth` Tabs scroll instead of breaking a word; BottomSheet's grip answers
+  a mouse click; a flick on a sheet is measured from the events' own times.
+- Drawer content clears the home indicator; MediaGrid's remove button shows a
+  pressed state on touch; SidebarAccountPanel's three-mode theme row follows a
+  theme changed elsewhere; CodeBlock announces "copied".
+- The brand menu in the docs site header stays on screen (it opened past the
+  right edge at 768px and 1024px); the Pine and Citron accents follow the Iris
+  recipe in light (fill at step 600 with a white label, focus ring at step 600;
+  Pine's light ring was 1.93:1 on the page, now 4.19:1); `theme-color` follows
+  the theme toggle; the site's cards carry `shadow-sm` and the showcase uses
+  surface tokens in place of raw ramp steps.
+- README links to RELEASING.md point at the repository, and the README says to
+  install `@lucide/svelte` and import icons per file.
+
+## [8.0.1] - 2026-09-29
+
+Fixes the documented setup. In 8.0.0 (and 7.0.2) the three-line Tailwind setup
+from the README left components unstyled; `@import "zabi-components/css"` was
+the only import that worked. No tokens or `exports` paths were added, removed
+or renamed.
+
+### Fixed
+
+- **Theme files are valid CSS again.** `theme`, `theme-only`, `theme-dark` and
+  `theme-dark-only` were written without semicolons between declarations, so a
+  CSS parser read all 355 tokens as one declaration. `scripts/build-css.js` now
+  terminates each declaration.
+- **`theme` and `theme-only` carry an `@source` directive** for the package's
+  own components. Tailwind CSS v4 does not scan `node_modules`, so the classes
+  the components use were never generated. No `@source` line is needed in your
+  own CSS.
+- **`theme` and `theme-only` ship the hand-written component rules**:
+  `.focus-ring` and its variants, `.text-action-primary`, the action hover,
+  active and disabled states, the semantic colour classes and the `z-*` scale.
+  These existed only in the compiled `css` bundle. Without them a primary
+  button's label took the colour of its fill, and nothing had a focus ring.
+- **ColorPicker renders on the server.** Its teardown ran in `onDestroy`, which
+  also runs during SSR, and threw `window is not defined`. It is now returned
+  from `onMount`.
+- **Progress has an accessible name.** Its label was a `<label for>`, which
+  only names form controls, so screen readers announced a progressbar with no
+  name. The label is now referenced through `aria-labelledby`.
+
+### Changed
+
+- The universal-selector scrollbar rules (`* { scrollbar-width: thin }` and the
+  `*::-webkit-scrollbar` family) are in the compiled `css` bundle only, not in
+  the theme files, so importing a theme does not restyle every scrollbar in
+  your app. `.scrollbar-semantic` is in both and is the opt-in.
+- `theme` and `theme-only` grew from about 22 kB to about 35 kB.
+- `scripts/validate-theme.js` parses the theme files instead of pattern-matching
+  them, and fails the build if the token block does not parse or the component
+  rules are missing. The old check passed on the broken files.
+
+### Migration
+
+Nothing to change if you import `zabi-components/css`. If you worked around the
+broken theme files with your own `@source` line or your own copies of
+`.focus-ring` or `.text-action-primary`, you can remove them.
+
+## [8.0.0] - 2026-09-22
+
+Consolidates two development cycles. 7.1.0 and 7.2.0 were both prepared but
+never published, so the last release on npm is 7.0.2 and everything below ships
+together in 8.0.0.
+
+### Breaking changes since 7.0.2
+
+What can break a working 7.0.2 consumer. Each item is detailed in the sections
+that follow.
+
+- **The `zabi-components/react` subpath is gone** from `exports`. It pointed at
+  `dist/react`, which was never built, so importing from it already failed at
+  resolution — but the subpath no longer exists at all.
+- **Three tokens were removed**: `--color-action-primary-disabled`,
+  `--color-action-secondary-disabled`, `--color-action-danger-disabled`. Use the
+  shared `--color-action-disabled`, `--color-action-disabled-text` and
+  `--color-action-disabled-border` instead. Your own CSS referencing the old
+  names will silently resolve to nothing, so grep for them before upgrading.
+- **Every chromatic ramp was regenerated** against a shared lightness curve, and
+  the semantic families moved from step 500 to step 600. Rendered colour changes
+  throughout, in both themes, with no opt-out. Screenshot tests will all churn.
+- **`max-w-*`, `w-*` and `min-w-*` with `xs`–`2xl` resolve to container sizes
+  again** (`max-w-lg` is 32rem, not 1.5rem). This is a bug fix, but anyone who
+  compensated for the broken values in their own CSS must undo that.
+- **No install scripts run in consumer installs.** The `postinstall` hook is
+  gone; it is now a dev-only `prepare` script and is not in the tarball.
+
+Not breaking, but worth knowing: the published tarball no longer contains
+`dist/lib/**`. Those were declaration files for this repo's demo site and
+showcase, emitted by mistake; no `exports` entry ever pointed at them.
+
+### Design system
+
+Outcome of a full design review of all 63 components. The headline change is
+that the colour ramps are now generated against one shared lightness curve, so
+the semantic families read as a single family instead of six unrelated colours.
+
+#### Colour — BREAKING (visual)
+
+- **All chromatic ramps regenerated** (`brand`, `citron`, `pine`, `iris`,
+  `warning`, `error`) against a shared CIE L\* curve defined in
+  `tokens/chromatic-scales.js`. `<ramp>-600` now means the same lightness in
+  every ramp. Previously the ramps spanned L\* 34.6–75.0 at step 500 — a
+  40-point spread at the same nominal step — and `pine` fell 29.8 points between
+  400 and 500, which made half that ramp unusable.
+- **Semantic tokens moved to step 600** across the board. `warning`, `error` and
+  `energetic` previously sat at step 500 (the dark mirror's fixed point) and so
+  did not invert between themes at all, while `success` and `info` did. Solid
+  badges were 2.15:1 (warning) and 1.97:1 (energetic) in light mode.
+- **New per-family tokens**: `--color-<family>-subtle` (step 100),
+  `--color-<family>-border` (step 200). `--color-<family>-text` is now step 700
+  for every family.
+- **`--color-action-primary` is now `brand-600`** (was `brand-950`). The primary
+  action carries the brand colour in both themes.
+- **`--color-action-primary-active` no longer jumps across the ramp.** It was
+  `brand-400` against a `brand-50` label — 1.66:1, so the label vanished while
+  the button was held. Hover/active now step darker in light, lighter in dark.
+- **`--color-action-secondary`** is a neutral alpha tint instead of a 10% brand
+  wash, which was too pale to read as a control.
+- **New**: `--color-action-disabled`, `--color-action-disabled-text`,
+  `--color-action-disabled-border` — one quiet neutral pair shared by every
+  variant. Disabled was previously `brand-500` + `opacity-50`, which made a
+  disabled primary *lighter and more colourful* than an enabled secondary.
+- **New**: `--color-surface-hover`, `--color-surface-active` — surface-relative
+  alpha tints. `hover:bg-base-100` resolved to exactly `--color-surface-base` in
+  dark mode, so ghost buttons had no hover feedback on the app shell.
+- **New**: `--color-control-track{,-hover,-active}` for switch rails.
+- **Removed**: `--color-action-{primary,secondary,danger}-disabled` (use
+  `--color-action-disabled`); the raw-hex `.dark` danger overrides (danger now
+  mirrors through `--color-error-*` like every other family).
+- `--color-input` is now a raised surface (white in light, an inset step in
+  dark) rather than a grey well that read as disabled.
+- `--color-input-placeholder` is wired up — it was defined but unused.
+- `--color-link` moved to `brand-700`: `brand-600` cleared AA on a card but only
+  managed 4.42:1 on the page surface.
+
+#### Geometry — BREAKING (visual)
+
+- **One control height scale**: `sm` 32px, `md` 40px, `lg` 48px, shared by
+  Button, IconButton, Input, Select and Textarea. They previously rendered at
+  40/48/64, 32/40/48 and 38/46/50 — a `lg` Button stood 14px taller than the
+  `lg` Input beside it.
+- **Four role-based radii** replace eight t-shirt radii: `--radius-control`
+  (8px), `--radius-container` (12px), `--radius-overlay` (16px),
+  `--radius-pill`. Radius no longer changes with size. `--radius-sm/md/lg/xl`
+  remain as legacy aliases for consumer overrides.
+- Button type is monotonic again: weight is `font-medium` at every size (it used
+  to drop to `font-normal` at `lg`, so the biggest button had the lightest
+  label), and the arbitrary letter-spacing values are gone.
+- **Elevation is two steps**, not four. `shadow-sm` means raised (cards, tables,
+  sidebars, toggle knobs), `shadow-lg` means floating (modals, sheets, menus,
+  toasts); `shadow-none` stays the explicit absence of one. `shadow-md` and
+  `shadow-xl` are gone, and so is the bare `shadow` on the Toggle knob, which
+  resolved to a Tailwind default `app.css` never defined. An elevated Card no
+  longer deepens its shadow on hover — it was already at the floating step, so
+  the hover now changes background only.
+- **Layout spacing snaps to the 4px grid.** 30 half-step utilities
+  (`gap-1.5`, `gap-2.5`, `px-2.5`, `px-3.5`, `py-2.5`, `space-y-1.5`, …) were
+  setting a second rhythm against the first across forms, sidebars and badges.
+  Margins are deliberately exempt: `mt-0.5` beside a first line of text is an
+  optical alignment nudge, not rhythm, and Alert, ListItem, ToasterToast and the
+  radio control still use it.
+- A one-row `Textarea` is now 40px like the `Input` beside it (was 44px, from
+  `py-2.5`).
+
+#### Components
+
+- **`Badge`**: rebuilt. New `emphasis` prop (`subtle` | `solid`, default
+  `subtle`), plus `class`, `children` and `...restProps` — none of which existed,
+  despite stories shipping for two of them. Pill radius instead of 2px. Renders
+  nothing when it has no label, rather than leaving an empty box.
+- **`Alert`**: tinted fill + tinted border instead of a bare 1px outline on a
+  transparent ground; full-width by default with a new `inline` prop; one Lucide
+  icon family instead of hand-rolled SVGs of mixed weight.
+- **`Heading`**: no longer hardcodes `font-family: "Nunito Sans"` in a local
+  `<style>` block — it uses `--font-family-sans`, so rebranding the font token
+  now actually rebrands headings. `level` is typed `1 | 2 | 3 | 4 | 5 | 6`
+  instead of `number`; new `size` prop decouples visual size from semantic
+  level; `children` snippet supported; display sizes carry negative tracking.
+- **New `SidebarShell`**: the chrome of a sidebar with the regions left open —
+  width, surface, collapse behaviour, the shared inset and a scrolling middle.
+  Regions are snippets (`header` / `children` / `footer`), each handed
+  `{ collapsed, insetX }`. `SidebarNavigation` is 39 props on one component and
+  is excellent right up until your sidebar is not shaped like that one, at
+  which point none of the parts are reachable; compose `SidebarBrandHeader`,
+  `SidebarNavSection` and `SidebarFooter` into the shell instead and skip the
+  ~30 props you never set. `SidebarNavigation` is now built on it rather than
+  duplicating the chrome, so the two cannot drift. Additive — its prop API is
+  unchanged.
+- **`SidebarNavigation`**: its Props table documented 7 of 39 props. All 39 are
+  documented now, with types and defaults.
+- **`Text`**: now sits on the same type ramp as `Heading` rather than carrying
+  its own — `size="md"` matches an `h6` and `size="lg"` an `h5`, line box
+  included, and a new `xs` step (12px) extends the bottom. Leading is stated
+  rather than inherited from Tailwind's defaults, so the shared steps stay
+  locked together if the scale is retuned. **New `weight` prop** (`normal` |
+  `medium` | `semibold` | `bold`) lets body copy carry emphasis without being
+  promoted to a heading; `tone="label"` defaults to `medium`, every other tone
+  to `normal`. Purely additive — existing `sm`/`md`/`lg` call sites are
+  unchanged visually.
+- **`Input`**: raised surface, quieter placeholder, `min-w-48` removed.
+- **`Card`**: radius no longer scales with size; `outlined` uses `border-border`.
+
+#### API consistency
+
+- **Class overrides actually win now.** `class` being "merged last" only held
+  for properties the component didn't already set: `rounded-control` and
+  `rounded-container` are equal-specificity utilities, so the winner was
+  whichever Tailwind emitted later. The sidebar's search field asked for
+  `rounded-container` and rendered at 8px. Every component now merges through
+  `cn()` (tailwind-merge, a new runtime dependency), with the role-based radii
+  declared explicitly since `control`/`container`/`overlay`/`pill` are role
+  names rather than scale values that tailwind-merge could recognise.
+- **`class` is now the public prop on every component.** 25 components exposed
+  `className`, 15 exposed `class`, and 21 exposed neither. `className` is kept
+  everywhere as a deprecated alias and both are merged, so existing call sites
+  keep working.
+- Every component spreads `...restProps` onto its host element.
+- `Button`: `fullWidth` replaces `isFullWidth` (deprecated alias retained).
+
+#### Guardrails
+
+- **New** `scripts/check-ramp-lightness.js` — fails if a ramp drifts off the
+  shared curve (±1.5 L\*) or develops a cliff (>15 L\* between adjacent steps).
+- **New** `scripts/check-contrast.js` — resolves every fill/foreground pair a
+  component can render, in both themes, and fails below WCAG AA. 84 pairs.
+- **New** `scripts/check-control-geometry.js` — fails if controls disagree on
+  height, or if any component uses a t-shirt radius.
+- **New** `scripts/generate-ramps.js` + `tokens/chromatic-scales.js` — ramp
+  generation, wired into `npm run sync:tokens`.
+- `scripts/check-token-violations.js` now also rejects fixed ramp steps in
+  interaction states (`hover:bg-base-*`, `active:bg-base-*`), which is how the
+  invisible ghost hover got in.
+- **New** `scripts/generate-surfaces.js` + `tokens/surface-ladder.js` — the four
+  dark surface levels are now derived from one wash ladder instead of four
+  independently tuned hex values, and regenerate with `npm run sync:tokens`.
+  `--color-surface-elevated` moves `#35353a` → `#363638` and
+  `--color-surface-overlay` `#44444c` → `#454547` (slightly less blue); base and
+  raised were already exactly on the ladder.
+- The ramp-interaction rule now also scans `src/lib/marketing` and the landing
+  route. The rest of the checks guard what ships in the package, but
+  `hover:bg-base-100` had reached two marketing specimens, where dark mode
+  painted the hover darker than the card it sat on.
+- `scripts/check-token-violations.js` also rejects **off-scale shadows**
+  (anything but `shadow-sm` / `shadow-lg` / `shadow-none`, including a bare
+  `shadow`) and **half-step spacing** on gap/space/padding utilities. Margins
+  are exempt by design. Comment lines are skipped so prose about shadow DOM
+  doesn't trip it.
+- New scripts: `npm run check:ramps`, `check:contrast`, `check:geometry`, and
+  `check:design` (all four). `build:css` and `check` run `check:design`.
+
+#### Stories
+
+- `Badge` → `AllVariantsWithIcons` no longer crashes. It used an invalid CSF
+  render shape (`Component: 'div'` with a `children` array) cast through
+  `as any`, so TypeScript could not catch it and it threw at runtime. Replaced
+  with real harness components, which also fixes `WithChildren` and
+  `WithCustomClass` (both silently rendered nothing).
+
+### Forms
+
+- **`ContactForm`**: invalid submissions no longer fall through to a native POST and page reload.
+- **`ImageUpload`**: `onchange` / `onclick` are now actually called; `value` supports `bind:value`; new `onfileselect({ file, url })` exposes the selected `File`. Change/Remove actions are visible on keyboard focus, and Space activates the drop zone.
+- **`ColorPicker`**: 3-digit hex (`#f00`) is parsed correctly; `value` supports `bind:value`.
+- **`Form`**: accepts standard form attributes and a `novalidate` prop; docs note that `onsubmit` handlers must call `preventDefault()` for client-side handling.
+
+### Widgets
+
+- **`Tabs`**: Arrow/Home/End move focus as well as selection; the tablist is no longer an extra tab stop; `activeTab` supports `bind:activeTab`.
+- **`Select`**: new `name` prop renders a hidden input for native form submission; the search field sits outside the `listbox`; string/number option values compare consistently.
+- **`Dropdown`**: new optional `header` snippet; Home/End/Space behave normally inside text inputs in the menu.
+- **`Toggle`**: new `id`, `name` and `value` props for label pairing and form submission.
+- **`ThemeToggle`**: a consumer `onclick` no longer overrides the toggle; pre-mount placeholder respects `size`/`variant` (no layout shift).
+
+### Overlays
+
+- **`Modal` / `SlideUp`**: `role="dialog"` moved from the backdrop to the panel; body scroll locked while open (nested-safe); focus trap picks up content added while open; Escape closes only the topmost dialog. `Modal` gains `showClose` (default `true`) so untitled modals still have a close button.
+- **`Toaster`**: countdown is no longer announced every second; it pauses on hover/focus; no double announcements from nested live regions.
+- **`NavigationMenu`**: fixed a leaked document `mousedown` listener; panels use the disclosure pattern (no `role="menu"` / `aria-haspopup`); new `ariaLabel` prop.
+- **`Dropdown`**: arrow keys, Home and End now reach `menuitemradio` and `menuitemcheckbox` items. The item query matched only `menuitem` and `option`, so a menu built from radio items had nothing to focus: opening it by keyboard focused nothing and Tab closed it, leaving the items unreachable.
+- **`Alert`**: `closable` now hides the alert; new bindable `open` prop.
+- **`Tooltip`**: Escape no longer steals focus; CSS custom properties no longer leak onto `:root`.
+- **`util/ssr-safe`**: timer helpers typed with `ReturnType<typeof setTimeout/setInterval>` instead of `NodeJS.Timeout`, so consumers don't need `@types/node`.
+
+### Surfaces
+
+- **New semantic surface elevation tokens** (both themes), lowest → highest: `--color-surface-base` (page), `--color-surface-raised` (cards, panels, sidebars), `--color-surface-elevated` (nested cards, hover/active fills), `--color-surface-overlay` (modals, sheets, menus, toasts), plus `--color-surface-overlay-hover` (row/icon hover inside overlays) and `--color-border-overlay` (1px overlay edge: transparent in light, visible in dark). Utilities: `bg-surface-base`, `bg-surface-raised`, `bg-surface-elevated`, `bg-surface-overlay`, `bg-surface-overlay-hover`, `border-border-overlay`.
+- **Dark mode elevation no longer relies on shadows**: levels step up +6 OKLCH lightness each (L 21 → 27 → 33 → 39) on the neutral base hue. Light mode is visually unchanged.
+- **Existing tokens are now aliases** (no renames): `background` → `surface-base`; `card` → `surface-raised`; `surface-1` → `surface-raised`; `surface-2` → `surface-elevated`; `card-elevated` → `surface-overlay` (light) / `surface-elevated` (dark); in dark, `card-hover` → `surface-elevated`, `card-active` and `surface-3` → `surface-overlay`. Dark values of `card`, `card-hover`, `card-active`, `surface-1`–`surface-3` shift slightly to land on the new levels.
+- **Floating components use the overlay level**: `Modal`, `SlideUp`, `Dropdown` (and `Select`'s menu), `NavigationMenu` panels, `Toaster` toasts and the `Toast` atom now paint `bg-surface-overlay` (previously `bg-card` / `bg-surface-1`, which in dark matched or undercut the card they floated over). Hover fills inside them use `bg-surface-overlay-hover` so they read above the overlay. `Modal`/`SlideUp` get a `border-border-overlay` edge. `Card variant="elevated"` uses `bg-card-elevated`.
+- **Dark `--color-description`** moves one step lighter (`base-650`) so description text keeps ≥ 4.5:1 contrast on every surface level, including overlays.
+- **New guard**: `scripts/check-surface-elevation.js` (run by `validate-theme.js` during `build:css`) fails the build if dark levels aren't strictly increasing, any step is outside 5–8 OKLCH L points, overlay hover/tooltip fills are darker than the overlay, or a floating component paints a surface below overlay.
+
+### Theme fixes
+
+- **`max-w-*`, `w-*` and `min-w-*` with `xs`–`2xl` now use Tailwind's container sizes again** (`max-w-lg` = 32rem). Tailwind v4 resolves these utilities through `--spacing-*` before `--container-*`, so the theme's named spacing tokens made `max-w-lg` resolve to 1.5rem for anyone importing the theme. New `--max-width-*`, `--width-*` and `--min-width-*` tokens (xs 20rem … 2xl 42rem) are checked first. Spacing utilities such as `p-lg` / `gap-md` are unchanged.
+- **`--color-caption` meets WCAG AA on every surface level**: light `base-500` → `base-550` (was 4.40:1 on the page background, now ≥ 5.58:1); dark `base-500` → `base-650` (was 2.00:1 on overlays, now ≥ 5.00:1). To keep caption visibly softer than description in dark mode, dark `--color-description` moves from `base-650` to `base-700` (≥ 6.53:1).
+- **New guard**: `scripts/check-surface-elevation.js` also fails the build if `headline`, `body`, `label`, `description` or `caption` drop below 4.5:1 on any surface level in either theme.
+- **`Modal`**: the title and close button line up with the body and footer. The inner `Card`'s own padding stacked on the header's padding and indented the title 24px past the content.
+
+### Packaging
+
+- **Removed `zabi-components/react`**: the export pointed at `dist/react`, which was never built, and the wrappers were out of sync with the Svelte components. The optional `react` peer dependency and `@types/react` are gone too.
+- **No more `postinstall` in consumer installs**: `scripts/fix-lucide-svelte-icon-dts.js` only ever patched this repo's own `node_modules` (from a consumer install it resolved to a non-existent nested path and did nothing). It now runs as a dev-only `prepare` script and is no longer shipped in the tarball. Installs with `--ignore-scripts` (pnpm/Bun defaults) are unaffected.
+- **`zabi-components/lib/ssr-safe` and `zabi-components/lib/variant-utils` now resolve to compiled `.js` + `.d.ts`** (`dist/util/ssr-safe.*`, `dist/routes/lib/variant-utils.*`) instead of raw `.ts` sources. Import paths are unchanged.
+- **`generateId` / `createId` from the package root** now use the shared `util/ssr-safe` implementation; the previous root version used `Date.now()` on the server, so two ids created in the same millisecond collided.
+- **`CodeBlock`**: window-chrome dots use semantic tokens (`bg-error` / `bg-warning` / `bg-success`) instead of raw Tailwind palette classes; props are now typed.
+- **`check:tokens`** also flags raw Tailwind palette utilities (e.g. `bg-red-500`) in `src/components`.
+- **Repo**: `dist/`, `.svelte-kit/` and `storybook-static/` are no longer tracked in git; unused Storybook template assets and `src/_tmp-lucide-import.ts` removed.
+- **CI**: Node 24; the smoke workflow now also runs `check`, unit tests, theme tests and the token scan; publish runs `check` and unit tests before building.
+
+## [7.0.2] - 2026-04-20
+
+### Changed
+
+- **`Tooltip`**: Tooltip surface styling now uses theme tokens **`--color-tooltip-bg`** / **`--color-tooltip-fg`** (with **`bg-tooltip-bg`** / **`text-tooltip-fg`** utilities) and **`z-tooltip`**, keeping layout/arrow logic in scoped CSS while aligning colors with the design system.
+- **`Tooltip` layout**: Tooltip panel uses **`width: max-content`** with a responsive **`max-width`** cap (`min(24rem, calc(100vw - 2rem))`) so typical copy stays on one line until the limit; arrow fill follows **`--color-tooltip-bg`**.
+- **Theme (`src/app.css`)**: Defines **`--color-tooltip-bg`** / **`--color-tooltip-fg`** (defaults to base-800 / base-50); **`prefers-contrast: high`** maps them to **`CanvasText`** / **`Canvas`** for stronger contrast. Regenerated **`zabi-components*.css`** picks up the new utilities.
+
+## [7.0.1] - 2026-04-19
+
+### Fixed
+
+- **`postinstall`**: The Lucide typings patch script is **included in the published package** (`scripts/fix-lucide-svelte-icon-dts.js` via `package.json` `files`), so `npm install zabi-components` no longer fails when lifecycle scripts run.
+- **Theme CSS (Tailwind v4)**: Replaced `theme(colors.*)` inside `@theme` / `.dark` with `var(--color-*)` for Zabi scales and stable hex literals for Tailwind default ramps (e.g. red/amber) and white, so consumers processing `theme-only` / `colors` bundles do not hit unresolved `theme()` during Tailwind passes.
+- **Props typings**: **`Button`**, **`IconButton`**, and **`Tooltip`** prop types now intersect native element attributes (`HTMLButtonAttributes` / `HTMLAttributes<HTMLDivElement>`) so passthrough attributes (`class`, ARIA, `data-*`, etc.) type-check when spread with `...restProps`.
+
+### Added
+
+- **`docs/lucide-icons.md`**: Lists Lucide icons imported by published components for teams using a custom `@lucide/svelte` barrel.
+
+### Changed
+
+- **`scripts/sync-theme-tokens.js`**: End marker after the mirrored base ramp now matches the **`Brand Color Scale - Dark mode variants`** comment (including the “no theme() forward refs” note).
+
+### Migration / discovery
+
+- **`Navbar` → `TopNavbar`**: The older **`Navbar`** export was removed in **6.0.0**; use **`TopNavbar`**. See the **6.0.0** migration notes in this file.
+
+## [7.0.0] - 2026-04-19
+
+### Breaking changes
+
+- **`Page`**: Removed the built-in `max-w-4xl` cap. Width is now fully controlled by the parent, or pass e.g. `className="max-w-4xl"` (or use **`Container`** / **`Section`** with `maxWidth` per the layout-width policy).
+- **`EmptyState`**: Removed the built-in `max-w-lg` cap. Add `className="max-w-lg"` (or another token) if you still want a narrow empty state.
+
+### Added
+
+- **`postinstall`**: After `npm install`, runs `scripts/fix-lucide-svelte-icon-dts.js` to strip a duplicate `type X = ReturnType<typeof X>` line from each `@lucide/svelte` per-icon `dist/icons/*.svelte.d.ts` file. Some TypeScript language services treat the unpatched file as a non-module, which breaks types for deep icon imports and root re-exports.
+- **`fixedSidebarFlyout`**: New Svelte **action** in the built package (`util/fixed-sidebar-flyout.js`) used by **`SidebarFooter`**. It pins flyouts with `position: fixed` to `[data-sidebar-flyout-anchor]` inside `[data-sidebar-flyout-root]`, teleports the panel to `document.body` while open to avoid scroll clipping, and updates position on scroll/resize. Options: `open`, `align` (`"top"` | `"bottom"`), `gap`, `anchorRole` (`"search"` | `"profile"`).
+
+### Changed
+
+- **`CodeBlock`**: Replaced the ad-hoc copy **`<button>`** with **`IconButton`** (ghost, sm). Copy / copied states use Lucide **`Check`** and **`Copy`** from **`@lucide/svelte/icons/*`**. Wrapper uses **`bg-surface-1`**, **`border-border`**, header **`bg-surface-2`**; code uses **`text-base-900`** on light surfaces instead of **`bg-base-900`** / **`bg-base-*`** chrome with **`text-base-100`** body text.
+- **`SidebarFooter`**: Profile panel markup restructured with **`data-sidebar-flyout-root`** on the footer host; **`data-sidebar-flyout-anchor="profile"`** on the launcher; the profile snippet is positioned with **`fixedSidebarFlyout`** (`align: "bottom"`, viewport-limited **`max-height`**, **`overflow-y-auto`**, **`overscroll-contain`**). Drops the previous **`absolute bottom-0 left-full`** positioning that misbehaved beside fixed sidebars / scroll ancestors.
+- **`SidebarNavigation`**: Search trigger wrapped with **`data-sidebar-flyout-anchor="search"`** (collapsed and expanded) so flyouts share the same anchor protocol as the footer profile panel.
+- **Lucide usage in source**: Prefer **`import Icon from "@lucide/svelte/icons/name"`** over the package barrel for clearer tree-shaking and alignment with the postinstall typings fix. Showcase demos replace **`CircleHelp`** with **`CircleQuestionMark`** (current Lucide export name).
+- **`zabi-components.css` (generated bundle)**: Picks up additional theme utilities used by the showcase and organisms—e.g. **`--spacing-xs`**, **`text-base-900`**, **`max-h-[min(32rem,calc(100dvh-6rem))]`**, **`overscroll-contain`**, prose/fit/max/min width utilities, responsive **`md:z-10`**, **`md:w-80`**, **`md:flex-nowrap`**, **`md:items-stretch`**, **`overflow-auto`**, **`align-top`**. Some rarely-used utilities were dropped from the scanned set where no longer referenced (e.g. **`left-full`**, base **`items-stretch`** in favor of **`md:items-stretch`**, **`bg-gray-50`**).
+
+### Fixed
+
+- **Lucide + TypeScript**: Consumers importing per-icon modules get consistent typings after install thanks to the **`postinstall`** patch for **`@lucide/svelte`** ~**0.544.x** declaration output.
+
+### Migration (from 6.x)
+
+1. **`Page` / `EmptyState`**: If layout relied on the old max widths, add them explicitly:
+   - `<Page className="max-w-4xl">` or wrap content in **`Container`** / **`Section`**.
+   - `<EmptyState className="max-w-lg" …>` (or another **`max-w-*`** from your layout policy).
+2. **`npm install`**: Keep **`postinstall`** enabled so Lucide icon **`.d.ts`** files are patched; if you use **`npm install --ignore-scripts`**, run `node scripts/fix-lucide-svelte-icon-dts.js` manually or rely on root **`@lucide/svelte`** barrel imports only (may bundle more code).
+3. **Demos copying Lucide icon names**: Replace **`CircleHelp`** with **`CircleQuestionMark`** when upgrading Lucide past names that removed **`CircleHelp`**.
+
+## [6.0.0] - 2026-04-12
+
+### Breaking changes
+
+- Removed the `Navigation` organism; use `TopNavbar` with `items`, optional `embedded`, or a `nav` snippet instead.
+- Renamed `SidebarProjectPanel` to `SidebarPanel` (including the `SidebarPanelItem` type).
+
+### Added
+
+- Package subpath exports `zabi-components/colors` and `zabi-components/css` for theme and full bundle CSS.
+- Published theme documentation files in the package (`THEME.md`, `THEMING.md`, `docs/theme-imports.md`).
+
+### Changed
+
+- Theme build runs `sync:tokens` before CSS generation; added theme output tests (`test:themes`).
+- Refined default border styling on several components.
+
+### Migration
+
+- Replace `import { Navigation } from 'zabi-components'` (or organisms path) with `TopNavbar` and the documented props/snippets.
+- Replace `SidebarProjectPanel` imports with `SidebarPanel` and align prop/type names to `SidebarPanelItem` where applicable.
+
+## Pending deprecations
+
+- Legacy deep CSS import paths under `zabi-components/dist/*.css` are still supported for compatibility but documented as legacy. Prefer short exports such as `zabi-components/theme-only`, `zabi-components/theme-dark-only`, `zabi-components/colors`, and `zabi-components/css`.
+
+## [5.0.22] - 2026-03-16
+
+### ✨ **Features**
+
+- **List Components**: Added new `List` and `ListItem` components with documentation and usage examples
+- **Sidebar**: Added `SidebarNavigation` and `SidebarPanel` with improved navigation behaviors
+
+### 🔧 **Improvements**
+
+- **Card Components**: Refactored `Card`, `CardHeader`, and `CardContent` and simplified composition patterns
+- **Documentation**: Updated Storybook setup and improved component documentation quality
+- **Config & Environment**: Refined environment variable definitions and release metadata handling
+
+### ✅ **No Breaking Changes**
+
+This is a backward-compatible update.
+
+---
+
+## [5.0.21] - 2026-01-17
+
+### ✨ **Features**
+
+- **IconButton**: Added a new icon-only button with variants, sizes, and accessible labels
+- **Exports & Storybook**: Included IconButton in atom exports and Storybook registry
+- **Docs**: Added IconButton examples to the docs and components showcase
+
+### 🔧 **Improvements**
+
+- **Navigation**: Header navigation now stacks for mobile-friendly layouts
+- **Select**: Improved selected label truncation and helper message layout
+- **Button**: Standardized disabled behavior without pointer-events override
+
+### ✅ **No Breaking Changes**
+
+This is a backward-compatible update.
+
+---
+
+## [5.0.20] - 2025-01-27
+
+### 🔧 **Patch Release**
+
+- **Maintenance**: General improvements and stability updates
+- **Build**: Enhanced build process and type definitions
+- **Documentation**: Minor documentation updates
+
+### ✅ **No Breaking Changes**
+
+This is a backward-compatible patch release.
+
+---
+
+## [5.0.19] - 2025-01-27
+
+### 🐛 **Bug Fixes**
+
+#### **Modal Component**
+- **Fixed SSR Import Error**: Resolved issue where Modal component was trying to import `focus-utils.js` from a relative path that didn't exist in consuming projects
+- **Internal Focus Utilities**: Moved focus management utilities (`focus-utils.ts`) to be properly included in the build output
+- **Build Process**: Added post-build script to fix import paths in built components
+- This fixes the "Failed to load url ../../routes/lib/focus-utils.js" error that occurred during SSR
+
+## [5.0.18] - 2025-01-27
+
+### ✨ **Component Enhancements & Documentation**
+
+#### **Card Component Improvements**
+- **Compound Components**: Added CardHeader, CardContent, CardFooter, CardTitle, and CardDescription sub-components
+  - Enables flexible card composition with better structure
+  - Maintains backward compatibility with existing title/description/image props
+  - Supports both old and new API patterns
+- **Enhanced Variants**: Improved elevated, outlined, and flat variants with better hover states
+- **Accessibility**: Added keyboard navigation (Enter/Space) and proper ARIA attributes for interactive cards
+- **Size Variants**: Enhanced size support (sm, md, lg) with responsive padding and typography
+
+#### **Button Component Enhancements**
+- **New Variants**: Added ghost, outline, and link variants for more design flexibility
+- **Improved Focus States**: Enhanced focus ring styles for better accessibility
+- **Size Refinements**: Improved size variants with better typography and spacing
+- **Better Disabled States**: Enhanced disabled state styling and interaction
+
+#### **Badge Component Updates**
+- **Icon Support**: Added optional icon display for success, warning, error, and info variants
+- **Size Variants**: Enhanced size support with responsive icon sizing
+- **Visual Consistency**: Improved color system integration
+
+#### **Component Accessibility Improvements**
+- **Modal Component**: Enhanced focus management and keyboard navigation
+- **Dropdown Component**: Improved ARIA attributes and keyboard navigation
+- **Card Component**: Added proper roles and keyboard handlers for interactive cards
+- **Focus Utilities**: New focus-utils.ts for better focus management across components
+
+#### **Documentation Additions**
+- **ACCESSIBILITY.md**: Comprehensive accessibility documentation with component-by-component analysis
+- **KEYBOARD_NAVIGATION.md**: Detailed keyboard navigation patterns and best practices
+- **VARIANTS.md**: Complete variant system documentation
+- **THEMING.md**: Enhanced theming guide with customization examples
+- **THEME_QUICK_REFERENCE.md**: Quick reference for theme customization
+- **SHADCN_INSPIRATION.md**: Design system inspiration and improvement roadmap
+
+#### **Theme & Styling Improvements**
+- **Color System**: Enhanced color variable resolution and consistency
+- **Theme Files**: Updated theme CSS files with improved structure
+- **Build Process**: Enhanced CSS build scripts for better theme processing
+
+#### **Build & Development**
+- **Type Definitions**: Updated TypeScript definitions for new components
+- **Component Exports**: Added exports for new Card compound components
+- **Storybook**: Enhanced Card stories with compound component examples
+
+### ✅ **No Breaking Changes**
+
+This is a backward-compatible update. Existing component usage continues to work, with new features available as optional enhancements.
+
+---
+
+## [5.0.17] - 2025-01-27
+
+### 🔧 **Patch Release**
+
+- **Documentation**: Updated changelog with version 5.0.16 release notes
+- **Build Improvements**: Adjusted theme validation script to be less strict for dark theme structure differences
+- **Version Bump**: Patch release for improved stability
+
+---
+
+## [5.0.16] - 2025-01-27
+
+### 🎨 **Color System & Component Styling Updates**
+
+#### **Color System Refactoring**
+- **Enhanced Color Variables**: Improved color system with better CSS variable resolution
+- **Theme Updates**: Updated theme files with improved color consistency
+- **Build Process**: Enhanced CSS build scripts for better color processing
+
+#### **Component Style Improvements**
+- **Checkbox Component**: Updated styling to match M3 design system with improved visual consistency
+- **Input Component**: Enhanced color system integration and styling updates
+- **Multiple Components**: Updated Button, CodeBlock, ColorPicker, FeatureCard, Progress, Skeleton, Textarea, Toast, Toggle, and more with consistent styling
+- **Molecule Components**: Updated Alert, ComponentDemo, Dropdown, ImageUpload, Modal, SlideUp, and Tabs with improved styling
+
+#### **Storybook Configuration**
+- **Story Organization**: Reorganized stories into atoms/, molecules/, and organisms/ folders for better structure
+- **Enhanced Stories**: Updated component stories with improved examples and controls
+- **Configuration Updates**: Enhanced Storybook configuration for better development experience
+
+#### **Build & Dependency Updates**
+- **Dependency Updates**: Updated package dependencies for improved compatibility
+- **Build Scripts**: Enhanced CSS build and cleanup scripts
+- **Type Definitions**: Updated TypeScript definitions for better type safety
+
+### ✅ **No Breaking Changes**
+
+This is a backward-compatible update focusing on styling improvements and build enhancements.
+
+---
+
+## [5.0.15] - 2025-01-27
+
+### 🎨 **Color System Improvements**
+
+#### **Standalone Colors File**
+- **New Export**: Added `zabi-components-colors.css` as a separate export for consumer apps
+  - Contains resolved CSS custom properties that work without Tailwind CSS processing
+  - Perfect for apps not using Tailwind CSS v4
+  - Includes all color variables with resolved hex values
+  - Supports both light and dark mode variants
+- **Package Export**: Added `./dist/zabi-components-colors.css` to package.json exports
+- **Usage**: Consumer apps can now import colors independently:
+  ```css
+  /* For Tailwind v4 users */
+  @import "zabi-components/dist/zabi-components.css";
+  
+  /* For non-Tailwind users */
+  @import "zabi-components/dist/zabi-components-colors.css";
+  ```
+
+#### **Component Cleanup**
+- **Badge Component**: Removed all arbitrary Tailwind values (`[var(--color-*)]`)
+  - Now uses proper utility classes: `bg-success border-success` instead of `bg-success border-[var(--color-success)]`
+  - More maintainable and consistent code
+- **Added Background Utilities**: Created explicit background utility classes to match border utilities
+  - Added: `bg-success`, `bg-warning`, `bg-error`, `bg-info`, `bg-neutral`, `bg-energetic`, `bg-secondary`
+  - Ensures consistent styling across all components
+
+#### **Build Improvements**
+- **Simplified Build Script**: Cleaned up CSS build process
+- **Better Separation**: Colors file is now separate from main CSS, making it easier to import independently
+
+### 🎯 **Technical Details**
+
+- **Color System**: Colors now work correctly in consumer apps regardless of Tailwind CSS setup
+- **Code Quality**: Removed all arbitrary value syntax for better maintainability
+- **Consistency**: All color utilities now follow the same pattern
+
+### ✅ **No Breaking Changes**
+
+This is a backward-compatible update. Existing usage continues to work, with improved color system support.
+
+---
+
+## [5.0.14] - 2025-01-27
+
+### ✨ **Component Improvements**
+
+#### **Textarea Component**
+- **Visual Consistency**: Updated Textarea styling to match Input component exactly
+  - Changed background to `bg-brand-100` (matching Input)
+  - Updated border radius from `rounded-md` to `rounded-lg`
+  - Removed border for default variant (matches Input's borderless design)
+  - Updated focus states to use `focus:ring-2 focus:ring-brand-500` with `focus:ring-offset-0`
+  - Standardized placeholder and text colors to match Input
+- **Simplified API**: Removed `size` prop - Textarea now uses a fixed size (matching Input's default "md" size)
+- **Enhanced Features**: Added message support with icons for success, warning, and error variants (matching Input component)
+
+#### **Storybook Updates**
+- **Storybook 10 Compatibility**: Standardized `argTypes` controls across all stories
+  - Updated Alert, Badge, Toggle, Tooltip, and SlideUp stories to use string shorthand for controls
+  - Improved consistency and cleaner code
+- **Textarea Stories**: Added message examples for success, warning, and error variants
+- **Removed Deprecated Stories**: Removed Small and Large Textarea stories (size prop removed)
+
+### 🎯 **Technical Details**
+
+- **Styling Alignment**: Textarea now visually matches Input component for consistent form design
+- **API Simplification**: Removed unnecessary size variations from Textarea
+- **Storybook Modernization**: All stories now use Storybook 10 best practices
+
+### ✅ **No Breaking Changes**
+
+This is a backward-compatible update. Existing Textarea usage continues to work, with improved visual consistency.
+
+---
+
+## [4.0.1] - 2025-01-27
+
+### 🛡️ **SSR Safety Overhaul - "Zero Runtime Errors" Edition**
+
+#### ✅ **Critical SSR Issues Resolved**
+
+This release completely eliminates the "Cannot read properties of null (reading 'f')" error and ensures 100% SSR safety across all components.
+
+#### 🔧 **SSR Safety Improvements**
+
+##### **Route Navigation Fixed**
+- **Replaced `window.location.href`**: All route pages now use SvelteKit's `goto()` from `$app/navigation`
+- **SSR-Safe Navigation**: No more direct window access during server-side rendering
+- **Files Updated**: `src/routes/+page.svelte`, `src/routes/docs/+page.svelte`
+
+##### **Component Lifecycle Fixed**
+- **ThemeToggle Component**: Replaced `$effect` with `onMount` for initial setup
+- **SSRSafe Component**: Simplified checks to rely solely on `mounted` state
+- **Eliminated Race Conditions**: Fixed timing issues during hydration
+
+##### **ID Generation Fixed**
+- **Input Component**: Moved ID generation to `onMount` to prevent hydration mismatches
+- **Checkbox Component**: Moved ID generation to `onMount` for consistency
+- **SSR-Safe IDs**: No more SSR/client ID mismatches
+
+##### **Enhanced SSR Utilities**
+- **New `ssr-safe.ts`**: Comprehensive SSR-safe utility functions
+- **SvelteKit Integration**: Uses `browser` from `$app/environment`
+- **Safe API Access**: `safeLocalStorage()`, `safeDocument()`, `safeWindow()`
+- **ID Generation**: `generateId()` function for consistent SSR-safe IDs
+
+#### 🎯 **Technical Improvements**
+
+##### **Consistent SSR Pattern**
+```svelte
+import { safeLocalStorage, safeDocument } from "../../lib/ssr-safe";
+
+onMount(() => {
+    mounted = true;
+    const storage = safeLocalStorage();
+    if (storage) {
+        // Safe browser API access
+    }
+});
+```
+
+##### **SvelteKit Best Practices**
+- Uses `browser` from `$app/environment` instead of manual checks
+- Uses `goto()` from `$app/navigation` for routing
+- Follows SvelteKit SSR patterns throughout
+
+##### **Hydration Safety**
+- No more SSR/client mismatches
+- Consistent ID generation across server and client
+- Proper lifecycle management
+
+#### ✅ **Results Achieved**
+
+##### **Build Status**
+- ✅ **Successful Builds**: All builds complete without errors
+- ✅ **Type Safety**: 0 TypeScript errors in zabi-components code
+- ✅ **SSR Compatible**: Full server-side rendering support
+
+##### **Runtime Safety**
+- ✅ **Zero Runtime Errors**: Eliminated all "Cannot read properties of null" errors
+- ✅ **Hydration Safe**: No more client/server mismatches
+- ✅ **Theme Toggle**: Works correctly on first load
+- ✅ **Form Inputs**: Stable IDs across SSR/hydration
+
+##### **Cross-Environment Compatibility**
+- ✅ **SvelteKit SSR**: Full compatibility with server-side rendering
+- ✅ **Client Hydration**: Smooth hydration without errors
+- ✅ **Production Ready**: Works correctly in production environments
+
+#### 📋 **Files Modified**
+
+1. `src/routes/+page.svelte` - Navigation fixes (6 instances)
+2. `src/routes/docs/+page.svelte` - Navigation fixes (2 instances)
+3. `src/components/atoms/ThemeToggle.svelte` - SSR safety improvements
+4. `src/components/atoms/Input.svelte` - ID generation fixes
+5. `src/components/atoms/Checkbox.svelte` - ID generation fixes
+6. `src/components/SSRSafe.svelte` - Simplified checks
+7. `src/lib/ssr-safe.ts` - Enhanced SSR utilities
+
+#### 🚀 **Performance Benefits**
+
+- **Faster Builds**: Reduced build time and complexity
+- **Better Reliability**: No more runtime crashes
+- **Improved DX**: Better developer experience with consistent patterns
+- **Production Ready**: Fully tested in production environments
+
+#### 🔄 **Migration Notes**
+
+**No Breaking Changes**: This is a backward-compatible update that fixes SSR issues without changing component APIs.
+
+**For Developers**: All existing component usage remains the same - the fixes are internal and transparent to users.
+
+---
+
+## [2.1.0] - 2025-01-27
+
+### 🚀 Major Event Handling Refactor - "Cross-Framework Compatible" Edition
+
+#### ⚠️ **BREAKING CHANGES** - Event Handling Overhaul
+
+This is a **major breaking change** that affects how all components handle events. The refactoring eliminates SSR/production errors and makes components compatible with React, Vue, and vanilla JavaScript applications.
+
+#### 🔧 **Event System Refactoring**
+- **Removed `createEventDispatcher`**: Eliminated all `createEventDispatcher` usage across 18 components
+- **Implemented Event Forwarding**: All components now use `{...$$restProps}` for native DOM event forwarding
+- **SSR-Safe**: Fixed hydration mismatches and production build errors
+- **Cross-Framework Compatible**: Components now work in React, Vue, Svelte, and vanilla JS
+
+#### 🎯 **Components Refactored**
+
+##### **Form Components**
+- **Input**: Replaced `bind:value` with `value` prop + `on:input` handler
+- **Textarea**: Replaced `bind:value` with `value` prop + `on:input` handler  
+- **Select**: Replaced `bind:value` with `value` prop + `on:change` handler
+- **Checkbox**: Replaced `bind:checked` with `checked` prop + `on:change` handler
+
+##### **Interactive Components**
+- **Button**: Added `{...$$restProps}` for native event forwarding
+- **Toggle**: Added event handler + `{...$$restProps}` for cross-framework compatibility
+- **ThemeToggle**: Added `{...$$restProps}` for event forwarding
+
+##### **Complex Components**
+- **Modal**: Removed `createEventDispatcher`, simplified event handling
+- **Tabs**: Removed `createEventDispatcher`, uses direct state management
+- **ImageUpload**: Removed `createEventDispatcher`, simplified file handling
+- **ContactForm**: Updated to use new event patterns
+- **Form**: Removed `createEventDispatcher`, added `{...$$restProps}`
+- **Alert**: Removed `createEventDispatcher`, added `{...$$restProps}`
+- **Toast**: Removed `createEventDispatcher`, simplified close handling
+- **Badge**: Removed `createEventDispatcher`, added `{...$$restProps}`
+- **SlideUp**: Removed `createEventDispatcher`, simplified modal handling
+- **TopNavbar**: Removed `createEventDispatcher`, added `{...$$restProps}`
+- **Navigation**: Removed `createEventDispatcher`, simplified navigation
+
+#### ✅ **Benefits Achieved**
+
+##### **SSR/Production Safe**
+- ✅ **No more hydration errors** in SSR environments
+- ✅ **Production builds work correctly** without runtime errors
+- ✅ **Eliminated `createEventDispatcher` errors** in SvelteKit applications
+
+##### **Cross-Framework Compatible**
+- ✅ **React Applications**: Components work with standard React event handlers
+- ✅ **Vue Applications**: Compatible with Vue's event system
+- ✅ **Vanilla JavaScript**: Full compatibility with native DOM events
+- ✅ **Svelte/SvelteKit**: Maintains full compatibility with improved reliability
+
+##### **Standards Compliant**
+- ✅ **Native DOM Events**: Uses web standards instead of framework-specific events
+- ✅ **Better Performance**: Reduced JavaScript overhead and bundle size
+- ✅ **More Predictable**: Event handling follows web standards
+
+#### 🔄 **Migration Required**
+
+**Before (Old Pattern):**
+```svelte
+<!-- This would cause SSR errors -->
+<Button on:click={handleClick}>Click me</Button>
+<Input bind:value={inputValue} />
+<Modal bind:isOpen onclick={handleClose} />
+```
+
+**After (New Pattern):**
+```svelte
+<!-- Now works in all environments -->
+<Button on:click={handleClick}>Click me</Button>
+<Input value={inputValue} on:input={(e) => inputValue = e.target.value} />
+<Modal bind:isOpen on:click={handleClose} />
+```
+
+#### 📋 **Breaking Changes Summary**
+
+1. **Form Components**: Must use `value` prop + event handlers instead of `bind:value`
+2. **Event Names**: Some custom events replaced with native DOM events
+3. **Event Structure**: Simplified event structures across all components
+4. **SSR Compatibility**: Components now work correctly in SSR environments
+
+#### 🛠️ **Technical Details**
+
+- **Event Forwarding**: All interactive elements now use `{...$$restProps}`
+- **Native Events**: Replaced custom events with standard DOM events where possible
+- **State Management**: Simplified internal state management
+- **Type Safety**: Maintained full TypeScript support with updated types
+
+#### 🎯 **Migration Guide**
+
+See the updated README.md for detailed migration examples and new usage patterns.
+
+---
+
+## [2.0.2] - 2025-01-27
+
+### 🎯 Major Simplification - "Less is More" Edition
+
+#### ✨ Simplified Components
+- **Massive Code Reduction**: Reduced component complexity by 60-80% across the board
+- **Modern CSS-First Approach**: Replaced complex JavaScript with modern CSS-only solutions
+- **Unified Form Component**: Consolidated 4 form components into 1 simple Form component
+- **Removed Complex Managers**: Eliminated NotificationManager, ToastManager, and other complex utilities
+
+#### 🔧 Atom Components Simplified
+- **Badge**: Removed complex variants, icons, and animations - now just basic color variants
+- **Button**: Simplified to 3 variants (primary, secondary, danger) with minimal props
+- **Card**: Merged ModernCard into Card, removed complex styling and animations
+- **Checkbox**: Removed complex validation, sizing, and custom CSS
+- **Input**: Simplified to essential props only, removed complex validation system
+- **Heading**: Clean heading component with just level and text props
+- **Progress**: Basic progress bar with simple percentage display
+- **Select**: Simplified dropdown with basic options support
+- **Textarea**: Essential textarea with minimal configuration
+- **Toggle**: Fixed-size toggle with simple on/off state
+- **ThemeToggle**: Emoji-based theme switcher, removed complex styling
+- **Toast**: Fixed-position toast with basic message display
+- **Tooltip**: CSS-only positioning with data-placement attributes
+- **Skeleton**: Simple loading placeholder with basic styling
+- **TextAlignment**: Emoji-based alignment selector
+- **OptimizedImage**: Basic image component with lazy loading
+- **ColorPicker**: Simple color grid without complex dropdown logic
+
+#### 🧩 Molecule Components Simplified
+- **Dropdown**: CSS-only positioning, removed complex JavaScript calculations
+- **ImageUpload**: Direct file selection, removed modal and progress bars
+- **Form**: Unified form component, removed complex validation and field management
+- **Modal**: Simple modal with basic backdrop and close functionality
+- **SlideUp**: CSS-only slide-up panel, removed complex state management
+- **Tabs**: Basic tab navigation with keyboard support, removed complex utilities
+
+#### 🏗️ Organism Components Simplified
+- **TopNavbar**: Responsive top navbar with mobile menu, removed complex variants
+- **Navigation**: Simple navigation list with active state
+- **Removed Complex Components**: Deleted NavigationItem, NotificationManager, ToastManager
+
+#### 🗑️ Removed Complexity
+- **External Utility Functions**: Removed complex tabs-utils, navigation-utils
+- **Complex Type Definitions**: Simplified event types and interfaces
+- **Svelte Transitions**: Replaced with CSS-only animations
+- **Custom CSS Variables**: Replaced with standard Tailwind classes
+- **Complex State Management**: Simplified to essential state only
+- **Redundant Folders**: Removed simple/ folder with duplicate exports
+
+#### 🎨 Modern CSS Features
+- **CSS-only Positioning**: Using `position: absolute` and `transform` for tooltips and dropdowns
+- **CSS Pseudo-elements**: Using `::before` for arrows and indicators
+- **CSS Data Attributes**: Using `data-placement` for component positioning
+- **CSS Transitions**: Smooth animations handled entirely by CSS
+- **Tailwind-First**: All styling using Tailwind utility classes
+
+#### 📦 Package Improvements
+- **Cleaner Structure**: Removed unnecessary abstraction layers
+- **Direct Imports**: Components available from their natural locations
+- **Simplified APIs**: Just the essential props needed for functionality
+- **Better Performance**: Reduced JavaScript overhead and complexity
+
+#### 🐛 Bug Fixes
+- **Accessibility**: Fixed label associations and ARIA attributes
+- **TypeScript**: Resolved all type errors and warnings
+- **Linting**: Fixed all ESLint and Svelte warnings
+- **Deprecation**: Replaced deprecated Lucide icons with emoji alternatives
+
+### Breaking Changes
+- **Removed Components**: KeyValueForm, ContactForm, ModernForm, NotificationManager, ToastManager
+- **Simplified Props**: Many components now have fewer configuration options
+- **Removed Variants**: Reduced complex variant systems to essential options only
+- **Event Simplification**: Simplified event structures across all components
+
+### Migration Guide
+- **Form Components**: Use the unified `Form` component instead of multiple form variants
+- **Complex Features**: Many complex features have been removed in favor of simplicity
+- **Styling**: Components now use standard Tailwind classes instead of custom CSS variables
+- **Imports**: Import components directly from atoms/, molecules/, organisms/ folders
+
+## [1.1.1] - 2025-10-06
+
+### Fixed
+- Updated generated TypeScript definitions for better type safety
+- Enhanced package structure with improved type exports
+- Fixed build consistency and versioning
+
+### Changed
+- Updated internal build files and generated assets
+- Improved TypeScript declaration file generation
+- Enhanced package.json structure and exports
+
+## [1.1.0] - 2025-10-05
+
+### Added
+- Comprehensive TypeScript definitions built into the library
+- Self-contained type system - no custom type definitions needed in consumer apps
+- Enhanced component type safety with proper event handling
+- SSR-safe utilities for better SvelteKit compatibility
+
+### Changed
+- Updated build configuration for proper SvelteKit compatibility
+- Removed SSR mode from library build (libraries should be client-side)
+- Enhanced package.json exports for better module resolution
+- Updated peer dependencies for Svelte 5 compatibility
+
+### Fixed
+- Fixed runtime errors with `Cannot read properties of null (reading 'f')`
+- Fixed event handling for Svelte 5 compatibility
+- Fixed TypeScript type inference for component props and events
+- Fixed package exports for proper module resolution
+
+### Removed
+- Removed need for custom type definitions in consumer applications
+- Removed unnecessary client-only component duplicates
+- Removed SSR wrapper components (not needed)
+
+### Breaking Changes
+- None - this is a backward-compatible update
+
+## [1.0.11] - Previous version
+- Initial release with basic components
+