@reliability-design/web 1.4.7 → 1.4.9

package/CHANGELOG.md

@@ -1,11 +1,107 @@
 # Changelog — @reliability-design/web
 
-## 1.4.7 (2026-09-05)
+## 1.4.9 (2026-09-26)
+
+
+Bug-fix release from a twenty-one item report against 1.4.8. Mostly geometry: things the token and
+variant gates cannot see, because those gates read source text and bound token names while every one
+of these defects is about what the browser actually *paints*. Two reported items turned out not to
+be defects at all and are noted under [Not changed](#notchanged-149) so they are not re-filed.
+
+Paired releases: `@reliability-design/angular` 1.4.9, which now requires web `^1.4.9`.
+`@reliability-design/icons` is unchanged and stays on 1.4.4.
+
+Three changes are visible without a rename to warn you; they are listed under
+[Changed](#changed-149).
+
+### Fixed
+
+- **`rel-textfield` `variant="legend"` was broken at every size.** It painted a 23 / 30 / 37px outline against the 32 / 40 / 48 ladder, sat its value 4–7.5px low and overflowed the bottom border by up to 6px at `small` — while `getBoundingClientRect()` reported the correct height, which is why nothing caught it. Two Blink fieldset behaviours caused it: a fieldset's border box *includes* the legend's protruding top half, and the legend's full height is subtracted from the content area (the intended remedy, `flex: 1` on the row, is inert — a fieldset's anonymous content box does not take a fixed height). The fieldset is now a decorative, absolutely-positioned outline layer and the content rides the ordinary container row, so the variant measures identically to `variant="default"`. Also fixed in the same pass: the legend's text sat 4px right of the value, its inline inset was frozen at 12px and could not see the size ramp, and the default size rendered a heavier legend than either neighbour.
+- **The floating label was struck through by the field's own border.** The label masks the border with an opaque strip rather than cutting a notch, and the strip was positioned against the wrong reference, leaving part of the painted band crossing the label text. Affects `rel-textfield`, `rel-select` and — through composition — `rel-autocomplete`. The two components need *different* corrections because their containing blocks differ; both are now derived from the border and ring widths rather than restated.
+- **`rel-select`'s floating label painted an opaque block over the field.** It filled the label's whole ~20px line box to hide a 1px border, erasing roughly 10px of the trigger's interior and 10px above it. Figma specifies a strip whose height *equals the border it masks* — 1px at rest, 2px focused — which `rel-textfield` already used. Two further defects fixed with it: there was no disabled fill swap, so a disabled select painted a lighter block over its own trigger; and a hard-coded `top: -2px` nudge applied to `.focused` but not `.has-value`, so the label **jumped 2px** when focus arrived on a filled select.
+- **`rel-autocomplete` lit three suggestion rows at once.** The committed selection, the keyboard cursor and a stale CSS `:hover` all painted the same wash, so arrowing through a list with the mouse resting on it left no way to tell which row `Enter` would commit. `:hover` was redundant in that rule — `pointerenter` already moves the keyboard cursor onto the hovered row — and it was the only thing keeping a passed-over row lit. Every individual state was, and remains, pixel-correct against the design file.
+- **`rel-accordion` appeared to gain a border on hover.** There was no hover border rule: `.accordion` always carried a 1px border and `appearance="shadow"` merely made it transparent, so the header was inset 1px on all four sides and the hover wash stopped short of the card edge, leaving a ring of untinted surface. The stroke is now an `outline` with a negative offset, which is what Figma's inside-aligned stroke means and costs no layout.
+- **`rel-upload`'s disabled cursor never appeared.** `cursor: not-allowed` was set on the dropzone, but an ancestor carried `pointer-events: none`, and an element that is not a hit target never has its cursor consulted. `getComputedStyle` reported `not-allowed` while the pointer showed an arrow. The cursor now sits on the host. Separately, the file list failed `aria-required-children`: its container has `role="list"` and its rows carried no `role="listitem"`.
+- **`rel-menu`'s submenu chevron was dulled to 60% opacity**, where the design file has it at full strength on the same token as the row label beside it. Its colour is now declared rather than inherited — `rel-menu` renders to the light DOM, so an inherited colour travelled through the consumer's page cascade.
+- **`rel-carousel`'s vertical orientation put the arrows on the horizontal axis.** A vertical carousel got a left-pointing chevron at mid-left and a right-pointing one at mid-right, flanking the caption while the motion ran up and down. The arrows now ride the vertical axis with rotated chevrons. Vertical slides also centre their content instead of stretching it and leaving the caption top-anchored in dead space.
+- **`rel-checkbox`'s indeterminate dash rendered 1.6× too thin.** An 8:1 viewBox was being letterboxed into a square box, so the dash painted at 6.875% of the frame where the design file has 11.11% — and at a fractional thickness at every size, which is what made it look soft. Both marks now use the design file's own 16-unit geometry. Corner radius was hand-written per size and *omitted* for `large` and `extra-large`, so a 24px box and an 18px box shared a corner; radius and border are now derived from the drawn square.
+- **All three pickers left their panel floating over sticky page furniture.** `rel-date-picker`, `rel-range-picker` and `rel-time-picker` repositioned their panel on scroll, tracking a trigger that had already scrolled out of view — and because the panel is promoted to the browser top layer it kept painting above everything. They now **close on an outside scroll**, matching `rel-select` and `rel-autocomplete`. Scrolling *inside* a panel does not close it, including the time picker's hour, minute and period columns, which are each their own scroller.
+- **`rel-date-picker` and `rel-range-picker` drew a hand-written calendar glyph** that matched no icon in the set. Both triggers now render the design system's `calendar-month`.
+- **`rel-alert` reserved a pixel no variant used.** A 1px transparent border sat on the shared base, so every appearance's content box was 1px tighter than the design file — only `outline` has a stroke there, and it is inside-aligned, which overlays rather than insets. The content column also hugged its text instead of filling the row it is specified to fill. Both fixed; every appearance keeps a visible boundary in forced-colors mode.
+- **`rel-radio` warned about a value you never set.** `density="compact"` with `alignment="trailing"` logged a notice — but `compact` is the default, so setting only `alignment` produced a warning about a coercion of a value the author never wrote. It now warns only when `density` was explicitly chosen.
+
+### Added
+
+- **`rel-stepper` `connector`.** `solid` (default, unchanged) or `dot` — a 1px connector dashed 2px on / 2px off, per the design file's `.Line Types`. Note `connector="dot"` is the **line between steps** while the existing `type="dot"` is the **step indicator disc**; they are independent axes that both use the word.
+- **`rel-checkbox` `field-aria-label`**, joining `rel-switch`, `rel-radio`, `rel-segmented-button` and `rel-autocomplete`. It was the only control in that family without one.
+- **`rel-change` as an alias on the last three components that lacked it.** `rel-select` and `rel-segmented-button` emitted only `changed`; `rel-tab` emitted only `rel-tab-change`. All three now emit `rel-change` *alongside* their existing event, with the same detail and timing. **Both fire — neither replaces the other**, and the legacy names are kept for as long as 1.x. Every interactive component in the library now emits `rel-change`.
+- **`--rel-overlay-fallback-z`** (default `1001`), shared by `rel-select`, `rel-autocomplete` and the three pickers. Consulted **only** on the no-Popover-API fallback path: wherever the browser top layer is available the panel is promoted into it and z-index is inert, because top-layer elements are not in the page stacking order at all.
+- **`--rel-select-surface`** and **`--rel-select-surface-disabled`**, mirroring `--rel-textfield-surface` — the colour of the strip the floating label lays over the trigger's border. Set them when the field sits on a surface that is not the trigger's own fill.
+- **`--rel-carousel-slide-display`** (default `flex`), the escape hatch for the vertical slide centring above. Set it to `block` if forcing flex reflows your slide's own children.
+- **`rel-stepper` `textalign` now logs its deprecation.** It has been a documented alias of `label-placement` for some time but said nothing at runtime. The notice fires once, only for a non-default value, and only when `label-placement` is unset.
+
+### Changed
+
+<a id="changed-149"></a>Three changes are visible with no rename to warn you:
+
+- **`rel-radio` `size="small"` renders larger again.** 1.4.8 gave Small its own 16px control on the premise that the ramp was 16/20/24. That premise was never read off the design file, which pins Small **and** Medium to one 20px control and separates them by type alone — verified across all forty-five variants. Small returns to a 20px control, 16px ring and 8px dot, keeping its smaller label type. This reverts a deliberate 1.4.8 change; the component's own README had said so correctly the whole time.
+- **`rel-textfield`'s `::part(control)` is a `div` for `variant="legend"`,** where it used to be the `<fieldset>`. The fieldset became a decorative outline layer so the variant could sit on the size ladder. `::part(control)` still matches; only rules that depended on it *being* a fieldset do not.
+- **`rel-alert` has no minimum width.** It carried `min-width: 360px`, which was code-invented — the design file's Alert is a fixed 400 with no minimum — and it stopped the alert fitting any column narrower than 360px. Set a floor on the host if you want one.
+
+Also changed, but only observable on the fallback path: the picker panels' fallback `z-index` drops
+from `2147483647` to the shared `--rel-overlay-fallback-z` (default `1001`). This value is consulted
+only in browsers without the Popover API and has no effect wherever the top layer is available. The
+old value unconditionally beat consumer application chrome.
+
+### Not changed
+
+<a id="notchanged-149"></a>Two reported items were investigated and found correct, recorded here so
+they are not re-filed:
+
+- **`rel-alert`'s colours and tones match the design file.** All twelve style × tone cells bind exactly the token the design file binds. The report came from comparing against a dark-mode rendering; the REST API resolves variable-bound fills in whichever mode is default, so a raw hex from it names no token and cannot be compared to a light-mode value.
+- **`rel-checkbox`'s four sizes are the design file's own ramp.** The drawn squares land 1.6px apart at the lower steps, which does read as tight, but 16 / 18 / 20 / 24 is what the file specifies and the code already matched it.
+
+## 1.4.8 (2026-09-21)
+
+
+Consumer-ticket release. Twelve tickets from the testing and implementation team, built development-side and documented from source; the design file is being updated to follow, not the other way round. **Nothing is deprecated in this release** — every new spelling is an *alternative* that normalises, with no console notice. Four changes are visible without a rename to warn you; they are listed under [Changed](#changed-148) and on the docs site at `/docs/migration#v148-visual`.
+
+Paired releases: `@reliability-design/angular` 1.4.8, which now requires web `^1.4.8` rather than `^1.4.1`. `@reliability-design/icons` is unchanged and stays on 1.4.4.
+
+### Added
+
+- **`rel-switch` text labels and a size axis.** `label` plus a default slot for rich content, `label-placement` (`end` default | `start`), and `size` (`small | medium | large`, with `sm`/`md`/`lg` accepted). The root element is now the `<label>` that owns the input, so clicking the text toggles natively. **`line` and `pill` ramp differently on purpose** — 16/20/24 against 20/24/28 — because Line's height *is* the handle while Pill adds a 2px inset each side. `medium` is unchanged, so no existing switch moves. There is no breakpoint logic: the ramp ships, choosing a size per breakpoint is the application's job.
+- **`rel-toast` positions, sizes and stacking.** `position` takes `top-left | top-center | top-right | bottom-left | bottom-center | bottom-right`, defaulting to today's `bottom-center`; top-anchored toasts now animate downward instead of upward out of their own anchor. `size` is `small | medium | large` with `medium` unchanged. Multiple toasts at one position **stack** instead of overlapping: newest against the anchor edge, `max-visible` (default 3), and overflow **queues rather than drops** — so the `duration` countdown starts when a toast becomes *visible*, not when `show` is set. `max-visible` is read from the first toast to arrive at a position.
+- **`rel-tooltip` `tone`.** `inverse` (default, pixel-identical to 1.4.7) and `neutral`, a light-surface bubble with a 1px border — and the tail carries the border too.
+- **Second lines in suggestion rows.** A `supportingText` key on an object item renders a smaller second line under the label, on `rel-autocomplete` (new) and `rel-select` (see Changed). On **rel-autocomplete** it is **matched by the filter and highlighted**, not merely displayed, so a record can be found by its subtitle — rename the key with `supporting-field`. On **rel-select** the second line is displayed but NOT searched: the panel's search matches the label only. The two differ deliberately, because an autocomplete's second line carries identifying data a user types to find the row while a select's is descriptive. New parts `option-label` and `option-supporting-text` — **single-select rows only**; under `multiple` the row is a nested `rel-checkbox` and the second line has no part path at all.
+- **`rel-autocomplete` multi-select.** `multiple` with `selected-values`, a Select-all row and checkbox rows, mirroring `rel-select`. One deliberate difference: the committed chips sit **below** the field rather than inside it, because a select's trigger is a button that displays a value while an autocomplete's is an editable input the caret lives in.
+- **`rel-range-picker` month and year navigation.** The header month label is now a period switcher with Months and Years views and an unbounded year pager, ported from `rel-date-picker`. Reaching January 2023 is 3 clicks instead of roughly 44.
+- **Full-word size values** on `rel-avatar`, `rel-container` (`padding`), `rel-popover-content` and `rel-modal`, joining badge, chip and slider. `sm` / `md` / `lg` / `xs` / `xl` remain accepted, normalised to the full words. **Not deprecations** — no console notice.
+- **`--rel-shadow-color`** (`rgba(11,11,11,0.10)`), the shadow colour on its own. `filter: drop-shadow()` takes a bare `<color>` and cannot consume a box-shadow-shaped token, so components needing it had no semantic token to bind.
+
+### Fixed
+
+- **`rel-radio` sizes rendered identically.** `sm` / `md` / `lg` matched no rule and fell through to the base scale — which *is* medium — so three differently-spelled groups were byte-identical. They now normalise. Separately, `small` gets its own 16px control (see Changed).
+- **Fields did not line up in a form row.** `label-style="floating"` put its control 26px above a labelled sibling, because it reserved no label row. All three label styles now share one baseline. Also fixed: the floating host was consistently 4px *shorter* than the control inside it, and `label-style="none"` ran 2px tall at `small` because its reserve was hard-bound to the medium label role. Affects `rel-textfield` and `rel-select`; `rel-autocomplete` inherits through composition.
+- **`rel-otp` drew a hyphen before a lone cell.** With the default grouping of 3, a 4-character code rendered `[][][]-[]`. Separators now render only when the length divides evenly by the group size, which also fixes lengths 5, 7 and 8.
+- **The calendars' Months and Years grids could lose every tab stop.** Cells carried `tabindex="0"` only when selected, and the year pager moves the page without moving the selected year — so paging back once left all twelve cells at `-1` and the grid unreachable by keyboard. Both `rel-date-picker` and `rel-range-picker`; the day grids were already correct. Arrow, Home/End and Escape navigation added to the range picker's period grids to match the date picker's, and the tab stop now follows focus in both.
+- **`rel-slider`** documented a Medium size that the docs never showed. The component was always correct.
+
+### Changed
+
+<a id="changed-148"></a>Four changes are visible with no rename to warn you:
+
+- **`rel-radio` `small` shrinks.** Its control was 20px, identical to `medium`; it is now 16px, so the ramp reads 16/20/24. This is a deliberate divergence from the design file, which pins Small and Medium to the same control — a size axis where two of three sizes look identical is a defective API. 16px is `rel-checkbox`'s Small, its sibling selection control.
+- **`rel-select` option `supportingText` now renders in single-select rows.** It previously rendered only in multi-select rows, so a single-select built from options that already carried the key gains a second line it did not have. Rows are then two lines, which makes 32/40/48px the *one-line* height rather than the row height.
+- **Floating-label fields are taller**, because they now reserve the label row so they line up with labelled siblings. `--rel-field-label-reserve: 0` collapses it for toolbars and table cells.
+- **Toasts stack.** Five toasts at one position used to paint on top of each other; now three show and two wait. An app-level toast queue built to work around the old behaviour will still work, but the queueing it exists to provide is now built in.
+
+## 1.4.7 (2026-09-12)
 
 
 Designer-audit release. Every rename is **additive** — the new prop or value is canonical, the old one keeps working and is mapped internally, and its first use logs **one** `console.warn` per component per page (never one per instance). Two breaking removals: `rel-topbar` and `rel-navbar` are gone. The full old → new table is under [Migrating](#migrating-to-147) below and on the docs site at `/docs/migration`.
 
-Paired releases: `@reliability-design/angular` 1.4.7; `@reliability-design/icons` 1.4.5.
+Paired releases: `@reliability-design/angular` 1.4.7. `@reliability-design/icons` is unchanged in this release and stays on 1.4.4 — icons keep their own version counter.
 
 ### Added
 

package/dist/components/rel-accordion/README.md

@@ -76,8 +76,9 @@ accordion.open = true;
 | `title` | `title` | `string` | `"Accordion"` | Header text. Note it is also the native HTML `title` attribute, so browsers show it as a tooltip on hover. |
 | `open` | `open` | `boolean` | `false` | Whether the body is expanded; toggled by the header and reported via `open-change`. Setting it from code does not fire the event. Reflected. |
 | `size` | `size` | `"md" \| "sm" \| "large" \| "medium" \| "small"` | `"md"` | Header scale (Figma "Size"): `large` = 56px header / heading-md title, `medium` = 48px / heading-sm, `small` = 44px / heading-xs (new in 1.4.7). The historical spellings stay supported as aliases: `md` = large (the default), `sm` = medium. Reflected. |
-| `type` | `type` | `"default" \| "action"` | `"default"` | Header layout (Figma "Type"): `default` = title + trailing rotating chevron; `action` = leading icon slot (rotating chevron by default) + static trailing arrow-expansion icon, with the body indented under the title. Reflected. |
+| `type` | `type` | `"default" \| "action"` | `"default"` | Header layout (Figma "Type"): `default` = title + trailing rotating chevron; `action` = leading icon slot (rotating chevron by default) + static trailing arrow-expansion icon, with the body indented under the title. DELIBERATE DIVERGENCE — do not "fix" this to a button. For `Type=Action` Figma draws the trailing affordance as a full ghost icon Button instance (Size=Medium 40x40, Size=Small 32x32, Style=Ghost, Type=Icon Only); the code keeps a bare icon. Ruled by the user: our behaviour stands and the DESIGN FILE follows our docs here, not the other way round. The whole header is the click target, so a nested button would add a second focusable control inside it and two competing hit areas. Reflected. |
 | `appearance` | `appearance` | `"shadow" \| "plain"` | `"shadow"` | Figma "Style" axis — named appearance because `style` collides with the HTML style attribute. `shadow` = 4px-radius card with the shadow-sm effect and no border; `plain` = square corners with a 1px border-subtle stroke and no elevation. Reflected. |
+| `disabled` | `disabled` | `boolean` | `false` | Figma "State=Disabled": dims the whole component to 40% and blocks toggling by pointer and keyboard. The header keeps its fill and stroke — the dulling is opacity alone, as Figma specifies. Reflected. |
 
 ## Events
 

package/dist/components/rel-alert/README.md

@@ -138,7 +138,7 @@ saved.dismissed = false;
 
 - `tone` and `appearance` are independent axes; every tone renders in every appearance. Solid uses inverse text and carries the `--rel-shadows-md` elevation; subtle and outline have no shadow.
 - The status icon is fixed per tone (`info` for neutral and info, `check-circle`, `alert-circle`, `error`) and cannot be replaced or removed — there are no slots.
-- The alert has `min-width: 360px`; it stretches to its container (`display: block`) but never shrinks below that.
+- The alert stretches to its container (`display: block`) and has **no minimum width**. It carried a `min-width: 360px` until 1.4.9; that floor was code-invented (Figma's Alert is a fixed 400 with `minWidth` unset on all twelve variants) and stopped the alert fitting a narrower column. Set a floor on the host if you want one.
 - The link renders only when both `url-text` and `url-href` are set; it opens in the same tab (no `target`).
 - `dismissible` and `dismissed` are Lit booleans: any attribute value (including `"false"`) counts as true. Toggle them as properties from script.
 - `dismissed` only hides the host; the element stays in the DOM and keeps its state. Resetting `dismissed = false` shows it again without re-firing `dismiss`.

package/dist/components/rel-autocomplete/README.md

@@ -67,22 +67,26 @@
 
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `items` | `items` | `(string \| Record<string, unknown>)[]` | `[]` | Local (or fallback initial) suggestion list. Ignored while searchFn drives results. Object items read two keys directly whatever `display-field` / `value-field` are set to: `icon` (a `rel-icon` name shown before the label) and `disabled` (`true` dulls the row and makes it unselectable by click or keyboard). |
+| `items` | `items` | `(string \| Record<string, unknown>)[]` | `[]` | Local (or fallback initial) suggestion list. Ignored while searchFn drives results. Object items are read through `displayField` / `valueField` plus the fixed keys `icon`, `disabled` and `supportingText` (the last renamable via `supporting-field`); `supportingText` renders as a second line in the row and is matched by the filter alongside the label. |
 | `value` | `value` | `string` | `""` | Committed value — the selected item's valueField string ("" = none). |
 | `displayField` | `display-field` | `string` | `"label"` | Object key read for the row label when items are objects. |
 | `valueField` | `value-field` | `string` | `"value"` | Object key read for the committed value when items are objects. |
+| `supportingField` | `supporting-field` | `string` | `"supportingText"` | Object key read for the row's optional second line. Defaults to `supportingText`, the fixed key `rel-select` and `rel-radio` already use; point it elsewhere when your records cannot be reshaped. |
 | `filter` | `filter` | `"contains" \| "starts-with" \| "none"` | `"contains"` | Local filtering mode. Ignored when searchFn is set (results arrive pre-filtered). |
 | `searchFn` | — | `(query: string) => Promise<AutocompleteItem[]>` | `undefined` | Async data source. When set, local filtering is bypassed entirely. Property only. |
 | `debounceMs` | `debounce-ms` | `number` | `300` | Debounce for searchFn calls, in ms. |
 | `minSearchLength` | `min-search-length` | `number` | `1` | Minimum typed characters before the panel opens / searchFn fires. 0 = open on focus. |
 | `maxSuggestions` | `max-suggestions` | `number` | `Infinity` | Optional cap on rendered suggestions (panel scrolls regardless). |
+| `multiple` | `multiple` | `boolean` | `false` | Multi-select mode: rows become checkboxes with a Select-all row, and the committed values live in `selectedValues` rather than `value`. Mirrors `rel-select`'s `multiple` rather than introducing a second pattern. THE TEXT INPUT STAYS A SEARCH BOX. In single mode the input shows the selected label, which is the point of a type-ahead; in multi mode there is no single label to show, and writing a value list into the field would destroy the query the user is typing. `rel-select` can put chips inside its trigger because a trigger is not an editable surface — an input is. So the chips render beneath the field, the query clears after each toggle so the next search starts fresh, and the panel stays open. Reflected. |
+| `selectedValues` | `selected-values` | `string[]` | `[]` | Committed values in `multiple` mode (ignored otherwise). Mirrors `rel-select.selectedValues`. |
+| `selectAllLabel` | `select-all-label` | `string` | `"Select all"` | Label of the Select-all row shown at the top of the panel in `multiple` mode. |
 | `clearable` | `clearable` | `boolean` | `false` | Shows a trailing ✕ that clears the text and the committed value. |
 | `loading` | `loading` | `boolean` | `false` | Externally-controlled loading state (internal searchFn loading is automatic). |
 | `noResultsText` | `no-results-text` | `string` | `"No results found"` | Row shown when a query yields nothing. |
 | `loadingText` | `loading-text` | `string` | `"Loading…"` | Text shown next to the spinner while suggestions load. |
 | `label` | `label` | `string` | `undefined` | Visible label, forwarded to the inner `rel-textfield`. Also names the suggestion panel. |
 | `placeholder` | `placeholder` | `string` | `""` | Placeholder of the input, forwarded to the inner `rel-textfield`. |
-| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Field height — `small` 32px, `medium` 40px, `large` 48px — forwarded to the inner `rel-textfield`. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Field height — `small` 32px, `medium` 40px, `large` 48px — forwarded to the inner `rel-textfield`. Also drives the suggestion panel's row ramp. Reflected. |
 | `variant` | `variant` | `"default" \| "underline" \| "legend"` | `"default"` | Field chrome (`default` outlined, `underline`, `legend` notched outline), forwarded to the inner `rel-textfield`. |
 | `labelStyle` | `label-style` | `"default" \| "floating" \| "none"` | `undefined` | Label presentation (`default` / `floating` / `none`), forwarded to the inner field. Left `undefined`, the deprecated `floatingLabel` decides. Reflected. |
 | `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the input. Required when `labelStyle="none"`. |
@@ -113,7 +117,7 @@
 
 | Event | Detail | Bubbles / composed | Description |
 | --- | --- | --- | --- |
-| `changed` | `{ value: this.value, item: item ? item.item : null }` | bubbles / composed | Fired when the committed value changes — an item was selected (click, Enter, or an exact text match on Enter / Tab / blur) or the field was cleared. Detail: `{ value, item }`, where `item` is the original string or object, or `null` after a clear. |
+| `changed` | `{ value: this.selectedValues, item: null } / { value: this.value, item: item ? item.item : null }` | bubbles / composed | Fired when the committed value changes — an item was selected (click, Enter, or an exact text match on Enter / Tab / blur) or the field was cleared. Detail: `{ value, item }`, where `item` is the original string or object, or `null` after a clear. |
 | `rel-change` | `inputText / ""` | bubbles / composed | Fired on every keystroke with the raw input text as the detail (and with `""` after a clear). The committed `value` does not change until an item is selected. |
 | `rel-clear` | — | bubbles / composed | Fired when the clear icon empties a non-empty field (followed by `changed` and `rel-change`). No detail. |
 | `rel-search-error` | `{ query, error: err }` | bubbles / composed | Fired when `searchFn` rejects; the panel then shows the no-results row. Detail: `{ query, error }`. |
@@ -128,9 +132,14 @@
 
 | Part | Description |
 | --- | --- |
+| `chips` | — |
+| `chip` | — |
 | `panel` | The suggestion listbox container (same node as `list`) |
 | `list` | Alias of `panel` |
-| `option` | A suggestion row |
+| `select-all` | — |
+| `option` | A suggestion row. Emitted in BOTH single and `multiple` mode, unlike the two parts below |
+| `option-label` | The row's first line (the matched label). SINGLE-SELECT ROWS ONLY |
+| `option-supporting-text` | The row's optional second line, rendered only when the item supplies one. SINGLE-SELECT ROWS ONLY — under `multiple` the row is a nested `rel-checkbox` and the second line is that component's own `helper` part, inside its shadow root with nothing forwarding it out, so it cannot be reached with `::part()` at all. Style both modes with the `--rel-*` tokens instead |
 | `label` | The inner field's label (re-exported from `rel-textfield`) |
 | `control` | The inner field's bordered control box (re-exported from `rel-textfield`) |
 | `input` | The inner native input (re-exported from `rel-textfield`) |
@@ -146,15 +155,18 @@ Set these on the host (or an ancestor) to customise the element without touching
 | Custom property | Default | Description |
 | --- | --- | --- |
 | `--rel-autocomplete-bg` | `var(--rel-bg-neutral)` | Panel and row background |
-| `--rel-autocomplete-divider` | `var(--rel-border-subtle)` | Hairline between rows |
+| `--rel-autocomplete-divider` | `transparent` | Hairline between rows |
 | `--rel-autocomplete-icon-color` | `var(--rel-text-default)` | Colour of a row's leading `icon` |
 | `--rel-autocomplete-menu-border` | `var(--rel-border-default)` | Panel border colour. The panel is borderless by design and only draws this on dark surfaces, where its shadow alone can't separate it from the page. |
+| `--rel-autocomplete-menu-max-height` | `360px` | Scroll ceiling of the suggestion panel; default `360px`. Code-owned rather than Figma-derived — every Figma Menu variant hugs its content with no ceiling, which is not shippable for an unbounded result list. |
 | `--rel-autocomplete-menu-radius` | `var(--rel-border-radius-xs)` | Panel corner radius |
 | `--rel-autocomplete-menu-shadow` | `var(--rel-shadows-md)` | Panel box-shadow |
 | `--rel-autocomplete-option-hover` | `var(--rel-action-overlay-hover)` | Background of the hovered / keyboard-highlighted / selected row |
 | `--rel-autocomplete-option-pressed` | `var(--rel-action-overlay-pressed)` | Background of a row while it is being pressed |
 | `--rel-autocomplete-status-color` | `var(--rel-text-body)` | Colour of the loading / no-results status rows |
+| `--rel-autocomplete-supporting-color` | `var(--rel-text-caption)` | — |
 | `--rel-autocomplete-value-color` | `var(--rel-text-default)` | Suggestion label colour |
+| `--rel-overlay-fallback-z` | `1001` | z-index of the panel on the **no-Popover-API fallback path only**. Wherever the browser top layer is available the panel is promoted into it and this value is inert, because top-layer elements are not in the page stacking order at all. Shared with the other overlays (select, autocomplete, the three pickers) so the whole family can be moved from one place. |
 
 <!-- readme-gen:end -->
 
@@ -180,6 +192,9 @@ Focus: `focus()` on the host delegates to the inner field. Focusing the field wi
 
 ## Notes / Edge Cases
 
+- **The second line is searchable, and that changes which rows appear.** `supportingText` is matched by the filter alongside the label, because the identifiers it usually carries (a DOT or MC number, a code) are the reason to show it at all. An item whose label does not match but whose supporting text does will now appear in the list, and the matched characters are emboldened on whichever line they were found. Set `filter="none"` or drop `supportingText` if you need the previous label-only behaviour.
+- The second line truncates with an ellipsis rather than wrapping — the panel is pinned to the field's width, and a suggestion row is a fixed-height scanning target. Rows grow from 32 / 40 / 48 to roughly 46 / 58 / 70 when an item supplies one; a row without `supportingText` is unchanged. This holds in `multiple` mode too (the nested checkbox rows used to wrap, and an unbroken identifier could push the panel sideways). Nothing is hyphenated. A row that carries a second line also gets a native `title` with its full label and supporting text, so hovering a truncated row reveals what was cut.
+- **In `multiple` mode the text input stays a search box.** It never displays the committed values: in single mode the input shows the selected label, but in multi there is no single label to show, and writing a value list into the field would overwrite the query being typed. The chips therefore render *beneath* the field (`rel-select` can carry them inside its trigger because a trigger is not editable), the query clears after each toggle so the next search starts fresh, and the panel stays open. Read the selection from `selectedValues`, not `value`; `changed` carries the array.
 - `value` and the visible text are separate: typing only emits `rel-change`; `value` (and `changed`) update when a row is picked, or when the text exactly matches an item's label or value (case-insensitive) on Enter, Tab, blur or outside click. Free text that matches nothing stays in the field but never becomes `value`.
 - Setting `value` externally (attribute, property, Angular `writeValue`) shows the matching item's label, or the raw string when no item matches (common with remote data on init) — provide the item in `items` to show its label.
 - Clearing emits, in order, `rel-clear`, `changed` (`value: ""`, `item: null`) and `rel-change` (`""`), and only when the field actually had text or a value.
@@ -190,3 +205,5 @@ Focus: `focus()` on the host delegates to the inner field. Focusing the field wi
 - `full-width` layout is keyed off the **attribute** (`:host(:not([full-width]))` renders inline-block) even though the property defaults to `true` and is not reflected — add the `full-width` attribute in markup when you need the block layout. This differs from `rel-textfield`, whose `fullwidth` attribute is reflected.
 - The suggestion panel mirrors `rel-select`'s listbox (same tokens, radius, shadow, row styling) and is promoted to the browser top layer (native Popover API, `popover="manual"`), so it renders correctly inside transformed or `overflow: hidden` containers such as a centered `rel-modal` or a `rel-drawer`; engines without the Popover API fall back to `position: fixed` with a measure-and-cancel correction. It matches the field width, flips above when short on space, and closes on outside pointerdown or outside scroll.
 - Only `label`, `control`, `input`, `helper` and `right-icon` are re-exported from the inner `rel-textfield`; its `prefix` / `suffix` parts and slots are not exposed.
+- The field passthroughs are a fixed subset, forwarded as **property** bindings (`.prefixIcon=${…}`), so they are unaffected by attribute-spelling differences between the two components. `rel-textfield` props outside that subset — `prefixText`, `prefixStyle`, `suffixText`, `suffixDivider`, `helperIcon`, `maxLength`, `multiline`, `rows`, `type` — are not forwarded and cannot be set through `rel-autocomplete`.
+- Several of the passthroughs take a **kebab attribute here and an all-lowercase one on `rel-textfield`**: `prefix-icon` / `prefixicon`, `helper-text` / `helpertext`, `error-message` / `errormessage`, `floating-label` / `floatinglabel`, `full-width` / `fullwidth`. Moving markup between the two elements therefore needs the attribute renamed, and a wrong spelling fails silently rather than erroring. `rel-textfield`'s README carries the full table; 3.0 unifies on the kebab spellings used here.

package/dist/components/rel-avatar/README.md

@@ -19,10 +19,10 @@
 </rel-avatar>
 
 <!-- Sizes: xs 20px, sm 24px, md 32px (default), lg 40px -->
-<rel-avatar type="text" text="XS" size="xs"></rel-avatar>
-<rel-avatar type="text" text="SM" size="sm"></rel-avatar>
-<rel-avatar type="text" text="MD" size="md"></rel-avatar>
-<rel-avatar type="text" text="LG" size="lg"></rel-avatar>
+<rel-avatar type="text" text="XS" size="extra-small"></rel-avatar>
+<rel-avatar type="text" text="SM" size="small"></rel-avatar>
+<rel-avatar type="text" text="MD" size="medium"></rel-avatar>
+<rel-avatar type="text" text="LG" size="large"></rel-avatar>
 
 <!-- Variants -->
 <rel-avatar type="text" text="AA" variant="fill"></rel-avatar>
@@ -50,7 +50,7 @@
 
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `size` | `size` | `"lg" \| "md" \| "sm" \| "xs"` | `"md"` | Diameter step: `lg` 40px, `md` 32px, `sm` 24px, `xs` 20px; each binds the matching body-*-semibold text role for initials. Reflected. |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "extra-small" \| "lg" \| "md" \| "sm" \| "xs"` | `"medium"` | Diameter step: `large` 40px, `medium` 32px, `small` 24px, `extra-small` 20px; each binds the matching body-*-semibold text role for initials. `lg` / `md` / `sm` / `xs` are alternative spellings and stay supported — they are normalised to the full words, not deprecated. Reflected. |
 | `type` | `type` | `"image" \| "text" \| "icon"` | `"image"` | What is rendered inside the circle: `image` shows `src`, `text` shows the `text` initials, `icon` shows the default slot. Reflected. |
 | `variant` | `variant` | `"fill" \| "subtle" \| "outline"` | `"fill"` | Fill style: `fill` = solid inverse background with light text, `subtle` = elevated neutral background, `outline` = transparent with a 1px border. Reflected. |
 | `src` | `src` | `string` | `""` | Image URL for `type="image"`; when empty nothing is rendered inside the circle (there is no fallback to initials). |
@@ -69,7 +69,7 @@
 
 | Slot | Description |
 | --- | --- |
-| (default) | Icon content rendered when `type="icon"` (typically an inline SVG, sized to 50% of the circle) |
+| (default) | Icon content rendered when `type="icon"` (typically an inline SVG, sized 20 / 18 / 16 / 12px by `size`) |
 
 ## CSS Parts
 
@@ -88,12 +88,14 @@ Set these on the host (or an ancestor) to customise the element without touching
 | Custom property | Default | Description |
 | --- | --- | --- |
 | `--rel-avatar-bg-fill` | `var(--rel-bg-neutral-inverse-2)` | Background colour of the `fill` variant |
+| `--rel-avatar-bg-outline` | `var(--rel-bg-neutral)` | Background colour of the `outline` variant; defaults to --rel-bg-neutral |
 | `--rel-avatar-bg-subtle` | `var(--rel-bg-neutral-elevated-1)` | Background colour of the `subtle` variant |
 | `--rel-avatar-border-outline` | `var(--rel-border-default)` | 1px border colour of the `outline` variant |
 | `--rel-avatar-color-fill` | `var(--rel-text-inverse)` | Text / icon colour of the `fill` variant |
 | `--rel-avatar-color-outline` | `var(--rel-text-default)` | Text / icon colour of the `outline` variant |
 | `--rel-avatar-color-subtle` | `var(--rel-text-default)` | Text / icon colour of the `subtle` variant |
 | `--rel-avatar-font-size` | `var(--_rel-avatar-font-size)` | Overrides the initials' font-size, for use alongside `--rel-avatar-size`; defaults to the preset's text role |
+| `--rel-avatar-icon-size` | `var(--_rel-avatar-icon-size)` | Overrides the slotted icon's size; defaults to the preset ramp (20 / 18 / 16 / 12px) |
 | `--rel-avatar-size` | `var(--_rel-avatar-size)` | Overrides the circle's width/height for sizes between (or below) the `size` presets; defaults to the preset's diameter |
 
 <!-- readme-gen:end -->
@@ -112,5 +114,5 @@ Set these on the host (or an ancestor) to customise the element without touching
 - `type="image"` with an empty `src` renders an empty circle — there is no automatic fallback to initials. Switch `type` yourself when the photo is missing.
 - Every variant keeps a 1px border (`--rel-stroke-sm`); `fill` and `subtle` make it transparent so the outer size is identical across variants.
 - `bg` and `color` are written as inline styles on the `base` part, so they win over both the `--rel-avatar-*` hooks and the variant tokens.
-- Initials are forced uppercase and `user-select: none`. `size`, `type` and `variant` are reflected, so `rel-avatar[size="lg"]` works as a selector.
+- Initials are forced uppercase and `user-select: none`. `size`, `type` and `variant` are reflected, so `rel-avatar[size="large"]` works as a selector. Because `lg` / `md` / `sm` / `xs` are normalised to the full words before reflection, the selector matches whichever spelling was written.
 - The `icon` part name is shared by the `<img>` (`type="image"`) and the slot wrapper (`type="icon"`); `::part(icon)` matches whichever one is rendered.

package/dist/components/rel-badge/README.md

@@ -12,9 +12,7 @@
 <rel-badge number="120" size="xl"></rel-badge>
 
 <!-- Dot badges (no text) -->
-<rel-badge variant="dot" size="sm"></rel-badge>
-<rel-badge variant="dot" size="md"></rel-badge>
-<rel-badge variant="dot" size="lg"></rel-badge>
+<rel-badge variant="dot"></rel-badge>
 
 <!-- Positioned over an icon button -->
 <div style="position: relative; display: inline-block;">
@@ -45,8 +43,8 @@
 | `number` | `number` | `string` | `""` | Text shown in the `number` variant (a count such as "5" or "99+"); not rendered by `variant="dot"` but still used to build the accessible name. |
 | `ariaLabel` | `arialabel` | `string` | `""` | Explicit accessible name; when empty it is composed as "<number> <suffix>" or, with no number, "New <suffix>". Attribute is `arialabel`. |
 | `suffix` | `suffix` | `string` | `"notifications"` | Noun appended to the count in the generated accessible name, e.g. "3 notifications". |
-| `size` | `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Badge scale (Figma Badge S/M/L/XL): number badges are 20 / 24 / 28 / 40px tall, dot badges 8 / 10 / 12 / 12px. Reflected. |
-| `variant` | `variant` | `"dot" \| "number"` | `"number"` | `number` renders the `number` text in a pill that widens with its content; `dot` renders a small disc with no text. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "extra-large" \| "sm" \| "md" \| "lg" \| "xl"` | `"medium"` | Badge scale (Figma Badge S/M/L/XL): number badges are 20 / 24 / 28 / 40px tall. `sm` / `md` / `lg` / `xl` are accepted and normalised to the full words. Ignored when `variant="dot"` — Figma models `Dot` as a fifth option of the same Size axis, so a dot has one size. Reflected. |
+| `variant` | `variant` | `"dot" \| "number"` | `"number"` | `number` renders the `number` text in a pill that widens with its content; `dot` renders a 6px disc with no text (Figma `Size=Dot`), ignoring `size`. Reflected. |
 | `color` | `color` | `string` | `""` | Direct CSS color override for the badge background. Accepts any valid CSS color value: hex, rgb(...), hsl(...), named color, or var(--token). Clear it (set to `''`) to fall back to the default token. Reflected. |
 | `textColor` | `text-color` | `string` | `""` | Direct CSS color override for the badge text/icon color. Accepts any valid CSS color value: hex, rgb(...), hsl(...), named color, or var(--token). Clear it (set to `''`) to fall back to the default (white). Reflected. |
 
@@ -78,6 +76,7 @@ Set these on the host (or an ancestor) to customise the element without touching
 | --- | --- | --- |
 | `--rel-badge-bg` | `var(--rel-bg-danger)` | Background colour of the badge; the `color` prop writes this on the host |
 | `--rel-badge-color` | `var(--rel-text-static-light)` | Text colour of the count; the `text-color` prop writes this on the host |
+| `--rel-badge-dot-size` | `6px` | Diameter of the `dot` variant; default 6px, the single dot size Figma draws. Set it to restore the larger discs shipped previously. |
 
 <!-- readme-gen:end -->
 

package/dist/components/rel-button/README.md

@@ -93,7 +93,7 @@ Action button implementing the Figma "Button" component: a native `<button>` wit
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `variant` | `variant` | `"default" \| "primary" \| "secondary" \| "text" \| "link" \| "icon" \| "static" \| "outline" \| "ghost"` | `"default"` | Style axis (Figma "Style"). Canonical: `default` (legacy neutral fill), `primary`, `secondary` (outlined), `ghost` (text-only), `link` (underlined inline text), `static` (transparent, static-light label for dark/colored surfaces). Deprecated aliases still accepted: `outline` = secondary, `text` = ghost, and `icon` (pre-2.0 40px circular icon button — use `icon-only` with a style instead). |
-| `tone` | `tone` | `"default" \| "primary" \| "secondary" \| "critical" \| "success" \| "neutral" \| "brand" \| "danger" \| "destructive"` | `"default"` | Tone axis (Figma "Tone"). Canonical: `neutral` (= `default`), `brand` (= `primary`), `destructive`. Deprecated aliases `critical` and `danger` map to destructive and log a one-time console notice. `secondary` and `success` are legacy extras with no Figma counterpart (secondary only affects the legacy `icon` variant). |
+| `tone` | `tone` | `"default" \| "primary" \| "secondary" \| "critical" \| "success" \| "neutral" \| "brand" \| "danger" \| "destructive"` | `undefined` | Tone axis (Figma "Tone"). Canonical: `neutral` (= `default`), `brand` (= `primary`), `destructive`. Deprecated aliases `critical` and `danger` map to destructive and log a one-time console notice. `secondary` and `success` are legacy extras with no Figma counterpart (secondary only affects the legacy `icon` variant). Left UNSET it means `neutral`, except on `variant="primary"`, where it still means `brand` for one release — see `effectiveTone`. Write the tone explicitly and you always get what you wrote. |
 | `iconOnly` | `icon-only` | `boolean` | `false` | Figma "Type=Icon Only": renders a square button (32/40/48px per `size`) of the current style and tone with no padding or min-width. Composes with every `variant`; slot a single `rel-icon` and set `aria-label`. Reflected. |
 | `loading` | `loading` | `boolean` | `false` | Figma "State=Loading": replaces the label with a spinner (`indicator` part), sets `aria-busy`, and blocks pointer and programmatic clicks. The button keeps its width. Reflected. |
 | `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Figma "Size": `small` = 32px, `medium` = 40px, `large` = 48px height, with matching padding, typography and minimum width. |
@@ -150,8 +150,38 @@ Focus: `:focus-visible` shows the shared 2px focus outline plus inner/outer halo
 
 ## Notes / Edge Cases
 
+### The `variant="primary"` tone transition
+
+Figma's `Style=Primary` is the **filled** style, and `Tone` picks its colour — so Primary + Neutral is the neutral fill and Primary + Brand is the brand fill. This component's `variant="primary"` historically meant *both* "filled" and "brand-coloured", which left the Figma-canonical Primary/Neutral cell unreachable by its own names.
+
+That cell now works: **`variant="primary" tone="neutral"` renders the neutral fill.**
+
+For one release there is a deliberate wrinkle, and it is worth knowing before you debug it:
+
+| Markup | Renders | Why |
+| --- | --- | --- |
+| `<rel-button>` | neutral fill | Unchanged. `variant` defaults to `default`, which is Figma's Primary/Neutral. |
+| `<rel-button variant="primary">` | **brand** fill | Unset tone still means brand *here only*, so existing brand buttons do not silently turn neutral. Logs a one-time console notice. |
+| `<rel-button variant="primary" tone="brand">` | brand fill | The explicit form. **Write this.** |
+| `<rel-button variant="primary" tone="neutral">` | neutral fill | The Figma-canonical cell, now reachable. |
+
+So for this release, writing the default value explicitly changes the result: `variant="primary"` alone and `variant="primary" tone="neutral"` render differently. Setting `tone` explicitly always gives you exactly what you wrote. A future major will make an unset tone mean `neutral` everywhere, matching every other style.
+
+### Tone × Style matrix
+
+Figma populates only part of the grid. Combinations outside it have no design-system definition and fall back to the style's neutral treatment:
+
+| Tone | Primary | Secondary | Ghost | Link | Static |
+| --- | --- | --- | --- | --- | --- |
+| Neutral | yes | yes | yes | yes | yes |
+| Brand | yes | — | — | — | — |
+| Destructive | yes | yes | yes | yes | — |
+
+`Link` additionally has no icon-only and no loading state in the design.
+
 - **Events.** The element dispatches no custom events. The native `click` is `composed`, so a listener on `<rel-button>` (or an ancestor) receives exactly one event per activation — do not re-dispatch it.
-- **Minimum widths** come from the Figma master: small/medium/large = 80/100/120px, ghost small = 56px. `link` has no minimum, `icon-only` is a fixed square (32/40/48px) and the legacy `icon` variant is always a 40px circle regardless of `size`. Override per instance with `--rel-button-min-width`.
+- **Minimum widths** come from the Figma master: small/medium/large = 80/100/120px, static = 40/50/60px. `link` has no minimum, `icon-only` is a fixed square (32/40/48px) and the legacy `icon` variant is always a 40px circle regardless of `size`. Override per instance with `--rel-button-min-width`.
+- **`border`** exposes `small-corner-radius` and `no-corner-radius`, which have no design-system backing — every one of Figma's 624 button nodes is fully rounded. They are a code-only extension, kept for existing layouts.
 - **Legacy `icon` variant vs `icon-only`.** `variant="icon"` keeps its pre-2.0 look (40px circle, tone-driven fill, `tone="secondary"` gives it an outline) and ignores `size` and `border`. `icon-only` is an axis that composes with any style and size — prefer it.
 - **`tone` on `secondary` / `ghost` / `link`** changes the label, border or text colour only; the fill stays on the surface. The destructive outline border is deliberately subtle at rest and only goes solid on hover/pressed, matching Figma.
 - **`static`** is a neutral-only style meant for coloured or dark backgrounds; other tones have no static treatment.

package/dist/components/rel-card/README.md

@@ -1,6 +1,6 @@
 # rel-card
 
-`<rel-card>` is a bordered, padded surface that groups related content — the Figma "Card" component. `type="custom"` (the default) pads whatever you slot in and applies the Figma card typography to slotted headings and paragraphs; `type="media"` adds a flush media region above the body, meant for a `<rel-card-media>` image header. Use it for dashboard tiles, summary blocks and list items that pair a title with body copy. It is a static container with no interaction of its own — for transient content use `rel-modal` or `rel-drawer` instead, and for a surface with its own tone/elevation variants use `rel-container`.
+`<rel-card>` is an elevated, padded surface that groups related content — the Figma "Card" component. `type="custom"` (the default) pads whatever you slot in and applies the Figma card typography to slotted headings and paragraphs; `type="media"` adds a flush media region above the body, meant for a `<rel-card-media>` image header. Use it for dashboard tiles, summary blocks and list items that pair a title with body copy. It is a static container with no interaction of its own — for transient content use `rel-modal` or `rel-drawer` instead, and for a surface with its own tone/elevation variants use `rel-container`.
 
 ## Usage
 
@@ -55,7 +55,7 @@
 
 | Part | Description |
 | --- | --- |
-| `base` | The outer bordered card surface |
+| `base` | The outer elevated card surface |
 | `header` | The media region wrapper (present only when `type="media"`) |
 | `content` | The padded body that wraps the default slot |
 
@@ -72,4 +72,4 @@
 - `type="media"` removes the card's own padding and clips overflow so the media sits flush against the rounded border; the body (`content` part) keeps the standard padding. Content placed in the `media` slot without `type="media"` is not rendered, because the slot only exists in that mode.
 - The `header` part exists only while `type="media"`; `::part(header)` matches nothing otherwise.
 - Slotted `h1`–`h4` and `p` elements get the Figma card roles (heading md / body lg) with their default margins reset; wrap other content in your own elements to style it.
-- There is no hover lift, shadow or transition — the card is a flat bordered surface in both light and dark themes.
+- The card is elevated with Figma's `shadow/sm` and draws no border, in both light and dark themes. There is no hover lift or transition.

package/dist/components/rel-carousel/README.md

@@ -142,8 +142,11 @@ Set these on the host (or an ancestor) to customise the element without touching
 | `--rel-carousel-dot-size` | `8px` | Diameter of an inactive dot (default 8px). |
 | `--rel-carousel-dot-size-active` | `16px` | Width of the active (brand-coloured, pill-shaped) dot (default 16px). |
 | `--rel-carousel-height` | `320px` | Viewport height in `orientation="vertical"` (default 320px); the horizontal viewport takes the height of its tallest slide. |
+| `--rel-carousel-slide-display` | `flex` | `display` given to each slide in `orientation="vertical"` only, which is what centres the slide's content in the fixed-height viewport as Figma draws it. Set it to `block` to opt out if forcing flex reflows your slide's own children. Horizontal slides are never touched. |
 | `--rel-carousel-nav-size` | `32px` | Width / height of the arrow buttons (default 32px, matching Figma; applies to both side and bottom arrows). |
+| `--rel-carousel-slide-bg` | `var(--rel-bg-neutral)` | — |
 | `--rel-carousel-slide-height` | `100%` | Written by the component on its own host to the computed panel height (used for vertical slides); not meant to be set by consumers. |
+| `--rel-carousel-slide-radius` | `var(--rel-border-radius-sm)` | — |
 | `--rel-carousel-slide-width` | `100%` | Written by the component on its own host to the computed panel width (viewport width for `panels="1"`, a fraction of it above that); not meant to be set by consumers (an inline value is overwritten on resize). |
 
 <!-- readme-gen:end -->

package/dist/components/rel-checkbox/README.md

@@ -1,6 +1,6 @@
 # rel-checkbox
 
-A tri-state checkbox implementing the Figma "Checkbox" sheet: a hidden native `<input type="checkbox">` behind a custom box, with a label, an optional label-prefix icon and optional supporting text. It exposes the sheet's vocabulary verbatim — `size` (small / medium / large), `density` (compact / comfortable) and `alignment` (leading / trailing) — plus `state` for error and disabled styling. Use it for independent yes/no choices and for "select all" parents (via `status="indeterminate"`); for a single choice among several options use `rel-radio`, and for an immediate on/off setting use `rel-switch`.
+A tri-state checkbox implementing the Figma "Checkbox" sheet: a hidden native `<input type="checkbox">` behind a custom box, with a label, an optional label-prefix icon and optional supporting text. It exposes the sheet's vocabulary verbatim — `size` (small / medium / large / extra-large), `density` (compact / comfortable) and `alignment` (leading / trailing) — plus `state` for error and disabled styling. Use it for independent yes/no choices and for "select all" parents (via `status="indeterminate"`); for a single choice among several options use `rel-radio`, and for an immediate on/off setting use `rel-switch`.
 
 ## Usage
 
@@ -64,12 +64,13 @@ A tri-state checkbox implementing the Figma "Checkbox" sheet: a hidden native `<
 | `label` | `label` | `string` | `"Label"` | Label text rendered next to the box. |
 | `icon` | `icon` | `string` | `""` | rel-icon name rendered between the checkbox and the label (label prefix icon); scales with `size`. Unset renders no icon and reserves no space. |
 | `supportingtext` | `supportingtext` | `string` | `""` | Supporting text under or beside the label; where it renders depends on `density`. |
-| `state` | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Visual and interaction state (Figma State): `"error"` swaps in the danger colours, `"disabled"` blocks input and dims the control to 0.55 opacity. |
+| `state` | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Visual and interaction state (Figma State): `"error"` swaps in the danger colours, `"disabled"` blocks input and dims the whole control to 0.4 opacity (colours unchanged, as Figma specifies). |
 | `status` | `status` | `"unchecked" \| "checked" \| "indeterminate"` | `"unchecked"` | Check state. `"indeterminate"` is programmatic-only — a user toggle always resolves to checked or unchecked. |
 | `value` | `value` | `string` | `""` | Value reported in the `rel-change` event detail (it is not submitted with a form). |
-| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Control scale (Figma Size). `"medium"` (default) = 18px box with body-lg label; `"small"` = 14px box with body-md label; `"large"` (Figma L, added 2026-09-04) = 20px box with body-lg label and body-sm supporting text — the same additive step rel-radio took for its large size. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "extra-large"` | `"medium"` | Control scale (Figma Size), on Figma's four-step ramp of control frames: `"small"` 16px / body-sm, `"medium"` (default) 18px / body-md, `"large"` 20px / body-lg, `"extra-large"` 24px / body-xl. Supporting text sits one body step below the label at every size (body-xs / sm / md / lg, i.e. 10 / 12 / 14 / 16px). The drawn square is inset to 80% of the frame, so the frame is the layout footprint (what the row gap and the compact indent measure from) rather than the visible square. Reflected. |
 | `density` | `density` | `"compact" \| "comfortable"` | `"compact"` | Supporting-text layout (Figma Density). `"compact"` (default) puts the supporting text on its own line under the row, indented past the box; `"comfortable"` stacks label + supporting text beside the box. Reflected. |
 | `alignment` | `alignment` | `"leading" \| "trailing"` | `"leading"` | Box position (Figma Alignment). `"leading"` (default) renders the box before the label; `"trailing"` pushes it to the far edge of the row. Trailing has no compact layout in the spec, so it always renders with comfortable density. Reflected. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the native checkbox, for when the visible `label` is absent or not a usable name on its own — a checkbox in a table row, or one whose meaning comes from its column header. Normally unnecessary: the input is wrapped in the `<label>` that renders `label`, so the visible text already names it natively. Setting this puts an `aria-label` on the input, which OVERRIDES that wrapping label — so set it only when the visible text is the wrong name, not to repeat it. Left unset the attribute is not emitted at all. |
 
 ### Public fields / accessors
 
@@ -121,7 +122,8 @@ A tri-state checkbox implementing the Figma "Checkbox" sheet: a hidden native `<
 - The host is `display: block`, so a trailing checkbox stretches to its container width; constrain the parent to control row width.
 - `value` is only reported in the `rel-change` detail — the element does not participate in native form submission.
 - The hidden native input is absolutely positioned against the `.row` containing block; keep `position: relative` on `.row` (Tab-scroll page-jump fix, shared with rel-radio).
-- Rendered box sizes are 18 / 22 / 24px (content + 2px border) for small / medium / large, against Figma's 16 / 18 / 20 outer frames — a known, unaudited oversize on S/M.
+- Control frames are 16 / 18 / 20 / 24px for small / medium / large / extra-large, matching Figma. The frame is the layout footprint — the row gap and the compact indent measure from it — while the drawn square is inset to 80% of the frame (12.8 / 14.4 / 16 / 19.2px), as Figma draws it.
+- The square's 2px border weight is **not** verified against Figma: the control is flattened artwork (a filled vector rather than a frame with a stroke), so the sheet gives the square's outer size but says nothing about its stroke. Carried forward from the previous implementation.
 
 ### Layout matrix (mirrors the Figma sheet)
 
@@ -133,6 +135,8 @@ A tri-state checkbox implementing the Figma "Checkbox" sheet: a hidden native `<
 | S | Compact | yes | renders comfortable |
 | L | Comfortable | yes | yes |
 | L | Compact | yes | renders comfortable |
+| XL | Comfortable | yes | yes |
+| XL | Compact | yes | renders comfortable |
 
 ### Recipes (intentionally not component props)
 

package/dist/components/rel-chip/README.md

@@ -5,22 +5,28 @@
 ## Usage
 
 ```html
-<!-- Basic chip (tone="neutral" variant="fill" size="md" border="default") -->
+<!-- Basic chip (tone="neutral" variant="fill" size="medium" border="default") -->
 <rel-chip label="Active"></rel-chip>
 
 <!-- Tones -->
 <rel-chip label="Info" tone="info"></rel-chip>
 <rel-chip label="Warning" tone="warning"></rel-chip>
-<rel-chip label="Error" tone="danger"></rel-chip>
+<rel-chip label="Error" tone="destructive"></rel-chip>
 <rel-chip label="Success" tone="success"></rel-chip>
 
 <!-- Subtle variant: tinted background, tone-coloured text -->
 <rel-chip label="Subtle" tone="info" variant="subtle"></rel-chip>
 
 <!-- Sizes -->
+<rel-chip label="Small" size="small"></rel-chip>
+<rel-chip label="Medium" size="medium"></rel-chip>
+<rel-chip label="Large" size="large"></rel-chip>
+
+<!-- Deprecated aliases — these still render, but prefer the canonical spellings above.
+     tone="danger" is an alias of tone="destructive" and logs a one-time console notice.
+     size="sm" / "md" / "lg" are alternative spellings (NOT deprecated, no notice). -->
+<rel-chip label="Error" tone="danger"></rel-chip>
 <rel-chip label="Small" size="sm"></rel-chip>
-<rel-chip label="Medium" size="md"></rel-chip>
-<rel-chip label="Large" size="lg"></rel-chip>
 
 <!-- Fully rounded corners -->
 <rel-chip label="Rounded" border="rounded"></rel-chip>
@@ -60,9 +66,9 @@
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `label` | `label` | `string` | `"Label"` | Text shown in the chip; also its accessible name and the drag payload. |
-| `tone` | `tone` | `"neutral" \| "danger" \| "warning" \| "success" \| "info"` | `"neutral"` | Colour tone (Figma Tone): `neutral`, `danger`, `warning`, `success` or `info`. Combined with `variant`. Reflected. |
-| `variant` | `variant` | `"fill" \| "subtle"` | `"fill"` | Emphasis (Figma Variant): `fill` = solid tone background, `subtle` = tinted background with tone-coloured text. Reflected. |
-| `size` | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height scale (Figma Size): `sm` 24px / body-sm, `md` 28px / body-md, `lg` 32px / body-lg. Icon size follows (12 / 14 / 16px). Reflected. |
+| `tone` | `tone` | `"neutral" \| "destructive" \| "warning" \| "success" \| "info" \| "danger"` | `"neutral"` | Colour tone (Figma Tone): `neutral`, `destructive`, `warning`, `success` or `info`. Combined with `variant`. `"danger"` is a deprecated alias of `"destructive"`: it keeps working, logs a one-time console notice, and is normalised to `"destructive"` on the property and the reflected attribute. Reflected. |
+| `variant` | `variant` | `"fill" \| "subtle" \| "primary" \| "secondary"` | `"fill"` | Emphasis (Figma Style): `fill` = solid tone background, `subtle` = tinted background with tone-coloured text. Figma's own spellings `primary` and `secondary` are accepted and normalised to `fill` / `subtle`. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Height scale (Figma Size): `small` 24px / body-sm, `medium` 28px / body-md, `large` 32px / body-lg. Icon size follows (12 / 14 / 16px). `sm` / `md` / `lg` are accepted and normalised to the full words. Reflected. |
 | `border` | `border` | `"default" \| "rounded"` | `"default"` | Corner shape (Figma Border): `default` = 4px radius, `rounded` = fully rounded with 12px horizontal padding. Reflected. |
 | `leadingIcon` | `leading-icon` | `string` | `undefined` | Icon name from the generated icon dictionary (e.g. "settings") — rendered via <rel-icon> before the label. Ignored when `avatar` is set. |
 | `trailingIcon` | `trailing-icon` | `string` | `undefined` | Icon name from the generated icon dictionary, rendered after the label. |