@reliability-design/web 1.4.8 → 1.4.10

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

@@ -1,186 +1,187 @@
-# 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)`.
+# 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 with `pause-on-hover="false"` or `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"`. Since 1.5.0 the button is a transparent target cell of at least 24 × 24px and the visible dot is its `::before` (style it with `::part(dot)::before`). |
+
+## 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); its target cell is at least 24px. |
+| `--rel-carousel-dot-size-active` | `16px` | Width of the active (brand-coloured, pill-shaped) dot (default 16px); its target cell is at least 24px. |
+| `--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-display` | `flex` | `display` given to each slide in `orientation="vertical"` only, which is what centres the slide's content in the fixed-height viewport as Figma draws it. Set it to `block` to opt out if forcing flex reflows your slide's own children. Horizontal slides are never touched. |
+| `--rel-carousel-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. Since 1.5.0 each dot sits in a target cell of at least 24 × 24px (WCAG 2.5.8 target size), so the indicator row is 24px tall (it was 8px). The cells touch, with no gap between them, so the visible dots sit 16px apart (three dots make a 72px row). The cell is transparent: `::part(dot)` styles the cell (and carries the focus ring), `::part(dot)::before` the visible dot. Also since 1.5.0, an inactive dot is filled with `--rel-bg-neutral-elevated-3` (it was `--rel-bg-neutral-elevated-2`), and the active pill keeps `--rel-bg-surface-brand` with a 1px inside edge in `--rel-text-default`. In forced-colours mode the dots paint in system colours (inactive `CanvasText`, active `Highlight` with a `CanvasText` edge) instead of disappearing.
+- 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)`.