prime-ui-kit 0.0.1

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,34 @@
+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"
+        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

@@ -0,0 +1,115 @@
+# Badge
+
+**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.
+
+- **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 (`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.
+
+## Examples
+
+### Canonical
+
+Source of truth: [`examples/canonical.tsx`](./examples/canonical.tsx).
+
+```tsx
+import { Badge } from "prime-ui-kit";
+
+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`**.
+- With **`variant="status"`**, pass **`label`** when visible `children` alone are not enough for assistive tech (e.g. a generic word without whose status it is).
+- **`Badge.Dot`** (both manual and the built-in status dot) is **`aria-hidden`** — do not rely on it alone to communicate state.
+- **`disabled`** dims the badge via `data-disabled`; there is no loading, error, or focus ring — the badge is not keyboard-operable.
+- **`color`** applies only when **`variant` is not `"status"`**; for status mode, dot appearance is driven by **`status`** (default **`online`** when unset).
+
+## API
+
+### Badge.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `color` | `"gray" \| "red" \| "blue" \| "green" \| "orange" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | No | Semantic palette; ignored for styling when `variant="status"`. |
+| `variant` | `"filled" \| "light" \| "lighter" \| "stroke" \| "status"` | `"light"` | No | Fill, stroke, or status layout with built-in dot. |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | from context or `"m"` | No | Explicit size; otherwise derived from control surface context, else `"m"`. |
+| `disabled` | `boolean` | — | No | Muted look; sets `data-disabled`. |
+| `status` | `"online" \| "offline" \| "away" \| "busy"` | `"online"` | No | Dot semantics when `variant="status"`; ignored otherwise. |
+| `label` | `string` | — | No | `aria-label` on the root when `variant="status"`. |
+| `children` | `React.ReactNode` | — | No | Text, `Badge.Dot`, `Badge.Icon`, or icons. |
+| `className` | `string` | — | No | Extra class on the root. |
+| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other attributes and `ref` on the root `div`. |
+
+### Badge.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `React.ReactNode` | — | Yes | Icon node. |
+| `className` | `string` | — | No | Wrapper class. |
+| … | `Omit<React.HTMLAttributes<HTMLDivElement>, "children">` | — | No | Other wrapper attributes. |
+
+### Badge.Dot
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `className` | `string` | — | No | Extra class on the dot. |
+| … | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes; node is `aria-hidden`. |
+
+## Related
+
+- [Tag](../tag/COMPONENT.md)
+- [Typography](../typography/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [LinkButton](../link-button/COMPONENT.md)
+- [Kbd](../kbd/COMPONENT.md)

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">
+        Staging
+      </Badge.Root>
+      <Badge.Root color="green" variant="light">
+        Production
+      </Badge.Root>
+      <Badge.Root color="gray" variant="stroke">
+        Internal
+      </Badge.Root>
+      <Badge.Root color="blue" variant="lighter">
+        Beta
+      </Badge.Root>
+      <Badge.Root color="purple" variant="filled">
+        Owner
+      </Badge.Root>
+      <Badge.Root color="yellow" variant="light">
+        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>;
+}

package/src/components/badge/examples/ecommerce-inventory.tsx

@@ -0,0 +1,35 @@
+import { Badge, Icon } from "prime-ui-kit";
+import type { CSSProperties } from "react";
+
+const row: CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "var(--prime-sys-spacing-s)",
+  alignItems: "center",
+};
+
+/** Product shelf: stock emphasis with `filled` / `light` / `lighter` / `stroke`. */
+export default function BadgeEcommerceInventoryExample() {
+  return (
+    <div style={row}>
+      <Badge.Root color="green" variant="filled">
+        In stock
+      </Badge.Root>
+      <Badge.Root color="orange" variant="light">
+        Low stock · 3 left
+      </Badge.Root>
+      <Badge.Root color="red" variant="lighter">
+        Out of stock
+      </Badge.Root>
+      <Badge.Root color="purple" variant="stroke">
+        Sale · 20% off
+      </Badge.Root>
+      <Badge.Root color="teal" variant="filled">
+        <Badge.Icon>
+          <Icon name="status.locked" />
+        </Badge.Icon>
+        Secure checkout
+      </Badge.Root>
+    </div>
+  );
+}

package/src/components/badge/examples/inbox-labels.tsx

@@ -0,0 +1,36 @@
+import { Badge, Icon } from "prime-ui-kit";
+import type { CSSProperties } from "react";
+
+const row: CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "var(--prime-sys-spacing-s)",
+  alignItems: "center",
+};
+
+/** Thread metadata: priority, unread-style emphasis, and channel type with `Badge.Icon`. */
+export default function BadgeInboxLabelsExample() {
+  return (
+    <div style={row}>
+      <Badge.Root color="red" variant="filled">
+        Urgent
+      </Badge.Root>
+      <Badge.Root color="blue" variant="light">
+        Unread
+      </Badge.Root>
+      <Badge.Root color="gray" variant="stroke">
+        Archived
+      </Badge.Root>
+      <Badge.Root color="sky" variant="lighter">
+        <Badge.Icon>
+          <Icon name="field.email" />
+        </Badge.Icon>
+        Newsletter
+      </Badge.Root>
+      <Badge.Root color="purple" variant="light">
+        <Badge.Dot />
+        VIP list
+      </Badge.Root>
+    </div>
+  );
+}

package/src/components/badge/examples/status-presence.tsx

@@ -0,0 +1,32 @@
+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",
+};
+
+/**
+ * Presence row: `variant="status"` sets `role="status"` and a built-in dot.
+ * Use `label` when visible text is not enough for screen readers.
+ */
+export default function BadgeStatusPresenceExample() {
+  return (
+    <div style={row}>
+      <Badge.Root variant="status" status="online" label="Alex Morgan is online">
+        Online
+      </Badge.Root>
+      <Badge.Root variant="status" status="offline" label="Alex Morgan is offline">
+        Offline
+      </Badge.Root>
+      <Badge.Root variant="status" status="away" label="Alex Morgan is away">
+        Away
+      </Badge.Root>
+      <Badge.Root variant="status" status="busy" label="Alex Morgan is busy">
+        Busy
+      </Badge.Root>
+    </div>
+  );
+}

package/src/components/banner/COMPONENT.md

@@ -0,0 +1,172 @@
+# Banner
+
+## Canonical
+
+In-flow announcement strip: `Banner.Root` (grid + optional dismiss) wraps `Banner.Content` (icon, title, optional description, optional actions). Control visibility by mounting the root or parent state—there is no `open` prop.
+
+**Defaults:** `variant="filled"`, `status="information"`, `size="m"`.
+
+```tsx
+import { Banner } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Banner.Root>
+      <Banner.Content>
+        <Banner.Title>Title</Banner.Title>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}
+```
+
+| Piece | Role |
+|--------|------|
+| `Banner.Root` | `variant`, `status`, `size`, `onDismiss`, passes control size to `Banner.CloseButton` |
+| `Banner.Content` | Center column: slots below |
+| `Banner.Icon` | Optional; use `as={Icon}` and `aria-hidden` when decorative |
+| `Banner.Title` / `Banner.Description` | Primary and supporting copy (`span`) |
+| `Banner.Actions` | Buttons / `LinkButton` |
+| `Banner.CloseButton` | **Direct child of `Banner.Root`** (sibling of `Banner.Content`), not nested inside `Content` |
+
+### Playground snippets
+
+Order matches [`playground/sections/BannerSection.tsx`](../../../playground/sections/BannerSection.tsx). Snippets import from `@/components/banner/Banner`; consumers use **`import { … } from "prime-ui-kit"`**.
+
+| File | Scenario |
+|------|----------|
+| `playground/snippets/banner/sizes.tsx` | `size` `s`–`xl` with `variant="light"` and `status="information"`. |
+| `playground/snippets/banner/variants.tsx` | `variant` `filled`, `light`, `lighter`, `stroke` at `status="information"`. |
+| `playground/snippets/banner/statuses.tsx` | `status` `information`, `warning`, `error`, `success`, `feature` at `variant="light"`. |
+| `playground/snippets/banner/controlled.tsx` | Visibility from React state: hide removes the root; external button shows again (no root `onDismiss` required). |
+| `playground/snippets/banner/composition.tsx` | Slots: `Banner.Icon` with `as`, title, description, `Banner.Actions` (`LinkButton`, `Button`); `size="l"`, `variant="stroke"`. |
+| `playground/snippets/banner/full-width.tsx` | Root fills parent width; narrow wrapper illustrates a card column or sidebar. |
+| `playground/snippets/banner/dismiss-patterns.tsx` | `onDismiss` only (auto close) · `Banner.CloseButton` only · both without duplicate injected control. |
+
+### Scenario examples (English)
+
+| File | Scenario |
+|------|----------|
+| [`examples/billing-alert.tsx`](examples/billing-alert.tsx) | Billing failure: `error` + `filled`, `onDismiss`, actions, `role="region"`. |
+| [`examples/maintenance.tsx`](examples/maintenance.tsx) | Downtime: `warning` + `stroke`, actions, region label. |
+| [`examples/cookie-consent-row.tsx`](examples/cookie-consent-row.tsx) | Consent: `information` + `lighter`, `onDismiss`, actions. |
+| [`examples/feature-promo.tsx`](examples/feature-promo.tsx) | Promo: `feature` + `lighter`, `onDismiss`, actions. |
+| [`examples/controlled-visibility.tsx`](examples/controlled-visibility.tsx) | Controlled show/hide by conditional render (mirrors `controlled.tsx` snippet). |
+| [`examples/dismiss-close-button.tsx`](examples/dismiss-close-button.tsx) | `Banner.CloseButton` as direct root child without `onDismiss` (mirrors manual-dismiss branch of `dismiss-patterns.tsx`). |
+
+---
+
+## Extended
+
+### About
+
+An in-flow announcement strip: a root grid with a central content column and an optional dismiss control on the right. Use `status` and `variant` for semantic color and density; optional slots cover icon, title, description, and actions.
+
+- **Use** for persistent page- or section-level messages (policy, incident, feature, validation summary) where the user should read the text in context.
+- **Use** when you need optional actions (`Banner.Actions`) or dismiss without leaving the page.
+- **Use** `size` to align spacing and typography with surrounding controls (`ControlSizeProvider` context applies to `Banner.CloseButton`).
+- **Do not use** for transient overlay feedback; prefer [Notification](../notification/COMPONENT.md) or similar patterns.
+- **Do not use** as a substitute for [Modal](../modal/COMPONENT.md) or [Drawer](../drawer/COMPONENT.md) when the user must complete a blocking task.
+- **Do not use** decorative icons without `aria-hidden` (or an accessible name) when the icon is not redundant with the title.
+
+### Composition
+
+- `Banner.Root` is the outer `div` and size provider; pass `variant`, `status`, `size`, and optionally `onDismiss`.
+- Put primary copy inside `Banner.Content`. Typical order: `Banner.Icon` (optional), `Banner.Title`, `Banner.Description` (optional), `Banner.Actions` (optional).
+- `Banner.CloseButton` must be a **direct child** of `Banner.Root` (a sibling of `Banner.Content`, not nested inside `Content`). The implementation only scans **direct** children to decide whether to inject a default close button when `onDismiss` is set; a close control placed only inside `Banner.Content` does not suppress injection.
+- If `onDismiss` is provided and no direct child is `Banner.CloseButton`, the root appends a default close button that calls `onDismiss`.
+
+### Rules
+
+- There is no `open` / `visible` prop: mount or unmount the root (or hide it with parent state) to show or hide the strip.
+- `variant` defaults to `filled`; `status` to `information`; `size` to `m`. `stroke` uses a neutral surface with a status-colored bottom accent bar.
+- Decorative icons: pass `aria-hidden` on the underlying SVG/component when the title already conveys the message.
+- For a meaningful page-level region, set `role="region"` and `aria-label` or `aria-labelledby` on `Banner.Root` via standard HTML attributes.
+- The auto-injected dismiss control uses `aria-label="Dismiss"`; set an explicit `aria-label` (or equivalent) on a custom `Banner.CloseButton` in the product language.
+- `Banner.Title` and `Banner.Description` render as `span` elements; keep markup intentional if you nest interactive elements.
+- `Banner.Icon` is driven by the `as` prop (not `asChild` on the root).
+
+### API
+
+#### Banner.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| variant | `"filled" \| "light" \| "lighter" \| "stroke"` | `"filled"` | No | Background density and accent treatment (`stroke` adds a status-colored bottom bar). |
+| status | `"information" \| "warning" \| "error" \| "success" \| "feature"` | `"information"` | No | Semantic palette for the strip. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Spacing and type scale; feeds `Banner.CloseButton` via control-size context. |
+| onDismiss | `() => void` | — | No | When set and no direct `Banner.CloseButton` child exists, renders a default close button that invokes this callback. |
+| className | `string` | — | No | Additional class on the root `div`. |
+| children | `React.ReactNode` | — | No | Typically `Banner.Content` and optionally `Banner.CloseButton`. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native attributes on the root `div` (e.g. `id`, `role`, ARIA). |
+
+#### Banner.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the content column `div`. |
+| children | `React.ReactNode` | — | No | Icon, title, description, and/or actions. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native attributes on the inner `div`. |
+
+#### Banner.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| as | `React.ElementType` | `"div"` | No | Element or component to render (often an icon component). |
+| className | `string` | — | No | Additional class on the wrapper. |
+| children | `React.ReactNode` | — | No | Content when using the default element or a custom wrapper. |
+| …rest | props of `T` without `as` and `className` | — | No | Forwarded to the element chosen by `as`. |
+
+#### Banner.Title
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the `span`. |
+| children | `React.ReactNode` | — | No | Primary heading text. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Native `span` attributes. |
+
+#### Banner.Description
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the `span`. |
+| children | `React.ReactNode` | — | No | Supporting text. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Native `span` attributes. |
+
+#### Banner.Actions
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the actions row `div`. |
+| children | `React.ReactNode` | — | No | Action controls (e.g. `Button`, `LinkButton`). |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native attributes on the row `div`. |
+
+#### Banner.CloseButton
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Native `button` type. |
+| className | `string` | — | No | Additional class on the button. |
+| children | `React.ReactNode` | — | No | Button content; defaults to a cross icon when omitted. |
+| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "size">` | — | No | Other button props; `size` is derived from banner context. |
+
+### Playground alignment
+
+Matrix demos (`sizes`, `variants`, `statuses`, `controlled`, `composition`, `full-width`, `dismiss-patterns`) are maintained next to [`BannerSection.tsx`](../../../playground/sections/BannerSection.tsx); keep this doc table and snippet filenames in sync when the playground order or scenarios change.
+
+### Related
+
+- [Button](../button/COMPONENT.md) — actions inside `Banner.Actions`; `Banner.CloseButton` wraps `Button.Root` (ghost neutral).
+- [LinkButton](../link-button/COMPONENT.md) — text-style navigation actions in the strip.
+- [Typography](../typography/COMPONENT.md) — surrounding captions or body copy outside the banner slots.
+- [Notification](../notification/COMPONENT.md) — transient or stacked overlay messages instead of an in-flow strip.
+
+---
+
+## LLM note
+
+- **Dismiss:** `onDismiss` on `Banner.Root` injects a default close control only when there is **no** `Banner.CloseButton` among **direct** children of `Banner.Root`. Nesting `CloseButton` only under `Banner.Content` does **not** count—root may still inject a second close.
+- **Visibility:** no `open` prop; toggle with conditional render or parent state.
+- **Semantics:** map product tone to `status` (`error` billing failures, `warning` maintenance, `information` policy/cookies, `feature` promos). Pair `variant` with chrome: `filled` for urgent billing, `stroke` for calm operational notices, `lighter` / `light` for promos and consent rows.
+- **A11y:** prefer `role="region"` + `aria-labelledby` pointing at `Banner.Title`’s `id` (or `aria-label` when no visible title).
+- **Sizing:** default `size` is `m`; use `Banner`’s `size` for density—do not fake scale with ad-hoc CSS on kit nodes.

package/src/components/banner/examples/billing-alert.tsx

@@ -0,0 +1,35 @@
+import { AlertCircle } from "lucide-react";
+
+import { Banner, Button, LinkButton } from "prime-ui-kit";
+
+/** Past-due or failed payment: high emphasis, primary remediation + secondary help. */
+export default function BillingAlertExample() {
+  return (
+    <Banner.Root
+      aria-labelledby="billing-banner-title"
+      role="region"
+      status="error"
+      variant="filled"
+      onDismiss={() => {
+        /* product: hide after acknowledge */
+      }}
+    >
+      <Banner.Content>
+        <Banner.Icon as={AlertCircle} aria-hidden />
+        <Banner.Title id="billing-banner-title">Payment failed</Banner.Title>
+        <Banner.Description>
+          We could not charge your card ending in 4242. Update your payment method to avoid service
+          interruption.
+        </Banner.Description>
+        <Banner.Actions>
+          <Button.Root size="s" type="button" variant="primary">
+            Update payment method
+          </Button.Root>
+          <LinkButton.Root href="/billing/support" size="s">
+            Contact billing
+          </LinkButton.Root>
+        </Banner.Actions>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}