prime-ui-kit 0.3.1 → 0.4.0

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

@@ -20,21 +20,81 @@ Circular avatar with an optional photo (`Avatar.Image`), a fallback layer (`Avat
 - **`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`.
 
-### Minimal example
+### 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 } from "prime-ui-kit";
+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 Example() {
+export function CanonicalAvatarDemo() {
   return (
-    <Avatar.Root>
-      <Avatar.Image src="/avatar.png" alt="" />
-      <Avatar.Fallback>AB</Avatar.Fallback>
-    </Avatar.Root>
+    <>
+      <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 size="m" 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 size="m" 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.

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

@@ -0,0 +1,41 @@
+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" size="m">
+            Overview
+          </LinkButton.Root>
+          <LinkButton.Root href="#projects" size="m">
+            Projects
+          </LinkButton.Root>
+          <LinkButton.Root href="#settings" size="m">
+            Settings
+          </LinkButton.Root>
+        </nav>
+      </div>
+      <div className={styles.navUser}>
+        <Avatar.Root size="m" aria-label="Signed in as Jamie Chen">
+          <Avatar.Image src={portrait} alt="" />
+          <Avatar.Fallback>JC</Avatar.Fallback>
+        </Avatar.Root>
+        <LinkButton.Root href="#account" size="m">
+          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 size="m" 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>
+  );
+}

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

@@ -0,0 +1,28 @@
+import { Avatar } from "@/components/avatar/Avatar";
+
+import styles from "./examples.module.css";
+
+const sampleSrc =
+  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
+
+/**
+ * Overlapping row of three avatars, group `size` cloned to children — mirrors `playground/snippets/avatar/group-three.tsx`.
+ */
+export default function AvatarGroupThreeExample() {
+  return (
+    <div className={styles.stack}>
+      <Avatar.Group.Root size="xl">
+        <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.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,24 @@
+import { Avatar, type AvatarSize } from "@/components/avatar/Avatar";
+
+import styles from "./examples.module.css";
+
+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>
+  );
+}

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

@@ -0,0 +1,35 @@
+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 = [
+  "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>
+      <Button.Root
+        mode="ghost"
+        size="m"
+        type="button"
+        onClick={() => setIndex((i) => (i + 1) % sources.length)}
+      >
+        Next portrait
+      </Button.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,26 @@
+import { Avatar } from "@/components/avatar/Avatar";
+
+import styles from "./examples.module.css";
+
+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>
+  );
+}

package/src/components/avatar/examples/team-list.tsx

@@ -0,0 +1,45 @@
+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";
+
+type Member = { id: string; name: string; role: string; src?: string };
+
+const members: Member[] = [
+  { id: "1", name: "Alex Morgan", role: "Design lead", src: portrait },
+  { id: "2", name: "Jordan Lee", role: "Engineer" },
+  { id: "3", name: "Sam Rivera", role: "PM", src: portrait },
+];
+
+/**
+ * Team roster: each row pairs Avatar with Typography; missing photo falls back to initials.
+ */
+export default function AvatarTeamListExample() {
+  return (
+    <ul className={styles.list} aria-label="Team members">
+      {members.map((m) => (
+        <li key={m.id} className={styles.listItem}>
+          <Avatar.Root size="l" aria-label={m.name}>
+            {m.src ? <Avatar.Image src={m.src} alt="" /> : null}
+            <Avatar.Fallback>
+              {m.name
+                .split(" ")
+                .map((p) => p[0])
+                .join("")}
+            </Avatar.Fallback>
+          </Avatar.Root>
+          <div className={styles.listItemBody}>
+            <Typography.Root as="span" variant="body-default" weight="medium">
+              {m.name}
+            </Typography.Root>
+            <Typography.Root as="span" variant="caption" tone="muted">
+              {m.role}
+            </Typography.Root>
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/components/badge/COMPONENT.md

@@ -1,35 +1,72 @@
 # Badge
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default sizing:** When designing screens or samples, prefer **`size="m"`** unless the scenario explicitly needs another value.
 
 ## About
 
 A compact, non-interactive label for status, category, or counts. Optional `Badge.Dot` and `Badge.Icon` slots align a decorative dot or an icon with text; `variant="status"` adds a built-in presence dot and live-region semantics.
 
-- **When to use:** surface short metadata next to headings, table rows, or list items (stage, environment, stock, role).
-- **When to use:** show presence or mode with `variant="status"` when short visible copy fits the layout; use `label` when screen readers need more than `children` alone (see Rules).
-- **When to use:** pair a semantic `color` and `variant` (`filled`, `light`, `lighter`, `stroke`) with density and emphasis needs on dashboards and catalogs.
-- **When to use:** combine `Badge.Icon` with text or icon-only content when the icon should inherit badge sizing from `ControlSizeProvider`.
-- **When not to use:** as the primary control for a click or navigation — use [Button](../button/COMPONENT.md) or [LinkButton](../link-button/COMPONENT.md) instead.
-- **When not to use:** for removable or selectable tags — use [Tag](../tag/COMPONENT.md).
-- **When not to use:** for keyboard shortcut glyphs — use [Kbd](../kbd/COMPONENT.md).
+- **Use** for short metadata next to headings, table rows, or list items (stage, environment, stock, role).
+- **Use** `variant="status"` for presence when visible copy fits; pass **`label`** when assistive tech needs more than `children` alone (see Rules).
+- **Use** semantic **`color`** with **`variant`** (`filled`, `light`, `lighter`, `stroke`) for emphasis on dashboards and catalogs.
+- **Use** **`Badge.Icon`** when the icon should inherit badge sizing from the surrounding `ControlSizeProvider` (root provides it for children).
+- **Do not use** as the primary control for clicks or navigation — use [Button](../button/COMPONENT.md) or [LinkButton](../link-button/COMPONENT.md).
+- **Do not use** for removable or selectable tags — use [Tag](../tag/COMPONENT.md).
+- **Do not use** for keyboard shortcut glyphs — use [Kbd](../kbd/COMPONENT.md).
 
 ## Composition
 
 - **`Badge.Root`** — root `div`; wraps `children` in `ControlSizeProvider` so nested icons can inherit control size. With **`variant="status"`**, renders a built-in status dot (`aria-hidden`), sets `role="status"`, optional `aria-label` from `label`, and ignores `color` for styling (dot color follows `status`).
-- **`Badge.Dot`** — optional decorative dot inside the label (`span`, `aria-hidden`); use with non-status variants when you need a manual indicator next to text or icons.
-- **`Badge.Icon`** — optional `span` wrapper for an icon node; place it before or after text, or use it alone for icon-only badges. Order of `Dot`, `Icon`, and text is up to layout needs.
+- **`Badge.Dot`** — optional decorative dot (`span`, `aria-hidden`); use with non-status variants when you need a manual indicator next to text or icons.
+- **`Badge.Icon`** — optional `span` wrapper for an icon node; place it before or after text, or use it alone for icon-only badges.
 
-### Minimal example
+## Examples
+
+### Canonical
+
+Source of truth: [`examples/canonical.tsx`](./examples/canonical.tsx).
 
 ```tsx
 import { Badge } from "prime-ui-kit";
 
-export function Example() {
+export default function BadgeCanonicalExample() {
   return <Badge.Root>New</Badge.Root>;
 }
 ```
 
+### Extended (copy from repo)
+
+| File | Scenario |
+|------|----------|
+| [`examples/status-presence.tsx`](./examples/status-presence.tsx) | Presence: `variant="status"`, `status`, `label` |
+| [`examples/ecommerce-inventory.tsx`](./examples/ecommerce-inventory.tsx) | Stock, promo, secure checkout with `Badge.Icon` |
+| [`examples/inbox-labels.tsx`](./examples/inbox-labels.tsx) | Priority, unread, channel type, `Badge.Dot` |
+| [`examples/admin-tags.tsx`](./examples/admin-tags.tsx) | Environment, access, feature-flag labels |
+
+### Playground snippets
+
+Order matches [`playground/sections/BadgeSection.tsx`](../../../playground/sections/BadgeSection.tsx). Snippets import from `@/components/badge/Badge` in-repo; consumers use **`import { Badge } from "prime-ui-kit"`**.
+
+| File | Scenario |
+|------|----------|
+| `playground/snippets/badge/sizes.tsx` | Explicit `size` `s`–`xl` with `variant="light"` and `color="gray"`. |
+| `playground/snippets/badge/variants.tsx` | `filled`, `light`, `lighter`, `stroke` on one `color`; `variant="status"` with `status` and `label`. |
+| `playground/snippets/badge/disabled.tsx` | `disabled` on `filled`, `stroke`, and `status`. |
+| `playground/snippets/badge/dot-icon.tsx` | `Badge.Dot` before text; `Badge.Icon` with text. |
+| `playground/snippets/badge/icons.tsx` | Icon left, variants/sizes, icon-only row, icon right, `Badge.Dot` + `Badge.Icon`. |
+| `playground/snippets/badge/semantic-colors.tsx` | Every `color` on `variant="light"` and `size="m"`. |
+| `playground/snippets/badge/context-size.tsx` | No `size` on root: `ControlSizeProvider`; context `xs` maps to badge visual `s`. |
+
+Prefer **`examples/*.tsx`** for product-shaped English samples.
+
+## Note for LLM consumers
+
+- **Imports:** In consumer code and doc samples, import **`Badge`** (and **`Icon`** when needed) from **`"prime-ui-kit"`** only — not from `@/components/...`.
+- **Status mode:** When **`variant="status"`**, set **`label`** if visible **`children`** do not carry enough meaning alone (e.g. generic “Away” without whose presence). The built-in dot is **`aria-hidden`**; do not use it as the only state signal.
+- **Tag vs Badge:** **Badge** is read-only metadata; **Tag** is for removable/filter chips — see [Tag](../tag/COMPONENT.md).
+- **Sizing:** Omit **`size`** to follow the nearest **`ControlSizeProvider`**; otherwise default effective size is **`m`** (context **`xs`** maps to badge **`s`**).
+- **Colors:** **`color`** is ignored for styling when **`variant="status"`**; use **`status`** for the dot.
+
 ## Rules
 
 - Omit `size` to inherit from the nearest `ControlSizeProvider` / control-surface context; if none is present, the effective size is **`m`**. Context value **`xs`** maps to badge size **`s`**.

package/src/components/badge/examples/admin-tags.tsx

@@ -0,0 +1,35 @@
+import { Badge } from "prime-ui-kit";
+import type { CSSProperties } from "react";
+
+const row: CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "var(--prime-sys-spacing-s)",
+  alignItems: "center",
+};
+
+/** Environment and access hints on admin surfaces (non-removable labels; use Tag for removable chips). */
+export default function BadgeAdminTagsExample() {
+  return (
+    <div style={row}>
+      <Badge.Root color="orange" variant="filled" size="m">
+        Staging
+      </Badge.Root>
+      <Badge.Root color="green" variant="light" size="m">
+        Production
+      </Badge.Root>
+      <Badge.Root color="gray" variant="stroke" size="m">
+        Internal
+      </Badge.Root>
+      <Badge.Root color="blue" variant="lighter" size="m">
+        Beta
+      </Badge.Root>
+      <Badge.Root color="purple" variant="filled" size="m">
+        Owner
+      </Badge.Root>
+      <Badge.Root color="yellow" variant="light" size="m">
+        Feature flag: new billing
+      </Badge.Root>
+    </div>
+  );
+}

package/src/components/badge/examples/canonical.tsx

@@ -0,0 +1,6 @@
+import { Badge } from "prime-ui-kit";
+
+/** Smallest valid usage: default `size` `m`, `variant` `light`, `color` `gray`. */
+export default function BadgeCanonicalExample() {
+  return <Badge.Root>New</Badge.Root>;
+}