@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,132 +1,133 @@
-# rel-accordion
-
-## Overview
-An animated accordion component with a collapsible body section. Features a clickable header with chevron icon rotation, smooth expand/collapse transitions, and keyboard support. Respects reduced motion preferences.
-
-## Usage
-```html
-<!-- Basic accordion -->
-<rel-accordion title="Section 1">
-  <p>This is the content of section 1.</p>
-</rel-accordion>
-
-<!-- Initially open -->
-<rel-accordion title="FAQ: How does it work?" open>
-  <p>This accordion starts in the open state.</p>
-  <ul>
-    <li>Bullet 1</li>
-    <li>Bullet 2</li>
-  </ul>
-</rel-accordion>
-
-<!-- Multiple accordions -->
-<rel-accordion title="Introduction">
-  <p>Introduction content...</p>
-</rel-accordion>
-<rel-accordion title="Features">
-  <p>Features content...</p>
-</rel-accordion>
-<rel-accordion title="Pricing">
-  <p>Pricing content...</p>
-</rel-accordion>
-
-<!-- Listen for open state changes -->
-<rel-accordion id="myAccordion" title="Details"></rel-accordion>
-<script>
-  const accordion = document.getElementById('myAccordion');
-  accordion.addEventListener('open-change', (e) => {
-    console.log('Accordion open:', e.detail); // true or false
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `string` | `"Accordion"` | Header title text |
-| `open` (reflected) | `boolean` | `false` | Whether the accordion is expanded |
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `open-change` | `boolean` | Fired when the accordion is toggled (detail is the new `open` state) |
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Accordion body content |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-
-### Font Tokens
-- `--rel-body-xl-regular-font-size` - Title font size (20px)
-- `--rel-body-md-regular-font-size` - Body font size (14px)
-- `--rel-fonts-weight-body-medium` - Title font weight (500)
-
-### Color Tokens
-- `--rel-bg-surface` - Background color
-- `--rel-text-label` - Title text color
-- `--rel-text-default` - Body text color, icon stroke color
-- `--rel-border-default` - Border color
-- `--rel-border-info` - Focus outline color
-
-### Shadow Tokens
-- `--rel-shadows-shadow-100` - Shadow
-
-### Border Tokens
-- `--rel-border-radius-sm` - Border radius (8px)
-
-### Spacing Tokens
-- `--rel-spacing-md` - Header horizontal padding, body horizontal padding in closed state (16px)
-- `--rel-spacing-xl` - Body top padding when open (24px)
-- `--rel-spacing-lg` - Body bottom padding when open (20px)
-
-## Accessibility
-- Header uses `role="button"` and `aria-expanded` attribute
-- Header is keyboard accessible with `tabindex="0"`
-- Supports Enter and Space key activation
-- Focus visible outline on keyboard focus
-
-### Keyboard Interactions
-| Key | Action |
-|-----|--------|
-| `Enter` | Toggle accordion open/closed |
-| `Space` | Toggle accordion open/closed |
-| `Tab` | Navigate to/from the header |
-
-### Focus Behavior
-- Header receives focus outline (`outline: 2px solid --rel-border-info`)
-- Focus offset is `-2px` inset
-
-## Notes / Edge Cases
-- **Animation details**:
-  - Chevron rotates 180° when open (`transform: rotate(180deg)`)
-  - Body expands from `max-height: 0` to `max-height: 1000px`
-  - Body padding animates from `0` to full padding when opening
-  - Transitions: `transform 0.25s ease`, `max-height 0.25s ease`, `padding 0.2s ease`
-
-- **Reduced motion**: When `prefers-reduced-motion: reduce`, icon rotation and body transitions are disabled
-
-- **Body rendering**: The slotted content is always in the DOM (not conditionally rendered), but hidden via `max-height: 0` and `overflow: hidden` when closed
-
-- The header has hover styling (`background: --rel-bg-neutral-elevated-1`)
-
-- The component is `display: block` and `width: 100%`
-
-- The accordion border is `1px solid` with rounded corners
-
-- The chevron icon is an inline SVG (9-point downward-pointing chevron)
-
-- When closed, the body has `padding: 0 var(--rel-spacing-md)` to maintain horizontal padding
-
-- The `open` attribute is reflected in HTML when set
-
-- Multiple accordions can be open simultaneously (no automatic closing of others)
+# rel-accordion
+
+`<rel-accordion>` is a single collapsible section of the Reliability Design System (Figma "Accordion", 6021:1085): a clickable header with a title and a chevron that expands or collapses the slotted body. Each element is independent — stack several to build an FAQ or a settings list, and nothing closes automatically when another opens. Use it for progressive disclosure of secondary content; do not use it to switch between peer views (use tabs) or to hide primary actions.
+
+## Usage
+
+```html
+<!-- Basic: closed by default, opens on click / Enter / Space -->
+<rel-accordion title="Shipping">
+  <p>Orders ship within two business days.</p>
+</rel-accordion>
+
+<!-- Initially open -->
+<rel-accordion title="Returns" open>
+  <p>Free returns within 30 days.</p>
+</rel-accordion>
+
+<!-- Header scale: 56 / 48 / 44 px -->
+<rel-accordion size="large" title="Large"></rel-accordion>
+<rel-accordion size="medium" title="Medium"></rel-accordion>
+<rel-accordion size="small" title="Small"></rel-accordion>
+
+<!-- Plain style: square corners and a 1px border instead of the shadow card -->
+<rel-accordion appearance="plain" title="Plain"></rel-accordion>
+
+<!-- Action type: leading rotating chevron + static trailing arrow-expansion, body indented -->
+<rel-accordion type="action" title="Filters">
+  <p>Filter options…</p>
+</rel-accordion>
+
+<!-- Action type with a custom leading icon (slotted icons never rotate) -->
+<rel-accordion type="action" title="Preferences">
+  <rel-icon slot="icon" name="settings"></rel-icon>
+  <p>Preference options…</p>
+</rel-accordion>
+
+<!-- Custom trailing icon on the default type -->
+<rel-accordion title="More">
+  <rel-icon slot="trailing-icon" name="plus"></rel-icon>
+  <p>Extra content…</p>
+</rel-accordion>
+```
+
+```js
+const accordion = document.querySelector("rel-accordion");
+
+accordion.addEventListener("open-change", (e) => {
+  e.detail; // true when the body was just expanded, false when collapsed
+});
+
+// Programmatic toggle (does not fire open-change)
+accordion.open = true;
+```
+
+### Deprecated aliases
+
+```html
+<!-- size="md" → size="large", size="sm" → size="medium". Both still work; no console notice is logged. -->
+<rel-accordion size="md" title="Legacy large"></rel-accordion>
+<rel-accordion size="sm" title="Legacy medium"></rel-accordion>
+<!-- canonical -->
+<rel-accordion size="large" title="Large"></rel-accordion>
+<rel-accordion size="medium" title="Medium"></rel-accordion>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-accordion.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `title` | `title` | `string` | `"Accordion"` | Header text. Note it is also the native HTML `title` attribute, so browsers show it as a tooltip on hover. |
+| `open` | `open` | `boolean` | `false` | Whether the body is expanded; toggled by the header and reported via `open-change`. Setting it from code does not fire the event. Reflected. |
+| `size` | `size` | `"md" \| "sm" \| "large" \| "medium" \| "small"` | `"md"` | Header scale (Figma "Size"): `large` = 56px header / heading-md title, `medium` = 48px / heading-sm, `small` = 44px / heading-xs (new in 1.4.7). The historical spellings stay supported as aliases: `md` = large (the default), `sm` = medium. Reflected. |
+| `type` | `type` | `"default" \| "action"` | `"default"` | Header layout (Figma "Type"): `default` = title + trailing rotating chevron; `action` = leading icon slot (rotating chevron by default) + static trailing arrow-expansion icon, with the body indented under the title. DELIBERATE DIVERGENCE — do not "fix" this to a button. For `Type=Action` Figma draws the trailing affordance as a full ghost icon Button instance (Size=Medium 40x40, Size=Small 32x32, Style=Ghost, Type=Icon Only); the code keeps a bare icon. Ruled by the user: our behaviour stands and the DESIGN FILE follows our docs here, not the other way round. The whole header is the click target, so a nested button would add a second focusable control inside it and two competing hit areas. Reflected. |
+| `appearance` | `appearance` | `"shadow" \| "plain"` | `"shadow"` | Figma "Style" axis — named appearance because `style` collides with the HTML style attribute. `shadow` = 4px-radius card with the shadow-sm effect and no border; `plain` = square corners with a 1px border-subtle stroke and no elevation. Reflected. |
+| `disabled` | `disabled` | `boolean` | `false` | Figma "State=Disabled": dims the whole component to 40% and blocks toggling by pointer and keyboard. The header keeps its fill and stroke — the dulling is opacity alone, as Figma specifies. Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `open-change` | `open` | bubbles / composed | Fired when the header toggles the accordion (click, Enter or Space). Detail: the new `open` state (boolean). Not fired when `open` is set programmatically. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Body content, revealed when `open` |
+| `icon` | Leading icon in the header (`type="action"` only); replaces the default rotating chevron-down |
+| `trailing-icon` | Trailing icon in the header; replaces the default chevron-down (default type) or arrow-expansion (action type) |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The outer card (`.accordion`) carrying the appearance border / shadow |
+| `trigger` | The `role="button"` header row |
+| `label` | The title row (leading icon + title text) |
+| `icon` | The trailing icon wrapper |
+| `content` | The `role="region"` body that holds the default slot |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The header (part `trigger`) is a `role="button"` with `tabindex="0"`, `aria-expanded` mirroring `open`, and `aria-controls` pointing at the body.
+- The body (part `content`) is a `role="region"` labelled by the header (`aria-labelledby`). While closed it carries the `inert` attribute, so collapsed content is removed from the Tab order and from the accessibility tree — not merely hidden visually.
+- The slotted `icon` / `trailing-icon` content and the built-in `rel-icon` chevrons are decorative; the accessible name of the header is the `title` text.
+- Keyboard focus is shown as a 2px `--rel-border-focus` outline inset 2px inside the header (it follows the card radius so it is not clipped).
+- No live-region announcements are made; the `aria-expanded` change is what screen readers report.
+
+| Key (header focused) | Action |
+| --- | --- |
+| Enter | Toggle open / closed (fires `open-change`) |
+| Space | Toggle open / closed (fires `open-change`) |
+| Tab / Shift + Tab | Move to the next / previous focusable element; the body's content is only reachable while open |
+
+## Notes / Edge Cases
+
+- `size` defaults to the legacy spelling `"md"`, which renders the Figma Large (56px) header; `"sm"` renders Medium (48px). The full-word values are the canonical ones — see Deprecated aliases.
+- `title` is also the element's native `title` attribute, so browsers show it as a hover tooltip on the whole component.
+- `open-change` fires only from user toggles (click, Enter, Space). Setting `open` from code updates the UI silently.
+- The body stays in the DOM when closed; it is collapsed with `max-height: 0` / `overflow: hidden` and `inert`. When open the cap is `max-height: 1000px`, so content taller than 1000px is clipped.
+- Rotation on open applies only to the built-in fallback icons (`chevron-down` in the trailing slot for `type="default"`, in the leading slot for `type="action"`). Anything you slot into `icon` or `trailing-icon` stays static, and the Action type's trailing `arrow-expansion` never rotates (Figma audit 1b).
+- `type="action"` indents the open body under the title: 56px at `large`, 48px at `medium` / `small`. The leading icon wrapper is 40px / 18px icon at `large` and 32px / 16px at the other sizes; the trailing icon wrapper follows the same tiers.
+- Header hover / pressed use the `--rel-action-overlay-hover` / `--rel-action-overlay-pressed` tokens. `appearance="shadow"` uses `--rel-shadows-sm` with a transparent border; `appearance="plain"` uses `--rel-border-subtle` with no shadow and zero radius.
+- Transitions (chevron rotation, body max-height and padding) are disabled under `prefers-reduced-motion: reduce`.
+- The host is `display: block; width: 100%`; wrap it to constrain the width.

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

@@ -1,141 +1,145 @@
-# rel-alert
-
-## Overview
-A versatile alert component for displaying informational, success, warning, error, or neutral messages. Features built-in icons, optional dismissibility, secondary message text, and inline links. Automatically hides when dismissed via the `dismissed` reflected attribute.
-
-## Usage
-```html
-<!-- Basic neutral alert -->
-<rel-alert
-  message1="This is a neutral alert"
-  type="neutral">
-</rel-alert>
-
-<!-- Info alert with secondary message -->
-<rel-alert
-  type="info"
-  message1="System Notification"
-  message2="Your settings have been updated successfully.">
-</rel-alert>
-
-<!-- Success alert -->
-<rel-alert
-  type="success"
-  message1="Operation Completed"
-  message2="Your data has been saved.">
-</rel-alert>
-
-<!-- Warning alert -->
-<rel-alert
-  type="warning"
-  message1="Warning"
-  message2="Please verify your input before continuing.">
-</rel-alert>
-
-<!-- Error alert -->
-<rel-alert
-  type="error"
-  message1="Error Occurred"
-  message2="Unable to process your request.">
-</rel-alert>
-
-<!-- With action link -->
-<rel-alert
-  type="info"
-  message1="Update Available"
-  message2="A new version is ready."
-  urlText="Learn More"
-  urlHref="https://example.com/release-notes">
-</rel-alert>
-
-<!-- Non-dismissible -->
-<rel-alert
-  type="warning"
-  message1="Required Action"
-  dismissible="false">
-</rel-alert>
-
-<!-- Listen for dismiss -->
-<rel-alert id="myAlert" type="success" message1="Success!"></rel-alert>
-<script>
-  const alert = document.getElementById('myAlert');
-  alert.addEventListener('dismiss', () => {
-    console.log('Alert was dismissed');
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `type` | `"info" \| "success" \| "warning" \| "error" \| "neutral"` | `"neutral"` | Alert type determining icon and color scheme |
-| `message1` | `string` | `""` | Primary message text (bold) |
-| `message2` | `string` | - | Optional secondary message text (smaller, slightly transparent) |
-| `urlText` | `string` | - | Link text (shown below messages) |
-| `urlHref` | `string` | - | Link URL (both `urlText` and `urlHref` required for link to show) |
-| `dismissible` | `boolean` | `true` | Whether to show the close (✕) button |
-| `dismissed` | `boolean` (reflected) | `false` | When true, hides the component via `:host([dismissed])` |
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `dismiss` | None | Fired when the close button is clicked (sets `dismissed` to true) |
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-md-regular-font-size` - Primary message font size
-- `--rel-body-sm-regular-font-size` - Secondary message and link font size
-- `--rel-fonts-weight-body-medium` - Primary message and link font weight
-- `--rel-fonts-weight-body-semibold` - Used implicitly in link styling
-
-### Spacing Tokens
-- `--rel-spacing-xs` - Gap between icon and content
-- `--rel-spacing-sm` - Vertical padding
-- `--rel-spacing-md` - Horizontal padding
-- `--rel-spacing-2xs` - Close button padding
-
-### Color Tokens (by type)
-- **info**: `--rel-bg-info-light` (background), `--rel-text-info` (text), `--rel-text-info` (icon)
-- **success**: `--rel-bg-success-light`, `--rel-text-success`, `--rel-text-success`
-- **warning**: `--rel-bg-warning-light`, `--rel-text-warning`, `--rel-text-warning`
-- **error**: `--rel-bg-danger-light`, `--rel-text-error`, `--rel-text-danger`
-- **neutral**: `--rel-bg-surface` (background), `--rel-text-default` (text), `--rel-text-default` (icon), `--rel-border-default` (border)
-
-### Border Tokens
-- `--rel-border-radius-sm` - Border radius
-
-## Accessibility
-- Uses `role="alert"` for screen reader announcements
-- Close button has `aria-label="Dismiss"`
-- Focus visible states on close button with 2px outline
-- Secondary message has reduced opacity for visual hierarchy
-
-### Keyboard Interactions
-- `Tab` - Focus the close button (if dismissible)
-- `Space/Enter` - Dismiss the alert (when close button focused)
-
-### Focus Behavior
-- Close button shows 2px outline matching the alert's text color with 2px offset
-- Border radius applied to maintain visual consistency
-
-## Notes / Edge Cases
-- Icons are built-in SVG graphics that change based on `type` (info: ℹ️, success: ✓, warning: ⚠️, error: ❗, neutral: ℹ️)
-- Icon colors are controlled by type-specific `--rel-icon-*` tokens
-- The alert has a minimum width of `360px`
-- Both `urlText` and `urlHref` must be set for the link to appear
-- Links inherit the alert's text color and are underlined
-- `message2` has `opacity: 0.9` for subtle contrast with `message1`
-- When `dismissed` is set to `true`, the component applies `display: none` via `:host([dismissed])`
-- `dismissed` is a reflected attribute, meaning it appears in the HTML when true
-- The close button is always positioned at the right edge via `margin-left: auto`
-- Neutral type includes a 1px border while colored types do not
+# rel-alert
+
+`<rel-alert>` is the inline status banner of the Reliability Design System (Figma "Alert"). It renders a tone-coloured box with a leading status icon, a bold title (`message1`), optional supporting text (`message2`), an optional inline link and an optional dismiss button, in the Figma Tone (neutral / info / success / warning / destructive) and Style (subtle / solid / outline) variants. Use it for persistent, in-flow messages about a page or section — form-level validation, degraded-service notices, onboarding hints. For transient feedback that disappears on its own use `<rel-toast>` or `<rel-snackbar>`; for blocking decisions use `<rel-modal>`.
+
+## Usage
+
+```html
+<!-- Neutral (default tone, subtle appearance) -->
+<rel-alert message1="Scheduled maintenance on Sunday 02:00–04:00 UTC"></rel-alert>
+
+<!-- Tones -->
+<rel-alert tone="info" message1="Update available" message2="Version 2.3 adds offline mode."></rel-alert>
+<rel-alert tone="success" message1="Changes saved" message2="Your profile is up to date."></rel-alert>
+<rel-alert tone="warning" message1="Storage almost full" message2="You have used 95% of your quota."></rel-alert>
+<rel-alert tone="destructive" message1="Upload failed" message2="The file exceeds the 25 MB limit."></rel-alert>
+
+<!-- Appearance: subtle (default) | solid | outline -->
+<rel-alert tone="info" appearance="solid" message1="Solid alert"></rel-alert>
+<rel-alert tone="info" appearance="outline" message1="Outline alert"></rel-alert>
+
+<!-- Inline link: both url-text and url-href are required for it to render -->
+<rel-alert
+  tone="info"
+  message1="Release notes"
+  message2="See what changed in this version."
+  url-text="Read more"
+  url-href="https://example.com/release-notes"
+></rel-alert>
+
+<!-- Non-dismissible: the boolean must be cleared from script (see the js block) -->
+<rel-alert id="locked" tone="warning" message1="Action required"></rel-alert>
+
+<!-- Listen for dismissal -->
+<rel-alert id="saved" tone="success" message1="Saved"></rel-alert>
+```
+
+```js
+// A Lit boolean attribute is true whenever present, so dismissible="false" does NOT work.
+document.getElementById("locked").dismissible = false;
+
+const saved = document.getElementById("saved");
+saved.addEventListener("dismiss", () => {
+  saved.dismissed; // true — the host is now display: none
+});
+// Show it again later:
+saved.dismissed = false;
+```
+
+### Deprecated aliases
+
+```html
+<!-- type= is the deprecated alias of tone= (tone wins when both are set). Logs once per page:
+     [rel-alert] "type" is deprecated and will be removed in 3.0 — use "tone" instead. Note: tone="destructive" replaces type="error". -->
+<rel-alert type="error" message1="Upload failed"></rel-alert>
+
+<!-- tone="error" | "danger" | "critical" are deprecated spellings of tone="destructive". Logs once per spelling:
+     [rel-alert] "tone="error"" is deprecated and will be removed in 3.0 — use "tone="destructive"" instead. -->
+<rel-alert tone="error" message1="Upload failed"></rel-alert>
+<rel-alert tone="critical" message1="Upload failed"></rel-alert>
+
+<!-- appearance="filled" is the deprecated alias of appearance="solid" (no console notice). -->
+<rel-alert tone="info" appearance="filled" message1="Solid alert"></rel-alert>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-alert.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `tone` | `"neutral" \| "info" \| "success" \| "warning" \| "destructive" \| "error" \| "danger" \| "critical"` | `undefined` | Semantic tone (Figma "Tone"): `"neutral"` (default) \| `"info"` \| `"success"` \| `"warning"` \| `"destructive"`. Drives the fill/border colour, the title colour and the leading icon (info, check-circle, alert-circle, error). `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"` and log a one-time console notice. Takes precedence over the deprecated `type` prop. |
+| `appearance` | `appearance` | `"solid" \| "subtle" \| "outline" \| "filled"` | `"subtle"` | Visual treatment (Figma "Style"): `"subtle"` (default: tone-light fill, no border) \| `"solid"` (tone fill, inverse text, `--rel-shadows-md` elevation) \| `"outline"` (transparent fill, tone border). `"filled"` is a deprecated alias of `"solid"` (no console notice). Reflected. |
+| `message1` | `message1` | `string` | `""` | Primary message (title), rendered in body-lg medium weight in the tone colour. |
+| `message2` | `message2` | `string` | `undefined` | Optional secondary message rendered under the title in body-md at 90% opacity; omitted when unset. |
+| `urlText` | `url-text` | `string` | `undefined` | Text of the inline link rendered under the messages. The link appears only when both `urlText` and `urlHref` are set. |
+| `urlHref` | `url-href` | `string` | `undefined` | `href` of the inline link. The link appears only when both `urlText` and `urlHref` are set. |
+| `dismissible` | `dismissible` | `boolean` | `true` | Shows the dismiss (✕) button. Defaults to true; because it is a Lit boolean, `dismissible="false"` is still true — set the property to `false` from script to hide the button. |
+| `dismissed` | `dismissed` | `boolean` | `false` | True once the alert has been dismissed; hides the host via `:host([dismissed]) { display: none }`. Set it back to `false` to show the alert again. Reflected. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `type` | `type` | `"neutral" \| "info" \| "success" \| "warning" \| "destructive" \| "error" \| "danger" \| "critical"` | Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"`. Ignored when `tone` is set. Logs a one-time console notice. |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `resolvedTone` | `AlertTone` | Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"destructive"`. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `dismiss` | — | bubbles / composed | Fired when the user clicks the dismiss button, after `dismissed` has been set to true. No detail. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The `role="alert"` container that carries the tone and appearance styling |
+| `icon` | Wrapper around the leading status `<rel-icon>` |
+| `content` | Column that stacks the title, helper text and link |
+| `label` | The primary message (`message1`) paragraph |
+| `helper` | The secondary message (`message2`) paragraph; rendered only when `message2` is set |
+| `action` | The inline link; rendered only when both `url-text` and `url-href` are set |
+| `close-button` | The dismiss (✕) button; rendered only while `dismissible` is true |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The container (part `base`) has `role="alert"` and `aria-atomic="true"`, so screen readers announce the whole message assertively when the element enters the DOM or its text changes. Because of that, reserve it for messages that warrant an interruption; render a `<rel-alert>` only when there is something to say rather than keeping an empty one mounted.
+- The leading status `<rel-icon>` renders `aria-hidden="true"`; the tone is not conveyed to assistive technology except through the text, so put the meaning in `message1` / `message2`.
+- The dismiss control is a native `<button>` with `aria-label="Dismiss"`. The inline link is a plain `<a href>`. Both are in the Tab order; the component adds no key handlers of its own:
+
+| Key | Action |
+| --- | --- |
+| Tab / Shift + Tab | Move between the inline link (if any) and the dismiss button (if any) |
+| Enter / Space | Activate the focused dismiss button (fires `dismiss`, sets `dismissed`) |
+| Enter | Follow the focused link |
+
+- Keyboard focus on the dismiss button is a 2px `currentColor` outline with 2px offset (`:focus-visible` only).
+- Dismissing hides the host with `display: none`; focus is not moved, so if the dismiss button had focus the browser drops focus to `<body>`. Move focus yourself in the `dismiss` handler when the alert sits in the middle of a form.
+
+## Notes / Edge Cases
+
+- `tone` and `appearance` are independent axes; every tone renders in every appearance. Solid uses inverse text and carries the `--rel-shadows-md` elevation; subtle and outline have no shadow.
+- The status icon is fixed per tone (`info` for neutral and info, `check-circle`, `alert-circle`, `error`) and cannot be replaced or removed — there are no slots.
+- The alert has `min-width: 360px`; it stretches to its container (`display: block`) but never shrinks below that.
+- The link renders only when both `url-text` and `url-href` are set; it opens in the same tab (no `target`).
+- `dismissible` and `dismissed` are Lit booleans: any attribute value (including `"false"`) counts as true. Toggle them as properties from script.
+- `dismissed` only hides the host; the element stays in the DOM and keeps its state. Resetting `dismissed = false` shows it again without re-firing `dismiss`.
+- `resolvedTone` is the tone actually rendered after alias resolution; use it (not `tone` / `type`) if you branch on tone in script.