prime-ui-kit 0.7.13 → 0.9.1

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

@@ -0,0 +1,50 @@
+/** A leading dot, a leading or trailing icon and an icon-only square with a name — `Badge.Dot`, `Badge.Icon`, `aria-label`. */
+import { Badge, Icon, Typography } from "prime-ui-kit";
+
+export default function BadgeWithIconExample() {
+  return (
+    <div>
+      <div>
+        <Badge.Root color="green">
+          <Badge.Dot />
+          Активен
+        </Badge.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          Badge.Dot
+        </Typography>
+      </div>
+      <div>
+        <Badge.Root color="purple">
+          <Badge.Icon>
+            <Icon name="status.locked" />
+          </Badge.Icon>
+          Приватный
+        </Badge.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          Badge.Icon · start
+        </Typography>
+      </div>
+      <div>
+        <Badge.Root color="blue">
+          Подробнее
+          <Badge.Icon>
+            <Icon name="nav.chevronRight" />
+          </Badge.Icon>
+        </Badge.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          Badge.Icon · end
+        </Typography>
+      </div>
+      <div>
+        <Badge.Root color="sky" aria-label="Почта">
+          <Badge.Icon>
+            <Icon name="field.email" />
+          </Badge.Icon>
+        </Badge.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          icon-only
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/banner/COMPONENT.md

@@ -1,172 +1,165 @@
 # Banner
 
-## Canonical
+**Category:** feedback
+**Kind:** primitive
 
-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.
+> Full-width in-flow message for a page, section or card: status icon, title, description, actions and dismiss.
 
-**Defaults:** `variant="filled"`, `status="information"`, `size="m"`.
+## When to use
+- A persistent message about the current page or account: trial ending, failed payment, maintenance, a new feature.
+- A message inside a card or a form section (`placement="inset"`).
+- An edge-to-edge strip above a page or the app shell (`placement="page"`).
 
+## When not to use
+- A short-lived reaction to an action («Сохранено») → use [Notification](../notification/COMPONENT.md).
+- An error of one field → the field `error` or [Hint](../hint/COMPONENT.md).
+- A blocking question or confirmation → use [Modal](../modal/COMPONENT.md).
+- An empty list or page → use [EmptyPage](../empty-page/COMPONENT.md).
+- A small status label → use [Badge](../badge/COMPONENT.md).
+
+## Import
 ```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
+## Anatomy
+```
+Banner.Root                 <div>; variant, tone, size, placement
+├─ Banner.Content           grid: [icon] [title / description] [actions]
+│  ├─ Banner.Icon           one Icon on the first line (aria-hidden)
+│  ├─ Banner.Title
+│  ├─ Banner.Description
+│  └─ Banner.Actions        buttons; with onDismiss the close button is last here
+└─ close button             with onDismiss and no Actions: ghost icon Button (tone="inherit"), top-right
+```
 
-- **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.
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Banner.Root
+`ref` → `HTMLDivElement`. The in-flow message block: fill of the tone, tier spacing; renders the close button with `onDismiss`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"solid" \| "soft" \| "outline"` | `"soft"` | `soft` tinted fill, `solid` saturated fill for urgent messages, `outline` card fill with a tone ring. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"info"` | Semantic color of the message. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Spacing, icon and title follow the control tier; the description is one step smaller. |
+| `placement` | `"inset" \| "page"` | `"inset"` | `inset` — rounded block in the flow or in a card; `page` — edge-to-edge strip above a page, content aligned to the page column. |
+| `onDismiss` | `() => void` | — | Renders a close button (top-right, or last in `Banner.Actions`) and calls this on click; the parent unmounts the banner. |
+| `labels` | `Partial<BannerLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` (`alert`, `status`, `region`), `aria-label` and the other div attributes. |
+
+### Banner.Content
+`ref` → `HTMLDivElement`. A `<div>` grid: icon on the first line, title over description, actions on the right (under the text below 36rem).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### Banner.Icon
+`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` holding one `Icon`, one title line high, in the tone color.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (`Icon`), `className` and the other span attributes. |
+
+### Banner.Title · Banner.Description
+`ref` → `HTMLSpanElement`. `<span>` elements: the medium title and the secondary text, both capped at the reading width.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
+### Banner.Actions
+`ref` → `HTMLDivElement`. A `<div>` row of buttons; with `onDismiss` the close button becomes its last square button.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Buttons in the banner `size`), `className` and the other div attributes. |
+
+## Variants
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `soft` | tinted tone fill, primary text, tone icon | most messages | yes |
+| `solid` | saturated tone fill, contrasting text | urgent: failed payment, outage | |
+| `outline` | card fill with a hairline tone ring | calm notices on a busy surface | |
+
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `info` | info fill | maintenance, facts | yes |
+| `success` | success fill | a finished long operation | |
+| `warning` | warning fill | trial ending, quota | |
+| `danger` | danger fill | failed payment, sync error | |
+| `accent` | accent fill | a new feature | |
+| `neutral` | muted fill | quiet notices | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` · `s` | tight padding, caption description | dense panels, side columns | |
+| `m` | padding 12 × 16, body-s description | most pages | yes |
+| `l` · `xl` | roomy padding, body-m description | hero areas, empty pages | |
+
+### placement
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `inset` | rounded block in the flow or inside a card | section messages | yes |
+| `page` | edge-to-edge strip, no radius, content on the page column | account-wide notices above a page | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| look | `variant`, `tone`, `size`, `placement` | `data-variant`, `data-tone`, `data-size`, `data-placement` |
+| dismissible | `onDismiss` | corner ghost Button (`xs`, `s` on `l` / `xl`), or the last outline Button in `Banner.Actions` |
+| narrow | own width < 36rem (a banner with `Banner.Actions` is a size container) | actions move under the text |
+
+No `open` prop: the parent mounts and unmounts the banner.
+
+## Layout & spacing
+- `width: 100%`; text column capped at `--prime-layout-reading-max-width`.
+- Spacing lives in item paddings, so absent parts leave no gutters.
+- Action buttons take the banner `size`; the close button is centered on the first text line and never grows the banner.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Actions and the close button are regular buttons in Tab order. |
+
+### ARIA
+- The banner has no role of its own: give an error after an action `role="alert"`, a calm status `role="status"`, a page strip `role="region"` with `aria-label`.
+- The icon is `aria-hidden`: the title carries the meaning, not the color.
+- The close button is named by `labels.dismiss`; after dismissing, move focus somewhere sensible.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `dismiss` | `"Закрыть"` | `aria-label` of the close button. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A maintenance notice: icon, title and description on a soft info fill. |
+| [variants.tsx](examples/variants.tsx) | Every treatment on every tone: soft by default, solid for urgent, outline for calm — `variant`, `tone`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier: padding, icon and title follow the control tier, the description is one step smaller — `size`. |
+| [structure.tsx](examples/structure.tsx) | Optional parts: a one-line title, a title with a description, and actions where the close button joins the row — `Banner.Description`, `Banner.Actions`, `onDismiss`. |
+| [dismissible.tsx](examples/dismissible.tsx) | The parent owns visibility: the close button calls back and the parent unmounts the banner; the button name comes from labels — `onDismiss`, `labels`. |
+| [page-strip.tsx](examples/page-strip.tsx) | An edge-to-edge strip above a page and a rounded block inside a card — `placement`. |
+| [narrow.tsx](examples/narrow.tsx) | Below 36rem of its own width the banner moves the actions under the text. |
+
+## Mistakes
+- A hand-made × next to the banner → pass `onDismiss`.
+- A lucide icon passed as a component → put `<Icon name="status.*" />` inside `Banner.Icon`.
+- A toast-like «Сохранено» in a banner → use Notification.
+- Several `solid` banners on one screen → keep `solid` for the one urgent message.
+
+## Related
+- **Built from:** Button, Icon
+- **See also:** [Notification](../notification/COMPONENT.md), [Hint](../hint/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Badge](../badge/COMPONENT.md)

package/src/components/banner/examples/dismissible.tsx

@@ -0,0 +1,38 @@
+/** The parent owns visibility: the close button calls back and the parent unmounts the banner; the button name comes from labels — `onDismiss`, `labels`. */
+import { Banner, Button, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function BannerDismissibleExample() {
+  const [visible, setVisible] = React.useState(true);
+
+  return (
+    <div className={styles.stack}>
+      {visible ? (
+        <Banner.Root
+          tone="accent"
+          onDismiss={() => setVisible(false)}
+          labels={{ dismiss: "Скрыть объявление" }}
+        >
+          <Banner.Content>
+            <Banner.Icon>
+              <Icon name="status.info" />
+            </Banner.Icon>
+            <Banner.Title>Тёмная тема</Banner.Title>
+            <Banner.Description>Включается в настройках профиля.</Banner.Description>
+          </Banner.Content>
+        </Banner.Root>
+      ) : (
+        <Button.Root
+          variant="outline"
+          tone="neutral"
+          className={styles.restore}
+          onClick={() => setVisible(true)}
+        >
+          Вернуть баннер
+        </Button.Root>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,32 @@
+/* Layout of the Banner scenarios: semantic tokens only. */
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+  width: 100%;
+  min-width: 0;
+}
+
+/* placement.tsx: a page frame above a card. */
+.sections {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-6);
+  width: 100%;
+  min-width: 0;
+}
+
+.pageBody {
+  padding: var(--prime-space-5) var(--prime-space-4) var(--prime-space-8);
+}
+
+/* narrow.tsx: a 320px column; the banner's container query moves actions under the text. */
+.narrow {
+  width: min(100%, calc(var(--prime-space-20) * 4));
+}
+
+/* dismiss.tsx */
+.restore {
+  align-self: flex-start;
+}

package/src/components/banner/examples/narrow.tsx

@@ -0,0 +1,23 @@
+/** Below 36rem of its own width the banner moves the actions under the text. */
+import { Banner, Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function BannerNarrowExample() {
+  return (
+    <div className={styles.narrow}>
+      <Banner.Root tone="warning" onDismiss={() => undefined}>
+        <Banner.Content>
+          <Banner.Icon>
+            <Icon name="status.warning" />
+          </Banner.Icon>
+          <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
+          <Banner.Description>Выберите тариф, чтобы сохранить отчёты команды.</Banner.Description>
+          <Banner.Actions>
+            <Button.Root>Выбрать тариф</Button.Root>
+          </Banner.Actions>
+        </Banner.Content>
+      </Banner.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,18 @@
+/** A maintenance notice: icon, title and description on a soft info fill. */
+import { Banner, Icon } from "prime-ui-kit";
+
+export default function BannerOverviewExample() {
+  return (
+    <Banner.Root>
+      <Banner.Content>
+        <Banner.Icon>
+          <Icon name="status.info" />
+        </Banner.Icon>
+        <Banner.Title>Плановые работы в ночь на субботу</Banner.Title>
+        <Banner.Description>
+          С 02:00 до 04:00 по Москве отчёты будут доступны только для чтения.
+        </Banner.Description>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}

package/src/components/banner/examples/page-strip.tsx

@@ -0,0 +1,53 @@
+/** An edge-to-edge strip above a page and a rounded block inside a card — `placement`. */
+import { Banner, Button, Card, Icon, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function BannerPageStripExample() {
+  return (
+    <div className={styles.sections}>
+      <Card.Root>
+        <Banner.Root
+          tone="warning"
+          placement="page"
+          role="region"
+          aria-label="Пробный период"
+          onDismiss={() => undefined}
+        >
+          <Banner.Content>
+            <Banner.Icon>
+              <Icon name="status.warning" />
+            </Banner.Icon>
+            <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
+          </Banner.Content>
+        </Banner.Root>
+        <div className={styles.pageBody}>
+          <Typography as="h3" variant="heading-s">
+            Отчёты
+          </Typography>
+        </div>
+      </Card.Root>
+      <Card.Root variant="panel">
+        <Card.Header>
+          <Card.Title>Оплата</Card.Title>
+        </Card.Header>
+        <Card.Body>
+          <Banner.Root tone="danger">
+            <Banner.Content>
+              <Banner.Icon>
+                <Icon name="status.danger" />
+              </Banner.Icon>
+              <Banner.Title>Не удалось списать оплату</Banner.Title>
+              <Banner.Description>
+                Карта •••• 4242 отклонена банком. Обновите способ оплаты до 15 октября.
+              </Banner.Description>
+              <Banner.Actions>
+                <Button.Root tone="danger">Обновить карту</Button.Root>
+              </Banner.Actions>
+            </Banner.Content>
+          </Banner.Root>
+        </Card.Body>
+      </Card.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,29 @@
+/** Every tier: padding, icon and title follow the control tier, the description is one step smaller — `size`. */
+import { Banner, Icon, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function BannerSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <div>
+            <Banner.Root size={size}>
+              <Banner.Content>
+                <Banner.Icon>
+                  <Icon name="status.info" />
+                </Banner.Icon>
+                <Banner.Title>Доступен новый отчёт</Banner.Title>
+                <Banner.Description>Описание на ступень мельче заголовка.</Banner.Description>
+              </Banner.Content>
+            </Banner.Root>
+            <Typography as="span" variant="caption" tone="muted">
+              {size}
+            </Typography>
+          </div>
+        </div>
+      ))}
+    </>
+  );
+}

package/src/components/banner/examples/structure.tsx

@@ -0,0 +1,45 @@
+/** Optional parts: a one-line title, a title with a description, and actions where the close button joins the row — `Banner.Description`, `Banner.Actions`, `onDismiss`. */
+import { Banner, Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const noop = () => undefined;
+
+export default function BannerStructureExample() {
+  return (
+    <div className={styles.stack}>
+      <Banner.Root tone="success">
+        <Banner.Content>
+          <Banner.Icon>
+            <Icon name="status.success" />
+          </Banner.Icon>
+          <Banner.Title>Оплата прошла</Banner.Title>
+        </Banner.Content>
+      </Banner.Root>
+      <Banner.Root tone="warning" onDismiss={noop}>
+        <Banner.Content>
+          <Banner.Icon>
+            <Icon name="status.warning" />
+          </Banner.Icon>
+          <Banner.Title>Подтвердите email</Banner.Title>
+          <Banner.Description>Без него уведомления о заказах не приходят.</Banner.Description>
+        </Banner.Content>
+      </Banner.Root>
+      <Banner.Root tone="warning" onDismiss={noop}>
+        <Banner.Content>
+          <Banner.Icon>
+            <Icon name="status.warning" />
+          </Banner.Icon>
+          <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
+          <Banner.Description>Выберите тариф, чтобы сохранить отчёты команды.</Banner.Description>
+          <Banner.Actions>
+            <Button.Root variant="outline" tone="neutral">
+              Сравнить
+            </Button.Root>
+            <Button.Root>Выбрать тариф</Button.Root>
+          </Banner.Actions>
+        </Banner.Content>
+      </Banner.Root>
+    </div>
+  );
+}