@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,130 +1,190 @@
-# rel-button
-
-## Overview
-A versatile button component with six variants (default, primary, secondary, text, link, icon), three tone options, three sizes, and configurable border radius. Features hover, active, and focus states with smooth transitions. Slots support custom content including text, icons, or combinations.
-
-## Usage
-```html
-<!-- Basic variants -->
-<rel-button variant="default">Default Button</rel-button>
-<rel-button variant="primary">Primary Button</rel-button>
-<rel-button variant="secondary">Secondary Button</rel-button>
-<rel-button variant="text">Text Button</rel-button>
-<rel-button variant="link">Link Style</rel-button>
-
-<!-- Icon button -->
-<rel-button variant="icon">⚙️</rel-button>
-
-<!-- Tones (affect color scheme) -->
-<rel-button variant="primary" tone="default">Default Tone</rel-button>
-<rel-button variant="primary" tone="critical">Critical Action</rel-button>
-<rel-button variant="primary" tone="success">Success Action</rel-button>
-
-<!-- Sizes -->
-<rel-button size="small">Small</rel-button>
-<rel-button size="medium">Medium</rel-button>
-<rel-button size="large">Large</rel-button>
-
-<!-- Border radius options -->
-<rel-button border="corner-radius">Rounded</rel-button>
-<rel-button border="small-corner-radius">Small Rounded</rel-button>
-<rel-button border="no-corner-radius">Sharp</rel-button>
-
-<!-- Disabled -->
-<rel-button disabled>Disabled Button</rel-button>
-
-<!-- With icon and text (using slot) -->
-<rel-button variant="primary">
-  <svg width="16" height="16" viewBox="0 0 16 16"><path d="M8 0l3 6h6l-5 4 2 6-6-4-6 4 2-6-5-4h6z"/></svg>
-  Save
-</rel-button>
-
-<!-- Listen for click -->
-<rel-button id="actionBtn" variant="primary">Click Me</rel-button>
-<script>
-  document.getElementById('actionBtn').addEventListener('click', () => {
-    console.log('Button clicked');
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `"default" \| "primary" \| "secondary" \| "text" \| "link" \| "icon"` | `"default"` | Visual style variant |
-| `tone` | `"default" \| "critical" \| "success"` | `"default"` | Color tone (affects default/primary variants) |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Button size |
-| `border` | `"corner-radius" \| "small-corner-radius" \| "no-corner-radius"` | `"corner-radius"` | Border radius style |
-| `disabled` | `boolean` (reflected) | `false` | Disables interaction and applies disabled styling |
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `click` | `MouseEvent` | Re-dispatched from the internal button (for framework compatibility) |
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Button content (text, icons, or combination) |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-fonts-weight-body-semibold` - Font weight
-- `--rel-body-sm-regular-font-size`, `--rel-body-md-regular-font-size`, `--rel-body-xl-regular-font-size` - Font sizes for sizes
-
-### Spacing Tokens
-- `--rel-spacing-2xs` - Internal gap between elements
-- `--rel-spacing-md`, `--rel-spacing-lg`, `--rel-spacing-xl` - Horizontal padding by size
-
-### Color Tokens (by variant/tone)
-- **default + default tone**: `--rel-text-default` (bg), `--rel-bg-surface` (text)
-- **default + critical tone**: `--rel-bg-danger` (bg), `--rel-bg-surface` (text)
-- **default + success tone**: `--rel-text-success` (bg), `--rel-bg-surface` (text)
-- **primary + default tone**: `--rel-bg-brand` (bg), `--rel-text-default` (text)
-- **primary + critical tone**: `--rel-bg-danger` (bg), `--rel-bg-surface` (text)
-- **primary + success tone**: `--rel-text-success` (bg), `--rel-bg-surface` (text)
-- **secondary**: `--rel-bg-surface` (bg), `--rel-text-default` (text + border)
-- **text**: transparent (bg), `--rel-text-default` (text)
-- **link**: transparent (bg), `--rel-bg-info` (text), underlined
-- **icon**: `--rel-bg-surface-elevated` (bg), `--rel-text-default` (text), circular (40px × 40px)
-- **disabled**: `--rel-border-default` (bg), `--rel-text-disabled` (text)
-
-### Border Tokens
-- `--rel-border-radius-full-rounded` - Large corner radius
-- `--rel-border-radius-sm` - Small corner radius
-- `--rel-border-radius-square` - No corner radius
-
-## Accessibility
-- Uses native `<button>` element for proper semantics
-- `aria-disabled` attribute set on disabled buttons
-- Focus visible state with blue outline
-- Keyboard accessible (Space/Enter activation)
-
-### Keyboard Interactions
-- `Tab` - Focus the button
-- `Space/Enter` - Activate the button
-
-### Focus Behavior
-- Blue 2px outline with 2px offset on focus-visible
-- Focus outline works across all variants
-
-## Notes / Edge Cases
-- **Icon variant** is always circular (40px × 40px), ignores size property, and has no padding
-- **Link variant** has `text-decoration: underline`
-- **Secondary variant** includes a 1px border matching the text color
-- Hover effect applies `filter: brightness(0.92)` to darken
-- Active (pressed) effect applies `transform: scale(0.97)` for tactile feedback
-- Disabled buttons have `pointer-events: none` and use `!important` to override theming
-- The component re-dispatches click events to ensure framework compatibility (e.g., Angular)
-- Clicking a disabled button prevents default and stops propagation
-- Size variants affect height (32px/40px/48px) and horizontal padding
-- The button has `display: inline-flex` with `align-items: center` and `justify-content: center`
-- Internal gap of `var(--rel-spacing-2xs)` allows icons + text combinations
-- Transitions are `0.15s ease` for all visual changes
+# rel-button
+
+Action button implementing the Figma "Button" component: a native `<button>` with the Figma **Style** (`variant`), **Tone** (`tone`) and **Size** axes, an independent **Icon Only** mode, a **Loading** state and an optional corner badge. Use it for every clickable action (submit, confirm, open, delete). Do not use it for navigation to another page — use a link instead.
+
+## Usage
+
+```html
+<!-- Styles (Figma "Style") -->
+<rel-button variant="primary">Primary</rel-button>
+<rel-button variant="secondary">Secondary</rel-button>
+<rel-button variant="ghost">Ghost</rel-button>
+<rel-button variant="link">Link style</rel-button>
+<rel-button variant="default">Neutral fill</rel-button>
+<div style="background: #1f2937; padding: 8px;">
+  <rel-button variant="static">Static (on dark surfaces)</rel-button>
+</div>
+
+<!-- Tones (Figma "Tone") -->
+<rel-button variant="primary" tone="brand">Save</rel-button>
+<rel-button variant="primary" tone="neutral">Cancel</rel-button>
+<rel-button variant="primary" tone="destructive">Delete</rel-button>
+<rel-button variant="secondary" tone="destructive">Remove</rel-button>
+<rel-button variant="ghost" tone="destructive">Discard</rel-button>
+
+<!-- Sizes: 32 / 40 / 48px -->
+<rel-button size="small">Small</rel-button>
+<rel-button size="medium">Medium</rel-button>
+<rel-button size="large">Large</rel-button>
+
+<!-- Corner radius -->
+<rel-button border="corner-radius">Pill</rel-button>
+<rel-button border="small-corner-radius">Small radius</rel-button>
+<rel-button border="no-corner-radius">Square</rel-button>
+
+<!-- Icon + label, and icon-only (needs an accessible name) -->
+<rel-button variant="primary">
+  <rel-icon name="plus"></rel-icon>
+  Add item
+</rel-button>
+<rel-button variant="secondary" icon-only aria-label="Settings">
+  <rel-icon name="settings"></rel-icon>
+</rel-button>
+<rel-button variant="ghost" icon-only size="small" aria-label="Close">
+  <rel-icon name="x"></rel-icon>
+</rel-button>
+
+<!-- States -->
+<rel-button variant="primary" loading>Saving</rel-button>
+<rel-button variant="primary" disabled>Unavailable</rel-button>
+
+<!-- Corner badges -->
+<rel-button variant="secondary" badge="3">Inbox</rel-button>
+<rel-button variant="ghost" icon-only badge-dot aria-label="Notifications">
+  <rel-icon name="bell"></rel-icon>
+</rel-button>
+
+<!-- Listen for clicks (native click bubbles through the shadow root) -->
+<rel-button id="save" variant="primary">Save</rel-button>
+<script>
+  document.getElementById('save').addEventListener('click', () => {
+    console.log('saved');
+  });
+</script>
+
+<!-- Per-instance minimum width -->
+<rel-button variant="primary" style="--rel-button-min-width: 160px;">Wide</rel-button>
+```
+
+### Deprecated aliases
+
+```html
+<!-- Legacy Style spellings — still rendered identically, prefer the canonical names -->
+<rel-button variant="outline">Outline</rel-button>   <!-- → variant="secondary" -->
+<rel-button variant="text">Text</rel-button>         <!-- → variant="ghost" -->
+<rel-button variant="icon" aria-label="Settings">    <!-- → icon-only + a variant -->
+  <rel-icon name="settings"></rel-icon>
+</rel-button>
+
+<!-- Legacy Tone spellings — each logs once per page:
+     [rel-button] "tone="critical"" is deprecated and will be removed in 3.0 — use "tone="destructive"" instead. -->
+<rel-button variant="primary" tone="critical">Delete</rel-button> <!-- → tone="destructive" -->
+<rel-button variant="primary" tone="danger">Delete</rel-button>   <!-- → tone="destructive" -->
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-button.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `variant` | `"default" \| "primary" \| "secondary" \| "text" \| "link" \| "icon" \| "static" \| "outline" \| "ghost"` | `"default"` | Style axis (Figma "Style"). Canonical: `default` (legacy neutral fill), `primary`, `secondary` (outlined), `ghost` (text-only), `link` (underlined inline text), `static` (transparent, static-light label for dark/colored surfaces). Deprecated aliases still accepted: `outline` = secondary, `text` = ghost, and `icon` (pre-2.0 40px circular icon button — use `icon-only` with a style instead). |
+| `tone` | `tone` | `"default" \| "primary" \| "secondary" \| "critical" \| "success" \| "neutral" \| "brand" \| "danger" \| "destructive"` | `undefined` | Tone axis (Figma "Tone"). Canonical: `neutral` (= `default`), `brand` (= `primary`), `destructive`. Deprecated aliases `critical` and `danger` map to destructive and log a one-time console notice. `secondary` and `success` are legacy extras with no Figma counterpart (secondary only affects the legacy `icon` variant). Left UNSET it means `neutral`, except on `variant="primary"`, where it still means `brand` for one release — see `effectiveTone`. Write the tone explicitly and you always get what you wrote. |
+| `iconOnly` | `icon-only` | `boolean` | `false` | Figma "Type=Icon Only": renders a square button (32/40/48px per `size`) of the current style and tone with no padding or min-width. Composes with every `variant`; slot a single `rel-icon` and set `aria-label`. Reflected. |
+| `loading` | `loading` | `boolean` | `false` | Figma "State=Loading": replaces the label with a spinner (`indicator` part), sets `aria-busy`, and blocks pointer and programmatic clicks. The button keeps its width. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Figma "Size": `small` = 32px, `medium` = 40px, `large` = 48px height, with matching padding, typography and minimum width. |
+| `border` | `border` | `"corner-radius" \| "small-corner-radius" \| "no-corner-radius"` | `"corner-radius"` | Corner treatment: `corner-radius` = fully rounded pill, `small-corner-radius` = small radius token, `no-corner-radius` = square corners. |
+| `disabled` | `disabled` | `boolean` | `false` | Figma "State=Disabled": dims the button to 50% opacity, flattens filled styles to the disabled fill, shows a `not-allowed` cursor and swallows every click (including programmatic `.click()`). Reflected. |
+| `ariaLabel` | `aria-label` | `string \| null` | `null` | Accessible name forwarded to the inner native `<button>`. Required for `icon-only` buttons, whose slotted icon has no visible text. |
+| `badge` | `badge` | `string` | `""` | Text for a small `rel-badge` anchored to the top-right corner (e.g. "3", "999+"). Empty string renders no badge. Ignored when `badge-dot` is set. |
+| `badgeDot` | `badge-dot` | `boolean` | `false` | Renders a small dot badge in the top-right corner instead of a numbered badge; takes precedence over `badge`. The dot is inset 2px from the corner so it lands on a circular icon button's edge. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Button content: label text, a `rel-icon`, or icon + text (kept on one line with the size's gap). |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The inner native `<button>` element (padding, min-width, fill, border, focus ring). |
+| `indicator` | The loading spinner, rendered only 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-button-min-width` | `80px` | Overrides the per-size minimum width (Figma small/medium/large = 80/100/120px, ghost small = 56px). Ignored by `icon-only` and `link`. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Renders a native `<button>` (the `base` part), so it is focusable, announced as a button and activated with the keyboard without extra work.
+- `aria-disabled` mirrors `disabled`; `aria-busy` mirrors `loading`. The spinner is `aria-hidden`, and the label stays in the DOM (visually hidden) while loading, so the accessible name does not change.
+- `aria-label` is forwarded to the inner button. Always set it on `icon-only` buttons and on the legacy `icon` variant — a slotted icon has no text.
+- Disabled and loading buttons swallow clicks in the capture phase on the host, so `el.click()` and delegated listeners never fire.
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move focus to / from the button |
+| `Enter` / `Space` | Activate (native button behaviour) |
+
+Focus: `:focus-visible` shows the shared 2px focus outline plus inner/outer halo on every style except `link`, which shows a 2px focus-coloured underline bar and the hover label colour instead (still a visible indicator per WCAG 2.4.7). Pressing scales the button to 97%; the spinner slows to 2s under `prefers-reduced-motion: reduce`.
+
+## Notes / Edge Cases
+
+### The `variant="primary"` tone transition
+
+Figma's `Style=Primary` is the **filled** style, and `Tone` picks its colour — so Primary + Neutral is the neutral fill and Primary + Brand is the brand fill. This component's `variant="primary"` historically meant *both* "filled" and "brand-coloured", which left the Figma-canonical Primary/Neutral cell unreachable by its own names.
+
+That cell now works: **`variant="primary" tone="neutral"` renders the neutral fill.**
+
+For one release there is a deliberate wrinkle, and it is worth knowing before you debug it:
+
+| Markup | Renders | Why |
+| --- | --- | --- |
+| `<rel-button>` | neutral fill | Unchanged. `variant` defaults to `default`, which is Figma's Primary/Neutral. |
+| `<rel-button variant="primary">` | **brand** fill | Unset tone still means brand *here only*, so existing brand buttons do not silently turn neutral. Logs a one-time console notice. |
+| `<rel-button variant="primary" tone="brand">` | brand fill | The explicit form. **Write this.** |
+| `<rel-button variant="primary" tone="neutral">` | neutral fill | The Figma-canonical cell, now reachable. |
+
+So for this release, writing the default value explicitly changes the result: `variant="primary"` alone and `variant="primary" tone="neutral"` render differently. Setting `tone` explicitly always gives you exactly what you wrote. A future major will make an unset tone mean `neutral` everywhere, matching every other style.
+
+### Tone × Style matrix
+
+Figma populates only part of the grid. Combinations outside it have no design-system definition and fall back to the style's neutral treatment:
+
+| Tone | Primary | Secondary | Ghost | Link | Static |
+| --- | --- | --- | --- | --- | --- |
+| Neutral | yes | yes | yes | yes | yes |
+| Brand | yes | — | — | — | — |
+| Destructive | yes | yes | yes | yes | — |
+
+`Link` additionally has no icon-only and no loading state in the design.
+
+- **Events.** The element dispatches no custom events. The native `click` is `composed`, so a listener on `<rel-button>` (or an ancestor) receives exactly one event per activation — do not re-dispatch it.
+- **Minimum widths** come from the Figma master: small/medium/large = 80/100/120px, static = 40/50/60px. `link` has no minimum, `icon-only` is a fixed square (32/40/48px) and the legacy `icon` variant is always a 40px circle regardless of `size`. Override per instance with `--rel-button-min-width`.
+- **`border`** exposes `small-corner-radius` and `no-corner-radius`, which have no design-system backing — every one of Figma's 624 button nodes is fully rounded. They are a code-only extension, kept for existing layouts.
+- **Legacy `icon` variant vs `icon-only`.** `variant="icon"` keeps its pre-2.0 look (40px circle, tone-driven fill, `tone="secondary"` gives it an outline) and ignores `size` and `border`. `icon-only` is an axis that composes with any style and size — prefer it.
+- **`tone` on `secondary` / `ghost` / `link`** changes the label, border or text colour only; the fill stays on the surface. The destructive outline border is deliberately subtle at rest and only goes solid on hover/pressed, matching Figma.
+- **`static`** is a neutral-only style meant for coloured or dark backgrounds; other tones have no static treatment.
+- **`success`** is a legacy tone without a Figma counterpart; it renders a green fill/outline/ghost tint but is not part of the current spec.
+- **Badges** render a small `rel-badge` positioned outside the button's box (numbered) or 2px inside the corner (dot); give the button room in tight layouts. `badge-dot` wins when both are set.
+- **Disabled styling**: only filled styles (`default`, `primary`, `icon`) flatten to the neutral disabled fill; `secondary`, `ghost`, `link` and `static` keep their shape at 50% opacity so they still read as their own style.

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

@@ -1,109 +1,109 @@
-# rel-calendar
-
-A fully accessible calendar component built with Lit for the Reliability Design System.
-
-## Features
-
-- Single date selection
-- Month navigation
-- Keyboard navigation support (arrow keys, Home/End, PageUp/PageDown)
-- Min/max date constraints
-- Custom disabled date predicate
-- Configurable week start (Sunday or Monday)
-- Locale-aware month names
-- Today indicator
-- Full ARIA support
-
-## Usage
-
-```html
-<rel-calendar></rel-calendar>
-```
-
-### With value
-
-```html
-<rel-calendar value="2026-01-16"></rel-calendar>
-```
-
-### With min/max
-
-```html
-<rel-calendar
-  min="2026-01-01"
-  max="2026-12-31"
-></rel-calendar>
-```
-
-### Week starting Monday
-
-```html
-<rel-calendar week-start="mon"></rel-calendar>
-```
-
-### Disabled
-
-```html
-<rel-calendar disabled></rel-calendar>
-```
-
-### Custom disabled dates (JavaScript)
-
-```javascript
-const calendar = document.querySelector('rel-calendar');
-
-// Disable weekends
-calendar.isDateDisabled = (date) => {
-  const day = date.getDay();
-  return day === 0 || day === 6; // Sunday or Saturday
-};
-
-// Listen to changes
-calendar.addEventListener('rel-change', (e) => {
-  console.log('Selected date:', e.detail.value); // "2026-01-16"
-  console.log('Selected date object:', e.detail.date); // Date object
-});
-```
-
-## Attributes
-
-| Attribute | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `value` | `string \| null` | `null` | Selected date in ISO format (YYYY-MM-DD) |
-| `min` | `string \| null` | `null` | Minimum selectable date (ISO format) |
-| `max` | `string \| null` | `null` | Maximum selectable date (ISO format) |
-| `disabled` | `boolean` | `false` | Disables all interaction |
-| `week-start` | `"sun" \| "mon"` | `"sun"` | First day of the week |
-| `locale` | `string` | `"en-US"` | Locale for month names (uses Intl.DateTimeFormat) |
-
-## Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `isDateDisabled` | `(date: Date) => boolean` | Custom function to disable specific dates |
-
-## Events
-
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `rel-change` | `{ value: string \| null, date: Date \| null }` | Fired when selection changes |
-
-## Keyboard Navigation
-
-- **Arrow keys**: Move focus by day (left/right) and week (up/down)
-- **Home/End**: Jump to start/end of current week
-- **PageUp/PageDown**: Change month
-- **Shift + PageUp/PageDown**: Change year
-- **Enter/Space**: Select focused day
-
-## Styling
-
-The component uses design tokens from the Reliability Design System. All colors, spacing, and typography are inherited from CSS variables.
-
-Key tokens used:
-- `--rel-bg-*` / `--rel-text-*` / `--rel-border-*` semantic colors
-- `--rel-spacing-*` for spacing
-- `--rel-body-*` / `--rel-headings-*` composite typography roles
-- `--rel-border-radius-*` for border radius
-- Focus outline uses `--rel-bg-info`
-- Selected state uses `--rel-bg-brand`
+# rel-calendar
+
+`<rel-calendar>` is the inline, always-visible month calendar of the Reliability Design System (Figma "Calendar"). It renders one month as a 7-column grid with previous/next navigation, a today ring, dimmed weekends and adjacent-month days, `min`/`max` bounds and a custom disabled-day predicate, and lets the user select a single date. Use it when the calendar itself is the interface — a scheduling sidebar, an inline availability view. For a form field that opens a calendar in a popover use `<rel-date-picker>`; for a from/to range use `<rel-range-picker>`.
+
+## Usage
+
+```html
+<!-- Default: today's month, nothing selected -->
+<rel-calendar></rel-calendar>
+
+<!-- Preselected date (ISO YYYY-MM-DD); the grid opens on that month -->
+<rel-calendar value="2026-01-16"></rel-calendar>
+
+<!-- Bounded: days outside min/max render disabled -->
+<rel-calendar min="2026-01-01" max="2026-12-31"></rel-calendar>
+
+<!-- Monday-first week with German month and weekday names -->
+<rel-calendar week-start="mon" locale="de-DE"></rel-calendar>
+
+<!-- Disabled: every cell and both navigation buttons are inert -->
+<rel-calendar value="2026-01-16" disabled></rel-calendar>
+```
+
+```js
+const calendar = document.querySelector("rel-calendar");
+
+// Disable individual days on top of min/max (property only — there is no attribute)
+calendar.isDateDisabled = (date) => date.getDay() === 0 || date.getDay() === 6;
+
+calendar.addEventListener("rel-change", (e) => {
+  e.detail.value; // "2026-01-16"
+  e.detail.date;  // Date at local midnight
+});
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-calendar.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | `string \| null` | `null` | Selected date as an ISO `YYYY-MM-DD` string, or `null` for no selection; setting it also moves the visible month. Reflected. |
+| `min` | `min` | `string \| null` | `null` | Earliest selectable date (ISO `YYYY-MM-DD`); earlier days render disabled. |
+| `max` | `max` | `string \| null` | `null` | Latest selectable date (ISO `YYYY-MM-DD`); later days render disabled. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables every day cell and the month navigation; the host dims to 40% opacity (Figma State=Disabled). Reflected. |
+| `weekStart` | `week-start` | `"sun" \| "mon"` | `"sun"` | First column of the week grid: `"sun"` (default) or `"mon"`. |
+| `locale` | `locale` | `string` | `"en-US"` | BCP 47 locale for the month name, weekday headers and day cell labels (via `Intl.DateTimeFormat`). |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `isDateDisabled` | `(date: Date) => boolean` | Custom predicate that disables individual days (return `true` to disable); applied on top of `min`/`max`. Property only — assign it from JavaScript. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `{ value: newValue, date: new Date(day.date), }` | bubbles / composed | Fired when the user selects a day. Detail: `{ value: string, date: Date }` — the ISO `YYYY-MM-DD` string and a local-midnight Date. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `header` | Month navigation row (previous button, month/year label, next button) |
+| `action` | The previous-month and next-month buttons |
+| `label` | The month/year heading and each weekday column header |
+| `list` | The weekday-header row and the day grid |
+| `item` | Each day cell button |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The day area is a `role="grid"` named "<Month> <Year>" (e.g. "January 2026"); the weekday header row and each week are `role="row"`, weekday names are `role="columnheader"`.
+- Every day is a native `<button role="gridcell">` whose `aria-label` is the full long date in `locale` ("Friday, January 16, 2026"), with `aria-selected` for the selected day, `aria-current="date"` on today, and the native `disabled` attribute for days outside `min`/`max`, rejected by `isDateDisabled`, or when the host is `disabled`.
+- The navigation buttons are labelled "Previous month" / "Next month".
+- Roving tabindex: exactly one cell is a Tab stop — the last cell the user arrowed to, else the selected day, else today, else the first enabled day of the month — so Tab can always re-enter the grid.
+- After every month or year change (buttons, PageUp/PageDown, or arrowing past the edge of the month) the new "<Month> <Year>" is read to screen readers through the shared `announce()` live region (`utils/announce.ts`).
+
+| Key | Action |
+| --- | --- |
+| ArrowLeft / ArrowRight | Focus the previous / next day (crossing into the adjacent month switches the view) |
+| ArrowUp / ArrowDown | Focus the same weekday one week earlier / later |
+| Home / End | Focus the first / last cell of the current row |
+| PageUp / PageDown | Show the previous / next month |
+| Shift + PageUp / Shift + PageDown | Show the previous / next year |
+| Enter / Space | Select the focused day (fires `rel-change`) |
+
+## Notes / Edge Cases
+
+- `value`, `min` and `max` must be `YYYY-MM-DD`; any other string is ignored (no selection, view unchanged). Setting `value` moves the visible month; clearing it to `null` leaves the view where it is.
+- The grid always renders six weeks (42 cells). The leading/trailing cells belong to the adjacent months and, unlike in `rel-date-picker`, they are selectable (subject to `min`/`max`/`isDateDisabled`); picking one fires `rel-change` and the view jumps to that month.
+- Comparisons happen at local midnight: the `Date` passed to `isDateDisabled` and returned in `rel-change` is `new Date(y, m, d)`, so read it with local getters, not `toISOString()`.
+- `disabled` makes every day fail the disabled check and disables both navigation buttons; pointer events stay on the host so the `not-allowed` cursor shows.
+- Each cell follows Figma ".Date Days": a 36 px full-rounded halo around a 28 px disc. The halo carries hover (`action/overlay/hover`), the focus ring and the selected day's `elevated-1` backing; the disc carries today's 1 px brand ring and the selected day's `inverse-2` fill with an inverse semibold label.
+- Figma treats the cell tone as one axis, so exactly one applies per day: today beats weekend beats adjacent-month. Adjacent-month labels render at 40% and weekend labels at 70% — on the label only, so a *selected* weekend or adjacent-month day still reads at full contrast on the dark disc. A disabled day switches to the disabled text colour, and a disabled today swaps its brand ring for a neutral one.
+- The month-navigation buttons are hand-rolled ghost buttons that bind the same action tokens as `<rel-button variant="ghost">` (audit 8b) — they are intentionally not `<rel-button>` instances.
+- The host has a fixed `max-width: 320px`, its own radius, shadow and padding and no border (Figma draws the card with `shadow/xl`, approximated here by `--rel-shadows-shadow-400`, the nearest shipped step); wrap it or override on the host if you need a different footprint.