@reliability-design/web 1.4.8 → 1.4.10

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

@@ -1,118 +1,228 @@
-# 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="extra-small"></rel-avatar>
-<rel-avatar type="text" text="SM" size="small"></rel-avatar>
-<rel-avatar type="text" text="MD" size="medium"></rel-avatar>
-<rel-avatar type="text" text="LG" size="large"></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` | `"large" \| "medium" \| "small" \| "extra-small" \| "lg" \| "md" \| "sm" \| "xs"` | `"medium"` | Diameter step: `large` 40px, `medium` 32px, `small` 24px, `extra-small` 20px; each binds the matching body-*-semibold text role for initials. `lg` / `md` / `sm` / `xs` are alternative spellings and stay supported — they are normalised to the full words, not deprecated. 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 20 / 18 / 16 / 12px by `size`) |
-
-## 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-outline` | `var(--rel-bg-neutral)` | Background colour of the `outline` variant; defaults to --rel-bg-neutral |
-| `--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-icon-size` | `var(--_rel-avatar-icon-size)` | Overrides the slotted icon's size; defaults to the preset ramp (20 / 18 / 16 / 12px) |
-| `--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="large"]` works as a selector. Because `lg` / `md` / `sm` / `xs` are normalised to the full words before reflection, the selector matches whichever spelling was written.
-- The `icon` part name is shared by the `<img>` (`type="image"`) and the slot wrapper (`type="icon"`); `::part(icon)` matches whichever one is rendered.
+# 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="extra-small"></rel-avatar>
+<rel-avatar type="text" text="SM" size="small"></rel-avatar>
+<rel-avatar type="text" text="MD" size="medium"></rel-avatar>
+<rel-avatar type="text" text="LG" size="large"></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>
+
+<!-- New in 1.5.0. Icon by name instead of a slotted SVG (Figma "Icon" swap) -->
+<rel-avatar type="icon" icon="person" variant="subtle"></rel-avatar>
+
+<!-- New in 1.5.0. Status badge (Figma "Show Badge"): a green dot, or an icon disc -->
+<rel-avatar type="image" src="./user-photo.jpg" alt="Priya Natarajan" badge="dot" badge-label="Online"></rel-avatar>
+<rel-avatar type="text" text="PN" badge="icon" badge-icon="edit-square" badge-label="Can edit"></rel-avatar>
+
+<!-- New in 1.5.0. Ring (Figma "Show Ring"): separates avatars that overlap -->
+<rel-avatar type="text" text="AB" ring></rel-avatar>
+```
+
+<!-- @unreleased-begin 1.5.0 -->
+### Avatar group
+
+```html
+<!-- New in 1.5.0. <rel-avatar-group> (Figma "Avatar Group"): overlapping avatars with a "+N" circle.
+     The group sets size and ring on every avatar; max hides the rest and counts them. -->
+<rel-avatar-group size="medium" max="3" label="Project members">
+  <rel-avatar type="image" src="./priya.jpg" alt="Priya Natarajan"></rel-avatar>
+  <rel-avatar type="text" text="JD"></rel-avatar>
+  <rel-avatar type="text" text="MK"></rel-avatar>
+  <rel-avatar type="text" text="LS"></rel-avatar>
+  <rel-avatar type="text" text="TO"></rel-avatar>
+</rel-avatar-group>
+
+<!-- Only some people loaded: total counts everyone else -->
+<rel-avatar-group total="57">
+  <rel-avatar type="text" text="AB"></rel-avatar>
+  <rel-avatar type="text" text="CD"></rel-avatar>
+  <rel-avatar type="text" text="EF"></rel-avatar>
+</rel-avatar-group>
+```
+
+`<rel-avatar-group>` (new in 1.5.0) lays its slotted `<rel-avatar>` elements in a row, each overlapping the previous one by a quarter of the diameter (Figma's 10 / 8 / 6 / 4px), later ones on top. It gives every avatar its `size` and turns their `ring` on. Avatars beyond `max` are hidden and counted, with anyone beyond the slotted avatars when `total` is larger, in a "+N" circle: the fill style, the same text role as the initials, and its own ring.
+<!-- @unreleased-end -->
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-avatar.ts — do not edit; run readme-generate.mjs -->
+
+## Elements
+
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-avatar>` | `RelAvatar` | `rel-avatar.ts` |
+
+<!-- @unreleased-begin 1.5.0 -->
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-avatar-group>` | `RelAvatarGroup` | `rel-avatar-group.ts` |
+<!-- @unreleased-end -->
+
+## API
+
+### `<rel-avatar>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "extra-small" \| "lg" \| "md" \| "sm" \| "xs"` | `"medium"` | Diameter step: `large` 40px, `medium` 32px, `small` 24px, `extra-small` 20px; each binds the matching body-*-semibold text role for initials. `lg` / `md` / `sm` / `xs` are alternative spellings and stay supported — they are normalised to the full words, not deprecated. 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. |
+| `icon` | `icon` | `string` | `""` | New in 1.5.0. rel-icon name shown for `type="icon"` (Figma's "Icon" swap, e.g. `person`), as an alternative to slotting an SVG. When set it replaces the slot. |
+| `ring` | `ring` | `boolean` | `false` | New in 1.5.0. Figma "Show Ring": a 2px ring in `--rel-border-inverse` just outside the circle, which separates overlapping avatars. It does not change the avatar's size. Reflected. |
+| `badge` | `badge` | `"" \| "dot" \| "icon"` | `""` | New in 1.5.0. Figma "Show Badge": a status badge on the bottom-right edge with a 1px `--rel-border-inverse` edge. `dot` is a `--rel-bg-success` disc; `icon` is a `--rel-bg-neutral-elevated-2` disc holding `badge-icon`. 12 / 10 / 8 / 6px for large / medium / small / extra-small. Empty (the default) renders none. |
+| `badgeIcon` | `badge-icon` | `string` | `"edit-square"` | New in 1.5.0. rel-icon name inside a `badge="icon"` badge. |
+| `badgeLabel` | `badge-label` | `string` | `""` | New in 1.5.0. What the badge means, for screen readers (e.g. "Online"). Without it the badge is decorative and hidden from assistive technology, because a dot conveys its meaning by colour alone. |
+
+### 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 20 / 18 / 16 / 12px by `size`); not rendered when the `icon` attribute is set |
+
+### 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"` |
+| `badge` | The status badge on the bottom-right edge, rendered when `badge` is set (new in 1.5.0) |
+
+### 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-badge-bg` | `var(--rel-bg-success)` | Fill of the `badge`; defaults to `--rel-bg-success` for `dot` and `--rel-bg-neutral-elevated-2` for `icon` (new in 1.5.0) |
+| `--rel-avatar-bg-fill` | `var(--rel-bg-neutral-inverse-2)` | Background colour of the `fill` variant |
+| `--rel-avatar-bg-outline` | `var(--rel-bg-neutral)` | Background colour of the `outline` variant; defaults to --rel-bg-neutral |
+| `--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-icon-size` | `var(--_rel-avatar-icon-size)` | Overrides the slotted icon's size; defaults to the preset ramp (20 / 18 / 16 / 12px) |
+| `--rel-avatar-ring-color` | `var(--rel-border-inverse)` | Colour of the `ring`; defaults to `--rel-border-inverse` (new in 1.5.0) |
+| `--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 |
+
+<!-- @unreleased-begin 1.5.0 -->
+### `<rel-avatar-group>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "extra-small" \| "lg" \| "md" \| "sm" \| "xs"` | `"medium"` | Diameter step given to every avatar in the group and to the "+N" circle: `large` 40px, `medium` 32px, `small` 24px, `extra-small` 20px. `lg` / `md` / `sm` / `xs` are accepted and normalised to the full words. Reflected. |
+| `max` | `max` | `number` | `0` | Most avatars to show; the rest are hidden and counted in the "+N" circle. `0` (the default) shows them all. |
+| `total` | `total` | `number` | `0` | The full number of people when only some avatars are slotted (e.g. 3 slotted of 57). The "+N" circle then counts everyone not shown. `0` (the default) counts the slotted avatars only. |
+| `label` | `label` | `string` | `""` | Accessible name of the group (e.g. "Project members"). No default: without it the group has no name. |
+| `overflowLabel` | `overflow-label` | `string` | `"{n} more"` | Accessible name of the "+N" circle; `{n}` is replaced by the count. |
+
+#### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `overflowCount` | `number` | People counted in the "+N" circle. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | The `rel-avatar` elements, in display order |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The `role="group"` row holding the avatars and the overflow circle |
+| `overflow` | The "+N" circle (a `rel-avatar` of `type="text"`, `variant="fill"`) shown when people are not displayed |
+
+### 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-group-overlap` | `var(--_rel-avatar-group-overlap)` | How far each avatar overlaps the previous one (a positive length); defaults to Figma's 10 / 8 / 6 / 4px for large / medium / small / extra-small |
+<!-- @unreleased-end -->
+
+<!-- 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 `icon` attribute (new in 1.5.0) renders a decorative `rel-icon`, hidden from assistive technology.
+- The badge (new in 1.5.0) shows a status by colour, or by a tiny icon, so it is not readable by itself. Set `badge-label` ("Online", "Away") and it is read right after the avatar's own name. Without `badge-label` the badge is hidden from assistive technology: say the status in nearby text instead.
+- The ring and the badge edge use `--rel-border-inverse`, the page-colour edge Figma draws. In forced-colours mode the badge is drawn in `CanvasText`, so a status dot stays visible.
+- The three variants differ only by colour; every colour used has a dark-mode value in `vars.css`, so no extra theming is needed.
+<!-- @unreleased-begin 1.5.0 -->
+- `<rel-avatar-group>` is a `role="group"` named by `label`; give it one ("Project members") so the list of names has context. Each avatar keeps its own name (image `alt`, initials). The "+N" circle is a `role="img"` named by `overflow-label` (default "{n} more", e.g. "54 more") with the exact count, even when it shows "99+". Hidden avatars are `display: none`, so they are not read. The group takes no focus and has no keyboard handling.
+<!-- @unreleased-end -->
+
+## 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="large"]` works as a selector. Because `lg` / `md` / `sm` / `xs` are normalised to the full words before reflection, the selector matches whichever spelling was written.
+- The `icon` part name is shared by the `<img>` (`type="image"`) and the slot wrapper (`type="icon"`); `::part(icon)` matches whichever one is rendered.
+- **Ring** (new in 1.5.0): a 2px outline just outside the circle, so the avatar keeps its 40 / 32 / 24 / 20px box and neighbours are not pushed apart. It is meant for avatars that overlap, on any surface; recolour it with `--rel-avatar-ring-color` when the surface is not the page colour.
+- **Badge** (new in 1.5.0): 12 / 10 / 8 / 6px by size, flush with the bottom-right of the avatar's box, with a 1px outside edge. `dot` fills with `--rel-bg-success` (Figma has only the green dot); `icon` fills with `--rel-bg-neutral-elevated-2` and draws `badge-icon` at two thirds of the disc. Recolour either with `--rel-avatar-badge-bg`. At the two smallest sizes an icon badge is too small to read; prefer `dot` there.
+- **`icon` vs the slot:** when `icon` is set it replaces the slot; leave it empty to slot your own SVG.
+<!-- @unreleased-begin 1.5.0 -->
+- **Avatar group.** The group writes `size` and `ring` on its avatars, so a size set on an avatar inside a group is replaced by the group's. It hides avatars beyond `max` with a `data-rel-group-hidden` attribute it manages itself; your own `hidden` attributes are left alone. The "+N" text steps down to 36% of the diameter from two digits ("+10"), and counts above 99 show "99+". Change the overlap with `--rel-avatar-group-overlap`.
+<!-- @unreleased-end -->

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

@@ -54,6 +54,7 @@ The `BreadcrumbItem` shape is `{ label: string; url?: string }`; the type is exp
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `items` | `items` | `BreadcrumbItem[]` | `[]` | Ordered trail, root first: `{ label: string; url?: string }[]`. Items with a `url` render as links except the last one, which is always the current page (and never a link). Set as a property — arrays do not survive attribute serialisation. |
+| `ariaLabel` | `aria-label` | `string` | `"Breadcrumb"` | Name the trail when several breadcrumb landmarks share a page. |
 
 ## Events
 

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

@@ -6,7 +6,7 @@ Action button implementing the Figma "Button" component: a native `<button>` wit
 
 ```html
 <!-- Styles (Figma "Style") -->
-<rel-button variant="primary">Primary</rel-button>
+<rel-button variant="primary" tone="brand">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>
@@ -33,7 +33,7 @@ Action button implementing the Figma "Button" component: a native `<button>` wit
 <rel-button border="no-corner-radius">Square</rel-button>
 
 <!-- Icon + label, and icon-only (needs an accessible name) -->
-<rel-button variant="primary">
+<rel-button variant="primary" tone="brand">
   <rel-icon name="plus"></rel-icon>
   Add item
 </rel-button>
@@ -41,21 +41,21 @@ Action button implementing the Figma "Button" component: a native `<button>` wit
   <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-icon name="close"></rel-icon>
 </rel-button>
 
 <!-- States -->
-<rel-button variant="primary" loading>Saving</rel-button>
-<rel-button variant="primary" disabled>Unavailable</rel-button>
+<rel-button variant="primary" tone="brand" loading>Saving</rel-button>
+<rel-button variant="primary" tone="brand" 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-icon name="notification-on"></rel-icon>
 </rel-button>
 
 <!-- Listen for clicks (native click bubbles through the shadow root) -->
-<rel-button id="save" variant="primary">Save</rel-button>
+<rel-button id="save" variant="primary" tone="brand">Save</rel-button>
 <script>
   document.getElementById('save').addEventListener('click', () => {
     console.log('saved');
@@ -63,7 +63,7 @@ Action button implementing the Figma "Button" component: a native `<button>` wit
 </script>
 
 <!-- Per-instance minimum width -->
-<rel-button variant="primary" style="--rel-button-min-width: 160px;">Wide</rel-button>
+<rel-button variant="primary" tone="brand" style="--rel-button-min-width: 160px;">Wide</rel-button>
 ```
 
 ### Deprecated aliases
@@ -182,7 +182,7 @@ Figma populates only part of the grid. Combinations outside it have no design-sy
 - **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.
+- **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`. Since 1.5.0 the neutral tone's hover and pressed state is the Icon Only (ghost) hover tint laid over its grey fill; before, its hover showed no change. `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.