@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,224 +1,168 @@
-# rel-sheet
-
-## Overview
-A slide-in panel component system with multiple helper components. Features four slide directions (top, right, bottom, left), configurable sizes, modal/non-modal modes, focus trapping, scroll locking, and optional overlay. Built with composition: `rel-sheet` (controller), `rel-sheet-trigger` (opener), `rel-sheet-content` (panel), and layout helpers (`rel-sheet-header`, `rel-sheet-footer`, `rel-sheet-title`, `rel-sheet-description`, `rel-sheet-close`).
-
-## Components
-- **`<rel-sheet>`**: Root wrapper that manages open state
-- **`<rel-sheet-trigger>`**: Button to open the sheet
-- **`<rel-sheet-content>`**: Slide-in panel with all visual elements
-- **`<rel-sheet-header>`**: Header layout helper with bottom border
-- **`<rel-sheet-footer>`**: Footer layout helper with top border
-- **`<rel-sheet-title>`**: Title text (auto-linked to `aria-labelledby`)
-- **`<rel-sheet-description>`**: Description text (auto-linked to `aria-describedby`)
-- **`<rel-sheet-close>`**: Custom close button wrapper
-
-## Usage
-```html
-<!-- Basic right-side sheet -->
-<rel-sheet>
-  <rel-sheet-trigger>
-    <button>Open Settings</button>
-  </rel-sheet-trigger>
-  
-  <rel-sheet-content>
-    <rel-sheet-header>
-      <rel-sheet-title>Settings</rel-sheet-title>
-      <rel-sheet-description>Configure your preferences</rel-sheet-description>
-    </rel-sheet-header>
-    
-    <p>Sheet content goes here...</p>
-    
-    <rel-sheet-footer>
-      <rel-sheet-close>
-        <button>Cancel</button>
-      </rel-sheet-close>
-      <button>Save</button>
-    </rel-sheet-footer>
-  </rel-sheet-content>
-</rel-sheet>
-
-<!-- Left-side sheet, large size -->
-<rel-sheet>
-  <rel-sheet-trigger>
-    <button>Open Menu</button>
-  </rel-sheet-trigger>
-  
-  <rel-sheet-content side="left" size="lg">
-    <nav>
-      <a href="#home">Home</a>
-      <a href="#about">About</a>
-      <a href="#contact">Contact</a>
-    </nav>
-  </rel-sheet-content>
-</rel-sheet>
-
-<!-- Bottom sheet without overlay -->
-<rel-sheet defaultopen>
-  <rel-sheet-trigger>
-    <button>Toggle Bottom Sheet</button>
-  </rel-sheet-trigger>
-  
-  <rel-sheet-content side="bottom" hide-overlay>
-    <p>Bottom sheet content</p>
-  </rel-sheet-content>
-</rel-sheet>
-
-<!-- Controlled state -->
-<rel-sheet id="controlledSheet" open>
-  <rel-sheet-trigger>
-    <button>Open</button>
-  </rel-sheet-trigger>
-  
-  <rel-sheet-content>
-    <p>This sheet is controlled externally</p>
-  </rel-sheet-content>
-</rel-sheet>
-<script>
-  const sheet = document.getElementById('controlledSheet');
-  sheet.addEventListener('rel-open-change', (e) => {
-    console.log('Sheet open:', e.detail.open);
-    console.log('Reason:', e.detail.reason);
-  });
-</script>
-
-<!-- Without built-in close button -->
-<rel-sheet>
-  <rel-sheet-trigger>
-    <button>Open</button>
-  </rel-sheet-trigger>
-  
-  <rel-sheet-content show-close="false">
-    <p>Custom close handling</p>
-    <rel-sheet-close>
-      <button>Close Me</button>
-    </rel-sheet-close>
-  </rel-sheet-content>
-</rel-sheet>
-```
-
-## API
-
-### rel-sheet Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `open` (reflected) | `boolean?` | `undefined` | Controlled open state |
-| `defaultopen` | `boolean` | `false` | Default open state (uncontrolled) |
-| `disabled` | `boolean` | `false` | Disable trigger |
-| `modal` | `boolean` | `true` | Enable modal behavior (focus trap) |
-
-### rel-sheet-content Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Which side the sheet slides from |
-| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Sheet width/height (320/420/540/640px) |
-| `hide-overlay` | `boolean` | `false` | Hide the backdrop overlay |
-| `close-on-overlay` | `boolean` | `true` | Allow closing by clicking overlay |
-| `show-close` | `boolean` | `true` | Show built-in close button (✕) |
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `rel-open-change` | `{ open, reason }` | Fired when sheet opens/closes |
-
-### Close Reasons
-- `"trigger"`: Toggled via trigger button
-- `"close"`: Closed via close button
-- `"overlay"`: Closed by clicking overlay
-- `"escape"`: Closed via Escape key
-- `"api"`: Changed via `setOpen()` method
-
-## Methods
-
-### Sheet Methods
-```typescript
-sheet.setOpen(nextOpen: boolean, reason?: string): void
-```
-
-## Slots
-| Slot | Component | Description |
-|------|-----------|-------------|
-| (default) | `rel-sheet` | Trigger and content elements |
-| (default) | `rel-sheet-trigger` | Trigger button/element |
-| (default) | `rel-sheet-content` | Panel content |
-| (default) | Layout helpers | Content within headers/footers/titles |
-
-## CSS Parts
-| Part | Description |
-|------|-------------|
-| `overlay` | Backdrop overlay element |
-| `panel` | Main panel container |
-
-## Tokens / CSS Variables
-
-### Size Tokens (defined on `<rel-sheet-content>`)
-- `--sheet-size-sm`: `320px`
-- `--sheet-size-md`: `420px`
-- `--sheet-size-lg`: `540px`
-- `--sheet-size-xl`: `640px`
-
-### Transition Tokens
-- `--sheet-transition-duration`: `0.3s`
-- `--sheet-transition-timing`: `cubic-bezier(0.32, 0.72, 0, 1)`
-
-### Color Tokens
-- `--rel-bg-surface` - Panel background
-- `--rel-text-label` - Title and close button color
-- `--rel-text-body` - Description color
-- `--rel-bg-surface-elevated` - Close button hover background
-- `--rel-border-default` - Header/footer borders
-- `--rel-overlay-scrim` - Overlay background
-- `--rel-bg-info` - Close button focus outline
-
-### Shadow Tokens
-- `--rel-shadows-shadow-500` - Panel shadow
-
-### Border Tokens
-- `--rel-border-radius-md` - Panel border radius (top corners for bottom, etc.)
-
-### Spacing Tokens
-- `--rel-spacing-lg` - Panel content padding
-- `--rel-spacing-md` - Header/footer padding, close button positioning
-- `--rel-spacing-xs` - Close button padding
-
-## Accessibility
-- Panel uses `role="dialog"` and `aria-modal`
-- Auto-links `aria-labelledby` to `<rel-sheet-title>`
-- Auto-links `aria-describedby` to `<rel-sheet-description>`
-- Focus trap in modal mode
-- Escape key closes sheet
-- Restores focus to trigger on close
-
-### Keyboard Interactions
-| Key | Action |
-|-----|--------|
-| `Escape` | Close sheet |
-| `Tab` | Focus trap within sheet (modal mode only) |
-
-### Focus Behavior
-- On open, focuses first focusable element (or panel if none found)
-- Focus trapped within panel in modal mode
-- On close, restores focus to trigger button
-
-## Notes / Edge Cases
-- **Side positioning and transforms**:
-  - **right**: Slides in from right edge, `translateX(100%)` to `translateX(0)`
-  - **left**: Slides in from left edge, `translateX(-100%)` to `translateX(0)`
-  - **bottom**: Slides in from bottom, `translateY(100%)` to `translateY(0)`
-  - **top**: Slides in from top, `translateY(-100%)` to `translateY(0)`
-
-- **Size constraints**:
-  - Left/right: `max-width: 90vw`
-  - Top/bottom: `max-height: 80vh`
-
-- **Scroll locking**: Body scroll is locked when sheet is open (with scrollbar width compensation)
-- **Close button position**: Top-right by default, but top-left for `side="left"`
-- **Reduced motion**: Transitions disabled, panel hidden via `display: none` instead of transform
-- The sheet root uses `display: contents`
-- Panel is overlaid with `z-index: 1000`, fixed position
-- Overlay detection for `aria-labelledby`/`aria-describedby` happens automatically based on slotted `<rel-sheet-title>` and `<rel-sheet-description>` elements
-- Built-in close button is "✕" character at font-size 20px
-
-### Controlled vs Uncontrolled
-- If `open` prop is set, the sheet is controlled and won't manage its own state
-- Use `rel-open-change` event to sync controlled state
+# rel-modal
+
+`<rel-modal>` is the design system's modal dialog and implements the Figma **Modal Sheet** component (8171:3412): a panel anchored to the bottom, top or centre of the viewport over a scrim, with a title/description header, a scrollable body, an optional right-aligned footer and a built-in loading state. It lives in the `rel-sheet` folder and is exported as the `RelModal` class — there is no separate sheet element; the "sheet" is the `side="bottom"` / `side="top"` presentation of this one element. Use it for confirmations, short forms and messages that must interrupt the page. For edge-anchored panels that hold navigation or longer editing flows use `<rel-drawer>`; for lightweight contextual content anchored to a trigger use `<rel-popover>`.
+
+## Usage
+
+```html
+<!-- Bottom sheet (default) with header, body and footer actions -->
+<rel-button id="open-delete">Delete project</rel-button>
+
+<rel-modal id="delete-modal" title="Delete project?" description="This action cannot be undone.">
+  <p>All files and history for <strong>Acme Rollout</strong> will be removed.</p>
+  <rel-button slot="footer" variant="secondary" id="cancel">Cancel</rel-button>
+  <rel-button slot="footer" tone="destructive" id="confirm">Delete</rel-button>
+</rel-modal>
+
+<script>
+  const modal = document.getElementById('delete-modal');
+  document.getElementById('open-delete').addEventListener('click', () => { modal.open = true; });
+  document.getElementById('cancel').addEventListener('click', () => { modal.open = false; });
+  modal.addEventListener('rel-open-change', (e) => {
+    console.log('open =', e.detail); // true | false
+  });
+</script>
+
+<!-- Centred dialog, small width -->
+<rel-modal side="center" size="small" title="Session expired" description="Sign in again to continue.">
+  <rel-button slot="footer" variant="primary">Sign in</rel-button>
+</rel-modal>
+
+<!-- Top-anchored sheet with extra header content -->
+<rel-modal side="top" size="large" title="New release">
+  <rel-tab slot="header" size="small">
+    <rel-tab-item slot="items" label="Summary"></rel-tab-item>
+    <rel-tab-item slot="items" label="Details"></rel-tab-item>
+  </rel-tab>
+  <p>Release notes go here.</p>
+</rel-modal>
+
+<!-- Message-only body (Figma "Text" slot) -->
+<rel-modal variant="text" side="center" title="Saved" open>
+  <p>Your changes were saved.</p>
+  <p>You can close this window.</p>
+</rel-modal>
+
+<!-- Fullscreen, fixed desktop layout at every viewport width -->
+<rel-modal size="fullscreen" breakpoint="web" title="Editor">
+  <p>Edge-to-edge content.</p>
+</rel-modal>
+
+<!-- Loading and locked states -->
+<rel-modal title="Publishing…" loading open>
+  <p>Please wait.</p>
+</rel-modal>
+<rel-modal title="Processing" disabled open>
+  <p>Closing is blocked until the job finishes.</p>
+  <rel-button slot="footer">Done</rel-button>
+</rel-modal>
+
+<!-- Non-dismissible: no close button, backdrop and Escape ignored -->
+<rel-modal id="locked" title="Accept terms">
+  <p>You must accept to continue.</p>
+  <rel-button slot="footer" variant="primary">Accept</rel-button>
+</rel-modal>
+<script>
+  // Boolean props that default to true can only be switched off from JS —
+  // an absent attribute leaves the default in place.
+  document.getElementById('locked').dismissible = false;
+</script>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-sheet.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `open` | `boolean` | `false` | Whether the modal is shown. Toggle it to open/close; every change fires `rel-open-change`. Reflected. |
+| `side` | `side` | `"top" \| "bottom" \| "center"` | `"bottom"` | Where the panel is anchored: `bottom` (48px above the bottom edge, slides up), `top` (48px below the top edge, slides down) or `center` (fades and scales in). Below 480px with `breakpoint="responsive"` every side collapses to a full-width bottom sheet. |
+| `title` | `title` | `string` | `""` | Heading text (rendered as an `<h2>`, linked via `aria-labelledby`). The `title` attribute is stripped from the host after it is read so no native tooltip appears. |
+| `description` | `description` | `string` | `""` | Supporting text under the title (linked via `aria-describedby`). |
+| `subtitle` | `subtitle` | `string` | `""` | Alias for `description`; rendered only when `description` is empty. |
+| `dismissible` | `dismissible` | `boolean` | `true` | Coarse dismissal switch. When false the close button is hidden and backdrop clicks / Escape are ignored regardless of the granular `close-on-*` / `show-close-button` props. |
+| `modal` | `modal` | `boolean` | `true` | Modal mode: renders the scrim, sets `role="dialog"` + `aria-modal`, traps Tab inside the panel and moves focus in on open. When false the panel is a `region` with no scrim and no focus trap. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "extra-large" \| "fullscreen" \| "sm" \| "md" \| "lg" \| "xl"` | `"medium"` | Panel width scale. `medium` (default) matches the Figma Modal Sheet width; `fullscreen` covers the viewport. `sm` / `md` / `lg` / `xl` are alternative spellings of `small` / `medium` / `large` / `extra-large` and stay supported — they are normalised to the full words, not deprecated. Reflected. |
+| `variant` | `variant` | `"default" \| "text"` | `"default"` | Body treatment — see `ModalVariant`. `"text"` styles the default slot as the Figma "Text" message slot; the header (and its divider) render as usual above it. Default rendering is unchanged. Reflected. |
+| `closeOnBackdropClick` | `close-on-backdrop-click` | `boolean` | `true` | Close when the scrim is clicked. Only effective while `dismissible` is true; ignored while `disabled` or `loading`. |
+| `closeOnEscape` | `close-on-escape` | `boolean` | `true` | Close on the Escape key. Only effective while `dismissible` is true; ignored while `disabled`. |
+| `showCloseButton` | `show-close-button` | `boolean` | `true` | Render the "X" close button in the header. Only effective while `dismissible` is true. |
+| `autoFocus` | `auto-focus` | `boolean` | `true` | Move focus into the panel when opened (modal mode only). |
+| `restoreFocus` | `restore-focus` | `boolean` | `true` | Return focus to the opener when closed. |
+| `scrollable` | `scrollable` | `boolean` | `true` | When false, the body no longer scrolls internally — tall content clips at the panel's max height. |
+| `loading` | `loading` | `boolean` | `false` | Shows a spinner overlay and blocks all interaction inside the panel. Reflected. |
+| `disabled` | `disabled` | `boolean` | `false` | Blocks user-initiated closes (X / backdrop / Escape) and footer actions. Reflected. |
+| `zIndex` | `z-index` | `number` | `1000` | Stacking order of the whole modal (backdrop + panel). |
+| `breakpoint` | `breakpoint` | `"responsive" \| "web"` | `"responsive"` | Figma "Breakpoint" axis. responsive (default) collapses to a full-width bottom sheet below 480px; web keeps the fixed desktop panel at every size. Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-open-change` | `true / false` | bubbles / composed | Fired whenever `open` changes, from any cause (prop set, close button, backdrop, Escape). Detail: the new `open` boolean. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Body content of the modal |
+| `header` | Extra header content rendered under the title/description (e.g. a stepper or tabs) |
+| `footer` | Actions row (right-aligned, 8px gap); the footer only renders when this slot has content |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `overlay` | The full-viewport scrim behind the panel |
+| `panel` | The dialog panel (role="dialog") |
+| `header` | Header row holding title, description, header slot and close button |
+| `close-button` | The "X" close button |
+| `content` | Scrollable body wrapper around the default slot |
+| `footer` | Footer wrapper around the `footer` slot |
+| `loading` | Spinner overlay shown while `loading` is set |
+
+## 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-modal-transition-duration` | `var(--modal-transition-duration)` | Open/close animation duration; default `0.3s` |
+| `--rel-modal-transition-timing` | `var(--modal-transition-timing)` | Open/close animation easing; default `cubic-bezier(0.32, 0.72, 0, 1)` |
+| `--rel-modal-width` | `var(--modal-width)` | Panel width; overrides the `size` scale (md default `clamp(360px, 49vw, 708px)`, sm `min(400px, 100vw - 32px)`, lg `min(900px, 100vw - 48px)`, xl `min(1140px, 100vw - 48px)`). Ignored by `fullscreen` and by the responsive collapse below 480px |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The panel is `role="dialog"` with `aria-modal="true"` while `modal` is on; with `modal` off it becomes a `role="region"` without scrim or focus trap.
+- `aria-labelledby` points at the rendered `<h2>` when `title` is set, otherwise the panel carries `aria-label="Dialog"`; `aria-describedby` points at the description paragraph when `description` (or `subtitle`) is set.
+- While `loading` the panel has `aria-busy="true"` and the header, body and footer are made `inert`; while `disabled` only the footer is `inert` and the close button is disabled.
+- The close button is a real `<button>` with `aria-label="Close"`.
+- Focus: on open (modal + `auto-focus`) focus moves to the first focusable element inside the panel, or to the panel itself (`tabindex="-1"`). On close (`restore-focus`) focus returns to the element that was active before opening — resolved through shadow roots, so a `<rel-button>` opener gets focus back.
+- Body scroll is locked while open; the scrollbar width is added as body padding so the page does not shift.
+- `prefers-reduced-motion: reduce` removes the slide/fade transitions and hides the closed panel outright.
+
+| Key | Action |
+| --- | --- |
+| `Escape` | Closes the modal when `dismissible` and `close-on-escape` are on and the modal is not `disabled`. |
+| `Tab` / `Shift+Tab` | Cycles focus inside the panel while `modal` is on (focus trap); wraps at either end. |
+
+## Notes / Edge Cases
+
+- `title` is also HTML's global tooltip attribute. The component reads the attribute into the property and then removes it from the host, so no native tooltip appears over the modal or its scrim.
+- `subtitle` is an alias for `description` and is only rendered when `description` is empty.
+- The footer is only rendered when the `footer` slot has content; the host gains a `has-footer` attribute while it does.
+- `dismissible` is the coarse switch and is ANDed with `close-on-backdrop-click`, `close-on-escape` and `show-close-button`; turning it off locks all three regardless of their own values.
+- `loading` blocks backdrop clicks and the close button but does **not** block `Escape`; set `disabled` (or `close-on-escape` = false) if Escape must be blocked as well.
+- Boolean props default to `true` (`dismissible`, `modal`, `close-on-*`, `show-close-button`, `auto-focus`, `restore-focus`, `scrollable`); an absent attribute keeps the default, so switch them off from JavaScript (`modal.closeOnEscape = false`).
+- `size` picks the panel width; `--rel-modal-width` overrides it for every size except `fullscreen`. Below 480px with `breakpoint="responsive"` every side and size (except `fullscreen`) collapses to a full-width bottom sheet, ignoring the width hook.
+- `z-index` is applied to the whole fixed container (scrim + panel); use it when the modal must sit above other stacked UI such as a toast region.
+- Legacy hook aliases still honoured: `--modal-transition-duration`, `--modal-transition-timing` and `--modal-width` are read as fallbacks of the `--rel-modal-*` hooks. Note `--modal-width` is also set internally per `size`, so only the canonical `--rel-modal-width` reliably overrides the width from outside.
+- The old `<rel-sheet>` / `<rel-sheet-*>` element family described in earlier docs was never shipped; this element is the only export of the folder.

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

@@ -0,0 +1,104 @@
+# rel-skeleton
+
+Loading placeholder that reserves the space of content still being fetched: a neutral `block`, a `circle` (avatars, icons) or a stack of text `line` bars, animated with a `pulse` or `shimmer` until you set `loaded`, at which point it hides itself. Use it when you know the shape of the incoming content (cards, list rows, avatars); use a spinner for indeterminate waits with no layout to preserve.
+
+## Usage
+
+```html
+<!-- Block (default): fills its container, height set explicitly -->
+<rel-skeleton height="160px"></rel-skeleton>
+
+<!-- Circle: only a width is needed, the aspect ratio keeps it round -->
+<rel-skeleton shape="circle" width="48px"></rel-skeleton>
+
+<!-- Paragraph: three text bars, the last one shorter -->
+<rel-skeleton shape="line" lines="3"></rel-skeleton>
+
+<!-- Animation variants -->
+<rel-skeleton shape="line" lines="2" animation="shimmer"></rel-skeleton>
+<rel-skeleton shape="block" height="80px" animation="none"></rel-skeleton>
+
+<!-- Custom colours -->
+<rel-skeleton
+  shape="block"
+  height="120px"
+  animation="shimmer"
+  style="--rel-skeleton-color: #e5e7eb; --rel-skeleton-highlight: #f9fafb;"
+></rel-skeleton>
+
+<!-- A list-row placeholder that swaps for real content -->
+<div style="display: flex; gap: 12px; align-items: center;">
+  <rel-skeleton id="avatar" shape="circle" width="40px"></rel-skeleton>
+  <div style="flex: 1;">
+    <rel-skeleton id="text" shape="line" lines="2"></rel-skeleton>
+  </div>
+</div>
+<script>
+  fetchUser().then(() => {
+    document.getElementById('avatar').loaded = true;
+    document.getElementById('text').loaded = true;
+  });
+</script>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-skeleton.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `shape` | `shape` | `"line" \| "circle" \| "block"` | `"block"` | Placeholder shape: `block` fills the host (min 16px tall), `circle` is a square-aspect disc sized by the host width, `line` renders `lines` 16px text bars with the last one at 65% width. Reflected. |
+| `lines` | `lines` | `number` | `1` | Number of text bars when `shape="line"` (minimum 1, --rel-spacing-xs apart); ignored by the other shapes. |
+| `width` | `width` | `string` | `""` | Any CSS width (e.g. `"240px"`, `"50%"`) applied to the host's inline style. Empty leaves the host at its natural block width. |
+| `height` | `height` | `string` | `""` | Any CSS height (e.g. `"120px"`) applied to the host's inline style. Not needed for `circle`, which derives its height from the width. |
+| `animation` | `animation` | `"pulse" \| "shimmer" \| "none"` | `"pulse"` | Motion: `pulse` fades opacity between 20% and 40% (Figma's Start/End states), `shimmer` sweeps a highlight band left to right, `none` is static. Both animations are disabled under `prefers-reduced-motion: reduce`. Reflected. |
+| `loaded` | `loaded` | `boolean` | `false` | Set once the real content is ready: hides the skeleton (`display: none`) and removes its `role="status"` / "Loading" label. Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | Each placeholder surface: the single block/circle, or every bar when `shape="line"`. |
+
+## 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-skeleton-color` | `var(--rel-bg-neutral-elevated-3)` | Fill colour of the placeholder (defaults to the elevated-3 neutral background token). |
+| `--rel-skeleton-highlight` | `var(--rel-bg-neutral-elevated-2)` | Lighter band that sweeps across the placeholder when `animation="shimmer"` (defaults to the elevated-2 neutral background token). |
+| `--rel-skeleton-line-height` | `16px` | Height of each text bar when `shape="line"`; default 16px (Figma's Line shape). |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- While not `loaded`, the host carries `role="status"` and `aria-label="Loading"`, so assistive technology announces that the region is loading; both are removed once `loaded` is set (the attributes are managed on each update, so they appear after the first render).
+- The placeholder is not focusable and has no keyboard interaction.
+- Under `prefers-reduced-motion: reduce` both `pulse` and `shimmer` are disabled and the placeholder renders static.
+
+## Notes / Edge Cases
+
+- **Sizing.** `width` / `height` are written to the host's inline `style` and accept any CSS length. A `block` with no `height` is 16px tall (its `min-height`); a `circle` needs only a width (`aspect-ratio: 1 / 1`); `line` bars are 16px tall, `--rel-spacing-xs` apart, full width, with the last bar at 65% when there is more than one.
+- **`loaded` hides, it does not remove.** The host switches to `display: none` and stays in the DOM; place the real content as a sibling rather than inside the skeleton (the element has no slot).
+- **Multiple `base` parts.** With `shape="line"` every bar carries `part="base"`, so `::part(base)` styles all of them.
+- **Shimmer overrides the fill.** In `shimmer` mode the background becomes a gradient built from `--rel-skeleton-color` and `--rel-skeleton-highlight`; set both when customising colours.