prime-ui-kit 0.7.13 → 0.9.1

package/src/components/accordion/examples/with-icon.tsx

@@ -0,0 +1,47 @@
+/** A leading icon per section; the content lines up with the label after it — `Accordion.Icon`. */
+import { Accordion, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  {
+    value: "calendar",
+    title: "Расписание отчётов",
+    icon: "field.calendar",
+    text: "Сводка уходит по понедельникам в 9:00.",
+  },
+  {
+    value: "mail",
+    title: "Рассылки",
+    icon: "field.email",
+    text: "Письма о новых заказах и возвратах.",
+  },
+  {
+    value: "access",
+    title: "Доступ",
+    icon: "status.locked",
+    text: "Кто из команды видит финансовые отчёты.",
+  },
+] as const;
+
+export default function AccordionWithIconExample() {
+  return (
+    <div className={styles.panel}>
+      <Accordion.Root defaultValue="calendar">
+        {SECTIONS.map((section) => (
+          <Accordion.Item key={section.value} value={section.value}>
+            <Accordion.Header>
+              <Accordion.Trigger>
+                <Accordion.Icon>
+                  <Icon name={section.icon} />
+                </Accordion.Icon>
+                {section.title}
+              </Accordion.Trigger>
+            </Accordion.Header>
+            <Accordion.Content>{section.text}</Accordion.Content>
+          </Accordion.Item>
+        ))}
+      </Accordion.Root>
+    </div>
+  );
+}

package/src/components/avatar/COMPONENT.md

@@ -1,160 +1,164 @@
 # Avatar
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** data-display
+**Kind:** primitive
 
-## About
+> A round photo of a person or organization with an initials or icon fallback, a presence dot and overlapping groups.
 
-Circular avatar with an optional photo (`Avatar.Image`), a fallback layer (`Avatar.Fallback`), and an optional horizontal stack (`Avatar.Group`) with an overflow cell.
+## When to use
+- A person or organization next to its name: lists, comments, table cells, headers.
+- The signed-in user in the app chrome.
+- Participants of a project or chat as an overlapping group with «+N».
+- Presence (online / away / busy / offline) on a person.
 
-- **Use** for profile pictures, participant lists, assignees in tables, and compact identity in headers or comments when a face or initials aid recognition.
-- **Use** `Avatar.Group` when several avatars should overlap in one row and you may show a “+N” overflow.
-- **Do not use** as the only focusable control without a wrapping `button` or `link` when the avatar itself must be actionable.
-- **Do not use** for non-circular crops or rich media cards; keep this primitive for round avatars and short fallback content.
-- **Do not use** expecting an external “controlled” image load state; status lives inside `Avatar.Root` and resets when `src` changes (see Rules).
-
-## Composition
-
-- **`Avatar.Root`** — outer `div` with `data-size`, provides context (`size`, internal image status). Place **`Avatar.Image`** (optional) and **`Avatar.Fallback`** inside; image is painted above the fallback in the layout.
-- **`Avatar.Image`** — `img` with `data-status` (`loading` \| `loaded` \| `error`). Requires **`src`**; the implementation remounts when **`src`** changes, which restarts loading and context status.
-- **`Avatar.Fallback`** — `span` shown when the image is absent, loading, or in error; when the image has loaded successfully, the fallback gets **`aria-hidden`**.
-- **`Avatar.Group.Root`** — horizontal flex row; passes its **`size`** into child **`Avatar.Root`** and **`Avatar.Group.Overflow`** that omit their own **`size`** (including through **`React.Fragment`** children).
-- **`Avatar.Group.Overflow`** — cell matching avatar dimensions for text such as `+3`.
-
-### Canonical example
-
-Один фрагмент разметки: одиночный аватар (**`Image`** + **`Fallback`**), группа с **`Overflow`**, плюс **`Fallback`** с иконкой и подписи через **[Typography](../typography/COMPONENT.md)**. Импорт только из **`prime-ui-kit`**.
-
-Те же идеи, что в плейграунде (**`playground/sections/AvatarSection.tsx`** + **`playground/snippets/avatar/*.tsx`**): полная шкала **`size`** (`s`–`6xl`), три статуса картинки (**`idle`** / **`loaded`** / **`error`**), группа из трёх, смена **`src`** из состояния родителя, пара **Image + Fallback** и **Fallback** с **`Icon`**, группа с **`Avatar.Group.Overflow`**. В монорепозитории см. **`examples/sizes.tsx`**, **`states.tsx`**, **`group-three.tsx`**, **`src-from-state.tsx`** (импорты **`@/`**); **`fallback-variants.tsx`** и **`group-overflow.tsx`** закрывают композицию и переполнение.
+## When not to use
+- A status or category of an item → use [Badge](../badge/COMPONENT.md).
+- A product, file or cover preview → use [Thumbnail](../thumbnail/COMPONENT.md).
+- A removable selected person in a field → [TagSelect](../tag-select/COMPONENT.md).
 
+## Import
 ```tsx
-import { Avatar, Icon, Typography } from "prime-ui-kit";
-
-const sampleSrc =
-  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
-
-export function CanonicalAvatarDemo() {
-  return (
-    <>
-      <Typography as="p" variant="body-small" tone="muted">
-        Profile cell
-      </Typography>
-      <Avatar.Root size="l" aria-label="Jamie Chen, online">
-        <Avatar.Image src={sampleSrc} alt="" />
-        <Avatar.Fallback>JC</Avatar.Fallback>
-      </Avatar.Root>
-
-      <Typography as="p" variant="body-small" tone="muted">
-        Overlapping group + overflow
-      </Typography>
-      <Avatar.Group.Root aria-label="Reviewers: three faces, two not shown">
-        <Avatar.Root>
-          <Avatar.Image src={sampleSrc} alt="" />
-          <Avatar.Fallback>A</Avatar.Fallback>
-        </Avatar.Root>
-        <Avatar.Root>
-          <Avatar.Fallback>B</Avatar.Fallback>
-        </Avatar.Root>
-        <Avatar.Root>
-          <Avatar.Fallback>C</Avatar.Fallback>
-        </Avatar.Root>
-        <Avatar.Group.Overflow aria-label="Two additional reviewers">+2</Avatar.Group.Overflow>
-      </Avatar.Group.Root>
-
-      <Typography as="p" variant="body-small" tone="muted">
-        Icon-only fallback
-      </Typography>
-      <Avatar.Root aria-label="Invitee, no photo yet">
-        <Avatar.Fallback>
-          <Icon name="field.email" size="l" tone="subtle" />
-        </Avatar.Fallback>
-      </Avatar.Root>
-    </>
-  );
-}
+import { Avatar } from "prime-ui-kit";
 ```
 
-### Extended examples
-
-Готовые сценарии с раскладкой на **`--prime-sys-`* (см. [`examples/examples.module.css`](./examples/examples.module.css)):
-
-| Файл | Сценарий |
-|------|----------|
-| [`examples/sizes.tsx`](./examples/sizes.tsx) | Все значения **`size`** подряд (`s`–`6xl`), как [`playground/snippets/avatar/sizes.tsx`](../../../playground/snippets/avatar/sizes.tsx) |
-| [`examples/states.tsx`](./examples/states.tsx) | Без **`Image`** / успешная загрузка / неверный URL, как [`states.tsx`](../../../playground/snippets/avatar/states.tsx) |
-| [`examples/group-three.tsx`](./examples/group-three.tsx) | **`Avatar.Group.Root`** из трёх **`Avatar.Root`**, как [`group-three.tsx`](../../../playground/snippets/avatar/group-three.tsx) |
-| [`examples/src-from-state.tsx`](./examples/src-from-state.tsx) | Родитель меняет **`src`** (сброс загрузки по URL), как [`src-from-state.tsx`](../../../playground/snippets/avatar/src-from-state.tsx) |
-| [`examples/fallback-variants.tsx`](./examples/fallback-variants.tsx) | Фото, инициалы и иконка в **`Fallback`** (см. также [`composition.tsx`](../../../playground/snippets/avatar/composition.tsx)) |
-| [`examples/group-overflow.tsx`](./examples/group-overflow.tsx) | Два лица + **`Avatar.Group.Overflow`**, как [`group-overflow.tsx`](../../../playground/snippets/avatar/group-overflow.tsx) |
-| [`examples/team-list.tsx`](./examples/team-list.tsx) | Список команды: аватар + имя + роль |
-| [`examples/comment-thread.tsx`](./examples/comment-thread.tsx) | Ветка комментариев с аватаром у каждого сообщения |
-| [`examples/app-header-nav.tsx`](./examples/app-header-nav.tsx) | Шапка: навигация **[LinkButton](../link-button/COMPONENT.md)** и блок «аккаунт» с аватаром |
-
-Файлы **`sizes`**, **`states`**, **`group-three`**, **`src-from-state`** используют импорты **`@/`** для сборки внутри репозитория; остальные примеры — из **`"prime-ui-kit"`** для копирования в приложение-потребитель.
-
-### Note for LLMs
-
-При генерации экранов опирайся на публичный API выше и на **исходники** в `src/components/avatar/examples/*.tsx`. Сценарии из таблицы выше **согласованы** с **`playground/snippets/avatar/*.tsx`** (размеры, состояния, группа, смена **`src`**, композиция слотов, переполнение). Для продуктовых экранов копируй примеры с **`prime-ui-kit`**; в самом ките правь зеркала с **`@/`**. Не дублируй длинные листинги в ответе — укажи путь к файлу примера или сниппета.
-
-## Rules
-
-- Image lifecycle is **internal**: context status is `idle` \| `loading` \| `loaded` \| `error`; there is no prop to control it from outside—change **`src`** (or remove **`Avatar.Image`**) to reset behavior.
-- Put **`Avatar.Image`** and **`Avatar.Fallback`** only under **`Avatar.Root`**; **`Avatar.Fallback`** does not accept a **`src`**—photos go through **`Avatar.Image`** only.
-- Give **`Avatar.Root`** or a wrapper a clear name for assistive tech (**`aria-label`**, **`aria-labelledby`**, or nearby visible text). On **`Avatar.Image`**, use a non-empty **`alt`** when the photo conveys meaning; use **`alt=""`** when it duplicates a visible name.
-- After a successful load, **`Avatar.Fallback`** is **`aria-hidden`** so screen readers do not double-announce initials and alt text.
-- For **`Avatar.Group.Root`** and **`Avatar.Group.Overflow`**, prefer summary labels (**`aria-label`**) when the stack or “+N” needs context.
-- There is no **`disabled`** prop; mute or disable via the parent (e.g. button **`disabled`**, link **`aria-disabled`**, reduced opacity).
-- **`Avatar.Group`** is laid out as a **horizontal** row only; nesting **`Avatar.Root`** inside another **`Avatar.Root`** is not a supported pattern.
+## Anatomy
+```
+Avatar.Root            <div> circle; size, color, image load state
+├─ Avatar.Image        <img>, fades in over the fallback once loaded
+├─ Avatar.Fallback     initials or Icon under the image
+└─ Avatar.Status       presence dot on the bottom-end edge
+
+Avatar.Group           overlapping row, gives its size to members
+├─ Avatar.Root …
+└─ Avatar.Overflow     «+N» cell of the same diameter
+```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### Avatar.Root
+`ref` → `HTMLDivElement`. The circle: diameter tier and fallback hue; tracks the image load for the Fallback.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | `"s" \| "m" \| "l" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl"` | `"m"` | No | Diameter, radius, and fallback typography scale |
-| children | `React.ReactNode` | — | No | Typically `Avatar.Image` and `Avatar.Fallback` |
-| className | `string` | — | No | Additional class on the root |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other root attributes |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl" \| "2xl"` | `"m"` | Diameter 20 · 24 · 32 · 40 · 48 · 64 px. Inside `Avatar.Group` the group size is used when it is not set. |
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Palette hue of the fallback; derive it from a stable user id. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `aria-label` (when no name is shown) and the other div attributes. |
 
 ### Avatar.Image
+`ref` → `HTMLImageElement`. The photo; hidden while it loads and after an error, so the Fallback shows through. A new `src` starts again.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| src | `string` | — | Yes | Image URL; changing `src` remounts the image and resets status |
-| alt | `string` | `""` | No | Alternative text for the image |
-| className | `string` | — | No | Class on the `img` |
-| …rest | `Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" \| "alt">` | — | No | e.g. `loading`, `decoding`, event handlers |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string` | — (required) | Photo URL. |
+| `alt` | `string` | `""` | Empty when the name is written next to the avatar, otherwise the name. |
+| `…rest` | `Omit<ImgHTMLAttributes<HTMLImageElement>, "src" \| "alt">` | — | `className`, `onLoad`, `onError` and the other img attributes. |
 
 ### Avatar.Fallback
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | No | Initials, icon, or placeholder |
-| className | `string` | — | No | Class on the `span` |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other attributes |
-
-### Avatar.Group.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | same as `Avatar.Root` | `"m"` | No | Size applied to child `Avatar.Root` and `Avatar.Group.Overflow` without their own `size` |
-| children | `React.ReactNode` | — | No | `Avatar.Root` nodes and optional `Avatar.Group.Overflow` |
-| className | `string` | — | No | Class on the group container |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other attributes |
-
-### Avatar.Group.Overflow
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | same as `Avatar.Root` | `"m"` | No | Local size when not inherited from the group |
-| children | `React.ReactNode` | — | No | e.g. `+3` |
-| className | `string` | — | No | Class on the overflow cell |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other attributes |
+`ref` → `HTMLSpanElement`. A `<span>` with initials or an `Icon` under the photo; `aria-hidden` once the photo has loaded.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
+### Avatar.Status
+`ref` → `HTMLSpanElement`. A presence dot on the bottom-end edge, `role="img"` named by the state, cut out by a ring in `--avatar-ring`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `status` | `"online" \| "offline" \| "away" \| "busy"` | — (required) | Presence state: green, gray, warning or danger dot. |
+| `labels` | `Partial<AvatarStatusLabels>` | — | Accessible names of the states, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+### Avatar.Group
+`ref` → `HTMLDivElement`. An overlapping row (`role="group"`); members overlap by 25% with a ring in `--avatar-ring`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl" \| "2xl"` | `"m"` | Size of every `Avatar.Root` / `Avatar.Overflow` inside without its own `size`. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `aria-label`, `className` and the other div attributes. |
+
+### Avatar.Overflow
+`ref` → `HTMLDivElement`. The «+N» cell at the end of a group, the same diameter as its avatars.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl" \| "2xl"` | `"m"` | Diameter; inside `Avatar.Group` the group size when not set. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` («+3»), `aria-label` («Ещё 3 участника») and the other div attributes. |
+
+## Variants
+
+### color
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `gray` | neutral soft fill, gray initials | unknown or system users | yes |
+| `blue` · `sky` · `teal` · `green` · `yellow` · `orange` · `red` · `pink` · `purple` | soft hue fill, hue initials | people: the hue comes from a stable user id | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 20px | dense tables, inline mentions | |
+| `s` | 24px | compact lists, groups in headers | |
+| `m` | 32px | lists, comments | yes |
+| `l` | 40px | cards, member lists | |
+| `xl` | 48px | profile cards | |
+| `2xl` | 64px | profile headers | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| loading | `Avatar.Image` mounted | image `data-status="loading"` (transparent), Fallback visible |
+| loaded | image `load` | `data-status="loaded"`, the image fades in over `base`; Fallback `aria-hidden` |
+| error | image `error` | `data-status="error"`, image hidden, Fallback visible |
+| presence | `Avatar.Status` `status` | `data-status` on the dot |
+| size / hue | `size`, `color` | `data-size`, `data-color` |
+
+## Layout & spacing
+- Inline-flex, never shrinks, `vertical-align: middle`.
+- Avatar → name: `--prime-space-3` in lists and cards, `--prime-space-2` in table cells.
+- Group: members overlap by 25% of the diameter with a 2px ring in `--avatar-ring` (surfaces set it to their fill).
+- A host slot may size the avatar by setting `--avatar-slot-size`.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- `Avatar.Image` `alt`: empty when the name is written next to it, otherwise the name. Without a photo and without a name nearby, put `aria-label` on `Avatar.Root`.
+- `Avatar.Status` is `role="img"` with `aria-label` from `labels`.
+- `Avatar.Group` is `role="group"`; give it `aria-label`. Give `Avatar.Overflow` an `aria-label` («Ещё 3 участника»).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `online` | `"В сети"` | Name of the `online` dot. |
+| `offline` | `"Не в сети"` | Name of the `offline` dot. |
+| `away` | `"Отошёл"` | Name of the `away` dot. |
+| `busy` | `"Занят"` | Name of the `busy` dot. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A photo with initials underneath while it loads, and initials alone — `Avatar.Image`, `Avatar.Fallback`. |
+| [variants.tsx](examples/variants.tsx) | Every palette hue of the fallback; derive it from a stable user id — `color`. |
+| [sizes.tsx](examples/sizes.tsx) | Every diameter, 20 to 64 px; initials take 40% of it — `size`. |
+| [states.tsx](examples/states.tsx) | A loaded photo, a broken URL that falls back to initials, and an icon fallback for a guest. |
+| [presence.tsx](examples/presence.tsx) | A presence dot on the avatar edge, announced by its state name — `Avatar.Status`, `labels`. |
+| [team-group.tsx](examples/team-group.tsx) | Project members as an overlapping row with a «+N» cell; the group size goes to every member — `Avatar.Group`, `Avatar.Overflow`, `size`. |
+| [src-from-state.tsx](examples/src-from-state.tsx) | A new photo source restarts loading; initials show until the new photo arrives — `src`. |
+
+## Mistakes
+- `Avatar.Image` without `Avatar.Fallback` → a failed photo leaves an empty circle; add initials.
+- `alt="Анна Климова"` while the name is printed next to it → `alt=""`.
+- A random `color` on every render → derive it from the user id.
+- A custom presence dot → use `Avatar.Status`.
+- A group on a custom filled block with a canvas-colored ring → set `--avatar-ring` to that fill.
+- `size` on every avatar in a group → set it once on `Avatar.Group`.
 
 ## Related
-
-- [Button](../button/COMPONENT.md)
-- [Dropdown](../dropdown/COMPONENT.md)
-- [Label](../label/COMPONENT.md)
-- [Tooltip](../tooltip/COMPONENT.md)
-- [Typography](../typography/COMPONENT.md)
+- **Built from:** —
+- **See also:** [Thumbnail](../thumbnail/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Card](../card/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md)

package/src/components/avatar/examples/examples.module.css

@@ -1,72 +1,25 @@
-.stack {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-m);
-}
+/* Layout of the Avatar scenarios: semantic tokens only. */
 
+/* src-from-state.tsx: the avatar and its button in one line. */
 .row {
   display: flex;
-  flex-direction: row;
   flex-wrap: wrap;
   align-items: center;
-  gap: var(--prime-sys-spacing-m);
-}
-
-.rowStretch {
-  display: flex;
-  flex-direction: row;
-  align-items: flex-start;
-  gap: var(--prime-sys-spacing-m);
+  justify-content: center;
+  gap: var(--prime-space-3);
 }
 
-.list {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-l);
+/* presence.tsx: a short people list. */
+.people {
+  display: grid;
+  gap: var(--prime-space-3);
   margin: 0;
   padding: 0;
   list-style: none;
 }
 
-.listItem {
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-  gap: var(--prime-sys-spacing-m);
-  min-width: 0;
-}
-
-.listItemBody {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-x1);
-  min-width: 0;
-}
-
-.navBar {
-  display: flex;
-  flex-direction: row;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--prime-sys-spacing-m);
-  padding: var(--prime-sys-spacing-m) var(--prime-sys-spacing-l);
-  border-radius: var(--prime-sys-shape-radius-m);
-  background: var(--prime-sys-color-surface-raised);
-  border: 1px solid var(--prime-sys-color-border-subtle);
-}
-
-.navCluster {
-  display: flex;
-  flex-direction: row;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: var(--prime-sys-spacing-l);
-}
-
-.navUser {
+.person {
   display: flex;
-  flex-direction: row;
   align-items: center;
-  gap: var(--prime-sys-spacing-s);
+  gap: var(--prime-space-3);
 }

package/src/components/avatar/examples/overview.tsx

@@ -0,0 +1,18 @@
+/** A photo with initials underneath while it loads, and initials alone — `Avatar.Image`, `Avatar.Fallback`. */
+import { Avatar } from "prime-ui-kit";
+
+const PHOTO = "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
+
+export default function AvatarOverviewExample() {
+  return (
+    <>
+      <Avatar.Root color="green">
+        <Avatar.Image src={PHOTO} alt="Михаил Котов" />
+        <Avatar.Fallback>МК</Avatar.Fallback>
+      </Avatar.Root>
+      <Avatar.Root color="purple" aria-label="Ольга Белова">
+        <Avatar.Fallback>ОБ</Avatar.Fallback>
+      </Avatar.Root>
+    </>
+  );
+}

package/src/components/avatar/examples/presence.tsx

@@ -0,0 +1,32 @@
+/** A presence dot on the avatar edge, announced by its state name — `Avatar.Status`, `labels`. */
+import { Avatar, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const PEOPLE = [
+  { initials: "АК", color: "blue", status: "online", name: "Анна Климова" },
+  { initials: "ДН", color: "green", status: "away", name: "Дмитрий Носов" },
+  { initials: "ЕО", color: "pink", status: "busy", name: "Елена Орлова" },
+  { initials: "ИС", color: "gray", status: "offline", name: "Игорь Савин" },
+] as const;
+
+export default function AvatarPresenceExample() {
+  return (
+    <ul className={styles.people}>
+      {PEOPLE.map((person) => (
+        <li key={person.status} className={styles.person}>
+          <Avatar.Root color={person.color}>
+            <Avatar.Fallback>{person.initials}</Avatar.Fallback>
+            <Avatar.Status
+              status={person.status}
+              labels={person.status === "away" ? { away: "Отошёл до 15:00" } : undefined}
+            />
+          </Avatar.Root>
+          <Typography as="span" variant="body-m">
+            {person.name}
+          </Typography>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/components/avatar/examples/sizes.tsx

@@ -1,23 +1,20 @@
-import { Avatar, type AvatarSize } from "@/components/avatar/Avatar";
+/** Every diameter, 20 to 64 px; initials take 40% of it — `size`. */
+import { Avatar, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
+const SIZES = ["xs", "s", "m", "l", "xl", "2xl"] as const;
 
-const sampleSrc =
-  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=256&h=256&fit=crop";
-
-const sizes: AvatarSize[] = ["s", "m", "l", "xl", "2xl", "3xl", "4xl", "5xl", "6xl"];
-
-/**
- * Full `size` scale in one row — mirrors `playground/snippets/avatar/sizes.tsx`.
- */
 export default function AvatarSizesExample() {
   return (
-    <div className={styles.row}>
-      {sizes.map((size) => (
-        <Avatar.Root key={size} size={size}>
-          <Avatar.Image src={sampleSrc} alt="" />
-          <Avatar.Fallback>{size}</Avatar.Fallback>
-        </Avatar.Root>
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Avatar.Root size={size} color="blue" aria-label="Анна Климова">
+            <Avatar.Fallback>АК</Avatar.Fallback>
+          </Avatar.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
       ))}
     </div>
   );

package/src/components/avatar/examples/src-from-state.tsx

@@ -1,33 +1,29 @@
+/** A new photo source restarts loading; initials show until the new photo arrives — `src`. */
+import { Avatar, Button } from "prime-ui-kit";
 import * as React from "react";
-import { Avatar } from "@/components/avatar/Avatar";
-import { Button } from "@/components/button/Button";
 
 import styles from "./examples.module.css";
 
-const sources = [
+const SOURCES = [
   "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop",
   "https://images.unsplash.com/photo-1527980965255-d3b416303d12?w=128&h=128&fit=crop",
 ] as const;
 
-/**
- * Parent-owned `src`; image remounts per URL — mirrors `playground/snippets/avatar/src-from-state.tsx`.
- */
 export default function AvatarSrcFromStateExample() {
   const [index, setIndex] = React.useState(0);
-  const src = sources[index];
 
   return (
     <div className={styles.row}>
-      <Avatar.Root size="xl">
-        <Avatar.Image src={src} alt="" />
-        <Avatar.Fallback>?</Avatar.Fallback>
+      <Avatar.Root size="xl" color="sky">
+        <Avatar.Image src={SOURCES[index]} alt="" />
+        <Avatar.Fallback>ИП</Avatar.Fallback>
       </Avatar.Root>
       <Button.Root
-        mode="ghost"
-        type="button"
-        onClick={() => setIndex((i) => (i + 1) % sources.length)}
+        variant="outline"
+        tone="neutral"
+        onClick={() => setIndex((i) => (i + 1) % SOURCES.length)}
       >
-        Next portrait
+        Сменить фото
       </Button.Root>
     </div>
   );

package/src/components/avatar/examples/states.tsx

@@ -1,26 +1,39 @@
-import { Avatar } from "@/components/avatar/Avatar";
+/** A loaded photo, a broken URL that falls back to initials, and an icon fallback for a guest. */
+import { Avatar, Icon, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
+const PHOTO = "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
 
-const okSrc = "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
-
-/**
- * No `Avatar.Image` (idle), successful load, bad URL (error) — mirrors `playground/snippets/avatar/states.tsx`.
- */
 export default function AvatarStatesExample() {
   return (
-    <div className={styles.row}>
-      <Avatar.Root size="xl">
-        <Avatar.Fallback>AB</Avatar.Fallback>
-      </Avatar.Root>
-      <Avatar.Root size="xl">
-        <Avatar.Image src={okSrc} alt="User" />
-        <Avatar.Fallback>CD</Avatar.Fallback>
-      </Avatar.Root>
-      <Avatar.Root size="xl">
-        <Avatar.Image src="https://example.com/missing-avatar.png" alt="" />
-        <Avatar.Fallback>!</Avatar.Fallback>
-      </Avatar.Root>
+    <div>
+      <div>
+        <Avatar.Root size="xl" color="green">
+          <Avatar.Image src={PHOTO} alt="Михаил Котов" />
+          <Avatar.Fallback>МК</Avatar.Fallback>
+        </Avatar.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          loaded
+        </Typography>
+      </div>
+      <div>
+        <Avatar.Root size="xl" color="orange">
+          <Avatar.Image src="https://example.com/missing-avatar.png" alt="Сергей Лебедев" />
+          <Avatar.Fallback>СЛ</Avatar.Fallback>
+        </Avatar.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          error
+        </Typography>
+      </div>
+      <div>
+        <Avatar.Root size="xl" aria-label="Гость">
+          <Avatar.Fallback>
+            <Icon name="field.email" />
+          </Avatar.Fallback>
+        </Avatar.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          icon
+        </Typography>
+      </div>
     </div>
   );
 }