@reliability-design/web 1.4.5 → 1.4.7

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.

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

@@ -1,94 +1,75 @@
-# rel-card
-
-## Overview
-A simple, versatile card container component with built-in elevation shadow and hover lift effect. Provides a clean, elevated surface for grouping related content. Respects user motion preferences by disabling animations when requested.
-
-## Usage
-```html
-<!-- Basic card with text content -->
-<rel-card>
-  <h3>Card Title</h3>
-  <p>This is some content inside the card.</p>
-</rel-card>
-
-<!-- Card with mixed content -->
-<rel-card>
-  <h2>Product Name</h2>
-  <img src="product.jpg" alt="Product" style="width: 100%; border-radius: 8px;">
-  <p>Product description goes here.</p>
-  <button>Add to Cart</button>
-</rel-card>
-
-<!-- Multiple cards in a grid -->
-<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px;">
-  <rel-card>
-    <h4>Feature 1</h4>
-    <p>Description of feature 1</p>
-  </rel-card>
-  <rel-card>
-    <h4>Feature 2</h4>
-    <p>Description of feature 2</p>
-  </rel-card>
-  <rel-card>
-    <h4>Feature 3</h4>
-    <p>Description of feature 3</p>
-  </rel-card>
-</div>
-```
-
-## API
-
-### Attributes/Properties
-None. This component is purely presentational and controlled via slots.
-
-## Events
-None.
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Card content (any HTML elements) |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-
-### Color Tokens
-- `--rel-bg-surface` - Card background color
-- `--rel-text-default` - Text color
-
-### Shadow Tokens
-- `--rel-shadows-shadow-200` - Default elevation shadow
-- `--rel-shadows-shadow-300` - Hover elevation shadow (larger)
-
-### Border Tokens
-- `--rel-border-radius-md` - Card border radius
-
-### Spacing Tokens
-- `--rel-spacing-md` - Internal padding
-
-## Accessibility
-- The card itself has no specific ARIA role (it's a generic container)
-- Ensure slotted content includes proper semantic HTML and ARIA attributes where needed
-- Hover effect is purely visual and does not affect accessibility
-
-### Keyboard Interactions
-- None (purely presentational container)
-
-### Focus Behavior
-- Does not receive focus (container only)
-- Ensure slotted interactive elements are keyboard accessible
-
-## Notes / Edge Cases
-- The card is `display: block` and takes full width of its container by default
-- **Hover effect**: Translates the card upward by 3px (`translateY(-3px)`) and increases shadow depth
-- **Animation**: Uses `transition: transform 0.2s ease, box-shadow 0.2s ease`
-- **Motion preferences**: When `prefers-reduced-motion: reduce`, both hover transform and transitions are disabled
-- The card has consistent padding on all sides via `--rel-spacing-md`
-- The internal `.card` wrapper is where all styling is applied
-- The component provides no default content styling—you control the layout of slotted elements
-- Works well with CSS Grid or Flexbox for creating card layouts
+# rel-card
+
+`<rel-card>` is a bordered, padded surface that groups related content — the Figma "Card" component. `type="custom"` (the default) pads whatever you slot in and applies the Figma card typography to slotted headings and paragraphs; `type="media"` adds a flush media region above the body, meant for a `<rel-card-media>` image header. Use it for dashboard tiles, summary blocks and list items that pair a title with body copy. It is a static container with no interaction of its own — for transient content use `rel-modal` or `rel-drawer` instead, and for a surface with its own tone/elevation variants use `rel-container`.
+
+## Usage
+
+```html
+<!-- Default type: padded body -->
+<rel-card>
+  <h3>Shipment 4821</h3>
+  <p>Departed Dallas · ETA Thursday 14:00</p>
+</rel-card>
+
+<!-- Media type: flush image header via <rel-card-media> in the "media" slot -->
+<rel-card type="media">
+  <rel-card-media slot="media" image-src="/img/warehouse.jpg" image-alt="Warehouse floor"></rel-card-media>
+  <h3>Dallas hub</h3>
+  <p>12 dock doors · 24/7 operations</p>
+</rel-card>
+
+<!-- Cards in a grid -->
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px;">
+  <rel-card><h4>On time</h4><p>98.2%</p></rel-card>
+  <rel-card><h4>Damage-free</h4><p>99.7%</p></rel-card>
+  <rel-card><h4>Claims</h4><p>3 open</p></rel-card>
+</div>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-card.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `type` | `type` | `"custom" \| "media"` | `"custom"` | Figma "Type" axis: custom (default) renders slotted content with card padding; media adds a flush media region (slot name="media") above the content — pair it with <rel-card-media>. Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Card body; slotted headings and paragraphs receive the Figma card typography |
+| `media` | Flush media region above the body; rendered only when `type="media"` |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The outer bordered card surface |
+| `header` | The media region wrapper (present only when `type="media"`) |
+| `content` | The padded body that wraps the default slot |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The card sets no ARIA role — it is a generic container (`display: block`), so the accessible structure comes entirely from the slotted content. Use real headings (`<h2>`–`<h4>`) and paragraphs inside it; they also pick up the card typography.
+- The host is not focusable and has no keyboard handling. Interactive children (links, `rel-button`) keep their own focus order and must be keyboard-reachable on their own.
+- A `<rel-card-media>` in the `media` slot carries the image's alt text via its `image-alt` attribute; leave it empty only for purely decorative imagery.
+
+## Notes / Edge Cases
+
+- `type="media"` removes the card's own padding and clips overflow so the media sits flush against the rounded border; the body (`content` part) keeps the standard padding. Content placed in the `media` slot without `type="media"` is not rendered, because the slot only exists in that mode.
+- The `header` part exists only while `type="media"`; `::part(header)` matches nothing otherwise.
+- Slotted `h1`–`h4` and `p` elements get the Figma card roles (heading md / body lg) with their default margins reset; wrap other content in your own elements to style it.
+- There is no hover lift, shadow or transition — the card is a flat bordered surface in both light and dark themes.

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

@@ -1,127 +1,100 @@
-# rel-card-media
-
-## Overview
-A media-rich card component combining an image, title, subtitle, and custom content area. Features automatic image sizing with object-fit, enhanced hover lift effect (4px), and semantic heading structure. Ideal for blog posts, product listings, or media galleries.
-
-## Usage
-```html
-<!-- Basic media card -->
-<rel-card-media
-  imageSrc="./photo.jpg"
-  imageAlt="Beautiful landscape"
-  title="Card Title"
-  subtitle="Card subtitle or description">
-</rel-card-media>
-
-<!-- With custom slotted content -->
-<rel-card-media
-  imageSrc="./product.jpg"
-  imageAlt="Product image"
-  title="Premium Product"
-  subtitle="$99.99">
-  <p>Additional product details go here.</p>
-  <button>Buy Now</button>
-</rel-card-media>
-
-<!-- Without image -->
-<rel-card-media
-  title="Text-Only Card"
-  subtitle="No image provided">
-  <p>This card has no image, just title, subtitle, and content.</p>
-</rel-card-media>
-
-<!-- With title only -->
-<rel-card-media
-  imageSrc="./banner.jpg"
-  imageAlt="Banner"
-  title="Event Title">
-  <p>Event description and details.</p>
-</rel-card-media>
-
-<!-- Gallery layout -->
-<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px;">
-  <rel-card-media
-    imageSrc="./img1.jpg"
-    title="Gallery Item 1">
-  </rel-card-media>
-  <rel-card-media
-    imageSrc="./img2.jpg"
-    title="Gallery Item 2">
-  </rel-card-media>
-  <rel-card-media
-    imageSrc="./img3.jpg"
-    title="Gallery Item 3">
-  </rel-card-media>
-</div>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `imageSrc` | `string` | `""` | URL of the card image (optional) |
-| `imageAlt` | `string` | `"Card image"` | Alt text for the image (for accessibility) |
-| `title` | `string` | `""` | Card title displayed as `<h3>` (optional) |
-| `subtitle` | `string` | `""` | Card subtitle displayed as `<p>` (optional) |
-
-## Events
-None.
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Additional content rendered below title and subtitle |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-md-regular-font-size` - Title font size
-- `--rel-body-sm-regular-font-size` - Subtitle font size
-- `--rel-fonts-weight-body-semibold` - Title font weight
-
-### Color Tokens
-- `--rel-bg-surface` - Card background color
-- `--rel-text-default` - General text color
-- `--rel-text-label` - Title color
-
-### Shadow Tokens
-- `--rel-shadows-shadow-200` - Default elevation shadow
-- `--rel-shadows-shadow-300` - Hover elevation shadow (larger)
-
-### Border Tokens
-- `--rel-border-radius-md` - Card border radius
-
-### Spacing Tokens
-- `--rel-spacing-md` - Content area padding
-
-## Accessibility
-- Image has `alt` attribute for screen reader support
-- Title uses semantic `<h3>` heading
-- Subtitle uses `<p>` for proper text hierarchy
-- Hover effect is purely visual and does not affect accessibility
-
-### Keyboard Interactions
-- None (purely presentational container)
-- Ensure slotted interactive elements are keyboard accessible
-
-### Focus Behavior
-- Does not receive focus (container only)
-
-## Notes / Edge Cases
-- **Image rendering**: If `imageSrc` is not provided or empty, the image section is not rendered
-- **Image sizing**: The image uses `width: 100%`, `height: auto`, and `object-fit: cover` for responsive scaling
-- The image is `display: block` to remove default inline spacing
-- **Title and subtitle**: Both are optional; if not provided, their respective elements are not rendered
-- Title has `margin: 0 0 4px 0` for spacing from subtitle
-- Subtitle has `margin: 0 0 8px 0` for spacing from slotted content
-- **Hover effect**: Translates the card upward by 4px (`translateY(-4px)`) and increases shadow depth (1px more than rel-card)
-- **Animation**: Uses `transition: transform 0.2s ease, box-shadow 0.2s ease`
-- **Motion preferences**: When `prefers-reduced-motion: reduce`, both hover transform and transitions are disabled
-- The card uses `overflow: hidden` to ensure image respects border radius
-- The `.card-content` wrapper provides consistent padding for title, subtitle, and slotted content
-- The component is `display: block` and takes full width of its container
+# rel-card-media
+
+Media card (element `<rel-card-media>`, folder `rel-cardmedia`): a bordered surface with an optional full-width image on top, then a title (`<h3>`), a subtitle and a slotted body inside a padded content area. Use it for previews that lead with an image — articles, products, gallery tiles. Use `rel-card` when you need a free-form layout or no image section.
+
+## Usage
+
+```html
+<!-- Image, title, subtitle -->
+<rel-card-media
+  image-src="/images/lake.jpg"
+  image-alt="A mountain lake at sunrise"
+  title="Alpine lakes"
+  subtitle="12 photos"
+></rel-card-media>
+
+<!-- With slotted body content -->
+<rel-card-media
+  image-src="/images/headphones.jpg"
+  image-alt="Over-ear headphones"
+  title="Studio headphones"
+  subtitle="$99.99"
+>
+  <p>Closed-back, 40 mm drivers, detachable cable.</p>
+  <rel-button variant="primary" size="small">Add to cart</rel-button>
+</rel-card-media>
+
+<!-- No image: just the content area -->
+<rel-card-media title="Text-only card" subtitle="No image provided">
+  <p>Body copy goes in the default slot.</p>
+</rel-card-media>
+
+<!-- Gallery grid -->
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px;">
+  <rel-card-media image-src="/images/1.jpg" image-alt="" title="Item 1"></rel-card-media>
+  <rel-card-media image-src="/images/2.jpg" image-alt="" title="Item 2"></rel-card-media>
+  <rel-card-media image-src="/images/3.jpg" image-alt="" title="Item 3"></rel-card-media>
+</div>
+
+<!-- Restyle through parts -->
+<style>
+  .flat::part(base) {
+    border: none;
+  }
+  .flat::part(content) {
+    padding: 24px;
+  }
+</style>
+<rel-card-media class="flat" title="Flat card"></rel-card-media>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-cardmedia.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `imageSrc` | `image-src` | `string` | `""` | URL of the hero image shown full-width at the top of the card. Empty (the default) omits the image section entirely. |
+| `imageAlt` | `image-alt` | `string` | `"Card image"` | Alternative text for the hero image. Replace the generic default with a real description, or an empty string for purely decorative images. |
+| `title` | `title` | `string` | `""` | Heading rendered as an `<h3>` above the subtitle; empty omits it. Note this is also the native `title` attribute, so a value shows as a browser tooltip on hover. |
+| `subtitle` | `subtitle` | `string` | `""` | Secondary line rendered as a paragraph under the title; empty omits it. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Body content rendered inside the padded content area below the title and subtitle. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The outer bordered card surface (background, border, radius, overflow clip). |
+| `icon` | The image wrapper above the content, rendered only when `image-src` is set. |
+| `content` | The padded area holding the title, subtitle and slotted body. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The image renders as an `<img>` whose `alt` is `image-alt`; the default "Card image" is a placeholder — supply a real description, or an empty `image-alt=""` when the picture is decorative.
+- The title is a real `<h3>`; make sure that fits the page's heading outline (there is no way to change the level).
+- The card itself is a non-focusable container with no keyboard handling. Slotted controls (buttons, links) keep their own focus and keyboard behaviour.
+
+## Notes / Edge Cases
+
+- **Attribute spellings are kebab-case**: `image-src` and `image-alt`. Setting `imageSrc="…"` as an HTML attribute does nothing; use the property in code (`el.imageSrc = …`).
+- **`title` is also the native tooltip attribute.** Because the property maps to the global `title` attribute, hovering the card shows the title text as a browser tooltip.
+- The image section (`icon` part) is omitted entirely when `image-src` is empty; the title and subtitle are likewise omitted when empty, so the content area may hold only slotted children.
+- The image is `width: 100%; height: auto; object-fit: cover` and the card clips overflow, so the top corners follow the card radius.
+- The card is static: no hover lift, shadow or transition is applied.