prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/reference/components/accordion/examples/controlled.tsx

@@ -0,0 +1,36 @@
+/** The parent owns the open sections and opens or closes all of them at once — `value`, `onValueChange`. */
+import { Accordion, Button } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { value: "general", title: "Общие", text: "Название компании, часовой пояс и валюта." },
+  { value: "team", title: "Команда", text: "12 сотрудников, 3 приглашения ждут ответа." },
+  { value: "billing", title: "Оплата", text: "Тариф «Бизнес», следующий счёт 12 ноября." },
+];
+
+const ALL = SECTIONS.map((section) => section.value);
+
+export default function AccordionControlledExample() {
+  const [open, setOpen] = React.useState<string[]>(["general"]);
+  const allOpen = open.length === ALL.length;
+
+  return (
+    <div className={styles.panel}>
+      <Button.Root variant="ghost" tone="neutral" onClick={() => setOpen(allOpen ? [] : ALL)}>
+        {allOpen ? "Свернуть все" : "Развернуть все"}
+      </Button.Root>
+      <Accordion.Root multiple value={open} onValueChange={setOpen}>
+        {SECTIONS.map((section) => (
+          <Accordion.Item key={section.value} value={section.value}>
+            <Accordion.Header>
+              <Accordion.Trigger>{section.title}</Accordion.Trigger>
+            </Accordion.Header>
+            <Accordion.Content>{section.text}</Accordion.Content>
+          </Accordion.Item>
+        ))}
+      </Accordion.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/accordion/examples/examples.module.css

@@ -0,0 +1,10 @@
+/* Layout of the Accordion scenarios: semantic tokens only. */
+
+/* A readable column for the accordion (the root itself is always full width), with whatever
+   sits above it (a caption, a toolbar button) kept at its own width. */
+.panel {
+  display: grid;
+  justify-items: start;
+  gap: var(--prime-space-2);
+  width: min(100%, calc(var(--prime-space-24) * 5));
+}

package/dist/skill/reference/components/accordion/examples/multiple.tsx

@@ -0,0 +1,31 @@
+/** Several sections stay open at once; the value is a list — `multiple`. */
+import { Accordion } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { value: "profile", title: "Профиль", text: "Имя, фото и язык интерфейса." },
+  {
+    value: "notifications",
+    title: "Уведомления",
+    text: "Письма о заказах и сводка по понедельникам.",
+  },
+  { value: "integrations", title: "Интеграции", text: "1С, Битрикс24 и вебхуки." },
+];
+
+export default function AccordionMultipleExample() {
+  return (
+    <div className={styles.panel}>
+      <Accordion.Root multiple defaultValue={["profile", "notifications"]}>
+        {SECTIONS.map((section) => (
+          <Accordion.Item key={section.value} value={section.value}>
+            <Accordion.Header>
+              <Accordion.Trigger>{section.title}</Accordion.Trigger>
+            </Accordion.Header>
+            <Accordion.Content>{section.text}</Accordion.Content>
+          </Accordion.Item>
+        ))}
+      </Accordion.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/accordion/examples/overview.tsx

@@ -0,0 +1,39 @@
+/** A FAQ where one answer is open at a time — `defaultValue`. */
+import { Accordion } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const FAQ = [
+  {
+    value: "delivery",
+    question: "Сколько идёт доставка?",
+    answer: "По Москве — 1–2 дня, по России — от 3 до 7 рабочих дней.",
+  },
+  {
+    value: "return",
+    question: "Как вернуть товар?",
+    answer: "Оформите возврат в личном кабинете в течение 14 дней после получения.",
+  },
+  {
+    value: "payment",
+    question: "Какие способы оплаты есть?",
+    answer: "Карта, СБП и счёт для юрлиц. Оплата при получении — в пунктах выдачи.",
+  },
+];
+
+export default function AccordionOverviewExample() {
+  return (
+    <div className={styles.panel}>
+      <Accordion.Root defaultValue="delivery">
+        {FAQ.map((item) => (
+          <Accordion.Item key={item.value} value={item.value}>
+            <Accordion.Header>
+              <Accordion.Trigger>{item.question}</Accordion.Trigger>
+            </Accordion.Header>
+            <Accordion.Content>{item.answer}</Accordion.Content>
+          </Accordion.Item>
+        ))}
+      </Accordion.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/accordion/examples/sizes.tsx

@@ -0,0 +1,28 @@
+/** Every size tier: trigger height, text, icon and padding grow together — `size`. */
+import { Accordion, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function AccordionSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <div key={size} className={styles.panel}>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+          <Accordion.Root size={size}>
+            <Accordion.Item value="plan">
+              <Accordion.Header>
+                <Accordion.Trigger>Тариф и продление</Accordion.Trigger>
+              </Accordion.Header>
+              <Accordion.Content>«Бизнес», продление 12 ноября.</Accordion.Content>
+            </Accordion.Item>
+          </Accordion.Root>
+        </div>
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/components/accordion/examples/states.tsx

@@ -0,0 +1,31 @@
+/** A disabled section that cannot be opened, next to regular ones — `disabled`. */
+import { Accordion } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function AccordionStatesExample() {
+  return (
+    <div className={styles.panel}>
+      <Accordion.Root defaultValue="profile">
+        <Accordion.Item value="profile">
+          <Accordion.Header>
+            <Accordion.Trigger>Профиль</Accordion.Trigger>
+          </Accordion.Header>
+          <Accordion.Content>Имя, фото и язык интерфейса.</Accordion.Content>
+        </Accordion.Item>
+        <Accordion.Item value="security">
+          <Accordion.Header>
+            <Accordion.Trigger>Безопасность</Accordion.Trigger>
+          </Accordion.Header>
+          <Accordion.Content>Пароль, двухфакторная защита и активные сессии.</Accordion.Content>
+        </Accordion.Item>
+        <Accordion.Item value="sso" disabled>
+          <Accordion.Header>
+            <Accordion.Trigger>Единый вход (SSO) — на тарифе «Корпоративный»</Accordion.Trigger>
+          </Accordion.Header>
+          <Accordion.Content>Подключите тариф, чтобы настроить единый вход.</Accordion.Content>
+        </Accordion.Item>
+      </Accordion.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/accordion/examples/variants.tsx

@@ -0,0 +1,35 @@
+/** One surface with hairlines between items, or every item as its own card — `layout`. */
+import { Accordion, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const LAYOUTS = ["grouped", "separate"] as const;
+
+const SECTIONS = [
+  { value: "plan", title: "Тариф", text: "«Бизнес», продление 12 ноября." },
+  { value: "invoices", title: "Счета", text: "Последний счёт оплачен 1 октября." },
+];
+
+export default function AccordionVariantsExample() {
+  return (
+    <>
+      {LAYOUTS.map((layout) => (
+        <div key={layout} className={styles.panel}>
+          <Typography as="span" variant="caption" tone="muted">
+            {layout}
+          </Typography>
+          <Accordion.Root layout={layout} defaultValue="plan">
+            {SECTIONS.map((section) => (
+              <Accordion.Item key={section.value} value={section.value}>
+                <Accordion.Header>
+                  <Accordion.Trigger>{section.title}</Accordion.Trigger>
+                </Accordion.Header>
+                <Accordion.Content>{section.text}</Accordion.Content>
+              </Accordion.Item>
+            ))}
+          </Accordion.Root>
+        </div>
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/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/dist/skill/reference/components/avatar/COMPONENT.md

@@ -0,0 +1,166 @@
+# Avatar
+
+**Category:** data-display
+**Kind:** primitive
+
+> A round photo of a person or organization with an initials or icon fallback, a presence dot and overlapping groups.
+
+## 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.
+
+## 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 } from "prime-ui-kit";
+```
+
+## 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 | 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. Loads lazily and decodes off the main thread (`loading="lazy"`, `decoding="async"`; pass either to override).
+
+| 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
+`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 | |
+
+The soft fill is opaque: the soft hue is composited over the surface the avatar stands on (`--avatar-ring`, else the current layer), so it looks like the soft hue on that surface and an overlapped neighbour in a group never shows through. `Avatar.Overflow` is composited the same way.
+
+### 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 such as a reaction chip sets it to its own fill, and the fills of initials and «+N» are composited over it).
+- 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 ring in the wrong color → set `--avatar-ring` to that fill (by default the ring is the current layer, `--prime-color-layer-current`).
+- `size` on every avatar in a group → set it once on `Avatar.Group`.
+
+## Related
+- **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), [FileUpload](../file-upload/COMPONENT.md) (a round upload zone around an avatar)

package/dist/skill/reference/components/avatar/examples/examples.module.css

@@ -0,0 +1,25 @@
+/* Layout of the Avatar scenarios: semantic tokens only. */
+
+/* src-from-state.tsx: the avatar and its button in one line. */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: var(--prime-space-3);
+}
+
+/* presence.tsx: a short people list. */
+.people {
+  display: grid;
+  gap: var(--prime-space-3);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.person {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-3);
+}

package/dist/skill/reference/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/dist/skill/reference/components/avatar/examples/presence.tsx

@@ -0,0 +1,47 @@
+/** 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 photo = (id: string) => `https://images.unsplash.com/photo-${id}?w=128&h=128&fit=crop`;
+
+const PEOPLE = [
+  {
+    initials: "АК",
+    color: "blue",
+    status: "online",
+    name: "Анна Климова",
+    src: photo("1534528741775-53994a69daeb"),
+  },
+  { initials: "ДН", color: "green", status: "away", name: "Дмитрий Носов" },
+  {
+    initials: "ЕО",
+    color: "pink",
+    status: "busy",
+    name: "Елена Орлова",
+    src: photo("1580489944761-15a19d654956"),
+  },
+  { 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}>
+            {"src" in person ? <Avatar.Image src={person.src} /> : null}
+            <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/dist/skill/reference/components/avatar/examples/sizes.tsx

@@ -0,0 +1,21 @@
+/** Every diameter, 20 to 64 px; initials take 40% of it — `size`. */
+import { Avatar, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl", "2xl"] as const;
+
+export default function AvatarSizesExample() {
+  return (
+    <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/dist/skill/reference/components/avatar/examples/src-from-state.tsx

@@ -0,0 +1,30 @@
+/** 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 styles from "./examples.module.css";
+
+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;
+
+export default function AvatarSrcFromStateExample() {
+  const [index, setIndex] = React.useState(0);
+
+  return (
+    <div className={styles.row}>
+      <Avatar.Root size="xl" color="sky">
+        <Avatar.Image src={SOURCES[index]} alt="" />
+        <Avatar.Fallback>ИП</Avatar.Fallback>
+      </Avatar.Root>
+      <Button.Root
+        variant="outline"
+        tone="neutral"
+        onClick={() => setIndex((i) => (i + 1) % SOURCES.length)}
+      >
+        Сменить фото
+      </Button.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/avatar/examples/states.tsx

@@ -0,0 +1,39 @@
+/** 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";
+
+const PHOTO = "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
+
+export default function AvatarStatesExample() {
+  return (
+    <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>
+  );
+}

package/dist/skill/reference/components/avatar/examples/team-group.tsx

@@ -0,0 +1,41 @@
+/** Project members as an overlapping row with a «+N» cell; the group size goes to every member — `Avatar.Group`, `Avatar.Overflow`, `size`. */
+import { Avatar, type PaletteColor } from "prime-ui-kit";
+
+const photo = (id: string) => `https://images.unsplash.com/photo-${id}?w=128&h=128&fit=crop`;
+
+/** Some members have a photo, some only initials — as in a real team. */
+const MEMBERS: { name: string; initials: string; color: PaletteColor; src?: string }[] = [
+  {
+    name: "Анна Котова",
+    initials: "АК",
+    color: "blue",
+    src: photo("1494790108377-be9c29b29330"),
+  },
+  { name: "Дмитрий Носов", initials: "ДН", color: "green" },
+  {
+    name: "Олег Смирнов",
+    initials: "ОС",
+    color: "orange",
+    src: photo("1500648767791-00dcc994a43e"),
+  },
+  {
+    name: "Мария Лебедева",
+    initials: "МЛ",
+    color: "pink",
+    src: photo("1438761681033-6461ffad8d80"),
+  },
+];
+
+export default function AvatarTeamGroupExample() {
+  return (
+    <Avatar.Group size="s" aria-label="Участники проекта: 7">
+      {MEMBERS.map((member) => (
+        <Avatar.Root key={member.initials} color={member.color}>
+          {member.src ? <Avatar.Image src={member.src} alt={member.name} /> : null}
+          <Avatar.Fallback>{member.initials}</Avatar.Fallback>
+        </Avatar.Root>
+      ))}
+      <Avatar.Overflow aria-label="Ещё 3 участника">+3</Avatar.Overflow>
+    </Avatar.Group>
+  );
+}