@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,166 +1,186 @@
-# rel-carousel
-
-A fully accessible carousel component built with Lit for the Reliability Design System.
-
-## Features
-
-- Horizontal sliding carousel
-- Touch/mouse drag support
-- Keyboard navigation
-- Optional autoplay
-- Navigation buttons and dot indicators
-- Loop mode
-- Smooth transitions with reduced motion support
-- Full ARIA support
-
-## Usage
-
-```html
-<rel-carousel>
-  <div>Slide 1</div>
-  <div>Slide 2</div>
-  <div>Slide 3</div>
-</rel-carousel>
-```
-
-### With Loop
-
-```html
-<rel-carousel loop>
-  <div>Slide 1</div>
-  <div>Slide 2</div>
-  <div>Slide 3</div>
-</rel-carousel>
-```
-
-### With Autoplay
-
-```html
-<rel-carousel autoplay interval="3000">
-  <div>Slide 1</div>
-  <div>Slide 2</div>
-  <div>Slide 3</div>
-</rel-carousel>
-```
-
-### Without Navigation
-
-```html
-<rel-carousel show-buttons="false" show-dots="false">
-  <div>Slide 1</div>
-  <div>Slide 2</div>
-  <div>Slide 3</div>
-</rel-carousel>
-```
-
-### Programmatic Control (JavaScript)
-
-```javascript
-const carousel = document.querySelector('rel-carousel');
-
-// Navigate to specific slide
-carousel.value = 2;
-
-// Listen to changes
-carousel.addEventListener('rel-change', (e) => {
-  console.log('Current slide:', e.detail.value);
-});
-```
-
-## Attributes
-
-| Attribute | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `value` | `number` | `0` | Current slide index (0-based) |
-| `loop` | `boolean` | `false` | Enable infinite loop |
-| `autoplay` | `boolean` | `false` | Enable automatic slide advancement |
-| `interval` | `number` | `5000` | Autoplay interval in milliseconds |
-| `pause-on-hover` | `boolean` | `true` | Pause autoplay on mouse hover |
-| `show-buttons` | `boolean` | `true` | Show prev/next navigation buttons |
-| `show-dots` | `boolean` | `true` | Show dot indicators |
-| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Carousel orientation (v1: horizontal only) |
-| `align` | `"start" \| "center" \| "end"` | `"center"` | Slide alignment in viewport |
-| `slides-per-view` | `number` | `1` | Number of slides visible at once (v1: 1 only) |
-| `gap` | `number` | - | Gap between slides in pixels (optional) |
-| `disabled` | `boolean` | `false` | Disable all interactions |
-
-## Events
-
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `rel-change` | `{ value: number }` | Fired when active slide changes |
-
-## Keyboard Navigation
-
-- **Arrow Left**: Go to previous slide
-- **Arrow Right**: Go to next slide
-- **Home**: Go to first slide
-- **End**: Go to last slide
-- **Tab**: Navigate through carousel controls
-
-## CSS Parts
-
-Use `::part()` to customize carousel appearance:
-
-```css
-rel-carousel::part(viewport) {
-  border-radius: 12px;
-}
-
-rel-carousel::part(prev-button),
-rel-carousel::part(next-button) {
-  background: rgba(0, 0, 0, 0.5);
-  color: white;
-}
-
-rel-carousel::part(dot) {
-  width: 10px;
-  height: 10px;
-}
-```
-
-Available parts:
-- `viewport` - The carousel viewport container
-- `track` - The sliding track container
-- `prev-button` - Previous navigation button
-- `next-button` - Next navigation button
-- `dots` - Dots container
-- `dot` - Individual dot indicator
-
-## Accessibility
-
-- Carousel uses `role="region"` with `aria-roledescription="carousel"`
-- Each slide has proper ARIA labels
-- Navigation buttons have descriptive `aria-label` attributes
-- Supports keyboard navigation
-- Respects `prefers-reduced-motion` user preference
-
-## Styling
-
-The component uses design tokens from the Reliability Design System. All colors, spacing, and typography are inherited from CSS variables.
-
-Key tokens used:
-- `--rel-bg-*` / `--rel-text-*` / `--rel-border-*` semantic colors
-- `--rel-spacing-*` for spacing
-- `--rel-shadows-*` for shadows
-- `--rel-border-*` for borders
-- Focus outline uses `--rel-bg-info`
-- Active dot uses `--rel-bg-brand`
-
-## Interaction
-
-### Mouse/Touch Drag
-- Click and drag to swipe between slides
-- Threshold-based snap: swipe 20% of slide width to trigger navigation
-- Smooth animation on release
-
-### Autoplay
-- Automatically advances slides at specified interval
-- Pauses on hover (configurable via `pause-on-hover`)
-- Pauses during manual interaction
-- Resumes after interaction ends
-
-### Reduced Motion
-- Component respects `prefers-reduced-motion` media query
-- Disables or reduces transitions when user prefers reduced motion
-- Drag interactions remain functional but with instant snap
+# rel-carousel
+
+A slide carousel implementing the Figma "Carousel" component and its three axes — `Type` (Default, Only Indicators, Side Arrows, Bottom Arrows), `Orientation` (Horizontal, Vertical) and `Multi Panels` — plus the `Show Dots` property. It shows one or more slotted slides at a time in a horizontal or vertical viewport and moves between them with arrows, dot indicators, pointer drag / swipe, the keyboard, or autoplay. Use it for a small, ordered set of equally important panels (hero images, onboarding cards, testimonials); do not use it as a substitute for tabs or for content the user must read in full — hidden slides are not reachable by page search or by screen readers until they are shown.
+
+## Usage
+
+```html
+<!-- Default type: slides only — swipe, drag or use the arrow keys -->
+<rel-carousel label="Product photos">
+  <img src="/photos/front.jpg" alt="Front view">
+  <img src="/photos/side.jpg" alt="Side view">
+  <img src="/photos/back.jpg" alt="Back view">
+</rel-carousel>
+
+<!-- Figma Type axis: overlaid arrows + dots -->
+<rel-carousel type="side-arrows" label="Highlights">
+  <div><h3>Fast setup</h3><p>Up and running in minutes.</p></div>
+  <div><h3>Secure by default</h3><p>Encrypted at rest and in transit.</p></div>
+  <div><h3>Works everywhere</h3><p>One component, every framework.</p></div>
+</rel-carousel>
+
+<!-- Dots flanked by arrows under the slide -->
+<rel-carousel type="bottom-arrows" label="Testimonials">
+  <blockquote>"Saved us a week." — Ada</blockquote>
+  <blockquote>"Zero regressions." — Grace</blockquote>
+</rel-carousel>
+
+<!-- Dots only -->
+<rel-carousel type="only-indicators" label="Tips">
+  <p>Tip 1</p>
+  <p>Tip 2</p>
+  <p>Tip 3</p>
+</rel-carousel>
+
+<!-- Arrows on their own: show-dots="false" suppresses the dots the type implies -->
+<rel-carousel type="side-arrows" show-dots="false" label="Highlights">
+  <div>Fast setup</div>
+  <div>Secure by default</div>
+</rel-carousel>
+
+<!-- Loop and autoplay (3 s), 16px between slides, start on the second slide -->
+<rel-carousel type="side-arrows" loop autoplay interval="3000" gap="16" value="1" label="Promotions">
+  <div>Spring sale</div>
+  <div>Free shipping</div>
+  <div>New arrivals</div>
+</rel-carousel>
+
+<!-- Figma Multi Panels: 1.5 panels leaves the next slide peeking in -->
+<rel-carousel type="side-arrows" panels="1.5" label="Related products">
+  <div>Product A</div>
+  <div>Product B</div>
+  <div>Product C</div>
+  <div>Product D</div>
+</rel-carousel>
+
+<!-- Two whole panels at a time, no peek -->
+<rel-carousel type="only-indicators" panels="2" label="Case studies">
+  <div>Case A</div>
+  <div>Case B</div>
+  <div>Case C</div>
+  <div>Case D</div>
+</rel-carousel>
+
+<!-- Vertical: the viewport height comes from --rel-carousel-height -->
+<rel-carousel orientation="vertical" type="side-arrows" label="Timeline" style="--rel-carousel-height: 240px">
+  <div>2024</div>
+  <div>2025</div>
+  <div>2026</div>
+</rel-carousel>
+
+<!-- Programmatic control -->
+<rel-carousel id="gallery" type="bottom-arrows" label="Gallery">
+  <div>A</div>
+  <div>B</div>
+  <div>C</div>
+</rel-carousel>
+<script>
+  const gallery = document.getElementById('gallery');
+  gallery.value = 2;                       // jump to the third slide
+  gallery.pauseOnHover = false;            // default-true booleans are switched off via the property
+  gallery.addEventListener('rel-change', (e) => {
+    console.log('Current slide:', e.detail.value);
+  });
+</script>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-carousel.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | `number` | `0` | Index of the current slide (0-based). Set it to jump; it is clamped to the slide count and reflected as an attribute. Reflected. |
+| `loop` | `loop` | `boolean` | `false` | Wrap from the last slide to the first (and back) with a seamless clone transition instead of stopping at the ends. |
+| `autoplay` | `autoplay` | `boolean` | `false` | Advance automatically every `interval` ms; implies looping and pauses while hovered (see `pause-on-hover`) or while focus is inside the carousel. |
+| `interval` | `interval` | `number` | `5000` | Autoplay delay between slides, in milliseconds (default 5000). |
+| `pauseOnHover` | `pause-on-hover` | `boolean` | `true` | Pause autoplay while the pointer is over the carousel or while dragging (default true; switch off via the property, e.g. `el.pauseOnHover = false`). |
+| `showButtons` | `show-buttons` | `boolean` | `false` | Legacy toggle for the overlaid previous / next arrows; ignored whenever `type` is set. |
+| `showDots` | `show-dots` | `boolean` | `undefined` | 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. |
+| `type` | `type` | `"default" \| "only-indicators" \| "side-arrows" \| "bottom-arrows"` | `undefined` | 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 boolean applies unchanged. The dots a type implies can always be overridden by an explicit `show-dots`. Reflected. |
+| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Slide axis: `horizontal` (default) translates the track left / right; `vertical` stacks slides in a fixed-height viewport (`--rel-carousel-height`) and translates up / down. Reflected. |
+| `label` | `label` | `string` | `"Carousel"` | Accessible name of the carousel region (`aria-label` on the viewport); default "Carousel". |
+| `gap` | `gap` | `number` | `8` | 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. |
+| `panels` | `panels` | `number` | `1` | 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. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables arrows, dots, drag and keyboard navigation, stops autoplay and renders the carousel at 60% opacity. Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `{ value: this.value }` | bubbles / composed | Fired whenever the current slide changes (arrows, dots, drag, keyboard, autoplay or a loop wrap). Detail: `{ value: number }` — the new 0-based slide index. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | The slides: one light-DOM element per slide (each is sized to one panel and given `role="group"` / `aria-roledescription="slide"`). |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `${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). |
+| `viewport` | The focusable `role="region"` box that clips the track (also the keyboard target). |
+| `track` | The flex row / column that translates to reveal the current slide. |
+| `dots` | The indicator row under the viewport (also hosts the arrows for `type="bottom-arrows"`). |
+| `dot-group` | The row of dots inside `dots` (for `type="bottom-arrows"` it is the middle child, between the two arrows). |
+| `dot` | One indicator button per reachable position (per slide at `panels="1"`); the active one carries the `active` class and `aria-current="true"`. |
+
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-carousel-dot-size` | `8px` | Diameter of an inactive dot (default 8px). |
+| `--rel-carousel-dot-size-active` | `16px` | Width of the active (brand-coloured, pill-shaped) dot (default 16px). |
+| `--rel-carousel-height` | `320px` | Viewport height in `orientation="vertical"` (default 320px); the horizontal viewport takes the height of its tallest slide. |
+| `--rel-carousel-nav-size` | `32px` | Width / height of the arrow buttons (default 32px, matching Figma; applies to both side and bottom arrows). |
+| `--rel-carousel-slide-bg` | `var(--rel-bg-neutral)` | — |
+| `--rel-carousel-slide-height` | `100%` | Written by the component on its own host to the computed panel height (used for vertical slides); not meant to be set by consumers. |
+| `--rel-carousel-slide-radius` | `var(--rel-border-radius-sm)` | — |
+| `--rel-carousel-slide-width` | `100%` | Written by the component on its own host to the computed panel width (viewport width for `panels="1"`, a fraction of it above that); not meant to be set by consumers (an inline value is overwritten on resize). |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The viewport renders with `role="region"`, `aria-roledescription="carousel"` and `aria-label` set from the `label` prop (default "Carousel"); give every carousel a meaningful `label`.
+- Each slotted slide is decorated with `role="group"`, `aria-roledescription="slide"` and `aria-label="n of N"`; the clone slides used for looping are `aria-hidden="true"`.
+- The arrow buttons are labelled "Previous slide" / "Next slide" and their chevrons are `aria-hidden`; each dot is labelled "Go to slide n" and the active dot carries `aria-current="true"`.
+- The viewport is a single Tab stop (`tabindex="0"`); the arrows and dots that are rendered are ordinary buttons and follow it in the Tab order.
+- Every user-initiated slide change is announced through the shared live region as "Slide n of N"; autoplay ticks are deliberately silent.
+- Autoplay pauses while the pointer is over the carousel (`pause-on-hover`, default on) and while keyboard focus is anywhere inside it (WCAG 2.2.2 Pause, Stop, Hide); it resumes when focus leaves.
+- Track transitions are disabled under `prefers-reduced-motion: reduce`; drag still snaps to the nearest slide, just without animation.
+
+| Key | Action |
+| --- | --- |
+| `ArrowLeft` / `ArrowUp` | Previous slide (wraps when `loop` or `autoplay` is set) |
+| `ArrowRight` / `ArrowDown` | Next slide (wraps when `loop` or `autoplay` is set) |
+| `Home` | First slide |
+| `End` | Last slide |
+| `Tab` | Move between the viewport, the arrows and the dots |
+
+Keys are handled on the viewport (and anything focused inside it) and are ignored while `disabled`.
+
+## Notes / Edge Cases
+
+- `type` is the canonical control switch. When it is unset the legacy `show-buttons` boolean still decides whether arrows render; when it is set `show-buttons` is ignored (`type="default"` hides the arrows).
+- `show-dots` is deliberately tri-state, because Figma's `Show Dots` is a property rather than part of the `Type` axis. Omit it and `type` decides, exactly as before; write `show-dots` to force the dots on; write `show-dots="false"` to force them off even for a `type` that would have shown them. Omitting it is what every pre-existing carousel does, so none of them change.
+- `panels` implements the Figma `Multi Panels` axis. Each panel measures `(viewport − gap × (ceil(panels) − 1)) / panels` along the scroll axis — a viewport showing `n` panels contains `ceil(n) − 1` whole gaps, so at the Figma frame width of 350px with the default 8px gap, `panels="1.5"` yields exactly the 228px slide the design specifies.
+- Navigation always advances one slide per step, never one page. Without `loop`, the track stops once the last slide is flush with the trailing edge instead of scrolling into empty space, so at `panels="1.5"` with three slides the reachable indices are `0` and `1`. The dot row follows that: one dot per reachable position, which is one per slide at `panels="1"` and whenever `loop` is on.
+- Slides are sized by the component: every slotted element gets `width: var(--rel-carousel-slide-width)` (or the height equivalent in `orientation="vertical"`) with `!important`, where the variable is written on the host to the computed panel size. Style the inside of a slide freely, but do not rely on a slide's own `width` / `height`.
+- `loop` and `autoplay` clone the edge slides into the shadow DOM so the wrap looks continuous — `ceil(panels)` of them at each end, since a viewport showing more than one panel would otherwise run out of slides mid-transition. `rel-change` still reports the real index (`0` … `N-1`) after the silent jump.
+- Drag / swipe uses a 20% threshold of the panel size; shorter drags snap back. Dragging pauses autoplay (when `pause-on-hover` is on) and resumes it on release.
+- `value` is clamped to the highest reachable index whenever the slot content changes; setting it out of range moves to the nearest valid slide.
+- Arrows are 32px circles with a 16px chevron, matching Figma. Side arrows (`type="side-arrows"`) overlay the viewport at the vertical centre, inset 8px from the edge; bottom arrows (`type="bottom-arrows"`) sit inside the indicator row, 20px from the dots. Both are hand-rolled ghost-style buttons, not `<rel-button>`, and both are sized by `--rel-carousel-nav-size`. Per the published Figma set the arrows stay on the left and right edges in `orientation="vertical"` too.
+- The active dot is a 16 × 8 fully-rounded brand pill and an inactive dot an 8px circle; `--rel-carousel-dot-size-active` and `--rel-carousel-dot-size` override them.
+- The horizontal viewport takes the height of its tallest slide; the vertical viewport is a fixed `--rel-carousel-height` (320px) — set it to fit your content.
+- Arrow buttons are exposed as `::part(prev-button)` and `::part(next-button)`; the indicator row is `::part(dots)`, the dots inside it `::part(dot-group)` and `::part(dot)`.

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

@@ -1,11 +1,11 @@
 # rel-checkbox
 
-## Overview
-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.
+A tri-state checkbox implementing the Figma "Checkbox" sheet: a hidden native `<input type="checkbox">` behind a custom box, with a label, an optional label-prefix icon and optional supporting text. It exposes the sheet's vocabulary verbatim — `size` (small / medium / large / extra-large), `density` (compact / comfortable) and `alignment` (leading / trailing) — plus `state` for error and disabled styling. Use it for independent yes/no choices and for "select all" parents (via `status="indeterminate"`); for a single choice among several options use `rel-radio`, and for an immediate on/off setting use `rel-switch`.
 
 ## Usage
+
 ```html
-<!-- Basic example -->
+<!-- Basic -->
 <rel-checkbox label="Accept terms"></rel-checkbox>
 
 <!-- Supporting text, compact density (default: text on its own line, indented past the box) -->
@@ -31,95 +31,116 @@ A tri-state checkbox component supporting checked, unchecked, and indeterminate
   supportingtext="Weekly summary of load activity">
 </rel-checkbox>
 
-<!-- Small size -->
+<!-- Sizes (medium is the default) -->
 <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>
+<rel-checkbox size="large" label="I agree to the terms"></rel-checkbox>
+
+<!-- Label prefix icon -->
+<rel-checkbox icon="truck" label="Truckload only"></rel-checkbox>
+
+<!-- Error and disabled states -->
+<rel-checkbox state="error" label="Required consent"></rel-checkbox>
+<rel-checkbox state="disabled" status="checked" label="Locked by admin"></rel-checkbox>
+
+<!-- Indeterminate (programmatic-only; a user toggle resolves to checked/unchecked) -->
+<rel-checkbox id="select-all" label="Select all" status="indeterminate"></rel-checkbox>
+<script>
+  document.getElementById('select-all').addEventListener('rel-change', (e) => {
+    console.log(e.detail.checked, e.detail.value);
+  });
+</script>
 ```
 
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-checkbox.ts — do not edit; run readme-generate.mjs -->
+
 ## API
 
-### Attributes/Properties
-| 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; 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 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 |
+### Attributes / Properties
 
-### Layout matrix (mirrors the Figma sheet)
-| Size | Density | Leading | Trailing |
-|------|---------|---------|----------|
-| M | Comfortable | ✓ | ✓ |
-| M | Compact | ✓ (default) | — renders comfortable |
-| S | Comfortable | ✓ | ✓ |
-| S | Compact | ✓ | — renders comfortable |
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `"Label"` | Label text rendered next to the box. |
+| `icon` | `icon` | `string` | `""` | rel-icon name rendered between the checkbox and the label (label prefix icon); scales with `size`. Unset renders no icon and reserves no space. |
+| `supportingtext` | `supportingtext` | `string` | `""` | Supporting text under or beside the label; where it renders depends on `density`. |
+| `state` | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Visual and interaction state (Figma State): `"error"` swaps in the danger colours, `"disabled"` blocks input and dims the whole control to 0.4 opacity (colours unchanged, as Figma specifies). |
+| `status` | `status` | `"unchecked" \| "checked" \| "indeterminate"` | `"unchecked"` | Check state. `"indeterminate"` is programmatic-only — a user toggle always resolves to checked or unchecked. |
+| `value` | `value` | `string` | `""` | Value reported in the `rel-change` event detail (it is not submitted with a form). |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "extra-large"` | `"medium"` | Control scale (Figma Size), on Figma's four-step ramp of control frames: `"small"` 16px / body-sm, `"medium"` (default) 18px / body-md, `"large"` 20px / body-lg, `"extra-large"` 24px / body-xl. The drawn square is inset to 80% of the frame, so the frame is the layout footprint (what the row gap and the compact indent measure from) rather than the visible square. Reflected. |
+| `density` | `density` | `"compact" \| "comfortable"` | `"compact"` | Supporting-text layout (Figma Density). `"compact"` (default) puts the supporting text on its own line under the row, indented past the box; `"comfortable"` stacks label + supporting text beside the box. Reflected. |
+| `alignment` | `alignment` | `"leading" \| "trailing"` | `"leading"` | Box position (Figma Alignment). `"leading"` (default) renders the box before the label; `"trailing"` pushes it to the far edge of the row. Trailing has no compact layout in the spec, so it always renders with comfortable density. Reflected. |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `checked` | `boolean` | Boolean view of `status`: `true` when `status === "checked"`; setting it writes `"checked"` / `"unchecked"`. |
 
 ## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `rel-change` | `{ checked: boolean, value: string }` | Fired on user toggle (bubbles, composed) |
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `{ checked: this.status === "checked", value: this.value, }` | bubbles / composed | Fired after a user toggle. Detail: `{ checked: boolean, value: string }`. |
 
 ## Slots
-Default slot not used.
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
 
 ## CSS Parts
-- `base` — outer wrapper
-- `label` — label text span
-- `helper` — supporting text span
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--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-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
+
+| Part | Description |
+| --- | --- |
+| `base` | The outer wrapper that carries the `state` / `status` classes |
+| `label` | The visible label text |
+| `helper` | The supporting text (rendered beside the box in comfortable density, under the row in compact) |
+
+<!-- readme-gen:end -->
 
 ## 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 (in trailing alignment the whole row is clickable)
-- Disabled state communicated through opacity reduction and cursor change
 
-### Keyboard Interactions
-- `Space` - Toggle checkbox state
-- `Tab` - Move focus to/from checkbox
+- A visually hidden native `<input type="checkbox">` carries the semantics; the custom box is decorative. The input is wrapped in a `<label>`, so clicking anywhere on the row (label, icon or box — the whole row in trailing alignment) toggles it.
+- `status="indeterminate"` sets the native `indeterminate` flag and `aria-checked="mixed"` on the input, so screen readers announce the mixed state.
+- `state="disabled"` sets the native `disabled` attribute (the input leaves the tab order) and blocks pointer events on the whole element.
+- Focus: `:focus-visible` on the hidden input draws a 2px `--rel-border-focus` outline with a 2px offset around the box.
+- No live-region announcements are made; the native checkbox reports its own state changes.
 
-### Focus Behavior
-- Focus outline appears with offset around the custom checkbox box
-- Uses focus border color for high contrast
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move focus to / from the checkbox |
+| `Space` | Toggle between checked and unchecked (native behaviour; indeterminate resolves to checked) |
 
 ## Notes / Edge Cases
-- 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 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`
+
+- User toggling is binary: indeterminate is never entered by interaction. Set `status="indeterminate"` programmatically (e.g. a Select-All parent driven by app state).
+- `checked` is a convenience accessor over `status` (used by the Angular ControlValueAccessor wrapper); reading it is `status === "checked"`, writing it sets `"checked"` / `"unchecked"`.
+- `alignment="trailing"` with `density="compact"` is "Not available" in the Figma sheet: the element renders comfortable density and logs `[rel-checkbox] density="compact" has no trailing layout; rendering comfortable density.` once per change.
+- Comfortable density with no supporting text is visually identical to compact.
+- The host is `display: block`, so a trailing checkbox stretches to its container width; constrain the parent to control row width.
+- `value` is only reported in the `rel-change` detail — the element does not participate in native form submission.
+- The hidden native input is absolutely positioned against the `.row` containing block; keep `position: relative` on `.row` (Tab-scroll page-jump fix, shared with rel-radio).
+- Control frames are 16 / 18 / 20 / 24px for small / medium / large / extra-large, matching Figma. The frame is the layout footprint — the row gap and the compact indent measure from it — while the drawn square is inset to 80% of the frame (12.8 / 14.4 / 16 / 19.2px), as Figma draws it.
+- The square's 2px border weight is **not** verified against Figma: the control is flattened artwork (a filled vector rather than a frame with a stroke), so the sheet gives the square's outer size but says nothing about its stroke. Carried forward from the previous implementation.
+
+### Layout matrix (mirrors the Figma sheet)
+
+| Size | Density | Leading | Trailing |
+| --- | --- | --- | --- |
+| M | Comfortable | yes | yes |
+| M | Compact | yes (default) | renders comfortable |
+| S | Comfortable | yes | yes |
+| S | Compact | yes | renders comfortable |
+| L | Comfortable | yes | yes |
+| L | Compact | yes | renders comfortable |
+| XL | Comfortable | yes | yes |
+| XL | Compact | yes | renders comfortable |
+
+### Recipes (intentionally not component props)
+
+- **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.