@reliability-design/web 1.4.6 → 1.4.8

package/dist/index.d.ts

@@ -3,13 +3,45 @@ import * as lit from 'lit';
 import { LitElement, PropertyValues, TemplateResult } from 'lit';
 export * from '@reliability-design/icons';
 
+/**
+ * Single collapsible section (Figma "Accordion", 6021:1085): a clickable header
+ * that expands/collapses the slotted body with an animated chevron.
+ * @slot - Body content, revealed when `open`
+ * @slot icon - Leading icon in the header (`type="action"` only); replaces the default rotating chevron-down
+ * @slot trailing-icon - Trailing icon in the header; replaces the default chevron-down (default type) or arrow-expansion (action type)
+ * @csspart base - The outer card (`.accordion`) carrying the appearance border / shadow
+ * @csspart trigger - The `role="button"` header row
+ * @csspart label - The title row (leading icon + title text)
+ * @csspart icon - The trailing icon wrapper
+ * @csspart content - The `role="region"` body that holds the default slot
+ */
 declare class RelAccordion extends LitElement {
+    /** Header text. Note it is also the native HTML `title` attribute, so browsers show it as a tooltip on hover. */
     title: string;
+    /** Whether the body is expanded; toggled by the header and reported via `open-change`. Setting it from code does not fire the event. */
     open: boolean;
-    size: "md" | "sm";
+    /**
+     * 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.
+     */
+    size: "md" | "sm" | "large" | "medium" | "small";
+    /**
+     * 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.
+     */
     type: "default" | "action";
-    /** Figma "Style" axis — named appearance because `style` collides with the HTML style attribute. */
+    /** 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. */
     appearance: "shadow" | "plain";
+    /** 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. */
+    disabled: boolean;
     static styles: lit.CSSResult;
     /** Stable id prefix wiring the header to its panel. */
     private accordionId;
@@ -17,15 +49,44 @@ declare class RelAccordion extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/** Canonical semantic tones (Figma "Tone"). */
+type AlertTone = "neutral" | "info" | "success" | "warning" | "destructive";
+/** Deprecated tone spellings, all mapped to "destructive". */
+type AlertToneAlias = "error" | "danger" | "critical";
+type AlertToneInput = AlertTone | AlertToneAlias;
+/**
+ * Inline status banner (Figma "Alert"): a tone-coloured box with a leading status icon, a bold title, optional supporting text, an optional link and an optional dismiss button. Use it for persistent page- or section-level messages; use `rel-toast` / `rel-snackbar` for transient feedback.
+ * @csspart base - The `role="alert"` container that carries the tone and appearance styling
+ * @csspart icon - Wrapper around the leading status `<rel-icon>`
+ * @csspart content - Column that stacks the title, helper text and link
+ * @csspart label - The primary message (`message1`) paragraph
+ * @csspart helper - The secondary message (`message2`) paragraph; rendered only when `message2` is set
+ * @csspart action - The inline link; rendered only when both `url-text` and `url-href` are set
+ * @csspart close-button - The dismiss (✕) button; rendered only while `dismissible` is true
+ */
 declare class RelAlert extends LitElement {
-    type: "info" | "success" | "warning" | "error" | "neutral";
-    /** Visual treatment (Figma "Style"): solid | subtle | outline. "filled" is a deprecated alias of solid. */
+    /**
+     * Semantic tone (Figma "Tone"): `"neutral"` (default) | `"info"` | `"success"` | `"warning"` | `"destructive"`. Drives the fill/border colour, the title colour and the leading icon (info, check-circle, alert-circle, error). `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"` and log a one-time console notice. Takes precedence over the deprecated `type` prop.
+     */
+    tone?: AlertToneInput;
+    /** @deprecated Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"`. Ignored when `tone` is set. Logs a one-time console notice. */
+    type?: AlertToneInput;
+    /** Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"destructive"`. */
+    get resolvedTone(): AlertTone;
+    willUpdate(changed: Map<string, unknown>): void;
+    /** Visual treatment (Figma "Style"): `"subtle"` (default: tone-light fill, no border) | `"solid"` (tone fill, inverse text, `--rel-shadows-md` elevation) | `"outline"` (transparent fill, tone border). `"filled"` is a deprecated alias of `"solid"` (no console notice). */
     appearance: "solid" | "subtle" | "outline" | "filled";
+    /** Primary message (title), rendered in body-lg medium weight in the tone colour. */
     message1: string;
+    /** Optional secondary message rendered under the title in body-md at 90% opacity; omitted when unset. */
     message2?: string;
+    /** Text of the inline link rendered under the messages. The link appears only when both `urlText` and `urlHref` are set. */
     urlText?: string;
+    /** `href` of the inline link. The link appears only when both `urlText` and `urlHref` are set. */
     urlHref?: string;
+    /** Shows the dismiss (✕) button. Defaults to true; because it is a Lit boolean, `dismissible="false"` is still true — set the property to `false` from script to hide the button. */
     dismissible: boolean;
+    /** True once the alert has been dismissed; hides the host via `:host([dismissed]) { display: none }`. Set it back to `false` to show the alert again. */
     dismissed: boolean;
     static styles: lit.CSSResult;
     private dismissAlert;
@@ -52,12 +113,37 @@ type TextFieldPrefixStyle = "clear" | "divider" | "fill";
  *                    `fieldAriaLabelledby` to keep an accessible name
  */
 type FieldLabelStyle = "default" | "floating" | "none";
+/**
+ * `<rel-textfield>` — single-line or multi-line text input (Figma "Text Field").
+ * @slot prefix - Custom content at the far left of the control (e.g. a unit dropdown); shares the prefix block with `prefixIcon` / `prefixText`. Hidden when `multiline` is set.
+ * @slot suffix - Custom content at the far right of the control (e.g. an action button); shares the suffix block with `rightIcon` / `suffixText`. Hidden when `multiline` is set.
+ * @csspart label - The visible label element (default and floating label styles)
+ * @csspart control - The bordered control box (the fieldset in the legend variant)
+ * @csspart input - The native input / textarea
+ * @csspart prefix - The prefix block (leading icon, prefix text and the `prefix` slot)
+ * @csspart suffix - The suffix block (suffix text, trailing icon and the `suffix` slot)
+ * @csspart right-icon - The trailing `rel-icon`
+ * @csspart helper - The helper / error text line below the control
+ * @csspart helper-icon - The leading `rel-icon` in the helper line; rendered only when `helper-icon` is set and there is helper text
+ * @cssprop --rel-field-label-reserve - Height held for the label row whenever no label renders above the control — `labelStyle="none"`, and `labelStyle="floating"` where the label sits inside the control — so the control still lines up with labelled siblings in a form row. Defaults to that size's label line-height plus the wrapper gap (24px at `small`, 26px at `medium` and `large`). Set to `0` to collapse the row entirely (toolbars, table cells).
+ * @cssprop --rel-textfield-surface - Colour the floating label's strip paints to mask the border behind it; defaults to the control's own fill (`--rel-bg-neutral`). Set it when the field sits on a tinted or elevated surface, otherwise the strip shows as a light dash across the border.
+ */
 declare class RelTextfield extends LitElement {
+    /**
+     * Visible label text. Rendered above the control (default), inside it as a
+     * floating label (`labelStyle="floating"`) or as the notch of the `legend`
+     * variant; omitted entirely under `labelStyle="none"`.
+     */
     label?: string;
+    /** Placeholder shown while the field is empty. Under the floating label style it stays hidden until the field is focused. */
     placeholder: string;
+    /** Native input `type` (`text`, `email`, `password`, `number`, …). Ignored when `multiline` is set. */
     type: string;
+    /** Current text. Updated on every keystroke; set it to control the field programmatically. */
     value: string;
+    /** Legacy name for the leading icon (a `rel-icon` name). `prefixIcon` wins when both are set. */
     leftIcon?: string;
+    /** Trailing `rel-icon` name rendered in the suffix block. Decorative unless `clickableRightIcon` is set. */
     rightIcon?: string;
     /** Makes the trailing icon interactive (pointer + focusable) and emits
      *  `rel-right-icon-click` — e.g. a password show/hide toggle or clear button. */
@@ -75,8 +161,15 @@ declare class RelTextfield extends LitElement {
     suffixText?: string;
     /** Draws a hairline between the input and the suffix block. */
     suffixDivider: boolean;
+    /** Legacy name for the helper line below the control. `helperText` wins when both are set. */
     supportingText?: string;
+    /**
+     * Legacy visual state. `"error"` / `"disabled"` behave like the `error` /
+     * `disabled` booleans, which are preferred and take precedence. Typing into a
+     * `state="error"` field resets it to `"default"` until the value is emptied again.
+     */
     state: TextFieldState;
+    /** Control height — `small` 32px, `medium` 40px, `large` 48px — which also scales the text and the affix icons. */
     size: TextFieldSize;
     /**
      * Label presentation. Left `undefined` the deprecated `floatingLabel` boolean
@@ -94,19 +187,35 @@ declare class RelTextfield extends LitElement {
     fieldAriaLabel?: string;
     /** IDREF list of external element(s) naming the input. Wins over `fieldAriaLabel`. */
     fieldAriaLabelledby?: string;
+    /** Field chrome: `default` outlined box, `underline` bottom border only, `legend` notched outline with the label sitting in the top border (native fieldset/legend). */
     variant: TextFieldVariant;
+    /** Disables the input (not focusable, not editable) and dims the control. */
     disabled: boolean;
+    /** Marks the input required: sets native `required` / `aria-required` and appends an asterisk to the label. */
     required: boolean;
+    /** Renders a textarea instead of a single-line input (see `rows`). Prefix/suffix blocks and `type` are ignored in this mode. */
     multiline: boolean;
+    /** Visible text rows of the textarea when `multiline` is set. */
     rows: number;
+    /** Leading `rel-icon` name rendered in the prefix block (preferred over the legacy `leftIcon`). */
     prefixIcon?: string;
+    /** Accessible label for the leading icon. Without it the icon is `aria-hidden` (decorative). */
     prefixIconAriaLabel?: string;
+    /** Puts the field in the error state: danger border, `aria-invalid`, and `errorMessage` replacing the helper text. */
     error: boolean;
+    /** Text shown below the control instead of `helperText` while the field is in the error state. */
     errorMessage?: string;
+    /** Helper line below the control (preferred over the legacy `supportingText`); linked to the input via `aria-describedby`. */
     helperText?: string;
+    /** Icon name from the generated icon dictionary, rendered before the helper line (Figma "Supporting Icon"). Sized 16px, or 14px at `size="small"`, and it takes the helper's colour — so it turns `--rel-text-danger` in the error state. Decorative: it is hidden from screen readers, since the helper text it sits beside is already announced. */
+    helperIcon?: string;
+    /** Makes the input read-only: focusable and selectable but not editable. */
     readonly: boolean;
+    /** Maximum number of characters (native `maxlength`). */
     maxLength?: number;
+    /** Form field name forwarded to the native input, for form submission and autofill. */
     name?: string;
+    /** Fills the parent width as a block element (default). Unset it to render inline at the content's natural width. */
     fullWidth: boolean;
     private internalState;
     /** Whether the `prefix` / `suffix` named slots currently have content. */
@@ -126,6 +235,16 @@ declare class RelTextfield extends LitElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     private handleSlotChange;
+    /**
+     * The whole control is the input's hit area. The input already stretches
+     * to the row (CSS), but the control's own border, the legend notch, and
+     * any padding around slotted content are still container pixels — press
+     * there and focus the input, as clicking a <label> would. Skipped when the
+     * press is on the input itself (native caret placement), a clickable icon,
+     * or slotted content (their own behaviour), and when disabled.
+     * preventDefault keeps the press from moving focus to the body first.
+     */
+    private handleControlMousedown;
     /** Clicking the (non-interactive) prefix/suffix area focuses the input, as a
      *  label would. Clickable icons and slotted controls keep their own clicks. */
     private handleAffixClick;
@@ -145,7 +264,191 @@ declare class RelTextfield extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
-/** An item is a plain string or any object read through displayField/valueField. */
+type CheckboxState = "default" | "error" | "disabled";
+type CheckboxStatus = "unchecked" | "checked" | "indeterminate";
+type CheckboxSize = "small" | "medium" | "large" | "extra-large";
+type CheckboxDensity = "compact" | "comfortable";
+type CheckboxAlignment = "leading" | "trailing";
+/**
+ * Tri-state checkbox (Figma "Checkbox"): a hidden native checkbox behind a custom box, with label, optional prefix icon and supporting text.
+ * @csspart base - The outer wrapper that carries the `state` / `status` classes
+ * @csspart label - The visible label text
+ * @csspart helper - The supporting text (rendered beside the box in comfortable density, under the row in compact)
+ */
+declare class RelCheckbox extends LitElement {
+    /** Label text rendered next to the box. */
+    label: 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. */
+    icon: string;
+    /** Supporting text under or beside the label; where it renders depends on `density`. */
+    supportingtext: string;
+    /** 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). */
+    state: CheckboxState;
+    /** Check state. `"indeterminate"` is programmatic-only — a user toggle always resolves to checked or unchecked. */
+    status: CheckboxStatus;
+    /** Value reported in the `rel-change` event detail (it is not submitted with a form). */
+    value: string;
+    /** 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. 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. */
+    size: CheckboxSize;
+    /** 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. */
+    density: CheckboxDensity;
+    /** 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. */
+    alignment: CheckboxAlignment;
+    /** Boolean view of `status`: `true` when `status === "checked"`; setting it writes `"checked"` / `"unchecked"`. */
+    get checked(): boolean;
+    set checked(val: boolean);
+    private _onChange;
+    private _onTouched;
+    static styles: lit.CSSResult;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /** Trailing has no compact layout in the spec — trailing wins. */
+    private get effectiveDensity();
+    private toggle;
+    /** @internal Angular ControlValueAccessor bridge. */
+    registerOnChange(fn: (value: boolean) => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
+    registerOnTouched(fn: () => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
+    writeValue(checked: boolean): void;
+    render(): lit_html.TemplateResult<1>;
+}
+
+/** Diameter step, spelled out. */
+type AvatarSize = "large" | "medium" | "small" | "extra-small";
+/** Alternative spellings, not deprecations — the short names keep working. */
+type AvatarSizeAlias = "lg" | "md" | "sm" | "xs";
+type AvatarSizeInput = AvatarSize | AvatarSizeAlias;
+/**
+ * Circular avatar (Figma "Avatar"): shows a photo, text initials or a slotted icon in one of four sizes and three fill variants.
+ * @slot - Icon content rendered when `type="icon"` (typically an inline SVG, sized 20 / 18 / 16 / 12px by `size`)
+ * @csspart base - The circular wrapper that carries the size, variant and inline `bg` / `color` overrides
+ * @csspart icon - The `<img>` (`type="image"`) or the icon wrapper span around the slot (`type="icon"`)
+ * @csspart label - The `<span>` holding the initials when `type="text"`
+ * @cssprop --rel-avatar-bg-fill - Background colour of the `fill` variant
+ * @cssprop --rel-avatar-color-fill - Text / icon colour of the `fill` variant
+ * @cssprop --rel-avatar-bg-subtle - Background colour of the `subtle` variant
+ * @cssprop --rel-avatar-color-subtle - Text / icon colour of the `subtle` variant
+ * @cssprop --rel-avatar-border-outline - 1px border colour of the `outline` variant
+ * @cssprop --rel-avatar-color-outline - Text / icon colour of the `outline` variant
+ * @cssprop --rel-avatar-icon-size - Overrides the slotted icon's size; defaults to the preset ramp (20 / 18 / 16 / 12px)
+ * @cssprop --rel-avatar-bg-outline - Background colour of the `outline` variant; defaults to --rel-bg-neutral
+ * @cssprop --rel-avatar-size - Overrides the circle's width/height for sizes between (or below) the `size` presets; defaults to the preset's diameter
+ * @cssprop --rel-avatar-font-size - Overrides the initials' font-size, for use alongside `--rel-avatar-size`; defaults to the preset's text role
+ */
+declare class RelAvatar extends LitElement {
+    /** 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. */
+    size: AvatarSizeInput;
+    /** What is rendered inside the circle: `image` shows `src`, `text` shows the `text` initials, `icon` shows the default slot. */
+    type: "image" | "text" | "icon";
+    /** Fill style: `fill` = solid inverse background with light text, `subtle` = elevated neutral background, `outline` = transparent with a 1px border. */
+    variant: "fill" | "subtle" | "outline";
+    /** Image URL for `type="image"`; when empty nothing is rendered inside the circle (there is no fallback to initials). */
+    src: string;
+    /** Initials shown for `type="text"`; rendered uppercase via `text-transform`. */
+    text: string;
+    /** Alt text of the `<img>` for `type="image"`; the default is the generic word "Avatar", so pass the person's name. */
+    alt: string;
+    /** Any CSS colour applied inline as `background-color` on the circle, overriding the variant background. */
+    bg: string;
+    /** Any CSS colour applied inline as `color` on the circle (initials / icon), overriding the variant text colour. */
+    color: string;
+    static styles: lit.CSSResult;
+    /** Alternative spellings, NOT deprecations — no console notice. Normalising
+     *  the property rather than duplicating every selector keeps the reflected
+     *  attribute and the rendered class canonical, so only one spelling reaches
+     *  the CSS. Same shape as rel-chip and rel-slider. */
+    protected willUpdate(changed: Map<string, unknown>): void;
+    render(): lit_html.TemplateResult<1>;
+}
+
+/** Canonical semantic tones (Figma "Tone"): neutral | destructive | warning | success | info. */
+type ChipTone = "neutral" | "destructive" | "warning" | "success" | "info";
+/** Deprecated spelling: "danger" → destructive. */
+type ChipToneAlias = "danger";
+type ChipToneInput = ChipTone | ChipToneAlias;
+/** Canonical emphasis (Figma "Style"): fill | subtle. */
+type ChipVariant = "fill" | "subtle";
+/** Figma's own spellings of the Style axis, accepted as alternatives. */
+type ChipVariantAlias = "primary" | "secondary";
+type ChipVariantInput = ChipVariant | ChipVariantAlias;
+/** Canonical size steps — full words, as elsewhere in the library. */
+type ChipSize = "small" | "medium" | "large";
+/** Short size spellings, accepted as alternatives. */
+type ChipSizeAlias = "sm" | "md" | "lg";
+type ChipSizeInput = ChipSize | ChipSizeAlias;
+type ChipBorder = "default" | "rounded";
+/**
+ * Compact chip (Figma "Chip") for tags, filters and selected values: tone x variant
+ * colouring, optional leading icon / avatar / trailing icon, a remove control and
+ * opt-in drag-and-drop.
+ * @csspart base - The chip body (`.chip`) that carries size, tone, variant and border styling
+ * @csspart icon - The leading `<rel-icon>` (rendered only when `leading-icon` is set and no avatar)
+ * @csspart label - The label text
+ * @cssprop --rel-chip-focus-ring - Colour of the keyboard focus outline; default `var(--rel-border-focus)`
+ */
+declare class RelChip extends LitElement {
+    static shadowRootOptions: ShadowRootInit;
+    /** Text shown in the chip; also its accessible name and the drag payload. */
+    label: string;
+    /** 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. */
+    tone: ChipToneInput;
+    /** 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`. */
+    variant: ChipVariantInput;
+    /** 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. */
+    size: ChipSizeInput;
+    /** Corner shape (Figma Border): `default` = 4px radius, `rounded` = fully rounded with 12px horizontal padding. */
+    border: ChipBorder;
+    /** Icon name from the generated icon dictionary (e.g. "settings") — rendered via <rel-icon> before the label. Ignored when `avatar` is set. */
+    leadingIcon?: string;
+    /** Icon name from the generated icon dictionary, rendered after the label. */
+    trailingIcon?: string;
+    /** Initials text for the avatar (e.g. "JD"), rendered as a `<rel-avatar type="text">` before the label. Mutually exclusive with leadingIcon (avatar wins). */
+    avatar?: string;
+    /** Shows a remove (close) button after the label; clicking it sets `removed` and fires `removed`. */
+    removable: boolean;
+    /** `true` once the chip has been removed — the host is hidden via `:host([removed])`. Reflected so CSS and Angular can see it; reset to `false` to show the chip again. */
+    removed: boolean;
+    /** Opt-in native drag-and-drop: sets `draggable="true"` on the host, shows the Figma "Dragged" state during a real drag gesture, and makes Left/Right arrow keys fire `chip-move`. */
+    draggableChip: boolean;
+    /** Reflected so CSS can target the Figma "Dragged" visual state. Driven automatically by dragstart/dragend when draggableChip is set. */
+    private dragging;
+    static styles: lit.CSSResult[];
+    private get classes();
+    private handleRemove;
+    /** The chip body is announced as a button, so it must also act on keys:
+     *  Enter/Space re-dispatch as a host click (consumers' @click handlers
+     *  fire), Delete/Backspace remove when removable, and arrow keys ask the
+     *  container to reorder a draggable chip (`chip-move`) — the keyboard
+     *  alternative to pointer drag-and-drop. */
+    private handleKeydown;
+    private onDragStart;
+    private onDragEnd;
+    protected willUpdate(changed: Map<string, unknown>): void;
+    protected updated(changed: Map<string, unknown>): void;
+    render(): lit_html.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "rel-chip": RelChip;
+    }
+}
+
+/**
+ * An item is a plain string or any object read through displayField/valueField.
+ * Two keys are read off objects directly, whatever those fields are named:
+ * `icon` (a `rel-icon` name shown before the label) and `disabled` (`true`
+ * renders the row dulled and makes it unselectable by click or keyboard).
+ */
 type AutocompleteItem = string | Record<string, unknown>;
 type AutocompleteFilter = "contains" | "starts-with" | "none";
 type AutocompleteSearchFn = (query: string) => Promise<AutocompleteItem[]>;
@@ -162,9 +465,30 @@ type AutocompleteSearchFn = (query: string) => Promise<AutocompleteItem[]>;
  * `valueField`) — typing alone emits `rel-change` with the raw text but does
  * not change `value` until an item is picked (or the text exactly matches an
  * item's label/value on Enter/blur).
+ * @csspart panel - The suggestion listbox container (same node as `list`)
+ * @csspart list - Alias of `panel`
+ * @csspart option - A suggestion row. Emitted in BOTH single and `multiple` mode, unlike the two parts below
+ * @csspart option-label - The row's first line (the matched label). SINGLE-SELECT ROWS ONLY
+ * @csspart 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
+ * @csspart label - The inner field's label (re-exported from `rel-textfield`)
+ * @csspart control - The inner field's bordered control box (re-exported from `rel-textfield`)
+ * @csspart input - The inner native input (re-exported from `rel-textfield`)
+ * @csspart helper - The inner field's helper / error line (re-exported from `rel-textfield`)
+ * @csspart right-icon - The clear icon shown when `clearable` (re-exported from `rel-textfield`)
+ * @cssprop --rel-autocomplete-bg - Panel and row background
+ * @cssprop --rel-autocomplete-menu-border - 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.
+ * @cssprop --rel-autocomplete-menu-radius - Panel corner radius
+ * @cssprop --rel-autocomplete-menu-shadow - Panel box-shadow
+ * @cssprop --rel-autocomplete-divider - Hairline between rows
+ * @cssprop --rel-autocomplete-option-hover - Background of the hovered / keyboard-highlighted / selected row
+ * @cssprop --rel-autocomplete-option-pressed - Background of a row while it is being pressed
+ * @cssprop --rel-autocomplete-value-color - Suggestion label colour
+ * @cssprop --rel-autocomplete-icon-color - Colour of a row's leading `icon`
+ * @cssprop --rel-autocomplete-status-color - Colour of the loading / no-results status rows
+ * @cssprop --rel-autocomplete-menu-max-height - 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.
  */
 declare class RelAutocomplete extends LitElement {
-    /** Local (or fallback initial) suggestion list. Ignored while searchFn drives results. */
+    /** 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. */
     items: AutocompleteItem[];
     /** Committed value — the selected item's valueField string ("" = none). */
     value: string;
@@ -172,6 +496,8 @@ declare class RelAutocomplete extends LitElement {
     displayField: string;
     /** Object key read for the committed value when items are objects. */
     valueField: string;
+    /** 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. */
+    supportingField: string;
     /** Local filtering mode. Ignored when searchFn is set (results arrive pre-filtered). */
     filter: AutocompleteFilter;
     /** Async data source. When set, local filtering is bypassed entirely. */
@@ -182,18 +508,41 @@ declare class RelAutocomplete extends LitElement {
     minSearchLength: number;
     /** Optional cap on rendered suggestions (panel scrolls regardless). */
     maxSuggestions: number;
+    /**
+     * 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.
+     */
+    multiple: boolean;
+    /** Committed values in `multiple` mode (ignored otherwise). Mirrors `rel-select.selectedValues`. */
+    selectedValues: string[];
+    /** Label of the Select-all row shown at the top of the panel in `multiple` mode. */
+    selectAllLabel: string;
     /** Shows a trailing ✕ that clears the text and the committed value. */
     clearable: boolean;
     /** Externally-controlled loading state (internal searchFn loading is automatic). */
     loading: boolean;
     /** Row shown when a query yields nothing. */
     noResultsText: string;
+    /** Text shown next to the spinner while suggestions load. */
     loadingText: string;
+    /** Visible label, forwarded to the inner `rel-textfield`. Also names the suggestion panel. */
     label?: string;
+    /** Placeholder of the input, forwarded to the inner `rel-textfield`. */
     placeholder: string;
+    /** Field height — `small` 32px, `medium` 40px, `large` 48px — forwarded to the inner `rel-textfield`. Also drives the suggestion panel's row ramp. */
     size: TextFieldSize;
+    /** Field chrome (`default` outlined, `underline`, `legend` notched outline), forwarded to the inner `rel-textfield`. */
     variant: TextFieldVariant;
-    /** See `FieldLabelStyle`. Left `undefined` the deprecated `floatingLabel` decides. */
+    /** Label presentation (`default` / `floating` / `none`), forwarded to the inner field. Left `undefined`, the deprecated `floatingLabel` decides. */
     labelStyle?: FieldLabelStyle;
     /** @deprecated Use `labelStyle="floating"`. Kept permanently as an alias. */
     floatingLabel: boolean;
@@ -201,14 +550,23 @@ declare class RelAutocomplete extends LitElement {
     fieldAriaLabel?: string;
     /** IDREF list of external element(s) naming the input. Wins over `fieldAriaLabel`. */
     fieldAriaLabelledby?: string;
+    /** Leading `rel-icon` name in the field's prefix block, e.g. `search`. */
     prefixIcon?: string;
+    /** Disables the field; the panel never opens and the clear affordance is hidden. */
     disabled: boolean;
+    /** Read-only field: focusable but not editable; the panel never opens and the clear affordance is hidden. */
     readonly: boolean;
+    /** Marks the input required (native `required` / `aria-required`, asterisk on the label). */
     required: boolean;
+    /** Puts the field in the error state (danger border, `aria-invalid`); pair with `errorMessage`. */
     error: boolean;
+    /** Text shown below the field instead of `helperText` while `error` is set. */
     errorMessage?: string;
+    /** Helper line below the field, linked to the input via `aria-describedby`. */
     helperText?: string;
+    /** Form field name forwarded to the native input. */
     name?: string;
+    /** Fills the parent width as a block element (default). Unset it to render inline at the content's natural width. */
     fullWidth: boolean;
     private open;
     private inputText;
@@ -247,6 +605,14 @@ declare class RelAutocomplete extends LitElement {
     private openPanel;
     private closePanel;
     private showNativePopover;
+    /**
+     * Gap between the field and the panel. Figma composes the two in a column
+     * with gap=--rel-spacing-2xs, so this is a bound token rather than a magic
+     * number; the position is computed in JS (the panel is in the top layer), so
+     * it is read from the resolved custom property instead of being hardcoded.
+     * That way a spacing re-export carries through here as it does in CSS.
+     */
+    private get panelOffset();
     private hideNativePopover;
     private updatePosition;
     /** Re-evaluates whether the panel should be showing for the current state. */
@@ -254,12 +620,25 @@ declare class RelAutocomplete extends LitElement {
     private onFieldInput;
     private announceResults;
     private runSearch;
+    /**
+     * Multi rows nest the checkbox at the SAME step as the field, not one below.
+     * rel-select records why (rel-select.ts, optionCheckboxSize): the old
+     * one-step-down compensated for rel-checkbox sitting a size above the system,
+     * and once that ramp was realigned to Figma the compensation became the bug.
+     */
+    private get optionCheckboxSize();
+    private get selectAllStatus();
+    private toggleMultiOption;
+    private toggleSelectAll;
+    private emitMultiChanged;
     private selectItem;
     /** Silent commit when typed text exactly matches an item (label or value, case-insensitive). */
     private commitExactMatch;
     private emitChanged;
     private clear;
     private onKeyDown;
+    /** First selectable row at or past `from`, walking in `step`; -1 if none. */
+    private nextEnabledIndex;
     private announceHighlighted;
     private onFocusIn;
     private onFocusOut;
@@ -275,24 +654,28 @@ declare global {
     }
 }
 
-declare class RelAvatar extends LitElement {
-    size: "lg" | "md" | "sm" | "xs";
-    type: "image" | "text" | "icon";
-    variant: "fill" | "subtle" | "outline";
-    src: string;
-    text: string;
-    alt: string;
-    bg: string;
-    color: string;
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-
+/** Canonical size steps — full words, as elsewhere in the library. */
+type BadgeSize = "small" | "medium" | "large" | "extra-large";
+/** Short size spellings, accepted as alternatives. */
+type BadgeSizeAlias = "sm" | "md" | "lg" | "xl";
+type BadgeSizeInput = BadgeSize | BadgeSizeAlias;
+/**
+ * Notification badge (Figma "Badge"): a small count pill or an unlabeled dot, usually positioned over an icon or avatar.
+ * @csspart base - The `role="status"` pill / dot that carries the size, variant and colour overrides
+ * @cssprop --rel-badge-bg - Background colour of the badge; the `color` prop writes this on the host
+ * @cssprop --rel-badge-color - Text colour of the count; the `text-color` prop writes this on the host
+ * @cssprop --rel-badge-dot-size - Diameter of the `dot` variant; default 6px, the single dot size Figma draws. Set it to restore the larger discs shipped previously.
+ */
 declare class RelBadge extends LitElement {
+    /** 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. */
     number: string;
+    /** Explicit accessible name; when empty it is composed as "<number> <suffix>" or, with no number, "New <suffix>". Attribute is `arialabel`. */
     ariaLabel: string;
+    /** Noun appended to the count in the generated accessible name, e.g. "3 notifications". */
     suffix: string;
-    size: "sm" | "md" | "lg" | "xl";
+    /** 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. */
+    size: BadgeSizeInput;
+    /** `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`. */
     variant: "dot" | "number";
     /**
      * Direct CSS color override for the badge background. Accepts any valid
@@ -309,6 +692,7 @@ declare class RelBadge extends LitElement {
      */
     textColor: string;
     static styles: lit.CSSResult;
+    protected willUpdate(changed: PropertyValues<this>): void;
     private get classes();
     private get computedAriaLabel();
     updated(changedProperties: Map<PropertyKey, unknown>): void;
@@ -319,61 +703,106 @@ interface BreadcrumbItem {
     label: string;
     url?: string;
 }
+/**
+ * Breadcrumb trail: a `<nav aria-label="Breadcrumb">` ordered list of links with chevron separators, whose last entry is the current page. Use it to show where a page sits in a hierarchy; do not use it as primary navigation.
+ * @csspart base - The `<nav>` landmark wrapping the ordered list.
+ * @csspart label - The non-link current-page text (`aria-current="page"`), also used for any item without a `url`.
+ */
 declare class RelBreadcrumbs extends LitElement {
+    /** Ordered trail, root first: `{ label: string; url?: string }[]`. Items with a `url` render as links except the last one, which is always the current page (and never a link). Set as a property — arrays do not survive attribute serialisation. */
     items: BreadcrumbItem[];
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
 }
 
 /**
- * Style axis. Canonical values are the historical ones; "outline"/"ghost" are
- * accepted Figma-vocabulary aliases for "secondary"/"text". "static" is the
- * Figma Style=Static treatment (transparent, static-light label — for use on
- * colored/dark surfaces). Legacy "icon" is the pre-2.0 collapsed icon-button
- * variant and keeps its exact behavior; prefer icon-only + a style instead.
+ * Style axis (Figma "Style"): primary | secondary | ghost | link | static.
+ * "outline" (= secondary) and "text" (= ghost) are the historical spellings
+ * and stay supported; "default" is the legacy neutral-fill style. "static" is
+ * the Figma Style=Static treatment (transparent, static-light label — for use
+ * on colored/dark surfaces). Legacy "icon" is the pre-2.0 collapsed
+ * icon-button variant and keeps its exact behavior; prefer icon-only + a
+ * style instead.
  */
 type ButtonVariant = "default" | "primary" | "secondary" | "text" | "link" | "icon" | "static" | "outline" | "ghost";
-/** Tone axis. "neutral"/"brand"/"danger" are Figma-vocabulary aliases. */
-type ButtonTone = "default" | "primary" | "secondary" | "critical" | "success" | "neutral" | "brand" | "danger";
+/**
+ * Tone axis (Figma "Tone"): neutral | brand | destructive. Historical
+ * spellings "default" (= neutral), "primary" (= brand), "critical" and
+ * "danger" (= destructive) stay supported; "critical"/"danger" log a one-time
+ * deprecation notice. "secondary"/"success" are legacy extras.
+ */
+type ButtonTone = "default" | "primary" | "secondary" | "critical" | "success" | "neutral" | "brand" | "danger" | "destructive";
+/**
+ * Action button (Figma "Button"): a native `<button>` with the Figma Style / Tone / Size axes, an icon-only mode, a loading spinner and an optional corner badge. Use it for every clickable action; use an anchor for navigation.
+ * @slot - Button content: label text, a `rel-icon`, or icon + text (kept on one line with the size's gap).
+ * @csspart base - The inner native `<button>` element (padding, min-width, fill, border, focus ring).
+ * @csspart indicator - The loading spinner, rendered only while `loading` is set.
+ * @cssprop --rel-button-min-width - Overrides the per-size minimum width (Figma small/medium/large = 80/100/120px, ghost small = 56px). Ignored by `icon-only` and `link`.
+ */
 declare class RelButton extends LitElement {
+    /** 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). */
     variant: ButtonVariant;
-    tone: ButtonTone;
     /**
-     * Figma "Type=Icon Only" as an independent axis: a square button of the
-     * current style/tone. Unlike legacy variant="icon", this composes with
-     * every style (outline/ghost/link included).
+     * 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.
      */
+    tone?: ButtonTone;
+    /** 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`. */
     iconOnly: boolean;
-    /** Figma "State=Loading": shows a spinner, blocks interaction. */
+    /** 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. */
     loading: boolean;
+    /** Figma "Size": `small` = 32px, `medium` = 40px, `large` = 48px height, with matching padding, typography and minimum width. */
     size: "small" | "medium" | "large";
+    /** Corner treatment: `corner-radius` = fully rounded pill, `small-corner-radius` = small radius token, `no-corner-radius` = square corners. */
     border: "corner-radius" | "small-corner-radius" | "no-corner-radius";
+    /** Figma "State=Disabled": dims the button to 50% opacity, flattens filled styles to the disabled fill, shows a `not-allowed` cursor and swallows every click (including programmatic `.click()`). */
     disabled: boolean;
+    /** Accessible name forwarded to the inner native `<button>`. Required for `icon-only` buttons, whose slotted icon has no visible text. */
     ariaLabel: string | null;
-    /** Numeric/overflow text shown in a corner badge (e.g. "3", "999+"). Ignored when badgeDot is set. */
+    /** Text for a small `rel-badge` anchored to the top-right corner (e.g. "3", "999+"). Empty string renders no badge. Ignored when `badge-dot` is set. */
     badge: string;
-    /** Shows a small corner dot instead of a numbered badge — takes precedence over `badge`. */
+    /** Renders a small dot badge in the top-right corner instead of a numbered badge; takes precedence over `badge`. The dot is inset 2px from the corner so it lands on a circular icon button's edge. */
     badgeDot: boolean;
-    static styles: lit.CSSResult;
+    static styles: lit.CSSResult[];
     connectedCallback(): void;
     disconnectedCallback(): void;
     private handleHostClick;
     /** Style axis with Figma-vocabulary aliases folded onto canonical values. */
     private get styleVariant();
-    /** Tone axis with Figma-vocabulary aliases folded onto canonical values. */
+    /** Tone axis with Figma-vocabulary aliases folded onto the internal class names. */
     private get effectiveTone();
+    willUpdate(changed: Map<string, unknown>): void;
     private get classes();
     private handleClick;
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Inline single-date calendar (Figma "Calendar"): a month grid with previous/next
+ * navigation, always visible — no trigger or popover. Use rel-date-picker for a form field.
+ * @csspart header - Month navigation row (previous button, month/year label, next button)
+ * @csspart action - The previous-month and next-month buttons
+ * @csspart label - The month/year heading and each weekday column header
+ * @csspart list - The weekday-header row and the day grid
+ * @csspart item - Each day cell button
+ */
 declare class RelCalendar extends LitElement {
+    /** Selected date as an ISO `YYYY-MM-DD` string, or `null` for no selection; setting it also moves the visible month. */
     value: string | null;
+    /** Earliest selectable date (ISO `YYYY-MM-DD`); earlier days render disabled. */
     min: string | null;
+    /** Latest selectable date (ISO `YYYY-MM-DD`); later days render disabled. */
     max: string | null;
+    /** Disables every day cell and the month navigation; the host dims to 40% opacity (Figma State=Disabled). */
     disabled: boolean;
+    /** First column of the week grid: `"sun"` (default) or `"mon"`. */
     weekStart: "sun" | "mon";
+    /** BCP 47 locale for the month name, weekday headers and day cell labels (via `Intl.DateTimeFormat`). */
     locale: string;
+    /** Custom predicate that disables individual days (return `true` to disable); applied on top of `min`/`max`. Property only — assign it from JavaScript. */
     isDateDisabled?: (date: Date) => boolean;
     private viewYear;
     private viewMonth;
@@ -406,6 +835,15 @@ declare class RelCalendar extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * `<rel-card>` — elevated surface that groups related content (Figma "Card").
+ * Use `type="media"` with a `<rel-card-media>` in the `media` slot for a flush image header.
+ * @slot - Card body; slotted headings and paragraphs receive the Figma card typography
+ * @slot media - Flush media region above the body; rendered only when `type="media"`
+ * @csspart base - The outer elevated card surface
+ * @csspart header - The media region wrapper (present only when `type="media"`)
+ * @csspart content - The padded body that wraps the default slot
+ */
 declare class RelCard extends LitElement {
     /**
      * Figma "Type" axis: custom (default) renders slotted content with card
@@ -417,24 +855,62 @@ declare class RelCard extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Slide carousel (Figma "Carousel"): shows one slotted slide at a time in a horizontal or vertical viewport, with optional arrows, dot indicators, drag/swipe, looping and autoplay.
+ * @slot - The slides: one light-DOM element per slide (each is sized to one panel and given `role="group"` / `aria-roledescription="slide"`).
+ * @csspart viewport - The focusable `role="region"` box that clips the track (also the keyboard target).
+ * @csspart track - The flex row / column that translates to reveal the current slide.
+ * @csspart ${direction}-button - The two arrow buttons, exposed as `prev-button` and `next-button` (`type="side-arrows"` overlays them on the viewport; `type="bottom-arrows"` inlines them in the dots row).
+ * @csspart dots - The indicator row under the viewport (also hosts the arrows for `type="bottom-arrows"`).
+ * @csspart dot - One indicator button per reachable position (per slide at `panels="1"`); the active one carries the `active` class and `aria-current="true"`.
+ * @csspart dot-group - The row of dots inside `dots` (for `type="bottom-arrows"` it is the middle child, between the two arrows).
+ * @cssprop --rel-carousel-height - Viewport height in `orientation="vertical"` (default 320px); the horizontal viewport takes the height of its tallest slide.
+ * @cssprop --rel-carousel-nav-size - Width / height of the arrow buttons (default 32px, matching Figma; applies to both side and bottom arrows).
+ * @cssprop --rel-carousel-dot-size - Diameter of an inactive dot (default 8px).
+ * @cssprop --rel-carousel-dot-size-active - Width of the active (brand-coloured, pill-shaped) dot (default 16px).
+ * @cssprop --rel-carousel-slide-width - 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).
+ * @cssprop --rel-carousel-slide-height - Written by the component on its own host to the computed panel height (used for vertical slides); not meant to be set by consumers.
+ */
 declare class RelCarousel extends LitElement {
+    /** Index of the current slide (0-based). Set it to jump; it is clamped to the slide count and reflected as an attribute. */
     value: number;
+    /** Wrap from the last slide to the first (and back) with a seamless clone transition instead of stopping at the ends. */
     loop: boolean;
+    /** Advance automatically every `interval` ms; implies looping and pauses while hovered (see `pause-on-hover`) or while focus is inside the carousel. */
     autoplay: boolean;
+    /** Autoplay delay between slides, in milliseconds (default 5000). */
     interval: number;
+    /** Pause autoplay while the pointer is over the carousel or while dragging (default true; switch off via the property, e.g. `el.pauseOnHover = false`). */
     pauseOnHover: boolean;
+    /** Legacy toggle for the overlaid previous / next arrows; ignored whenever `type` is set. */
     showButtons: boolean;
-    showDots: boolean;
+    /**
+     * Figma "Show Dots" property. Tri-state: left off it defers to `type` (dots for every type
+     * except `default`, and nothing at all when `type` is unset too); `show-dots` turns them on;
+     * `show-dots="false"` turns them off even when `type` would have shown them.
+     */
+    showDots?: boolean;
     /**
      * Figma "Type" axis. When set it drives which controls render:
      * default = content only · only-indicators = dots · side-arrows = overlaid
      * arrows + dots · bottom-arrows = dots flanked by arrows below the slide.
-     * When unset, the legacy show-buttons/show-dots booleans apply unchanged.
+     * When unset, the legacy show-buttons boolean applies unchanged. The dots a type
+     * implies can always be overridden by an explicit `show-dots`.
      */
     type?: "default" | "only-indicators" | "side-arrows" | "bottom-arrows";
+    /** Slide axis: `horizontal` (default) translates the track left / right; `vertical` stacks slides in a fixed-height viewport (`--rel-carousel-height`) and translates up / down. */
     orientation: "horizontal" | "vertical";
+    /** Accessible name of the carousel region (`aria-label` on the viewport); default "Carousel". */
     label: string;
-    gap?: number;
+    /** Space between consecutive slides in pixels (applied as the track `gap` and added to each slide step); default 8 (Figma `spacing/xs`), 0 = slides touch. */
+    gap: number;
+    /**
+     * Figma "Multi Panels" axis, as a count: how many slides are visible at once (default 1).
+     * Fractions are allowed and produce a peek of the next slide — `panels="1.5"` reproduces the
+     * Figma Multi Panels=True variant. Navigation still advances one slide at a time.
+     */
+    panels: number;
+    /** Disables arrows, dots, drag and keyboard navigation, stops autoplay and renders the carousel at 60% opacity. */
     disabled: boolean;
     private slideCount;
     private isDragging;
@@ -454,11 +930,30 @@ declare class RelCarousel extends LitElement {
     static styles: lit.CSSResult;
     connectedCallback(): void;
     firstUpdated(): void;
+    /**
+     * Write the computed panel size to the custom properties the slides (and the loop clones)
+     * are sized from, then re-align the track. The cross axis keeps the raw viewport measurement.
+     */
+    private measure;
     disconnectedCallback(): void;
     private handleSlotChange;
     private get vertical();
     /** Translate along the orientation axis. */
     private axisTransform;
+    private get panelCount();
+    private get gapPx();
+    /**
+     * Size of a single panel along the scroll axis. A viewport showing `n` panels contains
+     * `ceil(n) - 1` whole gaps — one for a 1.5-panel peek, two for three panels — so those are
+     * subtracted before the remainder is split. At `panels="1"` this is just the viewport size.
+     */
+    private panelSize;
+    /**
+     * Highest index that may lead the viewport. Without looping the track stops once the last
+     * slide is flush with the trailing edge, so multi-panel carousels never scroll into empty
+     * space; with clones in play every slide can lead because the clones fill the tail.
+     */
+    private get maxIndex();
     private unit;
     private updateTransform;
     private goToPrevious;
@@ -479,100 +974,119 @@ declare class RelCarousel extends LitElement {
     updated(changedProperties: Map<string, any>): void;
     /** Where nav arrows render, honouring the Figma type when set. */
     private get buttonPlacement();
+    /** Explicit `show-dots` wins; otherwise `type` decides, as it always has. */
     private get dotsVisible();
     private renderNavButton;
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Media card: a bordered surface with an optional full-width image on top, then a title, subtitle and slotted body. Use it for previews with a hero image (articles, products, galleries); use `rel-card` for free-form or custom layouts.
+ * @slot - Body content rendered inside the padded content area below the title and subtitle.
+ * @csspart base - The outer bordered card surface (background, border, radius, overflow clip).
+ * @csspart icon - The image wrapper above the content, rendered only when `image-src` is set.
+ * @csspart content - The padded area holding the title, subtitle and slotted body.
+ */
 declare class RelCardMedia extends LitElement {
+    /** URL of the hero image shown full-width at the top of the card. Empty (the default) omits the image section entirely. */
     imageSrc: string;
+    /** Alternative text for the hero image. Replace the generic default with a real description, or an empty string for purely decorative images. */
     imageAlt: string;
+    /** Heading rendered as an `<h3>` above the subtitle; empty omits it. Note this is also the native `title` attribute, so a value shows as a browser tooltip on hover. */
     title: string;
+    /** Secondary line rendered as a paragraph under the title; empty omits it. */
     subtitle: string;
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
 }
 
-type CheckboxState = "default" | "error" | "disabled";
-type CheckboxStatus = "unchecked" | "checked" | "indeterminate";
-type CheckboxSize = "small" | "medium";
-type CheckboxDensity = "compact" | "comfortable";
-type CheckboxAlignment = "leading" | "trailing";
-declare class RelCheckbox extends LitElement {
-    label: string;
-    /** rel-icon name rendered between the checkbox and the label (label prefix icon). */
-    icon: string;
-    supportingtext: string;
-    state: CheckboxState;
-    status: CheckboxStatus;
-    value: string;
-    /** Control scale (Figma Size). `"medium"` (default) = 18px box with body-lg
-     *  label; `"small"` = 14px box with body-md label. */
-    size: CheckboxSize;
-    /** 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. */
-    density: CheckboxDensity;
-    /** 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. */
-    alignment: CheckboxAlignment;
-    get checked(): boolean;
-    set checked(val: boolean);
-    private _onChange;
-    private _onTouched;
-    static styles: lit.CSSResult;
-    protected willUpdate(changed: PropertyValues<this>): void;
-    /** Trailing has no compact layout in the spec — trailing wins. */
-    private get effectiveDensity();
-    private toggle;
-    registerOnChange(fn: (value: boolean) => void): void;
-    registerOnTouched(fn: () => void): void;
-    writeValue(checked: boolean): void;
-    render(): lit_html.TemplateResult<1>;
-}
-
+/**
+ * Single-date form field (Figma "Date Picker"): a text field with typed date entry plus a
+ * popover calendar whose header pills drill into month and year grids, above
+ * Today/Tomorrow/Yesterday shortcut chips.
+ * Use rel-calendar for an always-visible grid and rel-range-picker for a from/to range.
+ * @csspart base - Outer wrapper carrying the size class (`small` / `medium` / `large`)
+ * @csspart label - The visible field label (rendered only when `label` is set)
+ * @csspart trigger - The field box that wraps the text input and the clear/calendar icons
+ * @csspart value - The editable text input inside the trigger
+ * @csspart shortcuts - The Today / Tomorrow / Yesterday chip row at the top of the popover
+ */
 declare class RelDatePicker extends LitElement {
+    /** Selected date as an ISO `YYYY-MM-DD` string, or `null` when empty; setting it also moves the popover to that month. */
     value: string | null;
+    /** Placeholder text shown while the field is empty (visual only; the accessible name comes from `label`, or "Select date" when unset). */
     placeholder: string;
+    /** Visible label rendered above the field and wired to the input via `aria-labelledby`; `null` renders no label. */
     label: string | null;
+    /** Disables the field, the icons and the popover; the host dims to 40% opacity. */
     disabled: boolean;
+    /** Appends a `*` to the label and sets `aria-required`; no validation is performed. */
     required: boolean;
+    /** Makes the input read-only and stops the field, icon, Enter and ArrowDown from opening the popover. */
     readonly: boolean;
+    /** Earliest selectable date (ISO `YYYY-MM-DD`); earlier days are disabled and typed dates before it are rejected. Wins over the deprecated `min`. */
     minDate: string | null;
+    /** Latest selectable date (ISO `YYYY-MM-DD`); later days are disabled and typed dates after it are rejected. Wins over the deprecated `max`. */
     maxDate: string | null;
-    /** @deprecated use minDate */
+    /** Legacy alias of `minDate`; ignored when `minDate` is set. @deprecated use minDate */
     min: string | null;
-    /** @deprecated use maxDate */
+    /** Legacy alias of `maxDate`; ignored when `maxDate` is set. @deprecated use maxDate */
     max: string | null;
+    /** First column of the calendar grid: `"sun"` (default) or `"mon"`. */
     weekStart: "sun" | "mon";
+    /** BCP 47 locale for weekday/month names, the default long-date display, and day/month order when parsing ambiguous typed input. */
     locale: string;
+    /** Token pattern for the displayed value (`YYYY`, `YY`, `MMMM`, `MMM`, `MM`, `M`, `DD`, `D`; literal text in `[ ]`), e.g. `DD/MM/YYYY`. Unset → the locale long date. Affects only the visible text, never `value`. */
     displayFormat: string | null;
     /**
-     * Full control over the selected-value display; wins over `displayFormat`.
-     * Reactive (attribute:false) so assigning it after render re-renders the
-     * trigger — frameworks set callbacks as properties post-creation.
+     * Callback with full control over the displayed value; wins over `displayFormat`.
+     * Assign it from JavaScript; it stays reactive so setting it after render re-renders
+     * the field. The Date it receives is at local midnight.
      */
     formatDate?: (date: Date) => string;
+    /** Whether the calendar popover is open; set it directly to open/close programmatically (focus then moves into the grid). */
     open: boolean;
+    /** Closes the popover after a day is picked in the grid (default `true`). */
     closeOnSelect: boolean;
+    /** Shows a clear (×) icon while a value is set; clearing fires `rel-change` with `value: null`. */
     clearable: boolean;
+    /**
+     * Figma ".Date Picker Calendar" Show Shortcuts: renders the Today / Tomorrow /
+     * Yesterday chip row and its divider at the top of the popover. On by default —
+     * write `show-shortcuts="false"` to hide both (a plain boolean attribute could
+     * not express a default of `true`). The typed `T` / `T±N` shortcuts and the
+     * in-panel `T` key keep working either way.
+     */
+    showShortcuts: boolean;
+    /** Forces the error style (danger border, `aria-invalid`) and shows `errorMessage` below the field. Typed-entry parse errors set the same style on their own. */
     error: boolean;
+    /** Text shown below the field while `error` is set (or a typed date failed to parse); falls back to `helperText`. */
     errorMessage?: string;
+    /** Supporting text shown below the field when there is no error. */
     helperText?: string;
+    /** When set, renders a hidden `<input name>` carrying the ISO value so the picker submits with a native form. */
     name?: string;
+    /** Field height scale shared with rel-textfield / rel-select: `small` 32px, `medium` 40px (default), `large` 48px. */
     size: "small" | "medium" | "large";
+    /** Visual style of the field; `outlined` is the only variant today. */
     variant: "outlined";
+    /** Stretches the host to fill its parent's width (attribute `fullwidth`); off by default so the field keeps its intrinsic inline width. */
     fullWidth: boolean;
+    /** Custom predicate that disables individual days (return `true` to disable); applied on top of `minDate`/`maxDate` and also rejects typed input. Property only — assign it from JavaScript. */
     isDateDisabled?: (date: Date) => boolean;
     private get minBound();
     private get maxBound();
     private viewYear;
     private viewMonth;
     private focusedDate;
-    private yearDropdownOpen;
-    private monthDropdownOpen;
+    /** Panel body: the day grid, or the month / year picker reached via the header pills. */
+    private panelView;
+    /** First year of the visible Years page; re-anchored whenever that view opens. */
+    private yearPageStart;
+    /** Period-grid cell the keyboard last moved to; -1 until the user moves. Kept
+     *  across a year page turn, since it is a grid POSITION and every page has the
+     *  same twelve slots. */
+    private periodRoved;
     /** Uncommitted typed text; null → the input shows the committed value. */
     private inputText;
     /** Parse/range error message for the typed text (cleared on next input). */
@@ -611,8 +1125,16 @@ declare class RelDatePicker extends LitElement {
     private dayLabelLocale;
     private formatDayLabel;
     private announceMonth;
+    /** Short month names for the Months grid (Figma shows "Jan", "Feb", …). */
     private getMonthsList;
-    private getYearsList;
+    /** The 12 years on the current Years page. */
+    private getYearsPage;
+    /**
+     * A month or year is out of bounds only when EVERY day it contains is —
+     * a min of the 10th must not grey out that whole month.
+     */
+    private isMonthOutOfBounds;
+    private isYearOutOfBounds;
     private toggleCalendarPopover;
     private closeCalendarPopover;
     private previousMonth;
@@ -642,44 +1164,119 @@ declare class RelDatePicker extends LitElement {
     /** T inside the panel (grid/header focus) applies Today directly. */
     private handlePanelKeydown;
     private handleDayKeydown;
-    private toggleMonthDropdown;
-    private toggleYearDropdown;
-    private handleDropdownTriggerKeydown;
-    private focusOpenDropdownSelection;
-    private handleDropdownKeydown;
+    /**
+     * The chevrons step by whatever the visible body is made of, so they stay
+     * useful in every view: a month, a year, or a whole 12-year page.
+     */
+    private goPrev;
+    private goNext;
+    private announceYearPage;
+    /** A pill toggles its own view; tapping it again returns to the day grid. */
+    private switchView;
+    /** Focus the month/year cell that holds the tab stop, so the keyboard lands
+     *  somewhere useful and focus can never disagree with the tab stop. */
+    private focusPanelGridSelection;
     private selectMonth;
     private selectYear;
+    /** Arrow-key roving across the 3-column month / year grid. */
+    private handlePeriodGridKeydown;
+    /**
+     * The tab stop follows focus, wherever focus came from — arrows, a click, Tab,
+     * or a cell that simply kept focus across a re-render. Doing this on focusin
+     * rather than in the key handler is what keeps the two from disagreeing: a
+     * year page turn reuses the same buttons with new labels, so the focused cell
+     * survives while `selected` moves off-page, and deriving the tab stop from
+     * anything other than focus itself puts them on different cells.
+     */
+    private handlePeriodGridFocusin;
     /**
      * Index of the single grid cell carrying tabindex="0". The old expression
      * (`isSelected || (index === 0 && !value)`) left the grid with ZERO tab
      * stops once the user arrowed around without a selection.
      */
     private getRovingIndex;
+    /** Days view: weekday header + the six week rows. */
+    private renderDaysView;
+    /** Months view: the 3x4 grid the month pill drills into. */
+    private renderMonthsView;
+    /** Years view: one 3x4 page, centred on the year in view. */
+    private renderYearsView;
     render(): lit_html.TemplateResult<1>;
 }
 
+/** Field scale, matching the other pickers. */
+type RangePickerSize = "small" | "medium" | "large";
+/** Alternative spellings, not deprecations. */
+type RangePickerSizeAlias = "sm" | "md" | "lg";
+type RangePickerSizeInput = RangePickerSize | RangePickerSizeAlias;
+/**
+ * Date-range form field (Figma "Date Range Picker"): a text field with typed "from → to"
+ * entry and a two-pane panel — quick-select presets with single-key shortcuts on the left,
+ * a month grid on the right — committed with Apply (Reset / Cancel discard the draft).
+ * Use rel-date-picker for a single date.
+ * @csspart trigger - The field box that wraps the text input and the clear/calendar icons (default trigger variant only)
+ * @csspart value - The editable text input inside the trigger
+ * @csspart overlay - The full-screen backdrop rendered in `mode="popup"` while open
+ * @csspart panel - The floating panel (`role="dialog"`) holding presets and calendar
+ * @csspart list - The preset column and the day grid
+ * @csspart option - Each quick-select preset button
+ * @csspart action - The header's previous and next buttons; they step a month, a year or a 12-year page depending on which view the panel is showing
+ * @csspart footer - The Reset / Cancel / Apply button row
+ */
 declare class RelRangePicker extends LitElement {
+    /** Committed range start as an ISO `YYYY-MM-DD` string; empty string when no range is set. */
     from: string;
+    /** Committed range end as an ISO `YYYY-MM-DD` string; empty string when no range is set. Always ≥ `from`. */
     to: string;
+    /** Locale used to match month names in typed input; the visible trigger text and calendar labels are always `en-US` (`MM/DD/YYYY`). */
     locale: string;
+    /** First column of the calendar grid: `"sun"` (default) or `"mon"`. Presets always compute weeks Sunday–Saturday. */
     weekStart: "mon" | "sun";
+    /** Earliest selectable date (ISO `YYYY-MM-DD`); earlier days are disabled and typed ranges starting before it are rejected. */
     minDate: string;
+    /** Latest selectable date (ISO `YYYY-MM-DD`); later days are disabled and typed ranges ending after it are rejected. */
     maxDate: string;
+    /** Disables the trigger, the icons and the panel controls; the host dims to 60% opacity. */
     disabled: boolean;
+    /** Whether the panel is open. Setting it directly shows/hides the panel but does not seed the draft from `from`/`to` or fire `rel-open-change` — user interaction does both. */
     open: boolean;
+    /** `popover` anchors the panel below the trigger; `popup` centres it in the viewport behind a dimmed backdrop (part `overlay`). */
     mode: "popover" | "popup";
+    /** CSS width applied to the host (any CSS length, e.g. `320px`); empty leaves the intrinsic width. */
     width: string;
+    /** CSS `min-width` applied to the host. */
     minWidth: string;
+    /** CSS `max-width` applied to the host. */
     maxWidth: string;
+    /** CSS height applied to the host. */
     height: string;
+    /** CSS `min-height` applied to the host. */
     minHeight: string;
+    /** CSS `max-height` applied to the host. */
     maxHeight: string;
+    /** Placeholder shown in the empty field; also the accessible name of the input (and of the icon trigger while no range is set). */
     placeholder: string;
+    /** `default` renders the text field; `icon` renders a single calendar icon button instead (no typed entry, no clear button, parts `trigger`/`value` absent). */
     triggerVariant: "default" | "icon";
+    /** Shows a clear (×) icon while a range is set; clearing fires `rel-change` with empty `from`/`to`. Only with the default trigger. */
     clearable: boolean;
+    /** Stretches the host to fill its parent's width (attribute `fullwidth`),
+     *  mirroring rel-time-picker / rel-date-picker. Off by default so the
+     *  existing intrinsic-width (`inline-block`) rendering is unchanged. */
+    fullWidth: boolean;
+    /** Trigger height on the shared field scale — `small` 32 / `medium` 40 / `large` 48px border-box — matching rel-textfield, rel-date-picker and rel-time-picker so the four align in a form row. Also ramps the trigger's text and inline padding. The panel is unaffected: Figma specifies one panel size. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. */
+    size: RangePickerSizeInput;
     private draftFrom;
     private draftTo;
     private draftActivePreset;
+    /** Which grid the panel shows. Ported from rel-date-picker so the two
+     *  calendars behave the same; reaching January 2023 was ~44 chevron clicks. */
+    private panelView;
+    private yearPageStart;
+    /** Period-grid cell the keyboard last moved to; -1 until the user moves. Kept
+     *  across a year page turn, since it is a grid POSITION and every page has the
+     *  same twelve slots. */
+    private periodRoved;
     private viewYear;
     private viewMonth;
     private isSelectingRange;
@@ -704,6 +1301,10 @@ declare class RelRangePicker extends LitElement {
     private handleClickOutside;
     private handleGlobalKeydown;
     private toggleOpen;
+    /** Alternative spellings, NOT deprecations — no console notice. Normalising
+     *  keeps the reflected attribute canonical so the :host([size=…]) rules only
+     *  need the full words. */
+    protected willUpdate(changed: Map<string, unknown>): void;
     private openPopover;
     private cancelPopover;
     private applySelection;
@@ -743,6 +1344,48 @@ declare class RelRangePicker extends LitElement {
     private isDateDisabled;
     private getQuickSelects;
     private selectQuickSelect;
+    private goPrev;
+    private goNext;
+    private announceYearPage;
+    /** A pill toggles its own view; tapping it again returns to the day grid. */
+    private switchView;
+    private selectMonth;
+    private selectYear;
+    /**
+     * Arrow-key roving across the Months / Years grid, matching rel-date-picker
+     * exactly. Without this the grid had ONE reachable cell — the selected one —
+     * because every other cell carries tabindex="-1" under the roving pattern and
+     * nothing moved the focus. A keyboard user could open the view and go nowhere,
+     * while the 44 chevron presses still worked: strictly worse than before the
+     * switcher existed.
+     *
+     * Movement clamps at the edges (shared with the date picker through
+     * periodGridTarget); Escape steps back to the day grid rather than falling
+     * through to the panel's own Escape, which closes the whole picker.
+     */
+    private handlePeriodGridKeydown;
+    /**
+     * The tab stop follows focus, wherever focus came from — arrows, a click, Tab,
+     * or a cell that simply kept focus across a re-render. Doing this on focusin
+     * rather than in the key handler is what keeps the two from disagreeing: a
+     * year page turn reuses the same buttons with new labels, so the focused cell
+     * survives while `selected` moves off-page, and deriving the tab stop from
+     * anything other than focus itself puts them on different cells.
+     */
+    private handlePeriodGridFocusin;
+    /**
+     * Return focus to the day grid after leaving Months / Years. Prefers the
+     * roving tab stop and falls back to the first selectable day, so a month with
+     * every leading cell disabled still lands somewhere. Disabled days here carry
+     * a CLASS, not the :disabled state, because they are not buttons.
+     */
+    private focusDayGrid;
+    /** Put focus in the grid when a view opens, so the keyboard has somewhere to
+     *  start; otherwise the arrows have nothing to move from. */
+    private focusPeriodGrid;
+    /** Months or Years, in the same 3x4 grid rel-date-picker uses. */
+    private renderPeriodGrid;
+    private getMonthsList;
     private previousMonth;
     private nextMonth;
     private getMonthName;
@@ -768,59 +1411,48 @@ declare global {
     }
 }
 
-type ChipTone = "neutral" | "danger" | "warning" | "success" | "info";
-type ChipVariant = "fill" | "subtle";
-type ChipSize = "sm" | "md" | "lg";
-type ChipBorder = "default" | "rounded";
-declare class RelChip extends LitElement {
-    static shadowRootOptions: ShadowRootInit;
-    label: string;
-    tone: ChipTone;
-    variant: ChipVariant;
-    size: ChipSize;
-    border: ChipBorder;
-    /** Icon name from the generated icon dictionary (e.g. "settings") — rendered via <rel-icon>. */
-    leadingIcon?: string;
-    trailingIcon?: string;
-    /** Initials text for the avatar (e.g. "JD"). Mutually exclusive with leadingIcon. */
-    avatar?: string;
-    removable: boolean;
-    /** IMPORTANT: reflected so CSS + Angular can see it */
-    removed: boolean;
-    /** Opt-in native drag-and-drop — reflects the Figma "Dragged" state automatically during a real drag gesture. */
-    draggableChip: boolean;
-    /** Reflected so CSS can target the Figma "Dragged" visual state. Driven automatically by dragstart/dragend when draggableChip is set. */
-    private dragging;
-    static styles: lit.CSSResult;
-    private get classes();
-    private handleRemove;
-    /** The chip body is announced as a button, so it must also act on keys:
-     *  Enter/Space re-dispatch as a host click (consumers' @click handlers
-     *  fire), Delete/Backspace remove when removable, and arrow keys ask the
-     *  container to reorder a draggable chip (`chip-move`) — the keyboard
-     *  alternative to pointer drag-and-drop. */
-    private handleKeydown;
-    private onDragStart;
-    private onDragEnd;
-    protected updated(changed: Map<string, unknown>): void;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-chip": RelChip;
-    }
-}
-
+/** Inner padding step, spelled out. */
+type ContainerPadding = "small" | "medium" | "large" | "extra-large";
+/** Alternative spellings, not deprecations — the short names keep working. */
+type ContainerPaddingAlias = "sm" | "md" | "lg" | "xl";
+type ContainerPaddingInput = ContainerPadding | ContainerPaddingAlias;
+/** Canonical surface names (audit 12). */
+type ContainerSurface = "default" | "elevated" | "transparent";
+/** @deprecated since 1.4.7 — use `ContainerSurface` / the `surface` prop. */
+type ContainerBackground = "light" | "white" | "none";
+/**
+ * Padded surface block (Figma "Container"): a full-width wrapper with a surface fill, a padding step and an optional shadow, used to group a section of content.
+ * @slot - Section content; slotted `h1`–`h4` get the headings-sm role and `p` the body-md role
+ * @csspart base - The padded surface `<div>` (same element as `container`)
+ * @csspart container - Alias of `base`, kept for existing `::part(container)` selectors
+ */
 declare class RelContainer extends LitElement {
-    padding: "sm" | "md" | "lg" | "xl";
+    /** Inner padding step: `small` = spacing-xs, `medium` = spacing-md, `large` = spacing-lg. `extra-large` = spacing-2xl is a code-only extension — Figma publishes only the three steps above — and is supported, not deprecated. `sm` / `md` / `lg` / `xl` are alternative spellings and stay supported, normalised to the full words. */
+    padding: ContainerPaddingInput;
+    /** Adds the shadow-300 elevation box-shadow to the surface. */
     shadow: boolean;
-    background: "light" | "white" | "none";
+    /**
+     * Surface fill: default (page surface) | elevated (raised surface) |
+     * transparent. Takes precedence over the deprecated `background` prop.
+     */
+    surface?: ContainerSurface;
+    /** @deprecated Deprecated since 1.4.7 — use `surface` (white→default, light→elevated, none→transparent). */
+    background?: ContainerBackground;
+    /** Resolved surface: explicit `surface` wins, else mapped `background`, else "default". */
+    get resolvedSurface(): ContainerSurface;
+    willUpdate(changed: Map<string, unknown>): void;
     static styles: lit.CSSResult;
     private get classes();
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Thin separator rule that splits content horizontally or vertically. Use it between sections, list groups or toolbar clusters; do not use it as a spacer.
+ * @csspart base - The rendered rule — restyle thickness, colour or margin here.
+ * @cssprop --rel-divider-spacing - Cross-axis margin around the rule; default 16px. Figma specifies none, so set it to `0` for strict parity — the default is kept for back-compat and is planned to become `0` in 3.0.
+ */
 declare class RelDivider extends LitElement {
+    /** Axis of the rule: `horizontal` spans the full width with vertical margin; `vertical` is a full-height line with horizontal margin (the parent needs a defined height or a flex row). Mirrored to `aria-orientation` on the host. */
     orientation: "horizontal" | "vertical";
     static styles: lit.CSSResult;
     connectedCallback(): void;
@@ -828,6 +1460,11 @@ declare class RelDivider extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Layout helper used by `<rel-drawer>` for its footer: a right-aligned flex
+ * row with an 8px gap. Can also be used standalone for a matching actions row.
+ * @slot - Footer actions (typically `<rel-button>`s)
+ */
 declare class RelDrawerFooter extends LitElement {
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
@@ -840,19 +1477,51 @@ declare global {
 
 type DrawerSide = "bottom" | "left" | "right";
 type DrawerCloseReason = "backdrop" | "escape" | "drag" | "programmatic";
+/**
+ * Edge-anchored drawer (Figma "Drawer", 5699:6844): a panel that slides in
+ * from the bottom, left or right over a scrim, with an optional drag handle
+ * (bottom only), a title/description header, a scrollable body and a footer.
+ * @slot - Body content of the drawer
+ * @slot footer - Actions row; rendered inside a `<rel-drawer-footer>` (right-aligned, 8px gap)
+ * @csspart overlay - The full-viewport scrim behind the panel
+ * @csspart panel - The sliding panel (role="dialog")
+ * @csspart handle - The drag-to-close grab bar (bottom drawers only)
+ * @csspart header - Header block holding title, description and close button
+ * @csspart close-button - The "X" close button
+ * @csspart content - Scrollable body wrapper around the default slot
+ * @csspart footer - Footer wrapper around the `footer` slot
+ * @cssprop --rel-drawer-width - Panel width. Default `clamp(640px, 66vw, 952px)` for `side="bottom"`, `clamp(280px, 24vw, 420px)` for left/right. The `width` prop sets this on the panel and wins over a host value
+ * @cssprop --rel-drawer-height - Panel height for `side="bottom"`; default `clamp(360px, 49vh, 600px)`. Left/right drawers are always full height
+ * @cssprop --rel-drawer-transition-duration - Slide/scrim animation duration; default `0.3s`
+ * @cssprop --rel-drawer-transition-timing - Slide/scrim animation easing; default `cubic-bezier(0.32, 0.72, 0, 1)`
+ * @cssprop --rel-drawer-scrim-opacity - Opacity of the scrim while open; default `1`
+ */
 declare class RelDrawer extends LitElement {
+    /** Whether the drawer is shown. Toggle it to open/close; every change fires `rel-open-change`. */
     open: boolean;
+    /** Edge the panel slides in from. `bottom` is centred horizontally and supports the drag handle; `left`/`right` are full-height side panels. */
     side: DrawerSide;
+    /** When false the close button is hidden and backdrop clicks / Escape are ignored (drag-to-close still works). */
     dismissible: boolean;
+    /** Modal mode: renders the scrim, sets `role="dialog"` + `aria-modal`, traps Tab inside the panel and moves focus in on open. When false the panel is a `region` with no scrim and no focus trap. */
     modal: boolean;
+    /** Close when the scrim is clicked. Only effective while `dismissible` is true. */
     closeOnBackdrop: boolean;
+    /** Close on the Escape key. Only effective while `dismissible` is true. */
     closeOnEscape: boolean;
+    /** Show the grab bar above the header. Only rendered when `side="bottom"` and `draggable` is true. */
     showHandle: boolean;
+    /** Enable drag-to-close on the handle (pointer or touch). Bottom drawers only. */
     draggable: boolean;
+    /** Fraction (0–1) of the panel height the user must drag down before release closes the drawer; shorter drags snap back. */
     snapThreshold: number;
+    /** Written to the panel as the `--drawer-max-height` custom property (any CSS length). No built-in rule reads it yet; use `--rel-drawer-height` to size a bottom drawer. */
     maxHeight: string;
+    /** Explicit panel width (any CSS length). Empty by default, which uses the per-side `--rel-drawer-width` default. */
     width: string;
+    /** Heading text (rendered as an `<h2>`, linked via `aria-labelledby`). */
     title: string;
+    /** Supporting text under the title (linked via `aria-describedby`). */
     description: string;
     private isDragging;
     private dragOffset;
@@ -862,12 +1531,23 @@ declare class RelDrawer extends LitElement {
     private previousFocus;
     private startY;
     private currentY;
+    /** Scrim opacity at rest, sampled once per drag so the fade starts from it. */
+    private scrimRestingOpacity;
     private originalBodyOverflow;
     private originalBodyPaddingRight;
     static styles: lit.CSSResult;
     connectedCallback(): void;
     disconnectedCallback(): void;
     updated(changed: Map<string, any>): void;
+    /**
+     * The footer divider is conditional: short content (a confirmation message)
+     * has no divider, but a body that scrolls does — it is a scroll affordance,
+     * not decoration (designer, confirmed). CSS cannot ask whether an element
+     * scrolls, so it is measured and reflected onto the host as `body-scrolls`,
+     * re-measured whenever the body or its contents resize.
+     */
+    private bodyScrollObserver?;
+    private watchBodyScroll;
     private handleOpen;
     private handleClose;
     private lockScroll;
@@ -889,11 +1569,31 @@ declare global {
     }
 }
 
+/**
+ * Key-cap scale (Figma Kbd 6316:284): S 20 / M 24 / L 28px tall with
+ * label-sm / label-md / label-lg type. `sm` / `md` / `lg` are the original
+ * names; the full words are accepted as aliases (Trello 4).
+ */
+type KbdSize = "sm" | "md" | "lg" | "small" | "medium" | "large";
+/**
+ * Single key cap (Figma "Kbd", 6316:284) for showing a keyboard key or shortcut
+ * inline with text; the key label is the slotted content.
+ * @slot - The key label (e.g. `Ctrl`, `K`, `⌘`)
+ */
 declare class RelKbd extends LitElement {
-    size: "sm" | "md" | "lg";
+    /** Key-cap scale (Figma Size): `small` 20px tall / label-sm, `medium` 24px / label-md, `large` 28px / label-lg; 4px radius at every size. `sm` / `md` / `lg` are the legacy short spellings and stay accepted. */
+    size: KbdSize;
+    /** Fill / text contrast: `default` = elevated-1 background with label text; `muted` = elevated-2 background with placeholder-tone text for secondary shortcuts. Both carry a 0.5px stroke and the hard 2px bottom edge Figma draws on the key cap. */
     variant: "default" | "muted";
+    /**
+     * Fully rounded corners. Logs a one-time console notice when set.
+     * @deprecated The Kbd spec has a single 4px radius at every size (audit
+     * 16); `pill` is kept working as an alias but logs a one-time notice.
+     */
     pill: boolean;
+    /** Pressed look: border-strong stroke, 1px downward nudge and (muted variant) a darker fill. */
     inset: boolean;
+    protected willUpdate(changed: PropertyValues<this>): void;
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
 }
@@ -902,11 +1602,17 @@ declare class RelKbd extends LitElement {
  * entry in `items` with "+" separators between them. Slotted <rel-kbd>
  * children may be used instead of the items array.
  *
- * <rel-kbd-group .items=${["Ctrl", "Shift", "P"]} size="md"></rel-kbd-group>
+ * <rel-kbd-group .items=${["Ctrl", "Shift", "P"]} size="medium"></rel-kbd-group>
+ * @slot - Extra content rendered after the generated keys (e.g. hand-written `<rel-kbd>` children)
+ * @csspart item - Each generated `<rel-kbd>` key cap
+ * @csspart label - The `+` separator between generated keys
  */
 declare class RelKbdGroup extends LitElement {
+    /** Key labels to render, one `<rel-kbd>` each, joined by `+` separators. Set as a property or as a JSON array attribute (`items='["Ctrl","K"]'`). */
     items: string[];
-    size: "sm" | "md" | "lg";
+    /** Passed through to every generated <rel-kbd>: `small` / `medium` / `large` (legacy `sm` / `md` / `lg` still accepted). */
+    size: KbdSize;
+    /** Passed through to every generated <rel-kbd>: `default` or `muted`. */
     variant: "default" | "muted";
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
@@ -931,23 +1637,48 @@ type StepperType = "default" | "dot" | "number" | "icon";
 type LabelPlacement = "top" | "centered" | "inverted";
 interface Step {
     title: string;
+    /** Optional second line under the title (Figma "Subtitle" / "Show Subtitle"). Omit it and the step stays single-line. */
+    subtitle?: string;
     status: StepStatus;
 }
+/**
+ * Multi-step progress indicator (Figma "Stepper"): renders one focusable step per entry in `steps` — a circular indicator (number, check, dot or icon per `type`), a label and a connector line to the next step — in a row or a column.
+ * @csspart indicator - The 24px circle (8px for `type="dot"`) that holds the step number, check mark or icon.
+ * @csspart track - The 1px connector line from a step to the next one (not rendered on the last step).
+ * @csspart label - The step title text.
+ * @csspart subtitle - The optional second line under the title; rendered only when a step sets `subtitle`.
+ * @cssprop --rel-stepper-indicator-size - Indicator diameter (default 24px; `type="dot"` is fixed at 8px).
+ * @cssprop --rel-stepper-connector-length - Length of the connector line; the step gap is derived from it by adding Figma's clear space at both ends. Defaults to Figma's fixed geometry: 96px horizontally, 34px vertically with `label-placement="centered"`, 51px with `inverted`.
+ * @cssprop --rel-stepper-connector-length-lg - Superseded by `--rel-stepper-connector-length`, which it still falls back to, so an existing override keeps working.
+ * @cssprop --rel-stepper-connector-length-md - No longer applies. It parameterised the code-only `size` axis, and Figma has one connector geometry rather than a scale.
+ * @cssprop --rel-stepper-connector-length-sm - No longer applies, for the same reason as `-md`.
+ */
 declare class RelStepper extends LitElement {
+    /** The steps in order, each `{ title: string; subtitle?: string; status: "done" | "progress" | "disabled" }`. Set as a property (or a JSON array attribute); the component never mutates it — update it from the `rel-step-change` handler. */
     steps: Step[];
+    /**
+     * Legacy label placement (attribute `textalign`): `below` (default) puts the label under the indicator, `right` puts it beside the indicator. Ignored whenever `label-placement` is set.
+     * @deprecated Deprecated alias of `label-placement`; use `label-placement="inverted"` instead of `textalign="below"` and `label-placement="centered"` instead of `textalign="right"`.
+     */
     textAlign: TextAlign;
+    /** Layout axis: `horizontal` (default) lays the steps out in a centred row; `vertical` stacks them. */
     orientation: Orientation;
-    size: StepperSize;
-    type: StepperType;
     /**
-     * Figma Typel axis: top = label top-aligned beside the indicator,
-     * centered = label vertically centered beside it, inverted = indicator above
-     * the label. When unset, the legacy textAlign prop drives the layout
-     * (below ≈ inverted, right ≈ centered). Note Figma marks Top+Horizontal
-     * as an unsupported combination.
+     * No longer has any effect. It used to set the connector length and step gap
+     * (86px for `large`, 60 / 42px for `small`) and to swap the step label to
+     * body/sm/regular at `small`.
+     * @deprecated Figma has no Size axis on the Stepper — the connector geometry
+     * is fixed — so this was a code-only scale. It stays accepted so existing
+     * markup keeps working, and now resolves to the one Figma geometry. Retune it
+     * with `--rel-stepper-connector-length` instead. Logs a one-time notice.
      */
+    size: StepperSize;
+    /** Figma "Type" axis — what the indicator shows: `default` (step number, check mark once done), `dot` (8px dot, no glyph), `number` (always the number) or `icon` (always the check mark). */
+    type: StepperType;
+    /** Figma "Typel" axis — where the label sits: `top` (top-aligned beside the indicator), `centered` (vertically centred beside it) or `inverted` (indicator above the label). When unset, the deprecated `textAlign` prop drives the layout (`below` ≈ `inverted`, `right` ≈ `centered`). Figma marks Top + Horizontal as an unsupported combination. */
     labelPlacement?: LabelPlacement;
     static styles: lit.CSSResult;
+    protected willUpdate(changed: Map<string, unknown>): void;
     private isDone;
     private isProgress;
     private isDisabled;
@@ -969,20 +1700,43 @@ interface RadioOption {
      *  Ignored when `icon` is also set. */
     avatar?: string;
 }
+/** Control scale, spelled out. */
 type RadioSize = "small" | "medium" | "large";
+/** Alternative spellings, not deprecations — the short names work too. */
+type RadioSizeAlias = "sm" | "md" | "lg";
+type RadioSizeInput = RadioSize | RadioSizeAlias;
 type RadioDensity = "compact" | "comfortable";
 type RadioAlignment = "leading" | "trailing";
+/**
+ * Single-select radio group (Figma "Radio"): renders one native radio input per
+ * entry in `options`, with optional supporting text, icon or avatar prefix.
+ * @csspart base - The `role="radiogroup"` container that lays out the options
+ * @csspart label - The visible label text of each option
+ */
 declare class RelRadio extends LitElement {
+    /** The options to render, in order. Each entry is a `RadioOption` (`value`, `label`,
+     *  optional `supportingText`, `disabled`, `icon` or `avatar`). Set as a property
+     *  (`.options=`) or as a JSON attribute. */
     options: RadioOption[];
+    /** `name` given to every native radio input inside this element. It scopes native
+     *  radio-group behaviour (arrow-key movement, mutual exclusion) to this group, so give
+     *  each group on a page a distinct name. */
     name: string;
     /** Layout axis of the option list. `"vertical"` (default) stacks options in
      *  a column; `"horizontal"` lays them out in a wrapping row. */
     orientation: Orientation;
-    /** Control scale (Figma Size). `"medium"` (default, Figma M) = 20px control
-     *  with body-lg labels; `"large"` (Figma L) = 24px control with body-xl
-     *  labels; `"small"` (Figma S) = 20px control with body-md labels — S and M
-     *  share the control size in the spec, only typography steps down. */
-    size: RadioSize;
+    /** Control scale. `"medium"` (default, Figma M) = 20px control with body-lg
+     *  labels; `"large"` (Figma L) = 24px control with body-xl labels;
+     *  `"small"` = 16px control with body-md labels. `sm` / `md` / `lg` are
+     *  alternative spellings and stay supported — normalised to the full words,
+     *  not deprecated.
+     *
+     *  DELIBERATE FIGMA DIVERGENCE on Small. Figma's `.Radio Control` has one
+     *  size (20x20) and its row variants pin Small AND Medium to 20, so the two
+     *  rendered identically and the Size axis did nothing between them. 16px is
+     *  not invented: it is rel-checkbox's Small, and checkbox is radio's sibling
+     *  selection control. See the size ramp in the styles below. */
+    size: RadioSizeInput;
     /** Supporting-text layout (Figma Density). `"compact"` (default) puts the
      *  supporting text on its own line under the row, indented past the control;
      *  `"comfortable"` stacks label + supporting text beside the control. */
@@ -993,13 +1747,27 @@ declare class RelRadio extends LitElement {
      *  with comfortable density. Meant for vertical orientation — trailing
      *  options stretch to the group's full width. */
     alignment: RadioAlignment;
+    /** `value` of the currently selected option, or `null` when nothing is selected.
+     *  Set it to preselect an option; it is updated on every user selection. */
     selectedValue: string | null;
+    /** Disables every option (Figma State=Disabled: the whole group at 40% opacity).
+     *  Individual options can also be disabled via `RadioOption.disabled`. */
     disabled: boolean;
+    /** Error state (Figma State=Error): rings, dots and supporting text turn danger.
+     *  Applies to every option while nothing is selected, and only to the selected
+     *  option once a choice is made. Selection is still allowed. */
     error: boolean;
+    /** Message rendered under the group (live region) while `error` is set; hidden
+     *  when `error` is false or the text is empty. */
     errorMessage: string;
     /** Accessible name for the radiogroup (it renders no visible group label). */
     fieldAriaLabel?: string;
+    /** Value reported to the Angular forms bridge (`registerOnChange` callback) on each
+     *  change and compared by `writeValue`. Not used for rendering; read `selectedValue`
+     *  or the `rel-change` detail for the selected option. */
     value: string;
+    /** Set by the Angular forms bridge (`writeValue`) to whether the written form value
+     *  equals `value`. Not used for rendering — read `selectedValue` for the selection. */
     checked: boolean;
     private _onChange;
     private _onTouched;
@@ -1008,8 +1776,11 @@ declare class RelRadio extends LitElement {
     /** Trailing has no compact layout in the spec — trailing wins. */
     private get effectiveDensity();
     private onChange;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnChange(fn: (value: string) => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnTouched(fn: () => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     writeValue(value: string): void;
     private get hasSelection();
     private renderPrefix;
@@ -1017,7 +1788,17 @@ declare class RelRadio extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
-type MenuType = "default" | "checkbox" | "arrow" | "select-option" | "fixed" | "fit";
+/**
+ * Row shape (Figma ".Menu Item" Type): list | checkbox | select-option.
+ * `default` is the deprecated spelling of `list`. `arrow` is a code-only
+ * extension with no Figma counterpart — it turns on the submenu flyout.
+ * `fixed` / `fit` are deprecated here and now live on `width`.
+ */
+type MenuType = "list" | "checkbox" | "select-option" | "arrow" | "default" | "fixed" | "fit";
+/** Sizing mode (Figma "Menu" Type). Both modes are --rel-menu-width wide; the axis varies the HEIGHT: fixed pins the panel to --rel-menu-height and scrolls, fit hugs its rows. */
+type MenuWidth = "fixed" | "fit";
+/** Figma ".Menu Item" Size: large (48px rows) | medium (40px) | small (32px). */
+type MenuSize = "large" | "medium" | "small";
 interface MenuItem {
     label: string;
     active?: boolean;
@@ -1026,16 +1807,67 @@ interface MenuItem {
     submenu?: MenuItem[];
     open?: boolean;
 }
+/**
+ * Declarative menu-item placeholder. It renders nothing and `<rel-menu>` does not
+ * currently read slotted children — menus are built from the `items` property.
+ * Registered so markup can carry item metadata for future declarative support.
+ */
 declare class RelMenuItem extends LitElement {
+    /** Display text of the item. */
     label: string;
+    /** Value that identifies the item (not used by `rel-menu` today). */
     value: string;
+    /** Marks the item as non-interactive. */
     disabled: boolean;
+    /** `rel-icon` name to render before the label (not used by `rel-menu` today). */
     icon: string;
     createRenderRoot(): this;
     render(): lit_html.TemplateResult<1>;
 }
+/**
+ * Light-DOM menu (Figma "Menu", 6326:2931) driven by the `items` array: single-select
+ * rows, checkbox rows, radio-style select-option rows, or hover/keyboard submenus.
+ * @csspart list - The `role="menu"` root list (a light-DOM `[part="list"]` attribute)
+ * @csspart panel - A submenu flyout (`type="arrow"` only; light-DOM `[part="panel"]` attribute)
+ * @cssprop --rel-menu-width - Width of the menu in BOTH sizing modes; default 300px
+ * @cssprop --rel-menu-height - Height of the menu when `width="fixed"`, which then scrolls; default 500px. `fit` ignores it and hugs its rows.
+ */
 declare class RelMenu extends LitElement {
+    /**
+     * Row shape (Figma ".Menu Item" Type). `list` (default) = plain rows;
+     * `checkbox` = toggling rows with a checkbox; `select-option` = single-select
+     * rows with a trailing check.
+     * `arrow` is a code-only extension with no Figma counterpart: rows whose
+     * `submenu` opens a flyout. Because it rides this axis, submenus cannot
+     * currently be combined with checkbox or select-option rows — see the README.
+     * DEPRECATED values, all still working: `default` is the old spelling of
+     * `list`; `fixed` / `fit` were width modes and now set `width` instead,
+     * leaving the row shape at `list`.
+     */
     type: MenuType;
+    /**
+     * Sizing mode (Figma "Menu" Type). Both modes are `--rel-menu-width` (300px)
+     * wide — Figma's Fixed and Fit variants are both 300px — and the axis varies
+     * the HEIGHT: `fixed` pins the panel to `--rel-menu-height` (500px) and
+     * scrolls, `fit` hugs its rows. `fit` previously varied the width instead,
+     * which was the wrong dimension. This was also fused into `type`, where
+     * choosing a width silently forced plain rows and choosing a row shape
+     * silently forced the default width.
+     */
+    width?: MenuWidth;
+    /** Row shape actually rendered: the deprecated width values fall back to `list`. */
+    private get resolvedType();
+    /** Width mode actually applied: explicit `width` wins, else the deprecated `type` spelling. */
+    private get resolvedWidth();
+    /**
+     * Row size (Figma ".Menu Item" Size, 6326:616): large = 48px rows with
+     * body-lg labels (Figma default), medium = 40px / body-md, small = 32px /
+     * body-sm. Added in 1.4.7; before that rows were a fixed 36px.
+     */
+    size: MenuSize;
+    /** The rows to render, in order. Each entry is a `MenuItem` (`label`, optional
+     *  `active`, `checked`, `disabled`, `submenu`, `open`). The array is copied on
+     *  assignment, so mutate and reassign it to update the menu. */
     items: MenuItem[];
     private focusedIndex;
     /** Index inside the open submenu that virtual focus sits on; -1 = main list. */
@@ -1043,7 +1875,7 @@ declare class RelMenu extends LitElement {
     private _items;
     /** Stable id prefix for aria-activedescendant targets. */
     private menuId;
-    static readonly _css = "\n    :host {\n      color: var(--rel-text-default);\n      display: inline-block;\n    }\n\n    .rel-menu {\n      position: relative;\n      display: inline-block;\n      background: var(--rel-bg-neutral);\n      color: var(--rel-text-default);\n      border-radius: var(--rel-border-radius-md);\n      box-shadow: var(--rel-shadows-shadow-300);\n      min-width: 220px;\n      /* No vertical padding: items fill edge-to-edge so a first/last-item hover\n         reaches the menu's top/bottom. NOT overflow:hidden \u2014 that clips the\n         type=arrow flyout (position:absolute at left:100%). Instead the first\n         and last items carry the outer corner radius so hover backgrounds clip\n         to the rounded shape without any overflow. */\n      padding: 0;\n      outline: none;\n      overflow: visible;\n      font-family: var(--rel-body-lg-regular-font-family);\n      font-weight: var(--rel-body-lg-regular-font-weight);\n      font-size: var(--rel-body-lg-regular-font-size);\n      line-height: var(--rel-body-lg-regular-line-height);\n      letter-spacing: var(--rel-body-lg-regular-letter-spacing);\n    }\n\n    .rel-menu:focus-visible,\n    :host(:focus-visible) .rel-menu {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: 2px;\n    }\n\n    .rel-menu-item {\n      position: relative;\n      display: flex;\n      align-items: center;\n      gap: var(--rel-spacing-xs);\n      padding: var(--rel-spacing-xs) var(--rel-spacing-sm);\n      line-height: var(--rel-body-sm-regular-line-height);\n      cursor: pointer;\n      transition: background 0.15s ease, color 0.15s ease;\n      user-select: none;\n    }\n\n    /* First/last items carry the menu's outer radius so their hover fill clips\n       to the rounded corners (replaces the removed overflow:hidden). */\n    .rel-menu > .rel-menu-item:first-child {\n      border-top-left-radius: var(--rel-border-radius-md);\n      border-top-right-radius: var(--rel-border-radius-md);\n    }\n\n    .rel-menu > .rel-menu-item:last-child {\n      border-bottom-left-radius: var(--rel-border-radius-md);\n      border-bottom-right-radius: var(--rel-border-radius-md);\n    }\n\n    .rel-menu-item:hover {\n      background: var(--rel-bg-neutral-elevated-1);\n    }\n\n    .rel-menu-item:active {\n      background: var(--rel-bg-neutral-elevated-1);\n    }\n\n    .rel-menu-item.active {\n      background: var(--rel-bg-neutral-elevated-2);\n      font-weight: var(--rel-body-lg-medium-font-weight);\n    }\n\n    .rel-menu-item.disabled {\n      background-color: transparent;\n      color: var(--rel-text-disabled);\n      /* Keep the item pointer-interactive so cursor:not-allowed actually\n         renders; clicks are already neutralised by the item.disabled guard in\n         onItemClick/onItemEnter. pointer-events:none here would make the row\n         transparent to the pointer and suppress the cursor. */\n      cursor: not-allowed;\n    }\n\n    /* [data-focused] (presence, not =\"true\"): the ?data-focused boolean\n       binding renders the attribute with an EMPTY value, so a =\"true\"\n       selector never matches. */\n    .rel-menu-item[data-focused] {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: -2px;\n    }\n\n    /* Width modes (Figma Type=Fixed / Type=Fit) */\n    .rel-menu.fixed {\n      width: var(--rel-menu-width, 300px);\n      min-width: 0;\n      box-sizing: border-box;\n    }\n\n    .rel-menu.fit {\n      min-width: 0;\n      width: max-content;\n    }\n\n    /* Checkbox (Type=Checkbox) / radio (Type=Select Option) rows render the real\n       rel-checkbox / rel-radio. pointer-events:none keeps the whole row the click\n       target so onItemClick stays the single source of truth. */\n    .menu-control {\n      pointer-events: none;\n      width: 100%;\n    }\n\n    .menu-label {\n      flex: 1 1 auto;\n    }\n\n    /* Submenu affordance \u2014 same rel-icon chevron the menubar uses. */\n    .submenu-chevron {\n      margin-left: auto;\n      display: inline-flex;\n      align-items: center;\n      opacity: 0.6;\n      pointer-events: none;\n    }\n\n    /* Shortcut / hint text (Figma body-sm-regular, caption tone) */\n    .menu-shortcut,\n    ::slotted([slot=\"shortcut\"]) {\n      font-family: var(--rel-body-sm-regular-font-family);\n      font-weight: var(--rel-body-sm-regular-font-weight);\n      font-size: var(--rel-body-sm-regular-font-size);\n      line-height: var(--rel-body-sm-regular-line-height);\n      letter-spacing: var(--rel-body-sm-regular-letter-spacing);\n      color: var(--rel-text-caption);\n      margin-left: auto;\n      padding-left: var(--rel-spacing-md);\n    }\n\n    \n    .rel-submenu {\n      border: 1px solid var(--rel-border-subtle);\n      position: absolute;\n      top: calc(-1 * var(--rel-spacing-3xs));\n      /* flush against the trigger (no gap) so moving the pointer into the flyout\n         never crosses a dead zone that would fire the trigger's mouseleave */\n      left: 100%;\n      min-width: 200px;\n      background: var(--rel-bg-neutral);\n      color: var(--rel-text-default);\n      border-radius: var(--rel-border-radius-md);\n      box-shadow: var(--rel-shadows-shadow-300);\n      /* padding:0 + overflow:hidden \u2014 safe here (a submenu has no further nested\n         flyout to clip) \u2014 so sub-item hovers fill fully and clip to the corners */\n      padding: 0;\n      overflow: hidden;\n      visibility: hidden;\n      pointer-events: none;\n      z-index: 20;\n    }\n\n    .rel-submenu.visible {\n      visibility: visible;\n      pointer-events: auto;\n    }\n\n    .rel-submenu .rel-menu-item {\n      padding: var(--rel-spacing-xs) var(--rel-spacing-sm);\n    }\n  ";
+    static readonly _css = "\n    :host {\n      color: var(--rel-text-default);\n      display: inline-block;\n    }\n\n    .rel-menu {\n      position: relative;\n      display: inline-block;\n      background: var(--rel-bg-neutral);\n      color: var(--rel-text-default);\n      /* Audit 17: 8px (border-radius/sm), was 16px; Figma Menu (6326:2931) = shadow/md */\n      border-radius: var(--rel-border-radius-sm);\n      box-shadow: var(--rel-shadows-md);\n      /* Figma's Menu container is 300px around 288px rows. */\n      min-width: 300px;\n      /* No vertical padding: items fill edge-to-edge so a first/last-item hover\n         reaches the menu's top/bottom. NOT overflow:hidden \u2014 that clips the\n         type=arrow flyout (position:absolute at left:100%). Instead the first\n         and last items carry the outer corner radius so hover backgrounds clip\n         to the rounded shape without any overflow. */\n      padding: 0;\n      outline: none;\n      overflow: visible;\n      font-family: var(--rel-body-lg-regular-font-family);\n      font-weight: var(--rel-body-lg-regular-font-weight);\n      font-size: var(--rel-body-lg-regular-font-size);\n      line-height: var(--rel-body-lg-regular-line-height);\n      letter-spacing: var(--rel-body-lg-regular-letter-spacing);\n    }\n\n    .rel-menu:focus-visible,\n    :host(:focus-visible) .rel-menu {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: 0;\n    }\n\n    /* Rows follow Figma \".Menu Item\" (6326:616) per size:\n       Large  48px = pad 12/12 + body-lg (24 line-height)\n       Medium 40px = pad 8/12  + body-md (22)\n       Small  32px = pad 4/8   + body-sm (20)\n       (audit 17a \u2014 before 1.4.7 every row was 36px: pad 8/12 + a 20px line-height) */\n    .rel-menu-item {\n      position: relative;\n      display: flex;\n      align-items: center;\n      gap: var(--rel-spacing-md);\n      padding: var(--rel-spacing-sm) var(--rel-spacing-sm);\n      line-height: var(--rel-body-lg-regular-line-height);\n      min-height: 48px;\n      cursor: pointer;\n      transition: background 0.15s ease, color 0.15s ease;\n      user-select: none;\n      box-sizing: border-box;\n      /* Figma strokes every item with --rel-border-subtle. Drawn as an inset\n         shadow on the BOTTOM edge only (the pattern rel-menubar already uses)\n         so the rows read as a divided list rather than 45 boxed cells, and so\n         it costs no layout height. */\n      box-shadow: inset 0 calc(-1 * var(--rel-stroke-sm)) 0 var(--rel-border-subtle);\n    }\n\n    .rel-menu-item:last-child {\n      box-shadow: none;\n    }\n\n    /* Light-DOM component: :host never matches here, so size rules key off the\n       reflected attribute on the <rel-menu> element itself. */\n    rel-menu[size=\"medium\"] .rel-menu,\n    rel-menu[size=\"medium\"] .rel-submenu {\n      font-family: var(--rel-body-md-regular-font-family);\n      font-weight: var(--rel-body-md-regular-font-weight);\n      font-size: var(--rel-body-md-regular-font-size);\n      line-height: var(--rel-body-md-regular-line-height);\n      letter-spacing: var(--rel-body-md-regular-letter-spacing);\n    }\n\n    /* Figma Medium / Small frames are fixed at 40 / 32 (content sums to 38 / 28) */\n    rel-menu[size=\"medium\"] .rel-menu-item {\n      padding: var(--rel-spacing-xs) var(--rel-spacing-sm);\n      line-height: var(--rel-body-md-regular-line-height);\n      min-height: 40px;\n    }\n\n    rel-menu[size=\"small\"] .rel-menu,\n    rel-menu[size=\"small\"] .rel-submenu {\n      font-family: var(--rel-body-sm-regular-font-family);\n      font-weight: var(--rel-body-sm-regular-font-weight);\n      font-size: var(--rel-body-sm-regular-font-size);\n      line-height: var(--rel-body-sm-regular-line-height);\n      letter-spacing: var(--rel-body-sm-regular-letter-spacing);\n    }\n\n    rel-menu[size=\"small\"] .rel-menu-item {\n      padding: var(--rel-spacing-2xs) var(--rel-spacing-xs);\n      line-height: var(--rel-body-sm-regular-line-height);\n      min-height: 32px;\n    }\n\n    /* First/last items carry the menu's outer radius so their hover fill clips\n       to the rounded corners (replaces the removed overflow:hidden). */\n    .rel-menu > .rel-menu-item:first-child {\n      border-top-left-radius: var(--rel-border-radius-sm);\n      border-top-right-radius: var(--rel-border-radius-sm);\n    }\n\n    .rel-menu > .rel-menu-item:last-child {\n      border-bottom-left-radius: var(--rel-border-radius-sm);\n      border-bottom-right-radius: var(--rel-border-radius-sm);\n    }\n\n    /* Figma states (6326:616): Hover = action overlay 0.05, Pressed = 0.10\n       (nearest token: overlay-pressed), Active/selected list row = the hover\n       overlay + medium label; Checkbox / Select Option rows keep no fill when\n       selected. Disabled = 40% opacity. (audit 17) */\n    .rel-menu-item:hover {\n      background: var(--rel-action-overlay-hover);\n    }\n\n    .rel-menu-item:active {\n      background: var(--rel-action-overlay-pressed);\n    }\n\n    .rel-menu-item.active {\n      background: var(--rel-action-overlay-hover);\n    }\n\n    /* The active weight bump follows the row's own size, and applies to plain\n       rows only \u2014 a checkbox row carries its state in the control, and Figma\n       does not bold its label. */\n    .rel-menu:not(.type-checkbox) .rel-menu-item.active {\n      font-weight: var(--rel-body-lg-medium-font-weight);\n    }\n\n    rel-menu[size=\"medium\"] .rel-menu:not(.type-checkbox) .rel-menu-item.active {\n      font-weight: var(--rel-body-md-medium-font-weight);\n    }\n\n    /* Small's active row is Figma's mixed tuple: an xs-medium WEIGHT with\n       sm-medium METRICS on the sm-regular family. Large and Medium step only\n       their weight and keep regular metrics, which is why they are one line\n       each and this one is four. */\n    rel-menu[size=\"small\"] .rel-menu:not(.type-checkbox) .rel-menu-item.active {\n      font-weight: var(--rel-body-xs-medium-font-weight);\n      font-size: var(--rel-body-sm-medium-font-size);\n      line-height: var(--rel-body-sm-medium-line-height);\n      letter-spacing: var(--rel-body-sm-medium-letter-spacing);\n    }\n\n    .rel-menu.type-checkbox .rel-menu-item.active,\n    .rel-menu.type-select-option .rel-menu-item.active {\n      background: transparent;\n    }\n\n    .rel-menu.type-checkbox .rel-menu-item.active:hover,\n    .rel-menu.type-select-option .rel-menu-item.active:hover {\n      background: var(--rel-action-overlay-hover);\n    }\n\n    .rel-menu-item.disabled {\n      background-color: transparent;\n      opacity: 0.4;\n      /* Keep the item pointer-interactive so cursor:not-allowed actually\n         renders; clicks are already neutralised by the item.disabled guard in\n         onItemClick/onItemEnter. pointer-events:none here would make the row\n         transparent to the pointer and suppress the cursor. */\n      cursor: not-allowed;\n    }\n\n    /* [data-focused] (presence, not =\"true\"): the ?data-focused boolean\n       binding renders the attribute with an EMPTY value, so a =\"true\"\n       selector never matches. */\n    /* Inset ring: items run the full width of the panel and butt against its\n       padding, so an outside ring would cross the panel edge. rel-menu has no\n       State=Focused variant in Figma; kept deliberately. */\n    .rel-menu-item[data-focused] {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: -2px;\n    }\n\n    /* Width modes (Figma Type=Fixed / Type=Fit). BOTH are 300px wide \u2014\n       COMPONENT \"Type=Fixed\" is 300x500 sizing=FIXED/FIXED and\n       COMPONENT \"Type=Fit\" is 300x48 sizing=FIXED/HUG \u2014 so the axis varies the\n       HEIGHT, not the width: Fixed pins a scrolling panel, Fit hugs its rows.\n       This had it inverted: fit varied the width (max-content) and neither mode\n       constrained the height, so the two modes differed on the wrong dimension. */\n    .rel-menu.fixed {\n      width: var(--rel-menu-width, 300px);\n      height: var(--rel-menu-height, 500px);\n      overflow-y: auto;\n      min-width: 0;\n      box-sizing: border-box;\n    }\n\n    .rel-menu.fit {\n      width: var(--rel-menu-width, 300px);\n      min-width: 0;\n      box-sizing: border-box;\n    }\n\n    /* Checkbox (Type=Checkbox) / radio (Type=Select Option) rows render the real\n       rel-checkbox / rel-radio. pointer-events:none keeps the whole row the click\n       target so onItemClick stays the single source of truth. */\n    .menu-control {\n      pointer-events: none;\n      width: 100%;\n    }\n\n    .menu-label {\n      flex: 1 1 auto;\n    }\n\n    /* Submenu affordance \u2014 same rel-icon chevron the menubar uses. */\n    .submenu-chevron {\n      margin-left: auto;\n      display: inline-flex;\n      align-items: center;\n      opacity: 0.6;\n      pointer-events: none;\n    }\n\n    /* Shortcut / hint text (Figma body-sm-regular, caption tone) */\n    .menu-shortcut,\n    ::slotted([slot=\"shortcut\"]) {\n      font-family: var(--rel-body-sm-regular-font-family);\n      font-weight: var(--rel-body-sm-regular-font-weight);\n      font-size: var(--rel-body-sm-regular-font-size);\n      line-height: var(--rel-body-sm-regular-line-height);\n      letter-spacing: var(--rel-body-sm-regular-letter-spacing);\n      color: var(--rel-text-caption);\n      margin-left: auto;\n      padding-left: var(--rel-spacing-md);\n    }\n\n    \n    /* No border: the flyout is the same surface as the parent menu, which has\n       none \u2014 overlapping surfaces are separated by shadow. Min-width tracks the\n       parent's 300px rather than a narrower 200px. */\n    .rel-submenu {\n      position: absolute;\n      top: calc(-1 * var(--rel-spacing-3xs));\n      /* flush against the trigger (no gap) so moving the pointer into the flyout\n         never crosses a dead zone that would fire the trigger's mouseleave */\n      left: 100%;\n      min-width: 300px;\n      background: var(--rel-bg-neutral);\n      color: var(--rel-text-default);\n      border-radius: var(--rel-border-radius-sm);\n      box-shadow: var(--rel-shadows-md);\n      /* padding:0 + overflow:hidden \u2014 safe here (a submenu has no further nested\n         flyout to clip) \u2014 so sub-item hovers fill fully and clip to the corners */\n      padding: 0;\n      overflow: hidden;\n      visibility: hidden;\n      pointer-events: none;\n      z-index: 20;\n    }\n\n    .rel-submenu.visible {\n      visibility: visible;\n      pointer-events: auto;\n    }\n\n    .rel-submenu .rel-menu-item {\n      padding: var(--rel-spacing-sm) var(--rel-spacing-sm);\n    }\n\n    rel-menu[size=\"medium\"] .rel-submenu .rel-menu-item {\n      padding: var(--rel-spacing-xs) var(--rel-spacing-sm);\n    }\n\n    rel-menu[size=\"small\"] .rel-submenu .rel-menu-item {\n      padding: var(--rel-spacing-2xs) var(--rel-spacing-xs);\n    }\n  ";
     createRenderRoot(): this;
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -1064,14 +1896,22 @@ declare class RelMenu extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/** Figma "Menu Bar" Type (8699:4): `fit` hugs the triggers, `fixed` spans the container. */
+type MenubarType = "fixed" | "fit";
+/**
+ * Horizontal application menubar (`role="menubar"`) that turns each child `<rel-menubar-menu>` into a trigger button with a dropdown panel of items, separators, submenus, checkbox items and radio groups; renders into light DOM (no slots or parts).
+ * @cssprop --rel-menubar-width - Width of the bar when `type="fixed"`; default 100%
+ * @cssprop --rel-menubar-panel-width - Width of the dropdown and submenu panels; default 300px
+ */
 declare class RelMenubar extends LitElement {
     /**
-     * Opt-in: actually BIND the keys declared via data-shortcut (e.g.
-     * data-shortcut="Ctrl+Z"), not just display them. "Ctrl" matches Cmd on
-     * Apple platforms when written as "Mod". Keystrokes originating in
-     * inputs/textareas/contenteditable are ignored.
+     * Opt-in: actually bind the keys declared via `data-shortcut` on items (e.g. `data-shortcut="Ctrl+Z"`) instead of only displaying them; a "Mod" token means Cmd on Apple platforms and Ctrl elsewhere, and keystrokes that originate in inputs, textareas or contenteditable regions are ignored.
      */
     bindShortcuts: boolean;
+    /**
+     * Width mode (Figma "Menu Bar" Type, 8699:4): `fit` sizes the bar to its triggers, `fixed` stretches it across its container (override the stretched width with `--rel-menubar-width`). The default stays `fit`, which is how the bar has always rendered.
+     */
+    type: MenubarType;
     private menus;
     private openMenuIndex;
     private focusedTriggerIndex;
@@ -1084,7 +1924,7 @@ declare class RelMenubar extends LitElement {
     /** Stable id prefix for aria-activedescendant targets (light DOM, so ids
      *  must be unique per menubar instance on the page). */
     private menubarId;
-    static readonly _css = "\n    /* This component renders into LIGHT DOM (createRenderRoot returns this), so\n       :host / <slot> don't work here \u2014 the raw <rel-menubar-menu> definitions\n       are data holders that must be hidden with a plain selector. Relying on the\n       global rel-menubar-menu.css is not enough: it can't cross a consumer's\n       shadow boundary AND it's a no-op in the tsup-built package (css:\"copy\"). */\n    rel-menubar {\n      color: var(--rel-text-default);\n      display: block;\n    }\n\n    rel-menubar-menu {\n      display: none;\n    }\n\n    .menubar-container {\n      display: flex;\n      align-items: stretch;\n      background: var(--rel-bg-surface-elevated);\n      border: var(--rel-stroke-sm) solid var(--rel-border-default);\n      border-radius: var(--rel-border-radius-sm);\n      overflow: hidden;\n      padding: 0;\n      gap: var(--rel-spacing-3xs);\n      height: 40px;\n      width: fit-content;\n      font-family: var(--rel-body-sm-regular-font-family);\n      font-weight: var(--rel-body-sm-regular-font-weight);\n      font-size: var(--rel-body-sm-regular-font-size);\n      line-height: var(--rel-body-sm-regular-line-height);\n      letter-spacing: var(--rel-body-sm-regular-letter-spacing);\n    }\n\n    .menubar-trigger {\n      display: flex;\n      align-items: center;\n      align-self: stretch;\n      height: 100%;\n      padding: 0 var(--rel-spacing-sm);\n      background: transparent;\n      border: none;\n      cursor: pointer;\n      font-family: inherit;\n      font-size: inherit;\n      color: var(--rel-text-label);\n      transition: background 0.15s ease;\n      user-select: none;\n      outline: none;\n    }\n\n    .menubar-trigger:hover,\n    .menubar-trigger.active {\n      background: var(--rel-bg-neutral-elevated-2);\n    }\n\n    .menubar-trigger:focus-visible {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: 2px;\n    }\n\n    .menubar-panel {\n      position: fixed;\n      min-width: 220px;\n      background: var(--rel-bg-surface);\n      border: var(--rel-stroke-sm) solid var(--rel-border-default);\n      border-radius: var(--rel-border-radius-sm);\n      box-shadow: var(--rel-shadows-shadow-300);\n      padding: 0;\n      overflow: hidden;\n      z-index: 1000;\n      display: none;\n    }\n\n    .menubar-panel.open {\n      display: block;\n    }\n\n    .menu-item {\n      position: relative;\n      display: flex;\n      align-items: center;\n      justify-content: space-between;\n      gap: var(--rel-spacing-sm);\n      padding: var(--rel-spacing-xs) var(--rel-spacing-md);\n      cursor: pointer;\n      transition: background 0.15s ease;\n      user-select: none;\n      color: var(--rel-text-label);\n      line-height: var(--rel-body-sm-regular-line-height);\n    }\n\n    .menu-item:hover,\n    .menu-item.focused {\n      background: var(--rel-bg-neutral-elevated-2);\n    }\n\n    .menu-item[data-disabled=\"true\"] {\n      opacity: 0.5;\n      cursor: not-allowed;\n    }\n\n    .menu-separator {\n      height: var(--rel-stroke-sm);\n      background: var(--rel-border-default);\n      margin: 0;\n      padding: 0;\n    }\n\n    rel-icon {\n      display: inline-flex;\n      pointer-events: none;\n    }\n\n    .menu-submenu-trigger {\n      position: relative;\n    }\n\n    .menu-submenu-trigger rel-icon {\n      opacity: 0.6;\n    }\n\n    .submenu-panel {\n      position: fixed;\n      min-width: 200px;\n      background: var(--rel-bg-surface);\n      border: var(--rel-stroke-sm) solid var(--rel-border-default);\n      border-radius: var(--rel-border-radius-sm);\n      box-shadow: var(--rel-shadows-shadow-300);\n      padding: 0;\n      overflow: hidden;\n      z-index: 1001;\n      display: none;\n    }\n\n    .submenu-panel.open {\n      display: block;\n    }\n\n    .menu-shortcut {\n      opacity: 0.6;\n      margin-left: auto;\n      display: flex;\n      align-items: center;\n      gap: var(--rel-spacing-3xs);\n      font-family: var(--rel-body-xs-regular-font-family);\n      font-weight: var(--rel-body-xs-regular-font-weight);\n      font-size: var(--rel-body-xs-regular-font-size);\n      line-height: var(--rel-body-xs-regular-line-height);\n      letter-spacing: var(--rel-body-xs-regular-letter-spacing);\n    }\n\n    .menubar-panel rel-checkbox {\n      display: block;\n      width: 100%;\n      padding: var(--rel-spacing-xs, 8px) var(--rel-spacing-md, 16px);\n      box-sizing: border-box;\n      cursor: pointer;\n    }\n  ";
+    static readonly _css = "\n    /* This component renders into LIGHT DOM (createRenderRoot returns this), so\n       :host / <slot> don't work here \u2014 the raw <rel-menubar-menu> definitions\n       are data holders that must be hidden with a plain selector. Relying on the\n       global rel-menubar-menu.css is not enough: it can't cross a consumer's\n       shadow boundary AND it's a no-op in the tsup-built package (css:\"copy\"). */\n    rel-menubar {\n      color: var(--rel-text-default);\n      display: block;\n      /* Figma Menu Bar / .Menu Bar Item (8699:4, 8698:13) label = body/lg.\n         Declared on the host, not on .menubar-container, so the position:fixed\n         panels \u2014 siblings of the container, not descendants \u2014 inherit it too. */\n      font-family: var(--rel-body-lg-regular-font-family);\n      font-weight: var(--rel-body-lg-regular-font-weight);\n      font-size: var(--rel-body-lg-regular-font-size);\n      line-height: var(--rel-body-lg-regular-line-height);\n      letter-spacing: var(--rel-body-lg-regular-letter-spacing);\n    }\n\n    rel-menubar-menu {\n      display: none;\n    }\n\n    /* Figma Menu Bar (8699:4): bg/fill/neutral/default on border-radius/sm,\n       clipping its children, gap spacing/none \u2014 no border and no shadow. */\n    .menubar-container {\n      display: flex;\n      align-items: stretch;\n      background: var(--rel-bg-neutral);\n      border-radius: var(--rel-border-radius-sm);\n      overflow: hidden;\n      padding: 0;\n      gap: 0;\n      min-height: 40px;\n      width: fit-content;\n    }\n\n    /* Type=Fit hugs its triggers (the default); Type=Fixed spans its container.\n       Light-DOM component: :host never matches, so these key off the reflected\n       attribute on the <rel-menubar> element itself. */\n    rel-menubar[type=\"fixed\"] .menubar-container {\n      width: var(--rel-menubar-width, 100%);\n    }\n\n    rel-menubar[type=\"fit\"] .menubar-container {\n      width: fit-content;\n    }\n\n    /* Figma .Menu Bar Item (8698:13): spacing/xs vertical + spacing/md\n       horizontal padding around a body/lg label = a 40px trigger. */\n    .menubar-trigger {\n      display: flex;\n      align-items: center;\n      justify-content: center;\n      align-self: stretch;\n      padding: var(--rel-spacing-xs) var(--rel-spacing-md);\n      background: transparent;\n      border: none;\n      cursor: pointer;\n      font: inherit;\n      color: var(--rel-text-default);\n      white-space: nowrap;\n      transition: background 0.15s ease;\n      user-select: none;\n      outline: none;\n    }\n\n    /* State=Hover / State=Pressed / State=Active / State=Disabled. Active (the\n       trigger whose menu is open) is the hover overlay plus a medium label \u2014\n       hence the .open class rather than .active, which would collide with the\n       :active pressed pseudo at equal specificity. */\n    .menubar-trigger:hover:not(.disabled) {\n      background: var(--rel-action-overlay-hover);\n    }\n\n    .menubar-trigger:active:not(.disabled) {\n      background: var(--rel-action-overlay-pressed);\n    }\n\n    .menubar-trigger.open:not(.disabled) {\n      background: var(--rel-action-overlay-hover);\n      font-weight: var(--rel-body-lg-medium-font-weight);\n    }\n\n    .menubar-trigger.disabled {\n      color: var(--rel-text-disabled);\n      background: transparent;\n      cursor: not-allowed;\n    }\n\n    /* Inset ring: the container clips (overflow:hidden), so a positive\n       outline-offset would be cut off on the first and last trigger. */\n    .menubar-trigger:focus-visible {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: -2px;\n    }\n\n    /* Figma pairs the Menu Bar with the Menu component (6326:2932) for the\n       panel each trigger opens: 300px, bg/fill/neutral/default, border\n       radius/sm, shadow/md, clipped \u2014 no border. */\n    .menubar-panel,\n    .submenu-panel {\n      position: fixed;\n      width: var(--rel-menubar-panel-width, 300px);\n      box-sizing: border-box;\n      background: var(--rel-bg-neutral);\n      border-radius: var(--rel-border-radius-sm);\n      box-shadow: var(--rel-shadows-md);\n      padding: 0;\n      overflow: hidden;\n      display: none;\n      outline: none;\n    }\n\n    .menubar-panel {\n      z-index: 1000;\n    }\n\n    .submenu-panel {\n      z-index: 1001;\n    }\n\n    .menubar-panel.open,\n    .submenu-panel.open {\n      display: block;\n    }\n\n    /* Rows follow Figma .Menu Item Large (6326:616): spacing/sm padding all\n       round on a body/lg label = 48px, with a border/neutral/subtle rule\n       between rows. The rule is an INSET shadow, not a border: Figma strokes\n       are drawn inside the 48px frame, so a real border-bottom would push\n       every row to 49px. */\n    .menu-item {\n      position: relative;\n      display: flex;\n      align-items: center;\n      gap: var(--rel-spacing-md);\n      padding: var(--rel-spacing-sm);\n      min-height: 48px;\n      box-sizing: border-box;\n      box-shadow: inset 0 calc(-1 * var(--rel-stroke-sm)) 0 var(--rel-border-subtle);\n      cursor: pointer;\n      transition: background 0.15s ease;\n      user-select: none;\n      color: var(--rel-text-default);\n      line-height: var(--rel-body-lg-regular-line-height);\n    }\n\n    .menu-label {\n      flex: 1 1 auto;\n    }\n\n    .menu-item:hover,\n    .menu-item.focused {\n      background: var(--rel-action-overlay-hover);\n    }\n\n    .menu-item:active {\n      background: var(--rel-action-overlay-pressed);\n    }\n\n    .menu-item[data-disabled=\"true\"] {\n      opacity: 0.4;\n      cursor: not-allowed;\n    }\n\n    .menu-separator {\n      height: var(--rel-stroke-sm);\n      background: var(--rel-border-default);\n      margin: 0;\n      padding: 0;\n    }\n\n    /* An explicit data-separator replaces the preceding row's subtle rule\n       instead of stacking a second line on top of it. */\n    .menu-item:has(+ .menu-separator),\n    .menubar-panel > rel-checkbox:has(+ .menu-separator),\n    .menubar-panel > rel-radio:has(+ .menu-separator) {\n      box-shadow: none;\n    }\n\n    rel-icon {\n      display: inline-flex;\n      pointer-events: none;\n    }\n\n    .menu-submenu-trigger {\n      position: relative;\n    }\n\n    /* Figma draws the 20px chevron at full contrast \u2014 no dimming. */\n    .submenu-chevron {\n      margin-left: auto;\n      display: inline-flex;\n      align-items: center;\n      pointer-events: none;\n    }\n\n    .menu-shortcut {\n      margin-left: auto;\n      padding-left: var(--rel-spacing-md);\n      display: flex;\n      align-items: center;\n      gap: var(--rel-spacing-3xs);\n      color: var(--rel-text-caption);\n      font-family: var(--rel-body-sm-regular-font-family);\n      font-weight: var(--rel-body-sm-regular-font-weight);\n      font-size: var(--rel-body-sm-regular-font-size);\n      line-height: var(--rel-body-sm-regular-line-height);\n      letter-spacing: var(--rel-body-sm-regular-letter-spacing);\n    }\n\n    /* Checkbox / radio rows are real rel-checkbox / rel-radio elements rendered\n       straight into the panel, so they carry the .Menu Item row box themselves. */\n    .menubar-panel > rel-checkbox,\n    .menubar-panel > rel-radio {\n      display: block;\n      width: 100%;\n      min-height: 48px;\n      padding: var(--rel-spacing-sm);\n      box-sizing: border-box;\n      box-shadow: inset 0 calc(-1 * var(--rel-stroke-sm)) 0 var(--rel-border-subtle);\n    }\n\n    .menubar-panel > rel-checkbox {\n      cursor: pointer;\n      transition: background 0.15s ease;\n    }\n\n    .menubar-panel > rel-checkbox:hover {\n      background: var(--rel-action-overlay-hover);\n    }\n  ";
     createRenderRoot(): this;
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -1099,6 +1939,8 @@ declare class RelMenubar extends LitElement {
      *  openMenuIndex to -1, which used to drop focus to <body>.) */
     private closeAllMenusAndRefocusTrigger;
     private openMenu;
+    /** A disabled <rel-menubar-menu> keeps its trigger focusable but never opens. */
+    private isMenuDisabled;
     private handleTriggerClick;
     private handleTriggerMouseEnter;
     private handleTriggerKeyDown;
@@ -1118,276 +1960,94 @@ declare class RelMenubar extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
-declare class RelMenubarMenu extends LitElement {
-    label: string;
-    createRenderRoot(): this;
-    render(): lit_html.TemplateResult<1>;
-}
-
-/**
- * @deprecated rel-navbar is deprecated and will be removed in a future release.
- * Use rel-topbar and its sub-components instead:
- * rel-topbar, rel-topbar-brand, rel-topbar-actions, rel-topbar-utilities,
- * rel-topbar-item, rel-topbar-dropdown, rel-topbar-dropdown-item
- */
-declare class RelNavbar extends LitElement {
-    constructor();
-    sticky: boolean;
-    device: "desktop" | "tablet" | "mobile";
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-
 /**
- * @deprecated Part of the deprecated rel-topbar family. Use a plain
- * `<a>`/logo markup inside the "Navbar" recipe at /docs/recipes/navbar.
+ * Declarative menu definition for `<rel-menubar>`: a hidden (`display: none`) light-DOM holder whose children (`data-item`, `data-separator`, `data-submenu`, `data-checkbox`, `data-radio-group`) the parent menubar reads and renders into a dropdown panel.
  */
-declare class RelTopbarBrand extends LitElement {
-    src: string;
-    href: string;
+declare class RelMenubarMenu extends LitElement {
+    /** Text of the trigger button the parent menubar renders for this menu. */
     label: string;
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-brand": RelTopbarBrand;
-    }
-}
-
-/**
- * @deprecated Part of the deprecated rel-topbar family. Use plain
- * `rel-button` elements inside the "Navbar" recipe at /docs/recipes/navbar.
- */
-declare class RelTopbarActions extends LitElement {
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-actions": RelTopbarActions;
-    }
-}
-
-/**
- * @deprecated Part of the deprecated rel-topbar family. Use plain
- * `rel-button` (icon variant) elements inside the "Navbar" recipe at /docs/recipes/navbar.
- */
-declare class RelTopbarUtilities extends LitElement {
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-utilities": RelTopbarUtilities;
-    }
-}
-
-/**
- * @deprecated Part of the deprecated rel-topbar family. Use `rel-drawer`
- * for the mobile nav panel in the "Navbar" recipe at /docs/recipes/navbar.
- */
-declare class RelTopbarMobilePanel extends LitElement {
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-mobile-panel": RelTopbarMobilePanel;
-    }
-}
-
-/**
- * @deprecated Part of the deprecated rel-topbar family. Use `rel-menu` or
- * `rel-popover` for nav dropdowns in the "Navbar" recipe at /docs/recipes/navbar.
- */
-declare class RelTopbarDropdown extends LitElement {
-    static styles: lit.CSSResult;
+    /**
+     * Renders this menu's trigger in the Figma State=Disabled style and stops it
+     * opening by pointer, keyboard or hover-switch. The trigger stays in the tab
+     * order and reachable with the arrow keys (`aria-disabled`, not the native
+     * `disabled` attribute), matching how disabled `data-item` rows behave.
+     */
+    disabled: boolean;
+    createRenderRoot(): this;
     render(): lit_html.TemplateResult<1>;
 }
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-dropdown": RelTopbarDropdown;
-    }
-}
 
+/** What the cells accept — digits only, or digits + ASCII letters. */
+type OtpInputMode = "numeric" | "alphanumeric";
+/** @deprecated Use `OtpInputMode`. */
+type OtpType = OtpInputMode;
 /**
- * @deprecated Part of the deprecated rel-topbar family. Use `rel-menu`'s
- * item slots or `rel-popover` content in the "Navbar" recipe at /docs/recipes/navbar.
+ * Cell scale. Canonical values are the full words (shared field scale:
+ * small 32 / medium 40 / large 48); `sm` / `md` / `lg` are the original
+ * names and keep working as aliases.
  */
-declare class RelTopbarDropdownItem extends LitElement {
-    label: string;
-    href: string;
-    active: boolean;
-    static styles: lit.CSSResult;
-    private _handleClick;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-dropdown-item": RelTopbarDropdownItem;
-    }
-}
-
-type TopbarVariant = "customer" | "carrier";
-type TopbarForceLayout = "auto" | "desktop" | "tablet" | "mobile";
-/**
- * `rel-topbar` — Application-level top navigation / header shell.
- *
- * @deprecated This component's fixed slot structure, hardcoded breakpoint,
- * and built-in overflow logic are too rigid for most real layouts. Use the
- * "Navbar" recipe at /docs/recipes/navbar instead, composed from
- * rel-menu/rel-popover, rel-drawer, and rel-button. Still supported, but
- * will be removed in a future major version.
- *
- * Slots:
- *   brand        — Logo / wordmark region (left)
- *   (default)    — Primary nav items (rel-topbar-item elements)
- *   actions      — CTA / action buttons (customer) or dark-pill area (carrier)
- *   utilities    — Utility icon buttons (notifications, search, etc.)
- *   profile      — rel-topbar-profile tile
- *   mobile-panel — Collapsed nav panel shown when mobileOpen is true
- *
- * Events:
- *   rel-menu-toggle        — fired when hamburger is clicked  { open: boolean }
- *   rel-mobile-open-change — alias of rel-menu-toggle for convenience
- *   rel-nav-select         — bubbled from child rel-topbar-item  { value, label }
- */
-declare class RelTopbar extends LitElement {
-    /** Visual variant — affects action/profile region styling */
-    variant: TopbarVariant;
-    /** Whether the mobile nav panel is currently open */
-    mobileOpen: boolean;
-    /** Whether to render the hamburger / close toggle button */
-    showMenuToggle: boolean;
-    /** Reduce height to compact (48 px) mode */
-    compact: boolean;
-    /** Stick topbar to top of viewport while scrolling */
-    sticky: boolean;
-    /**
-     * Override the responsive layout for demos / storybook.
-     * 'auto' respects CSS media queries.
-     */
-    forceLayout: TopbarForceLayout;
-    private _overflowItems;
-    private _overflowCount;
-    private _overflowItemsData;
-    private _resizeObserver?;
-    private _resizeTimer?;
-    private _measuring;
-    private _lastNavWidth;
-    static styles: lit.CSSResult;
-    firstUpdated(): void;
-    disconnectedCallback(): void;
-    private _measureNav;
-    private onRouterSlotChange;
-    private get layoutClass();
-    private handleMenuToggle;
-    render(): lit_html.TemplateResult<1>;
-}
-
+type OtpSize = "small" | "medium" | "large" | "sm" | "md" | "lg";
 /**
- * `rel-topbar-item` — A navigation item within rel-topbar.
- *
- * @deprecated Part of the deprecated rel-topbar family. Use the "Navbar" recipe at /docs/recipes/navbar, which composes nav links and
- * `rel-menu`/`rel-popover` dropdowns directly instead of a dedicated item component.
- *
- * Renders as an `<a>` when `href` is supplied, otherwise a `<button>`.
- *
- * Slots:
- *   (default)  — Label text / icon (overrides `label` property)
- *   prefix     — Icon/content before the label
- *   suffix     — Icon/content after the label (e.g. badge)
- *   dropdown   — Expandable panel content shown below the item
- *
- * Events:
- *   rel-select — fired when a non-disabled, non-expandable item is activated
- *   rel-toggle — fired when an expandable item is opened/closed  { open: boolean }
+ * One-time-password input (Figma "OTP Input"): one single-character cell per position, with auto-advance, smart backspace, paste distribution and optional group separators.
+ * @csspart base - The `role="group"` root container (same element as `root`)
+ * @csspart root - Alias of `base`, kept for existing `::part(root)` selectors
+ * @csspart input - Each single-character cell input (same element as `cell`)
+ * @csspart cell - Alias of `input`, kept for existing `::part(cell)` selectors
+ * @csspart separator - The dash rendered between cell groups
+ * @csspart hidden-input - The hidden form input rendered when `name` is set
  */
-declare class RelTopbarItem extends LitElement {
-    /** Accessible label — also shown as text when no default slot content */
-    label?: string;
-    /** Navigation href — renders an anchor element when set */
-    href?: string;
-    /** Marks this item as the current/active page */
-    active: boolean;
-    /** Prevents interaction */
-    disabled: boolean;
-    /** Shows a chevron and enables dropdown panel */
-    expandable: boolean;
-    /** Controlled open state of the dropdown panel */
-    open: boolean;
-    /** Optional string value forwarded in rel-select / rel-toggle events */
-    value?: string;
-    /** @internal tracks whether dropdown slot has content */
-    private _hasDropdown;
-    static styles: lit.CSSResult;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    private _handleOutsideClick;
-    private _handleDocKeydown;
-    private _setOpen;
-    private _handleTriggerClick;
-    private _routeSlots;
-    private _handleDropdownSlotChange;
-    render(): lit_html.TemplateResult<1>;
-}
-
-type TopbarProfileType = "avatar" | "carrier";
-type TopbarRewardTier = "gold" | "silver" | "platinum" | "bronze" | "regular";
-/**
- * `rel-topbar-profile` — Profile / user tile for the topbar right region.
- *
- * @deprecated Part of the deprecated rel-topbar family. Compose `rel-avatar`
- * directly inside the "Navbar" recipe at /docs/recipes/navbar.
- *
- * type="avatar"   Customer avatar with initials circle + optional name/subtitle.
- * type="carrier"  Carrier reward tile with reward-tier badge + name/subtitle.
- */
-declare class RelTopbarProfile extends LitElement {
-    /** Visual mode */
-    type: TopbarProfileType;
-    /** One or two initials shown in the avatar circle */
-    initials?: string;
-    /** Primary display name */
-    name?: string;
-    /** Secondary line (role, plan, etc.) */
-    subtitle?: string;
-    /** Reward tier — only meaningful when type="carrier" */
-    reward: TopbarRewardTier;
-    /** Compact mode — avatar only, no text */
-    compact: boolean;
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-    private _renderAvatar;
-    private _avatarBg;
-    private _renderCarrier;
-}
-
-type OtpType = "numeric" | "alphanumeric";
 declare class RelOtp extends LitElement {
+    /** The concatenated code (all cells joined). Set it to fill the cells programmatically; it never exceeds `length` characters. */
     value: string;
+    /** Total number of cells (characters in the code). */
     length: number;
+    /** Cells per visual group; a separator renders between groups. Grouping applies only when `length` divides evenly by this — otherwise the row renders ungrouped, because a ragged final group would put a separator before a lone cell. So the default `length="6"` is 3–3, `length="4"` is one ungrouped row of four, and `group-size="2"` with `length="4"` is 2–2. `0` (or `show-separator` off) also renders one ungrouped row. */
     groupSize: number;
+    /** Placeholder character shown in every empty cell. */
     placeholder: string;
+    /**
+     * Accepted character set (Trello 5). Describes what the field ACCEPTS, not
+     * a semantic input type — hence the name. Explicitly set it wins over the
+     * deprecated `type`; unset (`""`, like the native `inputMode` accessor it
+     * shadows on the host), `type` (default `"numeric"`) applies. Note the
+     * lowercase `inputmode` prop is a different thing: the raw native keyboard
+     * hint forwarded to each cell.
+     */
+    inputMode: OtpInputMode | "";
+    /** @deprecated Deprecated alias of `inputMode` (attribute `input-mode`); use `input-mode` instead. Kept working in 1.x and logs a one-time console notice. */
     type: OtpType;
+    /** Renders the cells as `type="password"` so entered characters are masked. */
     mask: boolean;
+    /** Disables every cell and dims the control to 0.4 opacity (cell fill and border unchanged, as Figma specifies). */
     disabled: boolean;
+    /** Makes every cell read-only: the value is shown but typing, paste and keyboard editing are ignored. */
     readonly: boolean;
+    /** Marks the first cell `required` for native form validation. */
     required: boolean;
+    /** When set, renders a hidden `<input name="…">` (part `hidden-input`) carrying `value` for native form submission. */
     name: string | null;
+    /** Reserved autocomplete hint. Currently every cell always renders `autocomplete="one-time-code"` regardless of this value. */
     autocomplete: string;
+    /** Raw native `inputmode` keyboard hint forwarded to every cell. Unset, it follows the accepted character set: `numeric` for numeric, `text` for alphanumeric. */
     inputmode: "numeric" | "text" | null;
+    /** Native `pattern` attribute forwarded to every cell (per-character regex for form validation). */
     pattern: string | null;
+    /** Accessible name of the whole group; defaults to "One-time password input". Each cell is additionally labelled "Digit/Character N of M". */
     ariaLabel: string | null;
+    /** Error styling (danger border on every cell) and `aria-invalid="true"`. */
     invalid: boolean;
+    /** Renders the dash separator between groups. Boolean attribute: its presence means true — set the property to `false` to hide separators. Even when on, separators appear only if `length` divides evenly by `group-size`; see `groupSize`. */
     showSeparator: boolean;
-    size: "sm" | "md" | "lg";
+    /** Cell size on the shared field scale (square, border-box): `small` 32px, `medium` 40px, `large` 48px (the Figma OTP Input cell). `sm` / `md` / `lg` are deprecated aliases of the full words. */
+    size: OtpSize;
     private cells;
     private hiddenInput?;
     private isUpdatingFromValue;
+    /** inputMode supersedes the deprecated type. */
+    private get mode();
     static styles: lit.CSSResult;
     connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
     updated(changedProperties: Map<string, any>): void;
     private initializeCells;
     private syncCellsFromValue;
@@ -1403,6 +2063,9 @@ declare class RelOtp extends LitElement {
     private handleFocus;
     private handleBlur;
     private focusCell;
+    /** Native `inputmode` hint for the cells (mobile keyboard). The lowercase
+     *  `inputmode` prop is a raw passthrough and wins; otherwise it follows
+     *  the accepted character set. */
     private getInputMode;
     private getAriaLabel;
     private getGroups;
@@ -1414,23 +2077,40 @@ declare global {
     }
 }
 
+/**
+ * Page navigation (Figma "Pagination"): prev/next ghost buttons with numbered pages, a compact "Page X of Y" readout, or a "1–10 of 50" item-range readout. Use it under tables and lists that load one page of results at a time; it never fetches data itself — listen for `rel-change`.
+ * @csspart base - The `role="navigation"` root of the extended layout (page buttons plus the optional "Viewing page" label).
+ * @csspart label - The `role="navigation"` root row of the count-text layout (item-range text plus prev/next nav).
+ */
 declare class RelPagination extends LitElement {
-    /** Layout type from Figma: extended (numbered pages), compact (prev/next + page text), count-text (range + nav) */
+    /** Figma "Type": `extended` = prev/next + numbered page buttons (auto-collapses to compact under 480px container width), `compact` = prev/next + "Page X of Y", `count-text` = "start–end of total" item range + prev/next around the current page number. */
     type: "extended" | "compact" | "count-text";
-    /** Controlled current page */
+    /** Controlled current page (1-based). When set, the element only emits `rel-change` and waits for the parent to update `page`; leave unset for uncontrolled behaviour. */
     page?: number;
-    /** Uncontrolled starting page */
+    /** Starting page for uncontrolled use (ignored when `page` is set). Attribute `defaultPage`, also read once as `default-page` on connect. */
     defaultPage: number;
-    /** Total number of pages */
+    /** Total number of pages. `0` (the default) lets `totalItems` / `perPage` compute the page count instead. Attribute `totalPages`, also read once as `total-pages` on connect. */
     totalPages: number;
-    /** Total items (used with perPage to auto-compute totalPages in count-text mode) */
+    /** Total item count; with `perPage` it computes the page count when `totalPages` is `0` and is the "of N" figure in the count-text readout. Attribute `totalItems`, also read once as `total-items` on connect. */
     totalItems: number;
-    /** Items per page (count-text mode) */
+    /** Items per page, used to compute the page count from `totalItems` and the "start–end" range in the count-text readout. Attribute `perPage`, also read once as `per-page` on connect. */
     perPage: number;
-    /** Show "Viewing page X of Y" label below extended pagination */
+    /** Shows a "Viewing page X of Y" caption under the extended layout (ignored by the other types). */
+    /**
+     * DELIBERATE DIVERGENCE — do not flip this default to `true`. Figma's
+     * `Type=Extended` has no boolean for the caption: the "Viewing page 1 of 10"
+     * text is a fixed child of both Extended variants and is load-bearing for
+     * their 78px height (40 + spacing-md + 22). Here it stays opt-in. Ruled by
+     * the user: our behaviour stands and the DESIGN FILE follows our docs.
+     * Defaulting it on would silently add 38px to every existing extended
+     * pagination.
+     */
     showLabel: boolean;
+    /** Dims the whole control to 40% opacity, shows a `not-allowed` cursor and ignores every page change. */
     disabled: boolean;
+    /** Reserved for link-mode pagination. Currently accepted but not rendered: every page control is a `<button>`, so navigate in your `rel-change` handler instead. */
     hrefTemplate: string;
+    /** Accessible name of the `role="navigation"` landmark (attribute `ariaLabel`). Set it when a page contains more than one pagination control. */
     ariaLabel: string;
     private currentPage;
     static styles: lit.CSSResult;
@@ -1454,17 +2134,50 @@ declare class RelPagination extends LitElement {
 
 type SideType = "top" | "right" | "bottom" | "left";
 type AlignType = "start" | "center" | "end";
+/**
+ * Click-to-open floating panel anchored to a trigger (Figma "Popover"): the first child is the trigger, the `content` slot is the panel, which is promoted to the browser top layer and positioned in viewport coordinates.
+ * @slot - The trigger: the first slotted element toggles the panel on pointer down / Enter / Space and receives `aria-haspopup`, `aria-expanded` and `aria-controls` (a bare `<div>` / `<span>` also gets `tabindex="0"` and `role="button"`).
+ * @slot content - The panel body, usually a `<rel-popover-content>`; rendered inside the fixed, top-layer wrapper only while open.
+ * @csspart arrow - The 14×14 chevron box rendered on the panel edge facing the trigger when `arrow` is set (absent otherwise).
+ * @cssprop --rel-popover-arrow-bg - Fill of the `arrow` chevron (default `--rel-bg-neutral`, matching `<rel-popover-content>`).
+ * @cssprop --rel-popover-arrow-border - **Deprecated.** Stroke of the `arrow` chevron's two slanted edges. The panel no longer draws a border — overlapping surfaces are separated by shadow — so this defaults to `transparent` and the chevron has no edge. Set it to restore a stroke.
+ */
 declare class RelPopover extends LitElement {
+    /** Controlled open state. Leave unset for uncontrolled mode; once set (true or false) the component only emits `rel-open-change` and you must update `open` yourself. */
     open?: boolean;
+    /** Initial state in uncontrolled mode (attribute `defaultopen`); ignored when `open` is set. */
     defaultOpen: boolean;
+    /** Blocks trigger interaction and dims the host to 60% opacity; does not close an already-open panel. */
     disabled: boolean;
+    /** Which side of the trigger the panel opens on: `top`, `right`, `bottom` (default) or `left`. The panel is clamped 8px inside the viewport but never flips to another side. */
     side: SideType;
+    /** Alignment along the cross axis: `start` (left / top edge of the trigger), `center` (default) or `end` (right / bottom edge). */
     align: AlignType;
+    /** Gap between trigger and panel in pixels (attribute `sideoffset`, default 8). With `arrow` the effective gap is at least 13px. */
     sideOffset: number;
+    /** Extra shift along the alignment axis in pixels (attribute `alignoffset`, default 0); positive moves right / down. */
     alignOffset: number;
+    /** Keep Tab / Shift+Tab cycling inside the panel while open (attribute `trapfocus`); use for forms. */
     trapFocus: boolean;
+    /** Close on Escape (attribute `closeonescape`, default true; switch off via the property, e.g. `el.closeOnEscape = false`). */
     closeOnEscape: boolean;
+    /** Close on a pointer-down outside the trigger and panel (attribute `closeonoutsideclick`, default true; switch off via the property). Also lets another popover's opening dismiss this one. */
     closeOnOutsideClick: boolean;
+    /**
+     * Opt-in pointer (audit 23a): a 14×11 triangle on the panel edge that faces
+     * the trigger — the Figma Popover "Chevron" — following `side` and tracking
+     * the trigger's centre along the cross axis (clamped inside the panel).
+     * It is drawn with the panel's tokens (`--rel-popover-arrow-bg` /
+     * `--rel-popover-arrow-border`, defaulting to rel-popover-content's
+     * background and border). With the arrow on, the panel keeps at least the
+     * arrow's height plus 2px away from the trigger so the tip never overlaps
+     * it; larger `sideOffset` values still apply. Default off — existing
+     * popovers render exactly as before.
+     */
+    arrow: boolean;
+    /** Figma Popover (6338:563) chevron: 14 wide × 11 tall. */
+    private static readonly ARROW_WIDTH;
+    private static readonly ARROW_HEIGHT;
     private internalOpen;
     private contentStyle;
     private contentWrapper;
@@ -1513,18 +2226,41 @@ declare global {
     }
 }
 
+/** Figma Size axis, spelled out. */
+type PopoverContentSize = "small" | "medium" | "large";
+/** Alternative spellings, not deprecations — the short names keep working. */
+type PopoverContentSizeAlias = "sm" | "md" | "lg";
+type PopoverContentSizeInput = PopoverContentSize | PopoverContentSizeAlias;
+/**
+ * Styled panel body for `<rel-popover>` (Figma "Popover" surface): neutral background, 1px border, 8px radius, shadow-300, max-width 400px, with heading / paragraph typography for slotted content. Place it in the popover's `content` slot; any other element works there too.
+ * @slot - The panel content (headings, paragraphs, form controls, buttons).
+ * @csspart content - The padded `role="dialog"` box that carries the surface, border, shadow and size padding.
+ */
 declare class RelPopoverContent extends LitElement {
+    /** Accessible name applied to the inner `role="dialog"` box (attribute `aria-label`); describe what the panel is for. */
     ariaLabel: string;
-    /** Figma Size axis (S/M/L): panel padding 12/16/20px. */
-    size: "sm" | "md" | "lg";
+    /** Figma Size axis: panel padding 12px (`small`), 16px (`medium`, default) or 20px (`large`). `sm` / `md` / `lg` are alternative spellings and stay supported — they are normalised to the full words, not deprecated. */
+    size: PopoverContentSizeInput;
+    /** Alternative spellings, NOT deprecations — no console notice. Normalising
+     *  keeps the reflected attribute canonical, so the :host([size=…]) rules only
+     *  need the full words. */
+    protected willUpdate(changed: Map<string, unknown>): void;
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
 }
 
 type ProgressMode = "linear-determinate" | "linear-indeterminate" | "circular-determinate" | "circular-indeterminate";
+/**
+ * Progress indicator (Figma "Progress"): a linear bar or a circular ring, each either value-driven (determinate) or looping (indeterminate).
+ * @csspart track - The linear track `<div>` that carries `role="progressbar"` (linear modes only)
+ * @csspart indicator - The filled / sliding bar inside the linear track (linear modes only)
+ */
 declare class RelProgress extends LitElement {
+    /** Shape and behaviour: `linear-*` is a full-width 2px bar, `circular-*` a 36px ring; `*-determinate` fills to `value`, `*-indeterminate` loops an animation and ignores `value`. */
     mode: ProgressMode;
+    /** Completion percentage 0–100 for the determinate modes; out-of-range values are clamped before rendering and before `aria-valuenow`. */
     value: number;
+    /** Accessible name of the progressbar (not rendered visually); defaults to "Progress" for determinate and "Loading" for indeterminate modes. */
     label: string;
     private radius;
     private circumference;
@@ -1538,7 +2274,14 @@ declare class RelProgress extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Flex container that lays out direct-child `<rel-resizable-panel>`s along one axis and lets the user drag or keyboard-nudge the `<rel-resizable-handle>` between two neighbours to trade percentage width/height between them.
+ * @slot - The panels and handles, as direct children in display order (panel, handle, panel, …)
+ * @fires rel-resize - Fired continuously while a handle is dragged. Detail: `{ direction, sizes: number[] }` with one percentage per panel.
+ * @fires rel-resize-end - Fired once when a drag ends (pointerup) and after every keyboard resize step. Detail: `{ direction, sizes: number[] }` with one percentage per panel.
+ */
 declare class RelResizableGroup extends LitElement {
+    /** Layout axis: `horizontal` places panels side by side and resizes widths, `vertical` stacks them and resizes heights; also pushed to every child handle's `orientation`. */
     direction: "horizontal" | "vertical";
     private panels;
     private handles;
@@ -1571,11 +2314,18 @@ declare global {
     }
 }
 
+/**
+ * One resizable region inside a `<rel-resizable-group>`: a padded, scrollable (`overflow: auto`) flex column whose size along the group axis is a percentage managed by the group.
+ * @slot - The panel's content; slotted `h1`–`h4` get the headings-md role
+ */
 declare class RelResizablePanel extends LitElement {
+    /** Initial size as a percentage of the group; panels without one share whatever is left of 100%, then all sizes are normalised to sum to 100. Attribute is `defaultsize`. */
     defaultSize?: number;
+    /** Smallest size (percentage) the panel can be resized to. Attribute is `minsize`. */
     minSize: number;
+    /** Largest size (percentage) the panel can be resized to. Attribute is `maxsize`. */
     maxSize: number;
-    /** Current computed size in percentage */
+    /** Current size as a percentage of the group (also written to the host's `flex-basis`); read-only — the parent group updates it on every resize. */
     currentSize: number;
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
@@ -1586,16 +2336,21 @@ declare global {
     }
 }
 
+/**
+ * Focusable `role="separator"` splitter placed between two `<rel-resizable-panel>`s inside a `<rel-resizable-group>`; the group owns the drag and keyboard logic, the handle only renders the grab bar and exposes the split via ARIA.
+ */
 declare class RelResizableHandle extends LitElement {
+    /** Axis the handle separates: `horizontal` = 8px-wide vertical bar with `col-resize` cursor, `vertical` = 8px-tall bar with `row-resize`; set automatically from the parent group's `direction` on first render and mirrored to `aria-orientation`. */
     orientation: "horizontal" | "vertical";
-    /** Index of this handle in the parent group */
+    /** @internal Index of this handle in the parent group; assigned by the group on first render. */
     handleIndex: number;
-    /** Current split value (0-100) for aria-valuenow */
+    /** Current split of the two neighbouring panels as a percentage 0–100 (share held by the leading panel); read-only — the parent group updates it and mirrors it to `aria-valuenow`. */
     splitValue: number;
     static styles: lit.CSSResult;
     connectedCallback(): void;
     updated(changed: Map<string, unknown>): void;
     private updateAriaOrientation;
+    /** @internal Called by the parent group after every resize to store `splitValue` and write `aria-valuenow` / `aria-valuemin` / `aria-valuemax`. */
     updateAriaValue(value: number): void;
     render(): lit_html.TemplateResult<1>;
 }
@@ -1605,17 +2360,38 @@ declare global {
     }
 }
 
-type SegmentSize = "small" | "medium";
+type SegmentSize = "small" | "medium" | "large";
 type SegmentAlign = "left" | "middle" | "right";
 interface SegmentOption {
     label: string;
     value: string;
     disabled?: boolean;
+    /** `rel-icon` name rendered before the label (Figma "Left Icon"), sized 16 / 18 / 20 with the control. */
+    icon?: string;
+    /**
+     * Trailing badge (Figma "Show Badge" / "Badge"), rendered after the label
+     * inside the segment's own 8px gap. A number or string shows the count at
+     * `medium` and `large`; at `small` Figma switches to the 6px dot, so the
+     * value is not displayed there. Use `true` for a dot at any size.
+     */
+    badge?: number | string | boolean;
 }
+/**
+ * Single-select segmented button group: renders one `<button role="radio">` per entry in `options` on a 2px-inset track (`role="radiogroup"`), with exactly one segment active at a time.
+ * @csspart base - The `role="radiogroup"` track that lays out the segments.
+ * @csspart option - Each segment's native `<button role="radio">`; the active one carries the `active` class and `aria-checked="true"`.
+ * @csspart icon - A segment's optional leading `rel-icon` element.
+ * @csspart badge - A segment's optional trailing `rel-badge`; rendered only when the option sets `badge`.
+ * @csspart label - The wrapper around a segment's label text.
+ */
 declare class RelSegmentedButton extends LitElement {
+    /** The segments in order, each `{ label: string; value: string; disabled?: boolean; icon?: string; badge?: number | string | boolean }`. Set as a property (or a JSON array attribute); a disabled entry is rendered but cannot be selected, and `icon` names a `rel-icon` drawn before the label. */
     options: SegmentOption[];
+    /** `value` of the currently selected segment. Updated by the component on click / arrow keys; set it to pre-select a segment (an unknown value selects nothing). */
     active: string;
+    /** Control height, matching the TextField ramp: `small` (32px — 28px segments, `action-md` 12px text, 16px icons), `medium` (default, 40px — 36px segments, `action-lg` 14px text, 18px icons) or `large` (48px — 44px segments, `action-xl` 16px text, 20px icons). */
     size: SegmentSize;
+    /** `justify-content` of the group's inline-flex container: `left` (default), `middle` or `right`. Only visible when the host is made wider than its content. */
     align: SegmentAlign;
     /** Accessible name for the radiogroup (it renders no visible group label). */
     fieldAriaLabel?: string;
@@ -1625,6 +2401,13 @@ declare class RelSegmentedButton extends LitElement {
      *  one Tab stop (roving tabindex on the selected segment). */
     private onKeyDown;
     private renderSegment;
+    /**
+     * Figma's Show Badge axis: a 20x20 numeric badge at medium and large, and a
+     * 6px dot at small — where the count is not shown at all, so a numeric value
+     * degrades to a dot rather than being squeezed in. `badge: true` asks for the
+     * dot at any size.
+     */
+    private renderBadge;
     render(): lit_html.TemplateResult<1>;
 }
 
@@ -1641,8 +2424,49 @@ interface SelectOptionObject {
     icon?: string;
 }
 type SelectOption = string | SelectOptionObject;
+/**
+ * `<rel-select>` — combobox-style dropdown (Figma "Dropdown"): single- or multi-select
+ * with an optional in-panel search field and width-adaptive selection chips.
+ * @csspart label - The visible label above the trigger (default label style)
+ * @csspart trigger - The button that opens the panel; styled like a text field
+ * @csspart value - The value area inside the trigger (selected label, placeholder or chips)
+ * @csspart helper - The supporting / error text below the trigger
+ * @csspart panel - The dropdown listbox container (same node as `list`)
+ * @csspart list - Alias of `panel`
+ * @csspart input - The search input inside the panel
+ * @csspart option - A single-select option row
+ * @csspart option-label - A single-select row's first line (the option label)
+ * @csspart option-supporting-text - A single-select row's optional second line; rendered only when the option supplies `supportingText`
+ * @cssprop --rel-field-label-reserve - Height held for the label row whenever no label renders above the trigger — `labelStyle="none"`, and `labelStyle="floating"` where the label sits inside the trigger — so the trigger still lines up with labelled siblings in a form row. Defaults to that size's label line-height plus the wrapper gap (24px at `small`, 26px at `medium` and `large`). Set to `0` to collapse the row entirely (toolbars, table cells).
+ * @cssprop --rel-select-bg - Background of the trigger, the floating label, the panel and its sticky header
+ * @cssprop --rel-select-bg-disabled - Trigger background when `state="disabled"`
+ * @cssprop --rel-select-border-default - Trigger border colour at rest
+ * @cssprop --rel-select-border-disabled - Trigger border colour when `state="disabled"`
+ * @cssprop --rel-select-border-focus - Trigger border colour on hover, while focused (where it also thickens to 2px) and while the panel is open
+ * @cssprop --rel-select-border-error - Trigger border colour when `state="error"`
+ * @cssprop --rel-select-radius - Trigger corner radius when `border="rounded"`
+ * @cssprop --rel-select-icon-color - Colour of the trigger icons, the search icon and option prefix icons
+ * @cssprop --rel-select-label-color - Colour of the static label and of the floated label
+ * @cssprop --rel-select-value-color - Colour of the selected value, the search text, option labels and the check mark
+ * @cssprop --rel-select-placeholder-color - Placeholder colour (trigger, resting floating label, search field, empty-list message)
+ * @cssprop --rel-select-placeholder-disabled-color - Placeholder colour when disabled
+ * @cssprop --rel-select-supporting-color - Supporting text colour (non-error)
+ * @cssprop --rel-select-menu-border - 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.
+ * @cssprop --rel-select-menu-radius - Panel corner radius
+ * @cssprop --rel-select-menu-shadow - Panel box-shadow
+ * @cssprop --rel-select-search-border - Border colour of the search field inside the panel
+ * @cssprop --rel-select-divider - Hairline under the search field, the Select-all row and every option row
+ * @cssprop --rel-select-option-hover - Background of the hovered / keyboard-highlighted / selected option and Select-all row
+ * @cssprop --rel-select-option-pressed - Background of an option row while it is being pressed
+ */
 declare class RelSelect extends LitElement {
+    /** Visible label. Rendered above the trigger (`labelStyle="default"`) or floating inside it; omitted under `labelStyle="none"`. */
     label: string;
+    /**
+     * Label presentation: `default` static label above the trigger; `floating` label
+     * rests in the value area and floats onto the border when focused, open or filled;
+     * `none` renders no label (supply `fieldAriaLabel` / `fieldAriaLabelledby`).
+     */
     labelStyle: SelectLabelStyle;
     /**
      * Accessible name for the trigger. Required when `labelStyle="none"`, since no
@@ -1651,21 +2475,53 @@ declare class RelSelect extends LitElement {
     fieldAriaLabel?: string;
     /** IDREF list of external element(s) naming the trigger. Wins over `fieldAriaLabel`. */
     fieldAriaLabelledby?: string;
+    /**
+     * Options to list. Each entry is a plain string (used as both value and label) or
+     * `{ value, label?, supportingText?, icon? }`; `icon` is a `rel-icon` name rendered
+     * before the label, `supportingText` renders as a second line in both single- and multi-select rows.
+     *
+     * NOTE — the panel's search matches the LABEL ONLY. `supportingText` is displayed but not
+     * searched, so an option is not findable by its second line here. This differs deliberately from
+     * `rel-autocomplete`, whose filter matches the supporting line as well: there the second line
+     * carries identifying data (a DOT or MC number) that a user types to find the row, whereas a
+     * select's is descriptive ("Read-only", "Can edit, not delete") and matching it would return rows
+     * whose visible label has nothing to do with the query.
+     */
     options: SelectOption[];
-    /** Enables multi-select: selected values render as removable chips and options as checkboxes. */
+    /** Enables multi-select: selected values render as removable chips, options as checkboxes, and a Select-all row appears in the panel. */
     multiple: boolean;
-    /** Selected value — single-select mode only. */
+    /** Selected option value in single-select mode. Ignored when `multiple` is set. */
     selected: string;
-    /** Selected values — multi-select mode only. */
+    /** Selected option values in multi-select mode. Reset to `[]` when `multiple` is turned off. */
     selectedValues: string[];
+    /** Visual / interaction state. `error` colours the border and supporting text and clears itself on the next selection; `disabled` blocks interaction and dims the whole field. */
     state: SelectState;
+    /** Helper line below the trigger; coloured as an error while `state="error"`. */
     supportingText: string;
+    /**
+     * `rel-icon` name shown before the supporting text (16px, 14px at `small`).
+     * Optional: the design pairs the helper line with an icon, but existing
+     * fields without one keep their current single-line look.
+     */
+    supportingIcon: string;
+    /**
+     * Field height — `small` 32px, `medium` 40px, `large` 48px. The whole component
+     * rides this one axis: label and supporting type, trigger padding, icons
+     * (20 / 18 / 16), selection chips, and the panel's rows, search field and
+     * checkboxes all scale with it.
+     */
     size: SelectSize;
+    /** Trigger corners: `rounded` applies the corner radius, `sharp` renders square corners. */
     border: SelectBorder;
+    /** `rel-icon` name rendered at the left edge of the trigger. */
     leftIcon: string;
+    /** `rel-icon` name replacing the default chevron at the right edge of the trigger. A custom icon does not rotate when the panel opens. */
     rightIcon: string;
+    /** Text shown in the trigger while nothing is selected. */
     placeholder: string;
+    /** Placeholder of the in-panel search field (the field is hidden when `noSearch` is set). */
     searchPlaceholder: string;
+    /** Label of the Select-all row shown at the top of the panel in multi-select mode. */
     selectAllLabel: string;
     /**
      * Optional hard cap on visible chips. By default (no cap) the visible
@@ -1674,6 +2530,16 @@ declare class RelSelect extends LitElement {
      */
     maxVisibleChips: number;
     /** Hides the in-panel search field. Figma's "Single Option" dropdown has no search bar at all — use this for short, non-searchable lists. */
+    /**
+     * DELIBERATE DIVERGENCE — do not default this to `!multiple`. Figma's
+     * `.Menu Dropdown` shows the search row only on `Type=Multioption`; its
+     * `Type=Single Option` panels contain five Select Option items and nothing
+     * else. Here the search row renders for single-select too unless this is set.
+     * Ruled by the user: our behaviour stands and the DESIGN FILE follows our
+     * docs. A long single-select list is unusable without search, and making the
+     * default depend on `multiple` would change the panel of every existing
+     * single-select.
+     */
     noSearch: boolean;
     private open;
     private highlightedIndex;
@@ -1691,7 +2557,7 @@ declare class RelSelect extends LitElement {
     private listboxEl;
     private valueEl;
     private chipsMeasureEl;
-    /** Must match the `gap` of .select-chips / .select-chips-measure. */
+    /** Must match the `gap` of .select-chips / .select-chips-measure (spacing/xs). */
     private static readonly CHIP_GAP;
     private chipResizeObserver?;
     private uniqueId;
@@ -1713,10 +2579,23 @@ declare class RelSelect extends LitElement {
     /** Options matching the current search text (substring match, case-insensitive). */
     private get filteredOptions();
     private get hasValue();
-    /** Icon size scales with the select's own size, matching the trigger. */
-    private get iconSize();
-    /** The search field uses "small" sizing for both small and medium select — only "large" select bumps it to "medium". */
-    private get searchIconSize();
+    /**
+     * Selection chips ramp with the field: rel-chip's sm / md / lg are already
+     * the 24 / 28 / 32 heights the spec asks the multi-select value area for.
+     */
+    private get chipSize();
+    /**
+     * Multi-select rows nest the checkbox at the SAME step as the field. This
+     * used to shift one down, compensating for rel-checkbox sitting a size above
+     * the rest of the system — but that ramp has since been realigned to Figma
+     * (16/18/20/24 with body-sm/md/lg/xl labels), so the compensation is now the
+     * bug: it is what made a small multi-select render 14px labels where Figma
+     * asks for 12px. Figma's option content heights are 20 / 22 / 24 for
+     * small / medium / large, which is exactly body-sm / body-md / body-lg — the
+     * checkbox step of the same name. The rows still land on 32 / 40 / 48
+     * through their own padding and min-height.
+     */
+    private get optionCheckboxSize();
     private get selectAllStatus();
     private addGlobalListeners;
     private removeGlobalListeners;
@@ -1761,12 +2640,25 @@ declare global {
 
 type SkeletonShape = "line" | "circle" | "block";
 type SkeletonAnimation = "pulse" | "shimmer" | "none";
+/**
+ * Loading placeholder: a neutral block, circle or stack of text lines that pulses or shimmers while real content loads, then hides itself once `loaded` is set. Use it in place of content whose size you already know; use a spinner for indeterminate waits.
+ * @csspart base - Each placeholder surface: the single block/circle, or every bar when `shape="line"`.
+ * @cssprop --rel-skeleton-color - Fill colour of the placeholder (defaults to the elevated-3 neutral background token).
+ * @cssprop --rel-skeleton-line-height - Height of each text bar when `shape="line"`; default 16px (Figma's Line shape).
+ * @cssprop --rel-skeleton-highlight - Lighter band that sweeps across the placeholder when `animation="shimmer"` (defaults to the elevated-2 neutral background token).
+ */
 declare class RelSkeleton extends LitElement {
+    /** Placeholder shape: `block` fills the host (min 16px tall), `circle` is a square-aspect disc sized by the host width, `line` renders `lines` 16px text bars with the last one at 65% width. */
     shape: SkeletonShape;
+    /** Number of text bars when `shape="line"` (minimum 1, --rel-spacing-xs apart); ignored by the other shapes. */
     lines: number;
+    /** Any CSS width (e.g. `"240px"`, `"50%"`) applied to the host's inline style. Empty leaves the host at its natural block width. */
     width: string;
+    /** Any CSS height (e.g. `"120px"`) applied to the host's inline style. Not needed for `circle`, which derives its height from the width. */
     height: string;
+    /** Motion: `pulse` fades opacity between 20% and 40% (Figma's Start/End states), `shimmer` sweeps a highlight band left to right, `none` is static. Both animations are disabled under `prefers-reduced-motion: reduce`. */
     animation: SkeletonAnimation;
+    /** Set once the real content is ready: hides the skeleton (`display: none`) and removes its `role="status"` / "Loading" label. */
     loaded: boolean;
     protected updated(changed: Map<string, unknown>): void;
     static styles: lit.CSSResult;
@@ -1779,20 +2671,63 @@ declare global {
 }
 
 type ModalSide = "top" | "bottom" | "center";
-type ModalSize = "sm" | "md" | "lg" | "xl" | "fullscreen";
+/** Panel width scale, spelled out. `fullscreen` has no short form. */
+type ModalSize = "small" | "medium" | "large" | "extra-large" | "fullscreen";
+/** Alternative spellings, not deprecations — the short names keep working. */
+type ModalSizeAlias = "sm" | "md" | "lg" | "xl";
+type ModalSizeInput = ModalSize | ModalSizeAlias;
+/**
+ * `"default"` — the body is a free-form slot (24px padding, your own layout).
+ * `"text"` — the Figma Modal Sheet "Text" slot: a message-only modal whose body
+ * is plain copy (16px vertical / 20px horizontal padding, body-lg type) under
+ * the header divider. Additive, opt-in (audit 20c).
+ */
+type ModalVariant = "default" | "text";
+/**
+ * Modal sheet dialog (Figma "Modal Sheet", 8171:3412) — a centred, top- or
+ * bottom-anchored panel over a scrim with a title/description header, a
+ * scrollable body, an optional footer and a loading state. Lives in the
+ * `rel-sheet` folder and is exported as `RelModal`.
+ * @slot - Body content of the modal
+ * @slot header - Extra header content rendered under the title/description (e.g. a stepper or tabs)
+ * @slot footer - Actions row (right-aligned, 8px gap); the footer only renders when this slot has content
+ * @csspart overlay - The full-viewport scrim behind the panel
+ * @csspart panel - The dialog panel (role="dialog")
+ * @csspart header - Header row holding title, description, header slot and close button
+ * @csspart close-button - The "X" close button
+ * @csspart content - Scrollable body wrapper around the default slot
+ * @csspart footer - Footer wrapper around the `footer` slot
+ * @csspart loading - Spinner overlay shown while `loading` is set
+ * @cssprop --rel-modal-width - Panel width; overrides the `size` scale (md default `clamp(360px, 49vw, 708px)`, sm `min(400px, 100vw - 32px)`, lg `min(900px, 100vw - 48px)`, xl `min(1140px, 100vw - 48px)`). Ignored by `fullscreen` and by the responsive collapse below 480px
+ * @cssprop --rel-modal-transition-duration - Open/close animation duration; default `0.3s`
+ * @cssprop --rel-modal-transition-timing - Open/close animation easing; default `cubic-bezier(0.32, 0.72, 0, 1)`
+ */
 declare class RelModal extends LitElement {
+    /** Whether the modal is shown. Toggle it to open/close; every change fires `rel-open-change`. */
     open: boolean;
+    /** Where the panel is anchored: `bottom` (48px above the bottom edge, slides up), `top` (48px below the top edge, slides down) or `center` (fades and scales in). Below 480px with `breakpoint="responsive"` every side collapses to a full-width bottom sheet. */
     side: ModalSide;
+    /** Heading text (rendered as an `<h2>`, linked via `aria-labelledby`). The `title` attribute is stripped from the host after it is read so no native tooltip appears. */
     title: string;
+    /** Supporting text under the title (linked via `aria-describedby`). */
     description: string;
     /** Alias for `description`; rendered only when `description` is empty. */
     subtitle: string;
+    /** Coarse dismissal switch. When false the close button is hidden and backdrop clicks / Escape are ignored regardless of the granular `close-on-*` / `show-close-button` props. */
     dismissible: boolean;
+    /** Modal mode: renders the scrim, sets `role="dialog"` + `aria-modal`, traps Tab inside the panel and moves focus in on open. When false the panel is a `region` with no scrim and no focus trap. */
     modal: boolean;
-    /** Panel width scale. `md` matches the Figma Modal Sheet width; `fullscreen` covers the viewport. */
-    size: ModalSize;
+    /** Panel width scale. `medium` (default) matches the Figma Modal Sheet width; `fullscreen` covers the viewport. `sm` / `md` / `lg` / `xl` are alternative spellings of `small` / `medium` / `large` / `extra-large` and stay supported — they are normalised to the full words, not deprecated. */
+    size: ModalSizeInput;
+    /** Body treatment — see `ModalVariant`. `"text"` styles the default slot as
+     *  the Figma "Text" message slot; the header (and its divider) render as
+     *  usual above it. Default rendering is unchanged. */
+    variant: ModalVariant;
+    /** Close when the scrim is clicked. Only effective while `dismissible` is true; ignored while `disabled` or `loading`. */
     closeOnBackdropClick: boolean;
+    /** Close on the Escape key. Only effective while `dismissible` is true; ignored while `disabled`. */
     closeOnEscape: boolean;
+    /** Render the "X" close button in the header. Only effective while `dismissible` is true. */
     showCloseButton: boolean;
     /** Move focus into the panel when opened (modal mode only). */
     autoFocus: boolean;
@@ -1818,8 +2753,18 @@ declare class RelModal extends LitElement {
     private originalBodyPaddingRight;
     static styles: lit.CSSResult;
     connectedCallback(): void;
+    /**
+     * The footer divider is conditional: the designer confirmed that short
+     * content (a confirmation message) has no divider, but a body that scrolls
+     * does — it is a scroll affordance, not decoration. There is no CSS way to
+     * ask "does this element scroll", so it is measured and reflected onto the
+     * host as `body-scrolls`, re-measured whenever the body or its contents
+     * resize.
+     */
+    private bodyScrollObserver?;
+    private watchBodyScroll;
     disconnectedCallback(): void;
-    protected willUpdate(): void;
+    protected willUpdate(changed: Map<string, unknown>): void;
     updated(changed: Map<string, unknown>): void;
     private handleOpen;
     private handleClose;
@@ -1842,26 +2787,71 @@ declare global {
  */
 type SliderType = "continuous" | "discrete" | "default" | "range";
 type TrackStyle = "solid" | "dotted";
+/** Figma Size axis, spelled out as in the design file. */
+type SliderSize = "small" | "medium" | "large";
+/** Alternative spellings, not deprecations — the original short names keep working. */
+type SliderSizeAlias = "sm" | "md" | "lg";
+type SliderSizeInput = SliderSize | SliderSizeAlias;
+/**
+ * Slider (Figma "Slider", 6417:1340): a pill track with a stroked round thumb,
+ * optional value tooltip, discrete tick marks and a dual-thumb range mode.
+ * Built on native `<input type="range">` so keyboard and assistive-technology
+ * behaviour come for free.
+ * @csspart track - The rail behind the thumb (the filled portion has no part)
+ * @csspart thumb - The round grab handle (one per thumb in range mode)
+ * @csspart tooltip - The value bubble + chevron above each thumb (only while `showBubble` is on)
+ * @cssprop --rel-slider-track-height - Rail thickness; 6 / 8 / 10px for size sm / md / lg
+ * @cssprop --rel-slider-thumb-size - Thumb diameter; 16 / 20 / 24px for size sm / md / lg
+ * @cssprop --rel-slider-thumb-stroke - Width of the hover / pressed / focus ring around the thumb; default 6px
+ * @cssprop --rel-slider-thumb-halo-color - Colour of the keyboard-focus ring; default `var(--rel-border-default)`
+ * @cssprop --rel-slider-tick-size - Tick-mark diameter in discrete mode; 4 / 5 / 6px for size sm / md / lg
+ * @cssprop --rel-slider-bubble-radius - Corner radius of the value bubble; 8px for size sm, otherwise 10px
+ */
 declare class RelSlider extends LitElement {
+    /** Slider mode: `continuous` (or its alias `default`) accepts any integer value, `discrete` snaps to `step` and draws tick marks, `range` shows two thumbs bounding `value`…`valueEnd`. */
     type: SliderType;
-    /** Figma Size axis (S/M/L): scales track, thumb and ticks. */
-    size: "sm" | "md" | "lg";
+    /**
+     * Draws the tick marks (Figma's separate `Is Determinated` boolean). Works
+     * with ANY `type` — Figma shows ticks on every variant, where the code used
+     * to gate them behind the code-only `type="discrete"`, so a `default` or
+     * `range` slider could never show them.
+     * Left unset it follows `type="discrete"`, so nothing changes for existing
+     * sliders; set it explicitly to override in either direction.
+     */
+    showTicks?: boolean;
+    /** Whether tick marks render: explicit `show-ticks` wins, else the legacy `type="discrete"`. */
+    private get ticksVisible();
+    /** Figma Size axis: `small` (6px track / 16px thumb), `medium` (8 / 20, default) or `large` (10 / 24), which also scales the ticks and the value bubble. `sm` / `md` / `lg` are alternative spellings and stay supported — they are normalised to the full words, not deprecated. */
+    size: SliderSizeInput;
+    /** Lowest selectable value. */
     min: number;
+    /** Highest selectable value. */
     max: number;
+    /** Increment between values. In `discrete` mode it also spaces the tick marks; in `continuous` mode the native input always moves in steps of 1. */
     step: number;
+    /** Disables interaction and dims the track, thumb and ticks; the tooltip is hidden. */
     disabled: boolean;
+    /** Style of the filled part of the track: `solid` or a `dotted` pattern. */
     track: TrackStyle;
+    /** Print the numeric value under every tick mark. Only has an effect in `discrete` mode. */
     showTickLabels: boolean;
+    /** Show the value tooltip above the thumb(s). */
     showBubble: boolean;
+    /** Current value (the lower value in `range` mode). */
     value: number;
     /** Upper value when type="range" (attribute value-end). */
     valueEnd: number;
+    /** Accessible name for the native range input. In `range` mode it is suffixed with " minimum" / " maximum" per thumb; without it the two thumbs read "Minimum value" / "Maximum value" and a single slider has no name. */
     fieldAriaLabel?: string;
     private ticks;
     private _onChange;
     private _onTouched;
     static styles: lit.CSSResult;
     connectedCallback(): void;
+    /** Alternative spellings, NOT deprecations — no console notice. Normalising
+     *  the property rather than duplicating every [size=] selector keeps the
+     *  reflected attribute canonical, so only one spelling can reach the CSS. */
+    protected willUpdate(changed: Map<string, unknown>): void;
     updated(changedProperties: Map<string, any>): void;
     private get isRange();
     private get percentage();
@@ -1879,8 +2869,11 @@ declare class RelSlider extends LitElement {
     private getTickLeftPct;
     private isTickActive;
     private onInput;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnChange(fn: (value: number) => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnTouched(fn: () => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     writeValue(value: number): void;
     private updateActiveWidth;
     private renderThumbContainer;
@@ -1890,16 +2883,50 @@ declare class RelSlider extends LitElement {
 }
 
 type SnackbarLines = "single" | "double";
+/** Canonical layout axis (Figma "Type"): default | longer-action. */
+type SnackbarVariant = "default" | "longer-action";
+/** Canonical semantic tones (Figma "Tone"): neutral | success | warning | destructive. */
+type SnackbarTone = "neutral" | "success" | "warning" | "destructive";
+/** Deprecated spellings: "default" → neutral; "error" | "danger" | "critical" → destructive. */
+type SnackbarToneAlias = "default" | "error" | "danger" | "critical";
+type SnackbarToneInput = SnackbarTone | SnackbarToneAlias;
+/** @deprecated since 1.4.7 — use `SnackbarToneInput`. */
 type SnackbarType = "default" | "success" | "error" | "warning";
+/**
+ * Snackbar (Figma "Snackbar"): a dark, elevated message bar with an optional tone accent and leading status icon, an optional action button and a close icon, shown via `show` and auto-dismissed after `duration` milliseconds. It is not positioned — place it (fixed or in-flow) yourself. Use it for brief feedback with a single follow-up action ("Undo", "Retry"); use `rel-alert` for persistent messages.
+ * @csspart label - The message text container
+ * @csspart action - The action button; rendered only when `action` is set
+ * @csspart close-button - The close icon button; rendered while `iconclose` is true
+ */
 declare class RelSnackbar extends LitElement {
+    /** Message text. Announced to screen readers through the shared live-region announcer when the snackbar is shown and whenever it changes while shown. The default is a placeholder — always set it. */
     message: string;
+    /** Label of the optional action button (Figma trailing button, Static / Small); omitted when unset. Clicking it fires `actionClick` and then dismisses the snackbar. */
     action?: string;
+    /**
+     * Layout and timing (Figma "Type"): `"default"` (message and actions on one row) | `"longer-action"` (message stacked above the actions, which align to the end, with the auto-dismiss delay doubled so there is time to use the action). Takes precedence over the deprecated `lines` and `longerAction` props.
+     */
+    variant?: SnackbarVariant;
+    /** @deprecated — use `variant="longer-action"`, which also sets the stacked layout. Doubles the auto-dismiss delay (`duration * 2`) on its own. Ignored when `variant` is set. Logs a one-time console notice. */
     longerAction: boolean;
+    /** Shows the trailing close icon button. Defaults to true; because it is a Lit boolean, `iconclose="false"` is still true — set the property to `false` from script to hide the button. */
     iconClose: boolean;
+    /** @deprecated — use `variant`; `lines="double"` maps to `variant="longer-action"`. Sets the stacked layout on its own but not the doubled delay. Ignored when `variant` is set. Logs a one-time console notice. */
     lines: SnackbarLines;
+    /** Auto-dismiss delay in milliseconds (doubled by `variant="longer-action"`), started when `show` becomes true and restarted when `duration` or the layout changes while shown. `0` (or a negative value) disables auto-dismiss. */
     duration: number;
-    type: SnackbarType;
+    /**
+     * Semantic tone (Figma "Tone"): `"neutral"` (default: no accent, no icon) | `"success"` | `"warning"` | `"destructive"` — the status tones add a 4px left accent and a leading icon (check-circle / warning / error) in the tone colour. `"default"` is a deprecated alias of `"neutral"`; `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"`; each logs a one-time console notice. Takes precedence over the deprecated `type` prop.
+     */
+    tone?: SnackbarToneInput;
+    /** @deprecated Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"` and `type="default"` to `tone="neutral"`. Ignored when `tone` is set. Logs a one-time console notice. */
+    type?: SnackbarToneInput;
+    /** Whether the snackbar is visible. Set it to true to show the snackbar and start the auto-dismiss timer; it is set back to false by the close icon, the action button and the timer. There is no open/close method — toggle this property. */
     show: boolean;
+    /** Read-only canonical layout actually rendered: explicit `variant` wins, else either deprecated prop (`lines="double"` or `longerAction`) promotes to `"longer-action"`, else `"default"`. */
+    get resolvedVariant(): SnackbarVariant;
+    /** Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"neutral"` / `"destructive"`. */
+    get resolvedTone(): SnackbarTone;
     private visible;
     private _dismissTimer;
     static styles: lit.CSSResult;
@@ -1915,47 +2942,158 @@ declare class RelSnackbar extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/** Control scale, spelled out. Figma has no Size axis on Switch; see the size ramp in the styles. */
+type SwitchSize = "small" | "medium" | "large";
+/** Alternative spellings, not deprecations — the short names work too. */
+type SwitchSizeAlias = "sm" | "md" | "lg";
+type SwitchSizeInput = SwitchSize | SwitchSizeAlias;
+/** Which side of the control the label sits on. */
+type SwitchLabelPlacement = "end" | "start";
+/**
+ * Toggle switch (Figma "Switch", 5917:1174, Type=Line): a 44×20 control with a
+ * thin 10px track and a 20px handle that slides 20px. Wraps a native checkbox
+ * with `role="switch"`, so keyboard and screen-reader behaviour are native.
+ * @slot - Rich label content beside the control, as an alternative to the `label` property. Clicking it toggles the switch.
+ * @csspart root - The `<label>` holding the control and its optional text; carries the `label-placement` order
+ * @csspart base - The control box around the hidden input and the track
+ * @csspart track - The thin rail; the handle is its `::before` pseudo-element
+ * @csspart label - The text beside the control; not rendered when there is neither a `label` nor slotted content
+ * @cssprop --rel-switch-track-width - Overall control width; defaults to the `size` ramp (36 / 44 / 52px)
+ * @cssprop --rel-switch-track-height - Overall control height; defaults to the `size` ramp — 16 / 20 / 24px for `type="line"`, 20 / 24 / 28px for `type="pill"`
+ * @cssprop --rel-switch-thumb-size - Handle diameter; defaults to the `size` ramp (16 / 20 / 24px), and the handle always travels its own width minus the 2px inset on each side
+ * @cssprop --rel-switch-track - Rail colour; default `var(--rel-bg-neutral-elevated-2)`
+ * @cssprop --rel-switch-knob-on - Handle colour when checked; default `var(--rel-bg-neutral-inverse-2)`
+ * @cssprop --rel-switch-knob-off - Handle colour when unchecked; default `var(--rel-text-static-light)`
+ * @cssprop --rel-switch-disabled - Handle colour while disabled; default `var(--rel-bg-neutral-elevated-1)`
+ */
 declare class RelSwitch extends LitElement {
+    /** Whether the switch is on. Set it to control the state programmatically; user toggles update it and fire `rel-change`. */
     checked: boolean;
+    /**
+     * Shape (Figma "Type"): `"line"` (default) is the 44x20 control with a thin
+     * 40x10 rail and the handle riding on it; `"pill"` is the 44x24 filled track
+     * with the handle inside it.
+     * NOTE: Figma's own default is Pill. We default to `line` deliberately —
+     * flipping it would restyle every existing switch — so this is a recorded
+     * divergence from the design default, not an oversight.
+     */
+    type: "line" | "pill";
+    /** Disables interaction and swaps in the dulled rail / handle fills; the handle shadow is removed. */
     disabled: boolean;
+    /** Arbitrary string echoed in the `rel-change` event detail — useful when one handler serves several switches. */
     value: string;
+    /** Accessible name for the native input. Without it the switch has no label of its own, so pair it with a visible `<label>` or set this. */
     fieldAriaLabel?: string;
+    /** Visible text beside the control. Clicking it toggles the switch, and it becomes the accessible name — use `fieldAriaLabel` instead when the switch has no visible text. For rich content (a bold word, an icon) slot it in the default slot rather than setting this. */
+    label?: string;
+    /**
+     * Which side the label sits on: `end` (default) puts it after the control, `start` before it.
+     *
+     * Note this is a PHYSICAL side, not a writing-direction one, matching every
+     * other placement prop in the library.
+     */
+    labelPlacement: SwitchLabelPlacement;
+    /**
+     * Control scale: `small`, `medium` (default) or `large`. `sm` / `md` / `lg`
+     * are alternative spellings and stay supported — normalised to the full
+     * words, not deprecated.
+     *
+     * Figma's Switch has axes Type / State / Enabled only, with no Size, so this
+     * ramp is ours. `medium` is exactly the control that shipped before it
+     * existed, so an existing switch is unchanged.
+     *
+     * It does NOT respond to viewport width. Picking a size per breakpoint is the
+     * consuming application's decision — a control that silently resized itself
+     * at some width would be undocumentable behaviour, and the breakpoint that
+     * matters belongs to the layout around it, not to the switch.
+     */
+    size: SwitchSizeInput;
     private _onChange;
     private _onTouched;
     private isFocused;
     private isPressed;
+    private hasSlottedLabel;
+    /** Alternative spellings, NOT deprecations — no console notice. Normalising
+     *  keeps the reflected attribute canonical so the :host([size=…]) rules only
+     *  need the full words. Same shape as rel-chip, rel-slider and rel-radio. */
+    protected willUpdate(changed: Map<string, unknown>): void;
     static styles: lit.CSSResult;
     private toggle;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnChange(fn: (value: boolean) => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnTouched(fn: () => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     writeValue(checked: boolean): void;
     private handleFocus;
     private handleBlur;
     private handleMouseDown;
     private handleMouseUp;
     render(): lit_html.TemplateResult<1>;
+    /** Rich label content can be slotted instead of set as text; this keeps the
+     *  label span out of the layout entirely when neither is present, so an
+     *  unlabelled switch has no stray gap beside it. */
+    private onSlotChange;
 }
 
 interface TabItem {
     label: string;
+    /** Icon name from the generated icon dictionary, rendered before the label (Figma "Show Icon" / "Icon"). Sized 20 / 18 / 16px with the tab's own size step. */
+    icon?: string;
     badge?: number;
     badgeDot?: boolean;
     disabled?: boolean;
 }
+/**
+ * Tab-strip scale. `sm` / `md` / `lg` are the original names; the full words
+ * `small` / `medium` / `large` are accepted as aliases (Trello 4). Each step
+ * is an explicit item height — 32 / 40 / 48px (Figma Tab Item S/M/L).
+ */
+type TabSize = "sm" | "md" | "lg" | "small" | "medium" | "large";
+/**
+ * Declarative tab definition for `<rel-tab>`. Renders nothing itself — place
+ * it in the parent's `items` slot and the parent reads its properties.
+ */
 declare class RelTabItem extends LitElement {
+    /** Text shown on the tab. */
     label: string;
+    /** Icon name from the generated icon dictionary, rendered before the label (Figma "Show Icon" / "Icon"). Sized 20 / 18 / 16px with the tab's own size step. */
+    icon: string;
+    /** Optional identifier for the tab. `<rel-tab>` does not read it; look it up from the item at `event.detail` when handling `rel-tab-change`. */
     value: string;
+    /** Count shown in a small badge after the label; `0` hides the badge. */
     badge: number;
     /** Shows a small dot instead of a numbered badge — takes precedence over `badge`. */
     badgeDot: boolean;
+    /** Greys the tab out and skips it in click, arrow-key and Home/End navigation. */
     disabled: boolean;
     render(): lit_html.TemplateResult<1>;
 }
+/**
+ * Underline tab strip (Figma "Tab Item", 6473:1075) with roving-tabindex
+ * keyboard navigation, optional count/dot badges and a single shared tabpanel
+ * below the strip. Tabs come either from the `tabs` array or from slotted
+ * `<rel-tab-item>` elements.
+ * @slot items - `<rel-tab-item>` definitions; when present they take precedence over the `tabs` array
+ * @slot - Content of the single tabpanel rendered under the strip (always visible — swap it yourself on `rel-tab-change`)
+ * @csspart list - The `role="tablist"` row
+ * @csspart item - Each `role="tab"` element
+ * @csspart label - The text span inside each tab
+ * @cssprop --rel-tab-active-color - Underline colour of the active tab; default `var(--rel-bg-brand)`
+ * @cssprop --rel-tab-underline-height - Thickness of the active underline; default 1px (`--rel-stroke-sm`, the weight Figma draws). Set it to restore the heavier 3px bar shipped previously.
+ * @cssprop --rel-tab-text-default - Label colour of the active tab; default `var(--rel-text-default)`
+ * @cssprop --rel-tab-text-hover - Label colour while hovering an enabled tab; default `var(--rel-text-label)`
+ * @cssprop --rel-tab-text-disabled - Label colour of a disabled tab; default `var(--rel-text-disabled)`
+ * @cssprop --rel-tab-hover-color - Background of an inactive tab on hover; default `var(--rel-bg-neutral-elevated-1)`
+ */
 declare class RelTab extends LitElement {
+    /** Tab definitions as `{ label, badge?, badgeDot?, disabled? }` objects — normally set as a property (as an attribute it must be a JSON string). Assign a new array to update; mutating in place does not re-render. Ignored when `<rel-tab-item>` children are slotted into `items`. */
     tabs: TabItem[];
+    /** Zero-based index of the selected tab. Set it to switch tabs programmatically (no event is fired for programmatic changes). */
     activeIndex: number;
-    /** Tab size — styled via :host([size]) rules. */
-    size: "sm" | "md" | "lg";
+    /** Tab size — styled via :host([size]) rules. Explicit item heights
+     *  32 / 40 / 48px (audit 34); `small|medium|large` alias `sm|md|lg`. */
+    size: TabSize;
     private _tabItems;
     /** Stable id prefix linking tabs to the shared tabpanel. */
     private tabsId;
@@ -1984,14 +3122,31 @@ declare class RelTab extends LitElement {
  * V1.0, node 8301:3771): fixed panel widths 220/250/280 by size, full-bleed
  * columns with 1px dividers, neutral selected state, and a Now / Cancel / OK
  * footer whose buttons are always size S.
+ *
+ * @csspart base - Outer wrapper; carries the size / error / readonly classes
+ * @csspart label - The field label above the trigger
+ * @csspart trigger - The field box that anchors the panel (wraps the text input and the icons)
+ * @csspart value - The editable text input showing the formatted time
+ * @csspart icon - The trailing clock icon
+ * @csspart panel - The popover panel (`role="dialog"`)
+ * @csspart shortcuts - The typed-shortcut chip row at the top of the panel (N → Now)
+ * @csspart option - Each hour / minute / second / AM-PM entry button
+ * @csspart footer - The Now / Cancel / OK row
+ * @csspart helper - The helper / error text live region under the field
+ * @fires rel-focus - Fired when the text input receives focus. No detail.
  */
 declare class RelTimePicker extends LitElement {
     /** Committed time, 24-hour "HH:mm" or "HH:mm:ss" (e.g. "09:30", "17:05:30"). */
     value: string | null;
+    /** Placeholder shown in the field while no value is committed and nothing is typed. */
     placeholder: string;
+    /** Field label rendered above the trigger; also the input's accessible name (unset → "Select time"). */
     label: string | null;
+    /** Disables the field (0.6 opacity, no pointer events); the panel cannot open. */
     disabled: boolean;
+    /** Renders the `*` mark after the label and sets `aria-required`; not enforced by the component. */
     required: boolean;
+    /** Shows the value but blocks typing and opening the panel. */
     readonly: boolean;
     /** Display format of the trigger text and hour column. Value stays 24-hour. */
     format: "12h" | "24h";
@@ -2003,16 +3158,25 @@ declare class RelTimePicker extends LitElement {
     minTime: string | null;
     /** Latest selectable time, "HH:mm" (inclusive). */
     maxTime: string | null;
+    /** Whether the panel is open. Settable from outside; opening resets the draft from `value` (programmatic changes do not fire `rel-open-change`). */
     open: boolean;
+    /** Shows a clear (×) button inside the field while a value is set; clearing commits `null`. */
     clearable: boolean;
+    /** Error styling (danger border, `aria-invalid`) and shows `errorMessage` below the field. */
     error: boolean;
     /** Alias for `error` (requested-API compat); either flag applies error styling. */
     invalid: boolean;
+    /** Text shown below the field while `error` / `invalid` is set (falls back to the typed-entry parse error, then `helperText`). */
     errorMessage?: string;
+    /** Assistive text shown below the field when not in error. */
     helperText?: string;
+    /** When set, renders a hidden `<input name="…">` carrying `value` for native form submission. */
     name?: string;
+    /** Trigger height on the shared field scale — small 32 / medium 40 / large 48px border-box; also sets the panel width (220 / 250 / 280px) and option row height (32 / 36 / 40px). Small lowers the trigger min-width from 160 to 128px. */
     size: "small" | "medium" | "large";
+    /** Visual style; only `"outlined"` exists today. */
     variant: "outlined";
+    /** Fills the parent width (the host is inline-block with intrinsic width otherwise). The attribute is lowercase `fullwidth`. */
     fullWidth: boolean;
     private draftHour;
     private draftMinute;
@@ -2116,19 +3280,110 @@ declare global {
     }
 }
 
+/** Canonical semantic tones (Figma "Tone"): neutral | destructive. */
+type ToastTone = "neutral" | "destructive";
+/** Deprecated spellings: "default" → neutral; "error" | "danger" | "critical" → destructive. */
+type ToastToneAlias = "default" | "error" | "danger" | "critical";
+type ToastToneInput = ToastTone | ToastToneAlias;
+/** @deprecated since 1.4.7 — use `ToastToneInput`. */
 type ToastType = "default" | "error";
+/**
+ * Where the toast is anchored in the viewport. PHYSICAL sides, not logical
+ * start/end: nothing else in this library adapts to writing direction, and a
+ * logical model in one component would make it the odd one out.
+ */
+type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+/** Toast scale, spelled out. Figma has no Size axis on Toast; see the ramp in the styles. */
+type ToastSize = "small" | "medium" | "large";
+/** Alternative spellings, not deprecations — the short names work too. */
+type ToastSizeAlias = "sm" | "md" | "lg";
+type ToastSizeInput = ToastSize | ToastSizeAlias;
+/**
+ * Transient notification: a fixed-position card with a message, an optional action button and a dismiss button, shown via `show` / `open()` and hidden again after `duration` milliseconds. Anchors to any of six viewport positions (`position`, default `bottom-center`) at three scales (`size`, default `medium`). Use it for brief, non-blocking confirmations; use `rel-alert` for persistent messages.
+ *
+ * STACKING. Toasts sharing a `position` stack automatically — no wrapper element
+ * and no change to your markup. Up to `max-visible` (default 3) show at once,
+ * newest against the anchor edge; any beyond that WAIT rather than being dropped,
+ * and a waiting toast's `duration` does not start until it is actually on screen.
+ * Dismissing one closes the gap for the rest. The six positions stack
+ * independently. Behaviour change: five toasts at one position used to render on
+ * top of each other; now three show and two wait.
+ * @csspart base - The `role="status"` toast container that carries the tone class
+ * @csspart label - The message text span
+ * @csspart action - The action button; rendered only when `actionlabel` is set
+ * @csspart close-button - The dismiss button; rendered while `dismissible` is true
+ * @cssprop --rel-toast-z - `z-index` of the fixed host (default `9000`); raise it when a modal or drawer layer covers the toast
+ * @cssprop --rel-z-toast - Deprecated alias of `--rel-toast-z`, still read as its fallback
+ */
 declare class RelToast extends LitElement {
+    /** Text of the toast. It is also announced to screen readers through the shared live-region announcer each time `show` becomes true. */
     message: string;
-    type: ToastType;
+    /**
+     * Semantic tone (Figma "Tone"): `"neutral"` (default: neutral surface) | `"destructive"` (danger fill, announced assertively). `"default"` is a deprecated alias of `"neutral"`; `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"`; each logs a one-time console notice. Takes precedence over the deprecated `type` prop.
+     */
+    tone?: ToastToneInput;
+    /** @deprecated Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"` and `type="default"` to `tone="neutral"`. Ignored when `tone` is set. Logs a one-time console notice. */
+    type?: ToastToneInput;
+    /** Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"neutral"` / `"destructive"`. */
+    get resolvedTone(): ToastTone;
+    /** Label of the optional action button rendered between the message and the dismiss button; the button is omitted when unset. Clicking it fires `action` and then closes the toast. */
     actionLabel?: string;
+    /** Auto-dismiss delay in milliseconds, started each time `show` becomes true. `0` (or a negative value) disables auto-dismiss so the toast stays until `close()` or the dismiss button. Changing it while the toast is visible does not restart the running timer. */
     duration: number;
+    /** Whether the toast is visible. Set it to true (or call `open()`) to show the toast and start the auto-dismiss timer; it is set back to false by `close()`, the dismiss button, the action button and the timer. */
     show: boolean;
+    /** Shows the trailing dismiss button (Figma "Show Close Button"). Defaults to true; because it is a Lit boolean, `dismissible="false"` is still true — set the property to `false` from script to hide the button. */
+    dismissible: boolean;
+    /**
+     * Where the toast is anchored: `bottom-center` (default, unchanged from
+     * before this prop existed), `bottom-left`, `bottom-right`, `top-left`,
+     * `top-center` or `top-right`. Top anchors also animate in from the top edge
+     * rather than upward from the bottom.
+     *
+     * Figma's Toast has axes Content / Show Button / Show Close Button / Tone and
+     * no position, so this axis is ours.
+     */
+    position: ToastPosition;
+    /**
+     * Toast scale: `small`, `medium` (default, unchanged) or `large`. `sm` / `md`
+     * / `lg` are alternative spellings and stay supported — normalised to the
+     * full words, not deprecated. Scales the padding, the inner gap, the message
+     * type role and the close icon. Figma has no Size axis on Toast.
+     */
+    size: ToastSizeInput;
+    /**
+     * How many toasts may be on screen at once AT THIS POSITION. Further ones
+     * wait their turn rather than being dropped — a notification the user never
+     * saw is worse than a late one — and each toast's `duration` only starts
+     * once it actually becomes visible, so a queued message cannot expire unseen.
+     * Default 3; unbounded stacking just fills the viewport.
+     */
+    maxVisible: number;
     private visible;
     private _dismissTimer;
+    /** The stack this instance is currently registered in, so a `position`
+     *  change while shown can leave the old stack before joining the new one. */
+    private _registeredAt;
     static styles: lit.CSSResult;
     willUpdate(changed: Map<string, unknown>): void;
+    private joinStack;
+    private leaveStack;
+    /**
+     * Called by the reflow with this instance's admission state. The
+     * auto-dismiss timer starts HERE, on becoming visible — not when `show` is
+     * set — so a toast waiting its turn cannot expire before anyone has seen it.
+     */
+    private _setVisible;
+    /** Offset from the anchor edge, written by the reflow. Index 0 gets no
+     *  transform at all, so a lone toast is untouched by the stacking code. */
+    private _setStackOffset;
+    /** Measured height of the rendered card, for the stack arithmetic. */
+    private get _cardHeight();
+    private get anchorsTop();
     disconnectedCallback(): void;
+    /** Shows the toast: sets `show = true`, which starts the auto-dismiss timer and announces `message`. */
     open(): void;
+    /** Hides the toast, clears the auto-dismiss timer and fires `dismissed`. It fires `dismissed` even when the toast was already hidden. */
     close(): void;
     private handleActionClick;
     render(): lit_html.TemplateResult<1>;
@@ -2136,12 +3391,31 @@ declare class RelToast extends LitElement {
 
 type TooltipPosition = "above" | "below" | "left" | "right";
 type TooltipType = "single-line" | "multi-line";
+/**
+ * Bubble appearance. `inverse` is the original look — an inverse-surface bubble
+ * that is dark-on-light in light mode and light-on-dark in dark mode.
+ * `neutral` is a light-surface bubble, the same sense the word already carries
+ * on rel-toast, where `tone="neutral"` is likewise the light surface.
+ */
+type TooltipTone = "inverse" | "neutral";
+/**
+ * Hover/focus tooltip (Figma "Tooltip"): wraps a trigger element and shows a short inverse-coloured text bubble above, below, left or right of it. Use it for supplementary hints on icons and truncated labels only — the text is not reachable on touch and must never be the only place critical information lives.
+ * @slot - The trigger element (one focusable element such as a button or icon button). It receives `aria-describedby` pointing at the bubble.
+ * @csspart panel - The tooltip bubble (`role="tooltip"`): background, padding, radius, shadow and max-width.
+ * @csspart indicator - The triangular tail pointing at the trigger, rendered only when `show-tail` is set.
+ * @cssprop --rel-tooltip-offset - Gap between the trigger and the bubble; defaults to `6px`, or `13px` when `show-tail` is set so the tail clears the trigger.
+ */
 declare class RelTooltip extends LitElement {
+    /** Plain-text content of the bubble. Empty text still renders an (empty) bubble on hover, so always set it. */
     text: string;
+    /** Side of the trigger the bubble appears on, centred and 6px away (13px when `show-tail` is set, so the tail clears the trigger; override with `--rel-tooltip-offset`): `above`, `below`, `left` or `right`. No collision detection — pick a side with room in the viewport. */
     position: TooltipPosition;
+    /** Renders the triangular tail (`indicator` part) on the bubble's edge facing the trigger. */
     showTail: boolean;
-    /** Figma "Type": single-line stays on one line; multi-line wraps at a max width. */
+    /** Figma "Type": `single-line` keeps the text on one line and sizes to content; `multi-line` wraps inside a 200px max-width bubble. */
     type: TooltipType;
+    /** Bubble appearance: `inverse` (default) is the original inverse-surface bubble, unchanged; `neutral` is a light surface — `--rel-bg-neutral` with `--rel-text-default` and a 1px `--rel-border-default`, tail included. Figma has no such variant; this is a deliberate addition. */
+    tone: TooltipTone;
     private uniqueId;
     static styles: lit.CSSResult;
     connectedCallback(): void;
@@ -2217,21 +3491,23 @@ interface UploadState {
  * `<rel-upload-actions>` so they can sit in `<rel-modal>`'s footer slot and
  * stay pinned while this body scrolls.
  *
- * Emits (bubbling + composed):
- *   - `rel-files-added`  — `{ added: UploadFile[], rejected: UploadRejection[] }`
- *   - `rel-invalid`      — `{ rejected: UploadRejection[] }`
- *   - `rel-change`       — selection changed; `{ files: UploadFile[] }`
- *   - `rel-remove`       — row removed; `{ id, file }`
- *   - `rel-upload`       — Upload pressed; `{ files: UploadFile[] }`
- *   - `rel-retry`        — Retry pressed; `{ files: UploadFile[] }`
- *   - `rel-cancel`       — Cancel pressed
- *   - `rel-progress`     — `{ id, progress, loaded, total }`
- *   - `rel-file-complete`— `{ id, file }`
- *   - `rel-file-error`   — `{ id, file, error }`
- *   - `rel-complete`     — batch settled; `{ succeeded, failed }`
- *   - `rel-state`        — derived snapshot changed; `detail: UploadState`
+ * All events bubble and are composed.
  *
  * @element rel-upload
+ * @fires rel-files-added - Fired after files are picked or dropped and validated. Detail: `{ added: UploadFile[], rejected: UploadRejection[] }`.
+ * @fires rel-invalid - Fired just before `rel-files-added` when at least one picked file fails `accept` / `max-size`. Detail: `{ rejected: UploadRejection[] }`.
+ * @fires rel-change - Fired whenever the file list changes (files added, a row removed, `reset()`). Detail: `{ files: UploadFile[] }`.
+ * @fires rel-remove - Fired when a row is removed via its delete button or `removeFile()`. Detail: `{ id: string, file?: File }`.
+ * @fires rel-upload - Fired when Upload is pressed (or `upload()` is called) with the rows still `ready`; in controlled mode the app performs the transfer. Detail: `{ files: UploadFile[] }`.
+ * @fires rel-retry - Fired when Retry re-queues the retryable failed rows. Detail: `{ files: UploadFile[] }`.
+ * @fires rel-cancel - Fired when Cancel is pressed (or `cancel()` is called); in-flight transfers are aborted, the list is kept. No detail.
+ * @fires rel-progress - Fired on every progress tick in self-driving mode. Detail: `{ id: string, progress: number (0–100), loaded: number, total: number }` (bytes).
+ * @fires rel-file-complete - Fired when one file finishes uploading in self-driving mode. Detail: `{ id: string, file: File }`.
+ * @fires rel-file-error - Fired when one file's `uploader` rejects in self-driving mode. Detail: `{ id: string, file: File, error: string }`.
+ * @fires rel-complete - Fired when the whole self-driving batch settles without being cancelled. Detail: `{ succeeded: UploadFile[], failed: UploadFile[] }`.
+ * @fires rel-state - Fired when the derived `state` snapshot changes (and once after connecting). Detail: `UploadState`.
+ * @cssprop --rel-upload-browse-hover-bg - Background of the Browse button on hover. Defaults to `transparent`, which is what the underlying `rel-button` secondary style draws (Figma's outline button reacts on its border, not its fill), so this only takes effect when you set it.
+ * @csspart browse - The `rel-button` that opens the file picker (Figma "Browse Button": Size=Medium, Style=Secondary).
  */
 declare class RelUpload extends LitElement {
     /** Comma-separated accept list, e.g. ".pdf,.png,.jpg" or "image/*". */
@@ -2253,7 +3529,7 @@ declare class RelUpload extends LitElement {
      * component also maintains it itself as files are added and removed.
      */
     files: UploadFile[];
-    /** Supply to run uploads internally. See {@link Uploader}. */
+    /** Supply an `Uploader` `(file, { file, signal, onProgress }) => Promise<void>` to switch to self-driving mode: the component runs the batch itself with `concurrency`, progress, the delay alert, abort and retry. Unset (default) the component only emits intents. */
     uploader?: Uploader;
     /** Max files transferred at once in self-driving mode. */
     concurrency: number;
@@ -2284,6 +3560,7 @@ declare class RelUpload extends LitElement {
      * rather than re-queueing it blindly.
      */
     private get retryable();
+    /** Whether the primary action is enabled: not disabled, nothing in flight, and either `ready` rows exist or (in the failed phase) at least one failed row can be retried. */
     get canUpload(): boolean;
     /** Footer button label — "Upload", "Upload 3 files" or "Retry upload". */
     get primaryLabel(): string;
@@ -2359,6 +3636,9 @@ declare global {
  * specific `<rel-upload>` by id when a container holds more than one.
  *
  * @element rel-upload-actions
+ * @csspart base - The right-aligned flex row holding the buttons
+ * @csspart cancel - The secondary Cancel `rel-button` (absent when `no-cancel` is set)
+ * @csspart primary - The primary Upload / Retry `rel-button`
  */
 declare class RelUploadActions extends LitElement {
     /** Id of the `<rel-upload>` to control. Omit to auto-discover a sibling. */
@@ -2447,8 +3727,7 @@ declare class FocusTrap {
  *
  * Shortcut strings are written as "+"-joined tokens, e.g. "mod+b",
  * "ctrl+shift+p", "escape". The "mod" token means Cmd on Apple platforms
- * and Ctrl everywhere else (this is the pattern rel-sidebar's Ctrl/Cmd+B
- * toggle established). Matching is case-insensitive.
+ * and Ctrl everywhere else. Matching is case-insensitive.
  */
 type ShortcutHandler = (e: KeyboardEvent) => void;
 interface ParsedShortcut {
@@ -2512,4 +3791,4 @@ type Politeness = "polite" | "assertive";
  */
 declare function announce(message: string, politeness?: Politeness): void;
 
-export { type AutocompleteFilter, type AutocompleteItem, type AutocompleteSearchFn, type BindShortcutOptions, type BreadcrumbItem, type ButtonTone, type ButtonVariant, type ChipBorder, type ChipSize, type ChipTone, type ChipVariant, type DrawerCloseReason, type DrawerSide, type FieldLabelStyle, FocusTrap, type LabelPlacement, type MenuItem, type MenuType, type ModalSide, type ModalSize, type Orientation, type OtpType, type ProgressMode, type RadioOption, RelAccordion, RelAlert, RelAutocomplete, RelAvatar, RelBadge, RelBreadcrumbs, RelButton, RelCalendar, RelCard, RelCardMedia, RelCarousel, RelCheckbox, RelChip, RelContainer, RelDatePicker, RelDivider, RelDrawer, RelDrawerFooter, RelKbd, RelKbdGroup, RelLayout, RelMenu, RelMenuItem, RelMenubar, RelMenubarMenu, RelModal, RelNavbar, RelOtp, RelPagination, RelPopover, RelPopoverContent, RelProgress, RelRadio, RelRangePicker, RelResizableGroup, RelResizableHandle, RelResizablePanel, RelSegmentedButton, RelSelect, RelSkeleton, RelSlider, RelSnackbar, RelStepper, RelSwitch, RelTab, RelTabItem, RelTextfield, RelTimePicker, RelToast, RelTooltip, RelTopbar, RelTopbarActions, RelTopbarBrand, RelTopbarDropdown, RelTopbarDropdownItem, RelTopbarItem, RelTopbarMobilePanel, RelTopbarProfile, RelTopbarUtilities, RelUpload, RelUploadActions, type SegmentAlign, type SegmentOption, type SegmentSize, type SelectBorder, type SelectLabelStyle, type SelectOption, type SelectOptionObject, type SelectSize, type SelectState, type ShortcutHandler, type SkeletonAnimation, type SkeletonShape, type SliderType, type SnackbarLines, type SnackbarType, type Step, type StepStatus, type StepperSize, type StepperType, type TabItem, type TextAlign, type TextFieldPrefixStyle, type TextFieldSize, type TextFieldState, type TextFieldVariant, type ToastType, type TooltipPosition, type TooltipType, type TopbarForceLayout, type TopbarProfileType, type TopbarRewardTier, type TopbarVariant, type TrackStyle, type UploadFile, type UploadPhase, type UploadRejection, type UploadState, type UploadStatus, type Uploader, type UploaderContext, announce, bindShortcut, formatShortcutParts, getDeepActiveElement, getFocusableElements, isApplePlatform, isEditableTarget, matchesShortcut, parseShortcut, trapTabKey };
+export { type AlertTone, type AlertToneAlias, type AlertToneInput, type AutocompleteFilter, type AutocompleteItem, type AutocompleteSearchFn, type AvatarSize, type AvatarSizeAlias, type AvatarSizeInput, type BadgeSize, type BadgeSizeAlias, type BadgeSizeInput, type BindShortcutOptions, type BreadcrumbItem, type ButtonTone, type ButtonVariant, type ChipBorder, type ChipSize, type ChipSizeAlias, type ChipSizeInput, type ChipTone, type ChipToneAlias, type ChipToneInput, type ChipVariant, type ChipVariantAlias, type ChipVariantInput, type ContainerBackground, type ContainerPadding, type ContainerPaddingAlias, type ContainerPaddingInput, type ContainerSurface, type DrawerCloseReason, type DrawerSide, type FieldLabelStyle, FocusTrap, type KbdSize, type LabelPlacement, type MenuItem, type MenuSize, type MenuType, type MenuWidth, type MenubarType, type ModalSide, type ModalSize, type ModalSizeAlias, type ModalSizeInput, type ModalVariant, type Orientation, type OtpInputMode, type OtpSize, type OtpType, type PopoverContentSize, type PopoverContentSizeAlias, type PopoverContentSizeInput, type ProgressMode, type RadioOption, type RadioSize, type RadioSizeAlias, type RadioSizeInput, type RangePickerSize, type RangePickerSizeAlias, type RangePickerSizeInput, RelAccordion, RelAlert, RelAutocomplete, RelAvatar, RelBadge, RelBreadcrumbs, RelButton, RelCalendar, RelCard, RelCardMedia, RelCarousel, RelCheckbox, RelChip, RelContainer, RelDatePicker, RelDivider, RelDrawer, RelDrawerFooter, RelKbd, RelKbdGroup, RelLayout, RelMenu, RelMenuItem, RelMenubar, RelMenubarMenu, RelModal, RelOtp, RelPagination, RelPopover, RelPopoverContent, RelProgress, RelRadio, RelRangePicker, RelResizableGroup, RelResizableHandle, RelResizablePanel, RelSegmentedButton, RelSelect, RelSkeleton, RelSlider, RelSnackbar, RelStepper, RelSwitch, RelTab, RelTabItem, RelTextfield, RelTimePicker, RelToast, RelTooltip, RelUpload, RelUploadActions, type SegmentAlign, type SegmentOption, type SegmentSize, type SelectBorder, type SelectLabelStyle, type SelectOption, type SelectOptionObject, type SelectSize, type SelectState, type ShortcutHandler, type SkeletonAnimation, type SkeletonShape, type SliderSize, type SliderSizeAlias, type SliderSizeInput, type SliderType, type SnackbarLines, type SnackbarTone, type SnackbarToneAlias, type SnackbarToneInput, type SnackbarType, type SnackbarVariant, type Step, type StepStatus, type StepperSize, type StepperType, type SwitchLabelPlacement, type SwitchSize, type SwitchSizeAlias, type SwitchSizeInput, type TabItem, type TabSize, type TextAlign, type TextFieldPrefixStyle, type TextFieldSize, type TextFieldState, type TextFieldVariant, type ToastPosition, type ToastSize, type ToastSizeAlias, type ToastSizeInput, type ToastTone, type ToastToneAlias, type ToastToneInput, type ToastType, type TooltipPosition, type TooltipTone, type TooltipType, type TrackStyle, type UploadFile, type UploadPhase, type UploadRejection, type UploadState, type UploadStatus, type Uploader, type UploaderContext, announce, bindShortcut, formatShortcutParts, getDeepActiveElement, getFocusableElements, isApplePlatform, isEditableTarget, matchesShortcut, parseShortcut, trapTabKey };