prime-ui-kit 0.0.1

package/src/components/accordion/examples/03-checkout-order-summary.tsx

@@ -0,0 +1,89 @@
+import { Minus, Plus } from "lucide-react";
+import { Accordion } from "@/components/accordion/Accordion";
+import { LinkButton } from "@/components/link-button/LinkButton";
+import { Typography } from "@/components/typography/Typography";
+
+import styles from "./examples.module.css";
+
+/**
+ * Checkout flow: custom open/close icons on the arrow, dense copy, and a policy link in the body.
+ */
+export default function AccordionExampleCheckoutOrderSummary() {
+  return (
+    <Accordion.Root type="single" layout="grouped" defaultValue="totals">
+      <Accordion.Item value="totals">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <span>Order totals</span>
+            <Accordion.Arrow openIcon={Plus} closeIcon={Minus} />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.bodyStack}>
+            <div className={styles.row}>
+              <Typography.Root as="span" variant="body-default">
+                Subtotal
+              </Typography.Root>
+              <Typography.Root as="span" variant="body-default">
+                $124.00
+              </Typography.Root>
+            </div>
+            <div className={styles.row}>
+              <Typography.Root as="span" variant="body-default" tone="muted">
+                Estimated tax
+              </Typography.Root>
+              <Typography.Root as="span" variant="body-default" tone="muted">
+                $9.92
+              </Typography.Root>
+            </div>
+            <div className={styles.row}>
+              <Typography.Root as="span" variant="body-small" weight="semibold">
+                Due today
+              </Typography.Root>
+              <Typography.Root as="span" variant="body-small" weight="semibold">
+                $133.92
+              </Typography.Root>
+            </div>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="delivery">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <span>Delivery window</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Arrives Tuesday–Thursday depending on carrier volume. You can reschedule from the
+            confirmation email.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="terms">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <span>Terms &amp; privacy</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.stack}>
+            <Typography.Root as="p" variant="body-small" className={styles.lead}>
+              By placing this order you agree to our terms of sale and refund policy.
+            </Typography.Root>
+            <div className={styles.actions}>
+              <LinkButton.Root href="#" size="s">
+                Terms of sale
+              </LinkButton.Root>
+              <LinkButton.Root href="#" size="s">
+                Privacy policy
+              </LinkButton.Root>
+            </div>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}

package/src/components/accordion/examples/04-api-docs-sections.tsx

@@ -0,0 +1,88 @@
+import { BookOpen, Code2, Webhook } from "lucide-react";
+import * as React from "react";
+import { Accordion } from "@/components/accordion/Accordion";
+import { Typography } from "@/components/typography/Typography";
+
+import styles from "./examples.module.css";
+
+/**
+ * Long-form API reference: controlled `value` / `onValueChange` so another part of the page (or
+ * deep link) can sync which section is open.
+ */
+export default function AccordionExampleApiDocsSections() {
+  const [open, setOpen] = React.useState<string>("auth");
+
+  return (
+    <Accordion.Root
+      type="single"
+      layout="grouped"
+      value={open}
+      onValueChange={(next) => {
+        if (typeof next === "string") setOpen(next);
+      }}
+    >
+      <Accordion.Item value="auth">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={BookOpen} />
+            <span>Authentication</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.bodyStack}>
+            <Typography.Root as="p" variant="body-default" className={styles.lead}>
+              Send a bearer token in the{" "}
+              <Typography.Root as="span" variant="caption" weight="medium">
+                Authorization
+              </Typography.Root>{" "}
+              header. Tokens expire after twelve hours; refresh using the endpoint described in the
+              session guide.
+            </Typography.Root>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="webhooks">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Webhook} />
+            <span>Webhooks</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Register HTTPS endpoints to receive signed event payloads. Retry policy uses exponential
+            backoff for non-2xx responses up to three days.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="errors">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Code2} />
+            <span>Error format</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Errors return JSON with{" "}
+            <Typography.Root as="span" variant="caption" weight="medium">
+              code
+            </Typography.Root>
+            ,{" "}
+            <Typography.Root as="span" variant="caption" weight="medium">
+              message
+            </Typography.Root>
+            , and optional{" "}
+            <Typography.Root as="span" variant="caption" weight="medium">
+              details
+            </Typography.Root>{" "}
+            for validation issues.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}

package/src/components/accordion/examples/05-knowledge-base-categories.tsx

@@ -0,0 +1,60 @@
+import { FileQuestion, LifeBuoy, ShieldCheck } from "lucide-react";
+import { Accordion } from "@/components/accordion/Accordion";
+import { Typography } from "@/components/typography/Typography";
+
+import styles from "./examples.module.css";
+
+/**
+ * Support hub: `collapsible={false}` keeps one section pinned open once chosen, and a disabled item
+ * marks content that is not yet available for the user’s plan.
+ */
+export default function AccordionExampleKnowledgeBaseCategories() {
+  return (
+    <Accordion.Root type="single" layout="separate" defaultValue="basics" collapsible={false}>
+      <Accordion.Item value="basics">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={LifeBuoy} />
+            <span>Getting started</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            New here? Complete the workspace checklist, invite teammates, and connect your first
+            data source from the integrations directory.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="billing" disabled>
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={ShieldCheck} />
+            <span>Billing &amp; contracts (Enterprise)</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Contract terms and invoice history appear here when your organization upgrades.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="troubleshoot">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={FileQuestion} />
+            <span>Troubleshooting</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Common fixes: clear the local cache, verify outbound firewall rules for our API hosts,
+            and confirm your SDK is on a supported major version.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}

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

@@ -0,0 +1,30 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+}
+
+.bodyStack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.lead {
+  margin: 0;
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-m);
+  margin-top: var(--prime-sys-spacing-s);
+}
+
+.row {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: var(--prime-sys-spacing-m);
+}

package/src/components/avatar/COMPONENT.md

@@ -0,0 +1,160 @@
+# Avatar
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Circular avatar with an optional photo (`Avatar.Image`), a fallback layer (`Avatar.Fallback`), and an optional horizontal stack (`Avatar.Group`) with an overflow cell.
+
+- **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`** закрывают композицию и переполнение.
+
+```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>
+    </>
+  );
+}
+```
+
+### 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.
+
+## API
+
+### Avatar.Root
+
+| 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 |
+
+### Avatar.Image
+
+| 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 |
+
+### 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 |
+
+## Related
+
+- [Button](../button/COMPONENT.md)
+- [Dropdown](../dropdown/COMPONENT.md)
+- [Label](../label/COMPONENT.md)
+- [Tooltip](../tooltip/COMPONENT.md)
+- [Typography](../typography/COMPONENT.md)

package/src/components/avatar/examples/app-header-nav.tsx

@@ -0,0 +1,33 @@
+import { Avatar, LinkButton, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const portrait =
+  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
+
+/**
+ * App chrome: product title, nav links, and a signed-in identity cluster (avatar + account link).
+ */
+export default function AvatarAppHeaderNavExample() {
+  return (
+    <header className={styles.navBar}>
+      <div className={styles.navCluster}>
+        <Typography.Root as="span" variant="heading-subsection" weight="semibold">
+          Prime Console
+        </Typography.Root>
+        <nav className={styles.row} aria-label="Primary">
+          <LinkButton.Root href="#overview">Overview</LinkButton.Root>
+          <LinkButton.Root href="#projects">Projects</LinkButton.Root>
+          <LinkButton.Root href="#settings">Settings</LinkButton.Root>
+        </nav>
+      </div>
+      <div className={styles.navUser}>
+        <Avatar.Root aria-label="Signed in as Jamie Chen">
+          <Avatar.Image src={portrait} alt="" />
+          <Avatar.Fallback>JC</Avatar.Fallback>
+        </Avatar.Root>
+        <LinkButton.Root href="#account">Account</LinkButton.Root>
+      </div>
+    </header>
+  );
+}

package/src/components/avatar/examples/comment-thread.tsx

@@ -0,0 +1,57 @@
+import { Avatar, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const portrait =
+  "https://images.unsplash.com/photo-1527980965255-d3b416303d12?w=128&h=128&fit=crop";
+
+type Comment = { id: string; author: string; initials: string; body: string; src?: string };
+
+const comments: Comment[] = [
+  {
+    id: "c1",
+    author: "Casey Ng",
+    initials: "CN",
+    body: "Shipped the first cut of filters. Can you sanity-check the empty state?",
+    src: portrait,
+  },
+  {
+    id: "c2",
+    author: "Riley Park",
+    initials: "RP",
+    body: "Looks good. Let’s add a single-line skeleton for slow networks.",
+  },
+  {
+    id: "c3",
+    author: "Morgan Blake",
+    initials: "MB",
+    body: "+1 on skeleton. I’ll wire it in the list cell tomorrow.",
+    src: portrait,
+  },
+];
+
+/**
+ * Comment thread: avatar + stacked author line and body copy.
+ */
+export default function AvatarCommentThreadExample() {
+  return (
+    <ul className={styles.list} aria-label="Discussion">
+      {comments.map((c) => (
+        <li key={c.id} className={styles.rowStretch}>
+          <Avatar.Root aria-label={c.author}>
+            {c.src ? <Avatar.Image src={c.src} alt="" /> : null}
+            <Avatar.Fallback>{c.initials}</Avatar.Fallback>
+          </Avatar.Root>
+          <div className={styles.stack}>
+            <Typography.Root as="span" variant="body-small" weight="semibold">
+              {c.author}
+            </Typography.Root>
+            <Typography.Root as="p" variant="body-default" tone="muted">
+              {c.body}
+            </Typography.Root>
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}

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

@@ -0,0 +1,72 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.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);
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-l);
+  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 {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--prime-sys-spacing-s);
+}

package/src/components/avatar/examples/fallback-variants.tsx

@@ -0,0 +1,33 @@
+import { Avatar, Icon, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const portrait =
+  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
+
+/**
+ * Side-by-side: loaded image, initials-only fallback, and icon-only fallback.
+ */
+export default function AvatarFallbackVariantsExample() {
+  return (
+    <div className={styles.stack}>
+      <Typography.Root as="p" variant="caption" tone="muted">
+        Same size tier; different fallback strategies
+      </Typography.Root>
+      <div className={styles.row}>
+        <Avatar.Root size="xl" aria-label="User with photo">
+          <Avatar.Image src={portrait} alt="" />
+          <Avatar.Fallback>PH</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Root size="xl" aria-label="User with initials only">
+          <Avatar.Fallback>IN</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Root size="xl" aria-label="Placeholder account">
+          <Avatar.Fallback>
+            <Icon name="field.email" size="xl" tone="subtle" />
+          </Avatar.Fallback>
+        </Avatar.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/avatar/examples/group-overflow.tsx

@@ -0,0 +1,32 @@
+import { Avatar, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const portrait =
+  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
+
+/**
+ * Overlapping group with an overflow cell for hidden participants.
+ */
+export default function AvatarGroupOverflowExample() {
+  return (
+    <div className={styles.stack}>
+      <Typography.Root as="p" variant="body-small" tone="muted">
+        Design review — 5 invited, 2 faces shown
+      </Typography.Root>
+      <Avatar.Group.Root
+        size="l"
+        aria-label="Participants: two avatars visible, three more not shown"
+      >
+        <Avatar.Root>
+          <Avatar.Image src={portrait} alt="" />
+          <Avatar.Fallback>A</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Root>
+          <Avatar.Fallback>B</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Group.Overflow aria-label="Three additional participants">+3</Avatar.Group.Overflow>
+      </Avatar.Group.Root>
+    </div>
+  );
+}