@reliability-design/web 1.4.6 → 1.4.7

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

@@ -1,130 +1,116 @@
-# rel-avatar
-
-## Overview
-A circular avatar component supporting three display types: image, text initials, or custom icon content. Provides four size variants and three style variants (fill, subtle, outline), with automatic text transformation and SVG sizing for icons.
-
-## Usage
-```html
-<!-- Image avatar -->
-<rel-avatar
-  type="image"
-  src="./user-photo.jpg"
-  alt="John Doe">
-</rel-avatar>
-
-<!-- Text initials avatar -->
-<rel-avatar
-  type="text"
-  text="JD">
-</rel-avatar>
-
-<!-- Icon avatar with slotted SVG -->
-<rel-avatar type="icon">
-  <svg viewBox="0 0 24 24" fill="currentColor">
-    <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"/>
-  </svg>
-</rel-avatar>
-
-<!-- Different sizes -->
-<rel-avatar type="text" text="XS" size="xs"></rel-avatar>
-<rel-avatar type="text" text="SM" size="sm"></rel-avatar>
-<rel-avatar type="text" text="MD" size="md"></rel-avatar>
-<rel-avatar type="text" text="LG" size="lg"></rel-avatar>
-
-<!-- Style variants -->
-<rel-avatar type="text" text="AA" variant="fill"></rel-avatar>
-<rel-avatar type="text" text="AA" variant="subtle"></rel-avatar>
-<rel-avatar type="text" text="AA" variant="outline"></rel-avatar>
-
-<!-- User list with avatars -->
-<div style="display: flex; gap: 8px; align-items: center;">
-  <rel-avatar type="image" src="user1.jpg" size="sm"></rel-avatar>
-  <span>John Doe</span>
-</div>
-
-<!-- Avatar group -->
-<div style="display: flex; margin-left: -8px;">
-  <rel-avatar type="text" text="A" size="md" style="margin-left: -8px;"></rel-avatar>
-  <rel-avatar type="text" text="B" size="md" style="margin-left: -8px;"></rel-avatar>
-  <rel-avatar type="text" text="C" size="md" style="margin-left: -8px;"></rel-avatar>
-</div>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `size` (reflected) | `"lg" \| "md" \| "sm" \| "xs"` | `"md"` | Avatar size variant |
-| `type` (reflected) | `"image" \| "text" \| "icon"` | `"image"` | Display type |
-| `variant` (reflected) | `"fill" \| "subtle" \| "outline"` | `"fill"` | Style variant |
-| `src` | `string` | `""` | Image URL (for `type="image"`) |
-| `text` | `string` | `""` | Text content (for `type="text"`, usually initials) |
-| `alt` | `string` | `"Avatar"` | Alt text for the image |
-| `bg` | `string` | `""` | Direct CSS background-color override (any valid CSS color), takes precedence over `variant` |
-
-## Events
-None.
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Custom icon content (for `type="icon"`, typically an SVG) |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-
-### Font Tokens
-- `--rel-headings-lg-font-size` - Large avatar text size
-- `--rel-body-xl-regular-font-size` - Medium avatar text size
-- `--rel-body-md-regular-font-size` - Small avatar text size
-- `--rel-body-xs-regular-font-size` - Extra small avatar text size
-- `--rel-fonts-weight-body-semibold` - Text font weight
-
-### Color Tokens (by variant)
-- **fill** (default): `--rel-avatar-bg-fill` (default `--rel-text-disabled`), `--rel-avatar-color-fill` (default `#ffffff`)
-- **subtle**: `--rel-avatar-bg-subtle` (default `--rel-bg-neutral-elevated-1`), `--rel-avatar-color-subtle` (default `--rel-text-label`)
-- **outline**: `--rel-avatar-bg-outline` (default `--rel-bg-surface`), `--rel-avatar-border-outline` (default `--rel-border-default`), `--rel-avatar-color-outline` (default `--rel-text-label`)
-- `--rel-stroke-sm` - Border width (all variants; `fill`/`subtle` use a transparent border to keep sizing consistent)
-
-All of the above semantic tokens (`--rel-bg-*`, `--rel-text-label`, `--rel-border-*`, `--rel-text-disabled`) have dark-mode overrides defined in `vars.css` under `:root[data-theme="dark"]`, so all three variants automatically adapt to dark mode with no extra configuration.
-
-## Accessibility
-- Image avatars include `alt` attribute for screen readers
-- Text is automatically uppercased for consistency
-- Ensure meaningful `alt` text is provided for image avatars
-
-### Keyboard Interactions
-- None (purely presentational)
-
-### Focus Behavior
-- Does not receive focus
-
-## Notes / Edge Cases
-- **Size variants**:
-  - **lg**: 40px × 40px, font-size: `--rel-headings-lg-font-size`
-  - **md**: 32px × 32px, font-size: `--rel-body-xl-regular-font-size`
-  - **sm**: 24px × 24px, font-size: `--rel-body-md-regular-font-size`
-  - **xs**: 18px × 18px, font-size: `--rel-body-xs-regular-font-size`
-
-- **Display types**:
-  - **image**: Displays an `<img>` with `src` and `alt`
-    - Uses `object-fit: cover` for proper image scaling
-    - Image is `width: 100%`, `height: 100%`
-  - **text**: Displays the `text` property in a `<span>`
-    - Text is automatically uppercased via `text-transform: uppercase`
-  - **icon**: Displays slotted content (typically SVG)
-    - Slotted SVGs are automatically sized to 50% of the avatar size
-
-- The avatar is always circular via `border-radius: 50%`
-- The avatar uses `overflow: hidden` to clip images to circle shape
-- Text and icons are centered using flexbox
-- The avatar is `inline-flex` for easy inline usage with text
-- The `size` and `type` attributes are reflected in HTML
-- The component uses `user-select: none` to prevent text selection
-- If `type` is `image` but `src` is empty, nothing is displayed (no fallback)
+# rel-avatar
+
+`<rel-avatar>` is the circular identity mark of the Figma "Avatar" component: a 20–40px disc that shows a photo (`type="image"`), uppercase initials (`type="text"`) or a slotted icon (`type="icon"`), in a solid `fill`, a neutral `subtle` or a bordered `outline` variant. Use it wherever a person, team or account needs a compact visual identity — user menus, comment threads, assignee columns, stacked avatar groups. It is purely presentational: it takes no focus and emits no events, so wrap it in a button or link when it should be clickable, and overlay a `rel-badge` when it needs a status or count.
+
+## Usage
+
+```html
+<!-- Image avatar (always pass a meaningful alt) -->
+<rel-avatar type="image" src="./user-photo.jpg" alt="Priya Natarajan"></rel-avatar>
+
+<!-- Initials -->
+<rel-avatar type="text" text="PN"></rel-avatar>
+
+<!-- Slotted icon -->
+<rel-avatar type="icon">
+  <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+    <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"/>
+  </svg>
+</rel-avatar>
+
+<!-- Sizes: xs 20px, sm 24px, md 32px (default), lg 40px -->
+<rel-avatar type="text" text="XS" size="xs"></rel-avatar>
+<rel-avatar type="text" text="SM" size="sm"></rel-avatar>
+<rel-avatar type="text" text="MD" size="md"></rel-avatar>
+<rel-avatar type="text" text="LG" size="lg"></rel-avatar>
+
+<!-- Variants -->
+<rel-avatar type="text" text="AA" variant="fill"></rel-avatar>
+<rel-avatar type="text" text="AA" variant="subtle"></rel-avatar>
+<rel-avatar type="text" text="AA" variant="outline"></rel-avatar>
+
+<!-- Inline colour overrides (any CSS colour) -->
+<rel-avatar type="text" text="JD" bg="#1d4ed8" color="#ffffff"></rel-avatar>
+
+<!-- Stacked group -->
+<div style="display: flex; padding-left: 8px;">
+  <rel-avatar type="text" text="A" style="margin-left: -8px;"></rel-avatar>
+  <rel-avatar type="text" text="B" style="margin-left: -8px;"></rel-avatar>
+  <rel-avatar type="text" text="C" style="margin-left: -8px;"></rel-avatar>
+</div>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-avatar.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `"lg" \| "md" \| "sm" \| "xs"` | `"md"` | Diameter step: `lg` 40px, `md` 32px, `sm` 24px, `xs` 20px; each binds the matching body-*-semibold text role for initials. Reflected. |
+| `type` | `type` | `"image" \| "text" \| "icon"` | `"image"` | What is rendered inside the circle: `image` shows `src`, `text` shows the `text` initials, `icon` shows the default slot. Reflected. |
+| `variant` | `variant` | `"fill" \| "subtle" \| "outline"` | `"fill"` | Fill style: `fill` = solid inverse background with light text, `subtle` = elevated neutral background, `outline` = transparent with a 1px border. Reflected. |
+| `src` | `src` | `string` | `""` | Image URL for `type="image"`; when empty nothing is rendered inside the circle (there is no fallback to initials). |
+| `text` | `text` | `string` | `""` | Initials shown for `type="text"`; rendered uppercase via `text-transform`. |
+| `alt` | `alt` | `string` | `"Avatar"` | Alt text of the `<img>` for `type="image"`; the default is the generic word "Avatar", so pass the person's name. |
+| `bg` | `bg` | `string` | `""` | Any CSS colour applied inline as `background-color` on the circle, overriding the variant background. |
+| `color` | `color` | `string` | `""` | Any CSS colour applied inline as `color` on the circle (initials / icon), overriding the variant text colour. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Icon content rendered when `type="icon"` (typically an inline SVG, sized to 50% of the circle) |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The circular wrapper that carries the size, variant and inline `bg` / `color` overrides |
+| `icon` | The `<img>` (`type="image"`) or the icon wrapper span around the slot (`type="icon"`) |
+| `label` | The `<span>` holding the initials when `type="text"` |
+
+## 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-avatar-bg-fill` | `var(--rel-bg-neutral-inverse-2)` | Background colour of the `fill` variant |
+| `--rel-avatar-bg-subtle` | `var(--rel-bg-neutral-elevated-1)` | Background colour of the `subtle` variant |
+| `--rel-avatar-border-outline` | `var(--rel-border-default)` | 1px border colour of the `outline` variant |
+| `--rel-avatar-color-fill` | `var(--rel-text-inverse)` | Text / icon colour of the `fill` variant |
+| `--rel-avatar-color-outline` | `var(--rel-text-default)` | Text / icon colour of the `outline` variant |
+| `--rel-avatar-color-subtle` | `var(--rel-text-default)` | Text / icon colour of the `subtle` variant |
+| `--rel-avatar-font-size` | `var(--_rel-avatar-font-size)` | Overrides the initials' font-size, for use alongside `--rel-avatar-size`; defaults to the preset's text role |
+| `--rel-avatar-size` | `var(--_rel-avatar-size)` | Overrides the circle's width/height for sizes between (or below) the `size` presets; defaults to the preset's diameter |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The host has no ARIA role and no keyboard handling, and it is never focusable. Put it inside a `<button>` or `<a>` when it should be interactive and give that element the accessible name.
+- `type="image"` renders a real `<img>` whose alt text comes from the `alt` prop. The default is the generic word "Avatar" — pass the person's name, or an empty string when the avatar sits next to visible text with the same name.
+- `type="text"` renders the initials as plain text in the `label` part, so screen readers read the letters ("P N"). If the initials alone are meaningless, add `aria-hidden="true"` and keep the full name in nearby text.
+- `type="icon"` slots your SVG unchanged; add `aria-hidden="true"` to decorative icons or a `<title>` to meaningful ones.
+- The three variants differ only by colour; every colour used has a dark-mode value in `vars.css`, so no extra theming is needed.
+
+## Notes / Edge Cases
+
+- The disc is `border-radius: 50%` with `overflow: hidden`; images use `object-fit: cover`, so non-square sources are centre-cropped rather than stretched.
+- `type="image"` with an empty `src` renders an empty circle — there is no automatic fallback to initials. Switch `type` yourself when the photo is missing.
+- Every variant keeps a 1px border (`--rel-stroke-sm`); `fill` and `subtle` make it transparent so the outer size is identical across variants.
+- `bg` and `color` are written as inline styles on the `base` part, so they win over both the `--rel-avatar-*` hooks and the variant tokens.
+- Initials are forced uppercase and `user-select: none`. `size`, `type` and `variant` are reflected, so `rel-avatar[size="lg"]` works as a selector.
+- The `icon` part name is shared by the `<img>` (`type="image"`) and the slot wrapper (`type="icon"`); `::part(icon)` matches whichever one is rendered.

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

@@ -1,93 +1,98 @@
-# rel-badge
-
-## Overview
-A simple notification badge component displaying numeric counts or dot indicators. Supports three sizes (sm, md, lg) and two variants (number, dot). Ideal for indicating counts, status, or notifications in UI elements.
-
-## Usage
-```html
-<!-- Number badges -->
-<rel-badge number="5"></rel-badge>
-<rel-badge number="12" size="md"></rel-badge>
-<rel-badge number="99+" size="lg"></rel-badge>
-
-<!-- Dot badges (no number shown) -->
-<rel-badge variant="dot" size="sm"></rel-badge>
-<rel-badge variant="dot" size="md"></rel-badge>
-<rel-badge variant="dot" size="lg"></rel-badge>
-
-<!-- Common use case: Badge on icon/button -->
-<div style="position: relative; display: inline-block;">
-  <button>🔔 Notifications</button>
-  <rel-badge number="3" size="sm" style="position: absolute; top: -8px; right: -8px;"></rel-badge>
-</div>
-
-<!-- Sizes comparison -->
-<rel-badge number="1" size="sm"></rel-badge>
-<rel-badge number="2" size="md"></rel-badge>
-<rel-badge number="3" size="lg"></rel-badge>
-
-<!-- Custom colors -->
-<rel-badge number="3" color="#7d7d7d"></rel-badge>
-<rel-badge number="3" color="teal" text-color="#1a1a1a"></rel-badge>
-<rel-badge variant="dot" color="lavender"></rel-badge>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `number` | `string` | `""` | Text to display in number variant (can be numeric or text like "99+") |
-| `size` | `"sm" \| "md" \| "lg"` (reflected) | `"md"` | Size variant |
-| `variant` | `"dot" \| "number"` (reflected) | `"number"` | Display mode (number shows text, dot shows indicator only) |
-| `color` | `string` (reflected) | `""` | Direct CSS color override for the badge background. Accepts any valid CSS color (hex, rgb, hsl, named, `var(...)`). Falls back to the default token when empty |
-| `text-color` | `string` (reflected) | `""` | Direct CSS color override for the badge text/icon color. Accepts any valid CSS color. Falls back to white when empty |
-
-## Events
-None.
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-fonts-weight-body-semibold` - Font weight (number variant)
-- `--rel-body-xs-regular-font-size`, `--rel-body-sm-regular-font-size`, `--rel-body-xl-regular-font-size` - Font sizes for number variant sizes
-
-### Color Tokens
-- `--rel-bg-danger` - Background color
-- `--rel-bg-surface` - Text color
-
-## Accessibility
-- Purely visual indicator (no ARIA roles)
-- For critical information, ensure accompanying text or ARIA labels on parent elements
-- Screen readers will not announce badge content unless used with proper labeling
-
-### Keyboard Interactions
-- None (not focusable)
-
-### Focus Behavior
-- Not focusable
-
-## Notes / Edge Cases
-- **Number variant sizes**:
-  - **sm**: 20px × 20px, 12px font
-  - **md**: 28px × 28px, 14px font
-  - **lg**: 40px × 40px, 20px font
-- **Dot variant sizes**:
-  - **sm**: 8px × 8px
-  - **md**: 10px × 10px
-  - **lg**: 12px × 12px
-- All badges are circular (`border-radius: 50%`)
-- The `number` property accepts any string (e.g., "99+", "NEW", or numeric values)
-- In dot variant, the `number` property is ignored and nothing is rendered inside
-- The component is `display: inline-flex` for easy positioning
-- Badges use `justify-content: center` and `align-items: center` for centering content
-- `size` and `variant` are reflected attributes (appear in HTML when set)
-- Common pattern: position badges absolutely over parent elements (e.g., icons, avatar images)
-- For very large numbers, consider truncating or using "99+" format to avoid overflow
+# rel-badge
+
+`<rel-badge>` is the Figma "Badge" count indicator: a small `number` pill ("5", "99+") or an unlabeled `dot`, in four sizes (S/M/L/XL), filled with the danger token by default and overridable per instance through `color` / `text-color`. Use it to flag unread counts or unseen activity on an icon, tab, avatar or navigation item — you position it over the target yourself. It is not a text tag (use `rel-chip`) and not a status message (use `rel-alert` or `rel-toast`); it only carries a count or a "something is new" signal.
+
+## Usage
+
+```html
+<!-- Number badges -->
+<rel-badge number="5"></rel-badge>
+<rel-badge number="12" size="md"></rel-badge>
+<rel-badge number="99+" size="lg"></rel-badge>
+<rel-badge number="120" size="xl"></rel-badge>
+
+<!-- Dot badges (no text) -->
+<rel-badge variant="dot" size="sm"></rel-badge>
+<rel-badge variant="dot" size="md"></rel-badge>
+<rel-badge variant="dot" size="lg"></rel-badge>
+
+<!-- Positioned over an icon button -->
+<div style="position: relative; display: inline-block;">
+  <button aria-label="Notifications">🔔</button>
+  <rel-badge number="3" size="sm" style="position: absolute; top: -8px; right: -8px;"></rel-badge>
+</div>
+
+<!-- Accessible-name control -->
+<rel-badge number="3" suffix="unread messages"></rel-badge>
+<rel-badge variant="dot" arialabel="New activity"></rel-badge>
+
+<!-- Colour overrides: any CSS colour, including a token via var() -->
+<rel-badge number="3" color="#7d7d7d"></rel-badge>
+<rel-badge number="3" color="teal" text-color="#1a1a1a"></rel-badge>
+<rel-badge variant="dot" color="seagreen"></rel-badge>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-badge.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `number` | `number` | `string` | `""` | Text shown in the `number` variant (a count such as "5" or "99+"); not rendered by `variant="dot"` but still used to build the accessible name. |
+| `ariaLabel` | `arialabel` | `string` | `""` | Explicit accessible name; when empty it is composed as "<number> <suffix>" or, with no number, "New <suffix>". Attribute is `arialabel`. |
+| `suffix` | `suffix` | `string` | `"notifications"` | Noun appended to the count in the generated accessible name, e.g. "3 notifications". |
+| `size` | `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Badge scale (Figma Badge S/M/L/XL): number badges are 20 / 24 / 28 / 40px tall, dot badges 8 / 10 / 12 / 12px. Reflected. |
+| `variant` | `variant` | `"dot" \| "number"` | `"number"` | `number` renders the `number` text in a pill that widens with its content; `dot` renders a small disc with no text. Reflected. |
+| `color` | `color` | `string` | `""` | Direct CSS color override for the badge background. Accepts any valid CSS color value: hex, rgb(...), hsl(...), named color, or var(--token). Clear it (set to `''`) to fall back to the default token. Reflected. |
+| `textColor` | `text-color` | `string` | `""` | Direct CSS color override for the badge text/icon color. Accepts any valid CSS color value: hex, rgb(...), hsl(...), named color, or var(--token). Clear it (set to `''`) to fall back to the default (white). 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` | The `role="status"` pill / dot that carries the size, variant and colour overrides |
+
+## 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-badge-bg` | `var(--rel-bg-danger)` | Background colour of the badge; the `color` prop writes this on the host |
+| `--rel-badge-color` | `var(--rel-text-static-light)` | Text colour of the count; the `text-color` prop writes this on the host |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The pill (`base` part) renders with `role="status"` and an `aria-label`. The label is `ariaLabel` when set; otherwise it is composed as `"<number> <suffix>"` (e.g. "3 notifications") or, when `number` is empty (dot badges), `"New <suffix>"` (e.g. "New notifications"). Set `suffix` so the announcement names the right thing, or `arialabel` for full control.
+- `role="status"` is an implicit polite live region, so a change to `number` may be announced without the badge ever taking focus; verify the behaviour with your target screen reader before relying on it.
+- The host is not focusable and handles no keys. Interactive meaning ("open notifications") belongs to the element the badge decorates — give that element its own accessible name.
+- A dot badge has no visible text; the generated name is the only thing a screen reader gets, and sighted users get colour alone. Pair it with nearby text when the meaning is not obvious from context.
+
+## Notes / Edge Cases
+
+- Number badge heights are 20 / 24 / 28 / 40px for `sm` / `md` / `lg` / `xl`; dot badges are 8 / 10 / 12 / 12px (`lg` and `xl` dots are the same size). The number badge sets `min-width`, not `width`, so a two-digit count stays a circle while "999+" grows into a pill.
+- The corner radius is a fixed `999px`, not `50%`, which is what lets wide content become a pill instead of clipping.
+- In `variant="dot"` the `number` text is not rendered but still feeds the accessible name ("3 notifications" for a dot with `number="3"`).
+- `color` and `text-color` are applied by writing `--rel-badge-bg` / `--rel-badge-color` as inline custom properties on the host; clearing the prop removes the inline value and falls back to whatever the hook resolves to (the danger / static-light tokens unless you set the hook in your own CSS).
+- The accessible-name property is `ariaLabel` with the attribute `arialabel` (no hyphen). A plain `aria-label` attribute on the host is not read by the component, and because the host has no role it does not reach the `role="status"` element either — use `arialabel`.
+- The host is `display: inline-flex`; the usual pattern is an absolutely positioned badge inside a `position: relative` wrapper around the decorated element.