@reliability-design/web 1.4.3 → 1.4.5

package/dist/components/rel-accordion/rel-accordion.ts

@@ -270,6 +270,9 @@ export class RelAccordion extends LitElement {
     }
   `;
 
+  /** Stable id prefix wiring the header to its panel. */
+  private accordionId = `rel-accordion-${Math.random().toString(36).slice(2)}`;
+
   private toggle() {
     this.open = !this.open;
     this.dispatchEvent(
@@ -286,9 +289,11 @@ export class RelAccordion extends LitElement {
       <div part="base" class="accordion">
         <div
           part="trigger" class="header"
+          id="${this.accordionId}-header"
           role="button"
           tabindex="0"
           aria-expanded="${this.open}"
+          aria-controls="${this.accordionId}-body"
           @click=${this.toggle}
           @keydown=${(e: KeyboardEvent) => {
             if (e.key === "Enter" || e.key === " ") {
@@ -315,7 +320,14 @@ export class RelAccordion extends LitElement {
             </slot>
           </div>
         </div>
-        <div part="content" class="body ${this.open ? "open" : "closed"}">
+        <div
+          part="content"
+          class="body ${this.open ? "open" : "closed"}"
+          id="${this.accordionId}-body"
+          role="region"
+          aria-labelledby="${this.accordionId}-header"
+          ?inert=${!this.open}
+        >
           <slot></slot>
         </div>
       </div>

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

@@ -94,3 +94,4 @@ Two data modes:
 - Form validation is *displayed* (`error`, `error-message`, `required`), not performed — validity logic belongs to the form layer (e.g. Angular validators)
 - CSS parts: `panel`, `list`, `option`, plus re-exported textfield parts (`label`, `control`, `input`, `helper`, `right-icon`)
 - Panel styling matches `rel-select`'s listbox; override via `--rel-autocomplete-bg`, `--rel-autocomplete-menu-border`, `--rel-autocomplete-menu-radius`, `--rel-autocomplete-menu-shadow`, `--rel-autocomplete-option-hover`
+- The open panel is promoted to the browser **top layer** (native Popover API, `popover="manual"`), so it renders correctly inside transformed / `overflow: hidden` containers — a centered `rel-modal`, a bottom `rel-drawer`. Engines without the Popover API fall back to `position: fixed` with a measure-and-cancel correction for transformed ancestors

package/dist/components/rel-autocomplete/rel-autocomplete.ts

@@ -143,6 +143,15 @@ export class RelAutocomplete extends LitElement {
       position: fixed;
       z-index: 1001;
       display: none;
+      /* Reset native [popover] UA styles (the panel is promoted to the
+         top layer so transformed ancestors — e.g. a centered rel-modal
+         panel — can't hijack its containing block or clip it). */
+      inset: auto;
+      margin: 0;
+      padding: 0;
+      width: auto;
+      height: auto;
+      color: inherit;
       box-sizing: border-box;
       background: var(--rel-autocomplete-bg, var(--rel-bg-neutral));
       border: 1px solid var(--rel-autocomplete-menu-border, var(--rel-border-default));
@@ -222,6 +231,7 @@ export class RelAutocomplete extends LitElement {
   disconnectedCallback() {
     super.disconnectedCallback();
     this.removeGlobalListeners();
+    this.hideNativePopover();
     clearTimeout(this.debounceTimer);
   }
 
@@ -309,7 +319,10 @@ export class RelAutocomplete extends LitElement {
     this.open = true;
     this.highlightedIndex = -1;
     this.addGlobalListeners();
-    requestAnimationFrame(() => this.updatePosition());
+    requestAnimationFrame(() => {
+      this.showNativePopover();
+      this.updatePosition();
+    });
   }
 
   private closePanel() {
@@ -317,6 +330,35 @@ export class RelAutocomplete extends LitElement {
     this.open = false;
     this.highlightedIndex = -1;
     this.removeGlobalListeners();
+    this.hideNativePopover();
+  }
+
+  /* A transformed ancestor (e.g. rel-modal's centered panel with
+   * translate(-50%,-50%)) becomes the containing block for position:fixed
+   * descendants, breaking viewport-based coordinates and letting the
+   * panel's overflow:hidden clip the suggestions. Promoting the panel to
+   * the browser top layer sidesteps both — same fix as rel-popover.
+   * `manual` keeps light-dismiss and Escape handling under this
+   * component's own control. */
+
+  private showNativePopover() {
+    const p = this.panelEl;
+    if (!p || typeof p.showPopover !== "function") return;
+    try {
+      if (!p.matches(":popover-open")) p.showPopover();
+    } catch {
+      /* older engines / detached element — fixed-position fallback applies */
+    }
+  }
+
+  private hideNativePopover() {
+    const p = this.panelEl;
+    if (!p || typeof p.hidePopover !== "function") return;
+    try {
+      if (p.matches(":popover-open")) p.hidePopover();
+    } catch {
+      /* already hidden or unsupported — nothing to do */
+    }
   }
 
   private updatePosition = () => {
@@ -337,6 +379,18 @@ export class RelAutocomplete extends LitElement {
       left = Math.max(8, window.innerWidth - t.width - 8);
     }
 
+    // Without top-layer support a transformed ancestor may be the containing
+    // block for position:fixed, shifting the panel away from the viewport
+    // coordinates computed above. Apply, re-measure, and cancel the offset.
+    this.panelEl.style.top = `${top}px`;
+    this.panelEl.style.left = `${left}px`;
+    this.panelEl.style.width = `${t.width}px`;
+    const applied = this.panelEl.getBoundingClientRect();
+    top -= applied.top - top;
+    left -= applied.left - left;
+    this.panelEl.style.top = `${top}px`;
+    this.panelEl.style.left = `${left}px`;
+
     this.panelStyle = `top:${top}px;left:${left}px;width:${t.width}px;`;
   };
 
@@ -583,6 +637,7 @@ export class RelAutocomplete extends LitElement {
         id="${panelId}"
         part="panel list"
         class="ac-panel"
+        popover="manual"
         role="listbox"
         aria-label="${this.accessibleName || "Suggestions"}"
         style="${this.panelStyle}"

package/dist/components/rel-button/rel-button.ts

@@ -137,9 +137,12 @@ export class RelButton extends LitElement {
       }
     }
 
-    /* Sizes */
+    /* Sizes. Min-widths come from the Figma Button master (S/M/L =
+       80/100/120) so short labels like "OK" keep a proper pill shape;
+       --rel-button-min-width lets a consumer override per instance. */
     .size-small {
       height: 32px;
+      min-width: var(--rel-button-min-width, 80px);
       padding: 0 var(--rel-spacing-sm);
       font-family: var(--rel-action-md-font-family);
       font-weight: var(--rel-action-md-font-weight);
@@ -150,6 +153,7 @@ export class RelButton extends LitElement {
 
     .size-medium {
       height: 40px;
+      min-width: var(--rel-button-min-width, 100px);
       gap: var(--rel-spacing-xs);
       padding: 0 var(--rel-spacing-md);
       font-family: var(--rel-action-lg-font-family);
@@ -161,6 +165,7 @@ export class RelButton extends LitElement {
 
     .size-large {
       height: 48px;
+      min-width: var(--rel-button-min-width, 120px);
       padding: 0 var(--rel-spacing-lg);
       font-family: var(--rel-action-xl-font-family);
       font-weight: var(--rel-action-xl-font-weight);
@@ -267,6 +272,11 @@ export class RelButton extends LitElement {
       color: var(--rel-action-neutral-label-icons-ghost);
     }
 
+    /* Figma master: ghost S has a narrower 56px min than primary/outline. */
+    .btn-text.size-small {
+      min-width: var(--rel-button-min-width, 56px);
+    }
+
     .btn-text.tone-critical {
       color: var(--rel-action-danger-label-icons-ghost);
     }
@@ -275,6 +285,8 @@ export class RelButton extends LitElement {
       background: transparent;
       color: var(--rel-action-neutral-label-icons-link);
       text-decoration: underline;
+      /* Links are inline actions — no minimum footprint in the Figma master. */
+      min-width: 0;
     }
 
     button.btn-link:hover:not(:disabled) {
@@ -303,6 +315,7 @@ export class RelButton extends LitElement {
     /* Icon Only as an independent axis: square button of the current style */
     .btn-icon-only {
       padding: 0;
+      min-width: 0;
     }
 
     .btn-icon-only.size-small {
@@ -321,6 +334,7 @@ export class RelButton extends LitElement {
       width: 40px;
       height: 40px;
       padding: 0;
+      min-width: 0;
       border-radius: 50%;
     }
     .btn-icon.tone-default {
@@ -365,7 +379,9 @@ export class RelButton extends LitElement {
        .btn-text: ghost gets tone-accent hovers below (this generic grey overlay
        has higher specificity than the per-tone ghost rules and was overriding
        them, which is why every ghost hover looked grey). */
-    button:hover:not(:disabled):not(.btn-primary):not(.btn-default):not(.btn-icon):not(.btn-secondary):not(.btn-static):not(.btn-text) {
+    /* Link buttons change label color only (rule above) — the overlay fill
+       here would make a hovered link read as a ghost button. */
+    button:hover:not(:disabled):not(.btn-primary):not(.btn-default):not(.btn-icon):not(.btn-secondary):not(.btn-static):not(.btn-text):not(.btn-link) {
       background: var(--rel-action-overlay-hover);
     }
 

package/dist/components/rel-calendar/rel-calendar.ts

@@ -426,9 +426,31 @@ export class RelCalendar extends LitElement {
     }
   }
 
+  /**
+   * Index of the single grid cell carrying tabindex="0". The old expression
+   * (`isSelected || (index === 0 && !focusedDate)`) left the grid with ZERO
+   * tab stops once the user arrowed around without a selection — Tab could
+   * never re-enter the calendar.
+   */
+  private getRovingIndex(days: CalendarDay[]): number {
+    const candidates = [
+      this.focusedDate
+        ? days.findIndex(
+            (d) => d.isCurrentMonth && this.isSameDay(d.date, this.focusedDate!)
+          )
+        : -1,
+      days.findIndex((d) => d.isSelected),
+      days.findIndex((d) => d.isCurrentMonth && d.isToday),
+      days.findIndex((d) => d.isCurrentMonth && !d.isDisabled),
+    ];
+    const found = candidates.find((i) => i >= 0);
+    return found ?? 0;
+  }
+
   render() {
     const days = this.getCalendarDays();
     const weekdayLabels = this.getWeekdayLabels();
+    const rovingIndex = this.getRovingIndex(days);
 
     return html`
       <div role="grid" aria-label="Calendar">
@@ -484,7 +506,7 @@ export class RelCalendar extends LitElement {
                 ?disabled=${day.isDisabled}
                 @click=${() => this.selectDay(day)}
                 @keydown=${(e: KeyboardEvent) => this.handleKeyDown(e, day, index)}
-                tabindex="${day.isSelected || (index === 0 && !this.focusedDate) ? 0 : -1}"
+                tabindex="${index === rovingIndex ? 0 : -1}"
               >
                 ${day.day}
               </button>

package/dist/components/rel-carousel/rel-carousel.ts

@@ -251,6 +251,11 @@ export class RelCarousel extends LitElement {
       "(prefers-reduced-motion: reduce)"
     ).matches;
 
+    // WCAG 2.2.2: auto-advance must pause while keyboard focus is inside the
+    // carousel, not just on mouse hover.
+    this.addEventListener("focusin", this.handleFocusIn);
+    this.addEventListener("focusout", this.handleFocusOut);
+
     if (this.autoplay) {
       this.startAutoplay();
     }
@@ -285,6 +290,8 @@ export class RelCarousel extends LitElement {
 
   disconnectedCallback() {
     super.disconnectedCallback();
+    this.removeEventListener("focusin", this.handleFocusIn);
+    this.removeEventListener("focusout", this.handleFocusOut);
     this._ro?.disconnect();
     this.stopAutoplay();
     if (this.animationId) {
@@ -556,6 +563,18 @@ export class RelCarousel extends LitElement {
     }
   }
 
+  private handleFocusIn = () => {
+    if (this.autoplay) this.stopAutoplay();
+  };
+
+  private handleFocusOut = (e: FocusEvent) => {
+    if (!this.autoplay) return;
+    const next = e.relatedTarget as Node | null;
+    // Resume only once focus has fully left the carousel (light or shadow).
+    if (next && (this.contains(next) || this.shadowRoot?.contains(next))) return;
+    this.startAutoplay();
+  };
+
   private handleMouseEnter() {
     if (this.autoplay && this.pauseOnHover) {
       this.stopAutoplay();
@@ -667,6 +686,7 @@ export class RelCarousel extends LitElement {
                       class="dot ${i === this.value ? "active" : ""}"
                       part="dot"
                       aria-label="Go to slide ${i + 1}"
+                      aria-current="${i === this.value ? "true" : nothing}"
                       @click=${() => this.goToSlide(i)}
                     ></button>
                   `)

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

@@ -1,20 +1,41 @@
 # rel-checkbox
 
 ## Overview
-A tri-state checkbox component supporting checked, unchecked, and indeterminate states. Includes label and supporting text with built-in error and disabled states for form validation scenarios.
+A tri-state checkbox component supporting checked, unchecked, and indeterminate states. Includes label, optional supporting text, and optional label prefix icon, with built-in error and disabled states. Supports two sizes, two densities, and leading/trailing box alignment — matching the Figma Checkbox sheet vocabulary (Size, Density, Alignment) verbatim.
 
 ## Usage
 ```html
 <!-- Basic example -->
 <rel-checkbox label="Accept terms"></rel-checkbox>
 
-<!-- Example with common options -->
+<!-- Supporting text, compact density (default: text on its own line, indented past the box) -->
 <rel-checkbox
   label="Subscribe to newsletter"
   supportingtext="We'll send you weekly updates"
   status="unchecked"
   state="default">
 </rel-checkbox>
+
+<!-- Comfortable density: label + supporting text stack beside the box -->
+<rel-checkbox
+  density="comfortable"
+  label="Notify the broker"
+  supportingtext="Sends an email when the POD is uploaded">
+</rel-checkbox>
+
+<!-- Trailing alignment: box at the far edge of the row (settings-row style).
+     Trailing always renders comfortable density — compact has no trailing layout. -->
+<rel-checkbox
+  alignment="trailing"
+  label="Email notifications"
+  supportingtext="Weekly summary of load activity">
+</rel-checkbox>
+
+<!-- Small size -->
+<rel-checkbox size="small" label="Include archived"></rel-checkbox>
+
+<!-- Indeterminate (programmatic-only; user toggle resolves to checked/unchecked) -->
+<rel-checkbox label="Select all" status="indeterminate"></rel-checkbox>
 ```
 
 ## API
@@ -23,42 +44,62 @@ A tri-state checkbox component supporting checked, unchecked, and indeterminate
 | Name | Type | Default | Description |
 |------|------|---------|-------------|
 | `label` | `string` | `"Label"` | Label text displayed next to the checkbox |
-| `icon` | `string` | `""` | `rel-icon` name rendered between the checkbox and the label (label prefix icon). Unset renders no icon and reserves no space |
-| `supportingtext` | `string` | `""` | Helper text displayed below the checkbox and label |
+| `icon` | `string` | `""` | `rel-icon` name rendered between the checkbox and the label (label prefix icon; scales with `size`). Unset renders no icon and reserves no space |
+| `supportingtext` | `string` | `""` | Helper text; placement depends on `density` |
 | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Visual and interaction state of the checkbox |
-| `status` | `"unchecked" \| "checked" \| "indeterminate"` | `"unchecked"` | Current checked state of the checkbox |
+| `status` | `"unchecked" \| "checked" \| "indeterminate"` | `"unchecked"` | Current check state. Indeterminate is programmatic-only |
+| `checked` | `boolean` (accessor) | `false` | Convenience accessor over `status` (used by the Angular CVA) |
+| `size` | `"small" \| "medium"` | `"medium"` | Control scale: medium = 18px box, body-lg label, body-sm supporting text; small = 14px box, body-md label, body-xs supporting text (reflected) |
+| `density` | `"compact" \| "comfortable"` | `"compact"` | Supporting-text layout: compact puts it on its own line under the row, indented past the box; comfortable stacks label + supporting text beside the box (reflected) |
+| `alignment` | `"leading" \| "trailing"` | `"leading"` | Box position: leading = before the label; trailing = far edge of the row. Trailing always renders comfortable density — compact+trailing is "Not available" in the Figma sheet, and a dev-mode `console.warn` fires if requested (reflected) |
+| `value` | `string` | `""` | Value reported in the `rel-change` event detail |
+
+### Layout matrix (mirrors the Figma sheet)
+| Size | Density | Leading | Trailing |
+|------|---------|---------|----------|
+| M | Comfortable | ✓ | ✓ |
+| M | Compact | ✓ (default) | — renders comfortable |
+| S | Comfortable | ✓ | ✓ |
+| S | Compact | ✓ | — renders comfortable |
 
 ## Events
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `change` | `{ checked: boolean, indeterminate: boolean }` | Fired when checkbox state changes through user interaction |
+| `rel-change` | `{ checked: boolean, value: string }` | Fired on user toggle (bubbles, composed) |
 
 ## Slots
 Default slot not used.
 
 ## CSS Parts
-None exposed.
+- `base` — outer wrapper
+- `label` — label text span
+- `helper` — supporting text span
 
 ## Tokens / CSS Variables
 
 ### Semantic Tokens
 - `--rel-fonts-font-family` - Font family
-- `--rel-body-md-regular-font-size`, `--rel-body-sm-regular-font-size` - Font sizes for label and supporting text
-- `--rel-fonts-weight-body-medium` - Font weight for label
+- `--rel-body-lg-regular-*` / `--rel-body-sm-regular-*` - Label and supporting text type (medium size)
+- `--rel-body-md-regular-*` / `--rel-body-xs-regular-*` - Label and supporting text type (small size)
+
+### Spacing Tokens
+- `--rel-spacing-xs` - Gap between box, icon, and label
+- `--rel-spacing-3xs` - Gap between label and supporting text (comfortable) / row and supporting text (compact)
 
 ### Color Tokens
-- `--rel-text-label` - Checkbox border and checked background color
-- `--rel-bg-surface` - Checkbox background and checkmark color
-- `--rel-text-default` - Label text color
-- `--rel-text-placeholder` - Supporting text color
-- `--rel-bg-danger` - Error state border and background color
-- `--rel-border-info` - Focus outline color
+- `--rel-text-default` - Box border and label text color (rest)
+- `--rel-text-body` - Hover color for box, label, and icon
+- `--rel-bg-neutral-inverse-2` - Checked box fill and indeterminate dash
+- `--rel-text-inverse` - Checkmark color
+- `--rel-text-caption` - Supporting text color
+- `--rel-border-focus` - Focus outline color
+- `--rel-border-danger` / `--rel-action-danger-fill` / `--rel-text-danger` - Error state colors
 
 ## Accessibility
 - Uses visually hidden native checkbox input for screen reader support
 - Custom visual checkbox with proper focus indicators
 - Focus visible state with outline offset for keyboard users
-- Label click targets the checkbox for larger interaction area
+- Label click targets the checkbox for larger interaction area (in trailing alignment the whole row is clickable)
 - Disabled state communicated through opacity reduction and cursor change
 
 ### Keyboard Interactions
@@ -67,12 +108,18 @@ None exposed.
 
 ### Focus Behavior
 - Focus outline appears with offset around the custom checkbox box
-- Uses info border color for high contrast
+- Uses focus border color for high contrast
 
 ## Notes / Edge Cases
-- Clicking cycles through three states in order: unchecked → checked → indeterminate → unchecked (repeating)
+- User toggling is binary: indeterminate is never entered by interaction — toggling from indeterminate resolves to checked. Set `status="indeterminate"` programmatically (e.g. a Select-All parent driven by app state)
 - When `state="disabled"`, click events are blocked and opacity is reduced to 0.55
-- The indeterminate state displays a horizontal line instead of a checkmark
-- In error state, the checkbox border and checked background use error color
-- Supporting text is positioned below with left padding to align with checkbox content
-- Native checkbox input is visually hidden but maintains accessibility features
+- The host is `display: block`, so a trailing checkbox stretches to its container width; constrain the parent to control row width
+- Comfortable density with no supporting text is visually identical to compact
+- The hidden native input is absolutely positioned against the `.row` containing block; keep `position: relative` on `.row` (Tab-scroll page-jump fix, shared with rel-radio)
+
+## Recipes (intentionally NOT component props)
+- **Selectable list row**: `alignment="trailing"` checkbox inside a padded, hover-highlighted container
+- **Select All / nested group**: parent checkbox with `status="indeterminate"` wired to children in app state
+- **Selectable card**: `rel-card` wrapping a checkbox; toggle a selected border on `rel-change`
+
+See the Storybook Checkbox stories for working recipe markup.

package/dist/components/rel-checkbox/rel-checkbox.ts

@@ -1,9 +1,12 @@
-import { LitElement, html, css } from "lit";
+import { LitElement, html, css, nothing, type PropertyValues } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import "@reliability-design/icons/rel-icon";
 
 type CheckboxState = "default" | "error" | "disabled";
 type CheckboxStatus = "unchecked" | "checked" | "indeterminate";
+type CheckboxSize = "small" | "medium";
+type CheckboxDensity = "compact" | "comfortable";
+type CheckboxAlignment = "leading" | "trailing";
 
 @customElement("rel-checkbox")
 export class RelCheckbox extends LitElement {
@@ -15,6 +18,21 @@ export class RelCheckbox extends LitElement {
   @property({ type: String }) status: CheckboxStatus = "unchecked";
   @property({ type: String }) value = "";
 
+  /** Control scale (Figma Size). `"medium"` (default) = 18px box with body-lg
+   *  label; `"small"` = 14px box with body-md label. */
+  @property({ type: String, reflect: true }) size: CheckboxSize = "medium";
+
+  /** 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. */
+  @property({ type: String, reflect: true }) density: CheckboxDensity = "compact";
+
+  /** 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. */
+  @property({ type: String, reflect: true }) alignment: CheckboxAlignment = "leading";
+
   get checked(): boolean {
     return this.status === "checked";
   }
@@ -53,6 +71,29 @@ export class RelCheckbox extends LitElement {
       cursor: pointer;
     }
 
+    /* Trailing alignment — box moves to the far edge, label stack to the
+       start. row-reverse keeps the box first in DOM order (input + .box
+       adjacency drives the focus ring) while space-between stretches the
+       row to its container. */
+    :host([alignment="trailing"]) .row {
+      flex-direction: row-reverse;
+      justify-content: space-between;
+    }
+
+    /* Comfortable density — label and supporting text stack beside the box. */
+    .content {
+      display: flex;
+      flex-direction: column;
+      gap: var(--rel-spacing-3xs);
+      min-width: 0;
+    }
+
+    .label-line {
+      display: flex;
+      align-items: center;
+      gap: var(--rel-spacing-xs);
+    }
+
     input {
       position: absolute;
       inset: 0;
@@ -195,7 +236,6 @@ export class RelCheckbox extends LitElement {
 
     .text {
       color: var(--rel-text-caption);
-      padding-left: 28px;
 
       font-family: var(--rel-body-sm-regular-font-family);
 
@@ -208,8 +248,63 @@ export class RelCheckbox extends LitElement {
       letter-spacing: var(--rel-body-sm-regular-letter-spacing);
 
     }
+
+    /* Compact density — supporting text sits under the whole row, indented
+       past the box (box width + row gap, matching the pre-existing 28px). */
+    .text-below {
+      padding-left: 28px;
+    }
+
+    /* Size variant (medium is the base scale above). */
+    :host([size="small"]) .box {
+      width: 14px;
+      height: 14px;
+      border-radius: 3px;
+    }
+
+    :host([size="small"]) svg {
+      width: 10px;
+      height: 10px;
+    }
+
+    :host([size="small"]) .label {
+      font-family: var(--rel-body-md-regular-font-family);
+      font-weight: var(--rel-body-md-regular-font-weight);
+      font-size: var(--rel-body-md-regular-font-size);
+      line-height: var(--rel-body-md-regular-line-height);
+      letter-spacing: var(--rel-body-md-regular-letter-spacing);
+    }
+
+    :host([size="small"]) .text {
+      font-family: var(--rel-body-xs-regular-font-family);
+      font-weight: var(--rel-body-xs-regular-font-weight);
+      font-size: var(--rel-body-xs-regular-font-size);
+      line-height: var(--rel-body-xs-regular-line-height);
+      letter-spacing: var(--rel-body-xs-regular-letter-spacing);
+    }
+
+    :host([size="small"]) .text-below {
+      padding-left: 24px;
+    }
   `;
 
+  protected willUpdate(changed: PropertyValues<this>) {
+    if (
+      (changed.has("alignment") || changed.has("density")) &&
+      this.alignment === "trailing" &&
+      this.density === "compact"
+    ) {
+      console.warn(
+        '[rel-checkbox] density="compact" has no trailing layout; rendering comfortable density.'
+      );
+    }
+  }
+
+  /** Trailing has no compact layout in the spec — trailing wins. */
+  private get effectiveDensity(): CheckboxDensity {
+    return this.alignment === "trailing" ? "comfortable" : this.density;
+  }
+
   private toggle() {
     if (this.state === "disabled") return;
 
@@ -239,6 +334,9 @@ export class RelCheckbox extends LitElement {
         <label class="row">
           <input
             type="checkbox"
+            .checked=${this.status === "checked"}
+            .indeterminate=${this.status === "indeterminate"}
+            aria-checked="${this.status === "indeterminate" ? "mixed" : nothing}"
             @click=${this.toggle}
             @blur=${() => this._onTouched()}
             ?disabled=${this.state === "disabled"}
@@ -256,15 +354,27 @@ export class RelCheckbox extends LitElement {
             </svg>
           </span>
 
-          ${this.icon
-            ? html`<rel-icon name="${this.icon}" size="md" class="icon-prefix"></rel-icon>`
-            : null}
-
-          <span part="label" class="label">${this.label}</span>
+          <span class="content">
+            <span class="label-line">
+              ${this.icon
+                ? html`<rel-icon
+                    name="${this.icon}"
+                    size="${this.size === "small" ? "sm" : "md"}"
+                    class="icon-prefix"
+                  ></rel-icon>`
+                : null}
+
+              <span part="label" class="label">${this.label}</span>
+            </span>
+
+            ${this.effectiveDensity === "comfortable" && this.supportingtext
+              ? html`<span part="helper" class="text">${this.supportingtext}</span>`
+              : null}
+          </span>
         </label>
 
-        ${this.supportingtext
-          ? html`<span part="helper" class="text">${this.supportingtext}</span>`
+        ${this.effectiveDensity === "compact" && this.supportingtext
+          ? html`<span part="helper" class="text text-below">${this.supportingtext}</span>`
           : null}
       </div>
     `;