@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,160 +1,162 @@
-# rel-stepper
-
-## Overview
-A comprehensive stepper component for visualizing multi-step processes. Supports horizontal and vertical orientations, text positioning (below or right of indicator), two size variants, and three step states (done, progress, disabled). Features clickable steps, automatic connector lines, and checkmark icons for completed steps.
-
-## Usage
-```html
-<!-- Basic horizontal stepper -->
-<rel-stepper id="checkout"></rel-stepper>
-<script>
-  const stepper = document.getElementById('checkout');
-  stepper.steps = [
-    { title: 'Cart', status: 'done' },
-    { title: 'Shipping', status: 'progress' },
-    { title: 'Payment', status: 'disabled' },
-    { title: 'Confirmation', status: 'disabled' }
-  ];
-</script>
-
-<!-- Vertical stepper with text to the right -->
-<rel-stepper
-  id="onboarding"
-  orientation="vertical"
-  textAlign="right">
-</rel-stepper>
-<script>
-  const onboarding = document.getElementById('onboarding');
-  onboarding.steps = [
-    { title: 'Create Account', status: 'done' },
-    { title: 'Verify Email', status: 'done' },
-    { title: 'Profile Setup', status: 'progress' },
-    { title: 'Complete', status: 'disabled' }
-  ];
-</script>
-
-<!-- Small size horizontal stepper -->
-<rel-stepper
-  id="wizard"
-  size="small"
-  textAlign="below">
-</rel-stepper>
-<script>
-  const wizard = document.getElementById('wizard');
-  wizard.steps = [
-    { title: 'Select', status: 'done' },
-    { title: 'Configure', status: 'progress' },
-    { title: 'Review', status: 'disabled' }
-  ];
-</script>
-
-<!-- Listen for step clicks -->
-<rel-stepper id="interactive"></rel-stepper>
-<script>
-  const interactive = document.getElementById('interactive');
-  interactive.steps = [
-    { title: 'Step 1', status: 'done' },
-    { title: 'Step 2', status: 'progress' },
-    { title: 'Step 3', status: 'disabled' }
-  ];
-  interactive.addEventListener('step-change', (e) => {
-    console.log('Clicked step:', e.detail.index, e.detail.step);
-    // Update step statuses or navigate to step content
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `steps` | `Step[]` | `[]` | Array of step items (see Step interface below) |
-| `textAlign` | `"right" \| "below"` | `"below"` | Position of step labels relative to indicators |
-| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction |
-| `size` | `"small" \| "large"` | `"large"` | Size variant (controls connector line length and spacing) |
-
-### Step Interface
-```typescript
-interface Step {
-  title: string;                               // Step label text
-  status: "done" | "progress" | "disabled";   // Step state
-}
-```
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `step-change` | `{ index: number, step: Step }` | Fired when a non-disabled step is clicked |
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-sm-regular-font-size` - Label font size
-- `--rel-fonts-weight-body-medium` - Default label font weight
-- `--rel-fonts-weight-body-semibold` - Active/done label font weight
-
-### Spacing Tokens
-- `--rel-spacing-2xs` - Gap between indicators and labels (text-right mode)
-
-### Color Tokens
-- `--rel-bg-surface` - Indicator background (progress, disabled states)
-- `--rel-text-default` - Active/done indicator background, text, and connector color
-- `--rel-border-default` - Disabled indicator border and inactive connector
-- `--rel-bg-surface-elevated` - Disabled indicator background
-- `--rel-text-disabled` - Disabled label text color
-- `--rel-text-default` - Default label text color
-
-## Accessibility
-- Steps can be clicked unless in disabled state
-- Checkmark SVG uses `currentColor` for proper theming
-- Focus states could be enhanced with keyboard navigation (not currently implemented)
-
-### Keyboard Interactions
-- Click-based interaction only (no keyboard navigation implemented)
-
-### Focus Behavior
-- No specific focus handling (steps are div elements, not buttons)
-
-## Notes / Edge Cases
-- **Indicator states**:
-  - **done**: Black circle with white checkmark SVG icon
-  - **progress**: White circle with black border and step number
-  - **disabled**: Light gray circle with gray border and step number
-  
-- **Connector lines**:
-  - Positioned absolutely relative to the indicator
-  - **Horizontal**: 2px height, extends from indicator to next step
-  - **Vertical**: 2px width, extends from indicator to next step
-  - **done/progress** connectors are black; **disabled** connectors are gray
-  - Last step has no connector
-
-- **Size variants** (control connector length and gap):
-  - **large horizontal**: 86px connector, 86px gap
-  - **small horizontal**: 60px connector, 60px gap
-  - **large vertical**: 86px connector, 86px gap
-  - **small vertical**: 42px connector, 42px gap
-
-- **Text positioning**:
-  - **below**: Labels appear centered below indicators
-  - **right**: Labels appear to the right of indicators with a small gap
-
-- **Layout combinations**:
-  - **horizontal + text-below**: Steps arranged in a row, labels centered below
-  - **horizontal + text-right**: Steps in a row, labels to the right of each indicator
-  - **vertical + text-below**: Steps stacked vertically, labels centered below each indicator
-  - **vertical + text-right**: Steps stacked vertically, labels to the right with indicators on the left
-
-- The indicator is 22px × 22px with a 2px border
-- Step numbers are 1-indexed (displayed as `index + 1`)
-- Clicking a disabled step does nothing (no event dispatched)
-- All transitions use `0.2s ease`
-- The component uses flexbox extensively for layout management
-- The stepper is `display: block` and `width: 100%`
+# rel-stepper
+
+A multi-step progress indicator implementing the Figma "Stepper" component: its `Type` axis (default, dot, number, icon indicators), its `Typel` label-placement axis (top, centered, inverted), two sizes and both orientations. Each entry in `steps` renders as a focusable step with a circular indicator, a label and a connector to the next step, styled by its status (`done`, `progress`, `disabled`). Use it to show where the user is in a linear flow (checkout, onboarding, a wizard) and to let them jump back to completed steps; the component is presentation only — it never changes a step's status itself, so drive `steps` from your own state.
+
+## Usage
+
+```html
+<!-- Horizontal (default), labels under the indicators -->
+<rel-stepper id="checkout"></rel-stepper>
+<script>
+  document.getElementById('checkout').steps = [
+    { title: 'Cart', status: 'done' },
+    { title: 'Shipping', status: 'progress' },
+    { title: 'Payment', status: 'disabled' },
+    { title: 'Confirmation', status: 'disabled' }
+  ];
+</script>
+
+<!-- Vertical, label beside the indicator (Figma Type = Centered).
+     `size` is DEPRECATED and deliberately omitted: Figma has no Size axis on the
+     Stepper — the connector geometry is fixed — so it was a code-only scale. It is
+     still accepted so existing markup keeps working, but it now resolves to the one
+     Figma geometry and logs a one-time notice. Retune with
+     `--rel-stepper-connector-length` instead. -->
+<rel-stepper id="onboarding" orientation="vertical" label-placement="centered"></rel-stepper>
+<script>
+  document.getElementById('onboarding').steps = [
+    { title: 'Create account', status: 'done' },
+    { title: 'Verify email', status: 'done' },
+    { title: 'Set up profile', status: 'progress' },
+    { title: 'Done', status: 'disabled' }
+  ];
+</script>
+
+<!-- Figma Type axis: dot / number / icon indicators -->
+<rel-stepper type="dot" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
+<rel-stepper type="number" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
+<rel-stepper type="icon" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
+
+<!-- Label placement (Figma Typel): top-aligned beside the indicator, or indicator above the label -->
+<rel-stepper orientation="vertical" label-placement="top" steps='[{"title":"Review","status":"done"},{"title":"Approve","status":"progress"}]'></rel-stepper>
+<rel-stepper label-placement="inverted" steps='[{"title":"Review","status":"done"},{"title":"Approve","status":"progress"}]'></rel-stepper>
+
+<!-- Let users jump back to a completed step -->
+<rel-stepper id="wizard"></rel-stepper>
+<script>
+  const wizard = document.getElementById('wizard');
+  wizard.steps = [
+    { title: 'Select', status: 'done' },
+    { title: 'Configure', status: 'progress' },
+    { title: 'Review', status: 'disabled' }
+  ];
+  wizard.addEventListener('rel-step-change', (e) => {
+    console.log('Activated step', e.detail.index, e.detail.step.title);
+    // Recompute statuses and assign a new array so the stepper re-renders
+    wizard.steps = wizard.steps.map((s, i) => ({
+      ...s,
+      status: i < e.detail.index ? 'done' : i === e.detail.index ? 'progress' : 'disabled'
+    }));
+  });
+</script>
+```
+
+### Deprecated aliases
+
+```html
+<!-- textalign="right" → label-placement="centered"; textalign="below" → label-placement="inverted".
+     Still supported and still the fallback when label-placement is unset; no console notice is logged. -->
+<rel-stepper textalign="right" steps='[{"title":"Review","status":"done"},{"title":"Approve","status":"progress"}]'></rel-stepper>
+```
+
+The `Step` type and the `StepStatus`, `StepperType` and `LabelPlacement` unions are exported from the package:
+
+```typescript
+import type { Step } from '@reliability-design/web';
+
+const steps: Step[] = [
+  { title: 'Cart', status: 'done' },        // filled indicator with a check mark
+  { title: 'Shipping', status: 'progress' }, // current step (aria-current="step")
+  { title: 'Payment', status: 'disabled' }   // not yet reachable; rendered at 40% opacity, not focusable
+];
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-stepper.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `steps` | `steps` | `Step[]` | `[]` | 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. |
+| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout axis: `horizontal` (default) lays the steps out in a centred row; `vertical` stacks them. |
+| `type` | `type` | `"default" \| "dot" \| "number" \| "icon"` | `"default"` | 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). Reflected. |
+| `labelPlacement` | `label-placement` | `"top" \| "centered" \| "inverted"` | `undefined` | 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. Reflected. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `textAlign` | `textalign` | `"right" \| "below"` | Deprecated alias of `label-placement`; use `label-placement="inverted"` instead of `textalign="below"` and `label-placement="centered"` instead of `textalign="right"`. |
+| `size` | `size` | `"small" \| "large"` | 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. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-step-change` | `{ index, step, }` | bubbles / composed | Fired when a step whose status is not `disabled` is clicked or activated with Enter / Space. Detail: `{ index: number, step: Step }`. Statuses are not changed by the component — update `steps` in the handler. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `indicator` | The 24px circle (8px for `type="dot"`) that holds the step number, check mark or icon. |
+| `track` | The 1px connector line from a step to the next one (not rendered on the last step). |
+| `label` | The step title text. |
+| `subtitle` | The optional second line under the title; rendered only when a step sets `subtitle`. |
+
+## 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-stepper-connector-length` | `var(--rel-stepper-connector-length-lg, 96px)` | 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`. |
+| `--rel-stepper-indicator-size` | `24px` | Indicator diameter (default 24px; `type="dot"` is fixed at 8px). |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The list renders as a `role="group"` with the fixed name "Progress steps" (not configurable).
+- Every step is a `role="button"` element with `aria-label="<title>, step n of N"`, plus ", completed" for `done` steps. The `progress` step carries `aria-current="step"`; `disabled` steps carry `aria-disabled="true"` and `tabindex="-1"` so they are skipped in the Tab order and by the arrow keys.
+- Enabled steps are individual Tab stops (`tabindex="0"`) with a 2px focus ring; the indicators and connectors are purely visual (the check mark SVG is `aria-hidden`).
+- Activating a step only emits `rel-step-change`; nothing is announced and no status changes until you update `steps`.
+
+| Key | Action |
+| --- | --- |
+| `Enter` / `Space` | Activate the focused step (emits `rel-step-change`; ignored on `disabled` steps) |
+| `ArrowRight` / `ArrowDown` | Move focus to the next enabled step (wraps to the first) |
+| `ArrowLeft` / `ArrowUp` | Move focus to the previous enabled step (wraps to the last) |
+| `Home` / `End` | Move focus to the first / last enabled step |
+
+## Notes / Edge Cases
+
+- `label-placement` is the canonical layout switch (Figma `Typel`). When it is unset the deprecated `textalign` prop decides: `below` renders like `inverted` (indicator above the label), `right` renders like `centered` (label beside the indicator). `top` differs from `centered` only in aligning the label to the top of the indicator. Figma marks Top + Horizontal as an unsupported combination.
+- Statuses map to the Figma `.Artwork` states: `done` = inverse fill with a check mark (or the number when `type="number"`, nothing when `type="dot"`), `progress` = neutral fill with a strong 1px border, `disabled` = the same drawn at 40% opacity. Connectors are `border-strong` after a `done` / `progress` step and `border-default` otherwise.
+- `type="icon"` shows the check mark on every step regardless of status; `type="dot"` shrinks the indicator to 8px and fills it for `done` and `progress`.
+- Connector length doubles as the gap between steps and depends on `size` and `orientation`: large = `--rel-stepper-connector-length-lg` (86px) in both orientations; small horizontal = `--rel-stepper-connector-length-md` (60px); small vertical = `--rel-stepper-connector-length-sm` (42px). Note the `md` / `sm` suffixes refer to those defaults, not to a size value.
+- Labels never wrap (`white-space: nowrap`); keep titles short or widen the connector hooks.
+- `steps` is compared by reference: mutate-in-place changes are not picked up — assign a new array.
+- Steps are `<div role="button">` elements, not native buttons, so they do not submit forms and do not get native disabled styling.

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

@@ -1,102 +1,117 @@
-# rel-switch
-
-## Overview
-A toggle switch component for binary on/off states. Features smooth animations, focus halo effects, pressed states, and respects user motion preferences. Built with custom visual styling while maintaining native checkbox accessibility.
-
-## Usage
-```html
-<!-- Basic switch -->
-<rel-switch></rel-switch>
-
-<!-- Pre-checked switch -->
-<rel-switch checked></rel-switch>
-
-<!-- Disabled switch -->
-<rel-switch disabled></rel-switch>
-<rel-switch checked disabled></rel-switch>
-
-<!-- With event listener -->
-<rel-switch id="notifications"></rel-switch>
-<script>
-  const toggle = document.getElementById('notifications');
-  toggle.addEventListener('changed', (e) => {
-    console.log('Switch state:', e.detail); // boolean: true/false
-  });
-</script>
-
-<!-- Programmatically control -->
-<rel-switch id="darkMode"></rel-switch>
-<script>
-  const darkModeSwitch = document.getElementById('darkMode');
-  darkModeSwitch.checked = true;
-  darkModeSwitch.disabled = false;
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `checked` | `boolean` | `false` | Whether the switch is in the ON position |
-| `disabled` | `boolean` | `false` | Disables the switch and reduces opacity |
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `changed` | `boolean` (the new checked state) | Fired when the switch is toggled by user interaction |
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Component-Level Custom Properties
-The component defines these CSS custom properties on `:host` which can be overridden:
-
-- `--switch-track` - Track color when unchecked (default: `--rel-text-placeholder`)
-- `--switch-knob-on` - Knob color when checked (default: `--rel-text-default`)
-- `--switch-knob-off` - Knob color when unchecked (default: `--rel-bg-surface`)
-- `--switch-halo` - Focus halo color (default: `--rel-border-default`)
-- `--switch-disabled` - Color for disabled state (default: `--rel-text-disabled`)
-
-### Design Token References
-- `--rel-text-placeholder` - Default track color
-- `--rel-text-dark-placeholder` - Hover track color
-- `--rel-text-default` - ON knob color
-- `--rel-bg-surface` - OFF knob color
-- `--rel-border-default` - Focus halo
-- `--rel-text-disabled` - Disabled state color
-- `--rel-bg-neutral-elevated-1` - Used in disabled styling
-
-## Accessibility
-- Uses native checkbox input with `role="switch"` and `aria-checked`
-- Visually hidden checkbox maintains keyboard and screen reader support
-- Focus visible state shows prominent halo around knob
-- Disabled state prevents interaction and reduces opacity to 0.5
-- Smooth transitions respect `prefers-reduced-motion` media query
-
-### Keyboard Interactions
-- `Space` - Toggle switch on/off
-- `Tab` - Move focus to/from switch
-
-### Focus Behavior
-- Focus ring appears as a 6px halo around the knob using `--switch-halo` color
-- Halo uses box-shadow for smooth visual feedback
-
-### Motion Support
-- Animations disabled when `prefers-reduced-motion: reduce` is set
-- Transitions apply to track color, knob position, knob color, and box-shadow
-
-## Notes / Edge Cases
-- The switch is 42px wide × 22px tall with a 12px tall track and 18px diameter knob
-- Visual knob animates 22px horizontally when toggling from OFF to ON
-- Hover effect only applies when not disabled (track darkens slightly)
-- Pressed state applies a `scale(0.9)` transform to the knob for tactile feedback
-- The knob includes a subtle drop shadow (`0 1px 3px rgba(0,0,0,0.3)`) for depth
-- When disabled, both track and knob use `--switch-disabled` color
-- The component is `display: inline-block` by default
-- Focus halo appears on keyboard focus only (`:focus-visible`), not on mouse click
+# rel-switch
+
+`<rel-switch>` implements the Figma **Switch** component (5917:1174, Type=Line): a 44×20 toggle with a thin 10px track and a 20px handle that slides 20px, with hover, focused, pressed and disabled states from the Figma State axis. It wraps a native checkbox with `role="switch"`, so keyboard and screen-reader behaviour are native. Use it for settings that take effect immediately (notifications on/off, dark mode); for choices that are collected and submitted with a form use `<rel-checkbox>`.
+
+## Usage
+
+```html
+<!-- Basic -->
+<rel-switch field-aria-label="Email notifications"></rel-switch>
+
+<!-- On by default -->
+<rel-switch checked field-aria-label="Dark mode"></rel-switch>
+
+<!-- Disabled, off and on -->
+<rel-switch disabled field-aria-label="Locked setting"></rel-switch>
+<rel-switch checked disabled field-aria-label="Locked setting"></rel-switch>
+
+<!-- One handler for several switches: `value` is echoed in the event detail -->
+<rel-switch value="marketing" field-aria-label="Marketing emails"></rel-switch>
+<rel-switch value="product" field-aria-label="Product updates"></rel-switch>
+<script>
+  document.addEventListener('rel-change', (e) => {
+    if (e.target.tagName !== 'REL-SWITCH') return;
+    console.log(e.detail.value, e.detail.checked); // "marketing", true
+  });
+</script>
+
+<!-- Programmatic control (no event is fired) -->
+<rel-switch id="wifi" field-aria-label="Wi-Fi"></rel-switch>
+<script>
+  const wifi = document.getElementById('wifi');
+  wifi.checked = true;
+</script>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-switch.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `checked` | `checked` | `boolean` | `false` | Whether the switch is on. Set it to control the state programmatically; user toggles update it and fire `rel-change`. |
+| `type` | `type` | `"line" \| "pill"` | `"line"` | 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. Reflected. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables interaction and swaps in the dulled rail / handle fills; the handle shadow is removed. |
+| `value` | `value` | `string` | `""` | Arbitrary string echoed in the `rel-change` event detail — useful when one handler serves several switches. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | 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. |
+| `label` | `label` | `string` | `undefined` | 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. |
+| `labelPlacement` | `label-placement` | `"end" \| "start"` | `"end"` | 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. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | 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. Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `{ checked: this.checked, value: this.value, }` | bubbles / composed | Fired when the user toggles the switch (not on programmatic `checked` changes). Detail: `{ checked: boolean, value: string }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Rich label content beside the control, as an alternative to the `label` property. Clicking it toggles the switch. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `root` | The `<label>` holding the control and its optional text; carries the `label-placement` order |
+| `base` | The control box around the hidden input and the track |
+| `track` | The thin rail; the handle is its `::before` pseudo-element |
+| `label` | The text beside the control; not rendered when there is neither a `label` nor slotted content |
+
+## 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-switch-disabled` | `var(--switch-disabled)` | Handle colour while disabled; default `var(--rel-bg-neutral-elevated-1)` |
+| `--rel-switch-knob-off` | `var(--switch-knob-off)` | Handle colour when unchecked; default `var(--rel-text-static-light)` |
+| `--rel-switch-knob-on` | `var(--switch-knob-on)` | Handle colour when checked; default `var(--rel-bg-neutral-inverse-2)` |
+| `--rel-switch-thumb-size` | `var(--_rel-sw-thumb)` | 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 |
+| `--rel-switch-track` | `var(--switch-track)` | Rail colour; default `var(--rel-bg-neutral-elevated-2)` |
+| `--rel-switch-track-height` | `var(--_rel-sw-h)` | Overall control height; defaults to the `size` ramp — 16 / 20 / 24px for `type="line"`, 20 / 24 / 28px for `type="pill"` |
+| `--rel-switch-track-width` | `var(--_rel-sw-w)` | Overall control width; defaults to the `size` ramp (36 / 44 / 52px) |
+| `--switch-halo` | `var(--rel-action-overlay-hover-strong)` | — |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Renders a native `<input type="checkbox" role="switch">` with `aria-checked` mirroring `checked`; the input is visually hidden (opacity 0, zero size) inside a `<label part="base">`, so clicking anywhere on the control toggles it.
+- `field-aria-label` becomes the input's `aria-label`. The input lives in the shadow root, so an external `<label for>` cannot reference it — set `field-aria-label` for the accessible name and place any visible text beside the switch.
+- Focus: the wrapper shows a 1.5px focus outline whenever the input is focused (mouse or keyboard).
+- `disabled` disables the native input (removed from the tab order), dims the control to 50% and drops the handle shadow.
+- `prefers-reduced-motion: reduce` removes the track and handle transitions.
+
+| Key | Action |
+| --- | --- |
+| `Space` | Toggles the switch (native checkbox behaviour). |
+| `Tab` / `Shift+Tab` | Moves focus to / from the switch. |
+
+## Notes / Edge Cases
+
+- `rel-change` fires for user toggles only; setting `checked` from JavaScript updates the visuals but emits nothing.
+- Geometry follows the `size` ramp, derived from the Figma Line switch at `medium`: 44×20 control, 40×10 track inset 2px, 20px handle travelling 20px. `small` is 36×16 and `large` 52×24, holding the same invariants (handle = control height, width = 2× height + 4, rail = height ÷ 2, travel = width − 4 − handle). `type="pill"` shares the width, handle and travel but is 4px taller at every size — 20 / 24 / 28 — because its height is the handle plus its 2px inset, where Line's height *is* the handle. Changing `--rel-switch-track-width` widens the control without moving the "on" position.
+- **`size` does not respond to viewport width.** Figma has no Size axis on Switch, so the ramp is ours, and choosing a size per breakpoint is the application's decision — set it from your own media queries or container queries. A control that resized itself at some width would be behaviour a design system cannot document, and the breakpoint that matters belongs to the layout around the switch, not to the switch.
+- A `label` (or slotted content) becomes the switch's accessible name and is clickable, because the root element is the `<label>` that owns the input. Use `field-aria-label` instead when there is no visible text; when both are set, `label` wins.
+- Figma's default Type=Pill switch (44×24 filled track with the handle inside) is not implemented.
+- Hover tints the track with the action overlay and raises the handle shadow; pressed shows a 28px overlay disc behind the handle and squashes it to 20×16.
+- Legacy hook aliases still honoured: `--switch-track`, `--switch-knob-on`, `--switch-knob-off` and `--switch-disabled` are read as fallbacks of the `--rel-switch-*` hooks. The old `--switch-halo` name was never read by any rule and is not a hook.
+- `registerOnChange`, `registerOnTouched` and `writeValue` exist for the Angular `ControlValueAccessor` wrapper and are not public API.