prime-ui-kit 0.7.11 → 0.9.0

package/src/components/badge/examples/in-controls.tsx

@@ -0,0 +1,35 @@
+/** Without `size` a badge inside Button or Input takes the tier one step down (button m → badge s). Use for counters in buttons and affixes in fields. */
+import { Badge, Button, Input } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function BadgeInControlsExample() {
+  return (
+    <div className={styles.stack}>
+      <div className={styles.controls}>
+        <Button.Root variant="outline" tone="neutral" size="s">
+          Входящие
+          <Badge.Root color="blue">12</Badge.Root>
+        </Button.Root>
+        <Button.Root variant="outline" tone="neutral">
+          Входящие
+          <Badge.Root color="blue">12</Badge.Root>
+        </Button.Root>
+        <Button.Root variant="outline" tone="neutral" size="l">
+          Входящие
+          <Badge.Root color="blue">12</Badge.Root>
+        </Button.Root>
+      </div>
+      <div className={styles.field}>
+        <Input.Root label="Промокод">
+          <Input.Wrapper>
+            <Input.Field defaultValue="SPRING25" />
+            <Input.InlineAffix side="end">
+              <Badge.Root color="green">−25%</Badge.Root>
+            </Input.InlineAffix>
+          </Input.Wrapper>
+        </Input.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/badge/examples/order-list.tsx

@@ -0,0 +1,48 @@
+/** Order list with a status column: a soft badge with text, the color only repeats the meaning. Use for status columns in lists and tables. */
+import { Badge, type PaletteColor, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const orders: { id: string; client: string; total: string; status: string; color: PaletteColor }[] =
+  [
+    {
+      id: "№ 10482",
+      client: "ООО «Северный ветер»",
+      total: "48 200 ₽",
+      status: "Оплачен",
+      color: "green",
+    },
+    {
+      id: "№ 10481",
+      client: "ИП Кузнецова",
+      total: "12 900 ₽",
+      status: "Ожидает оплаты",
+      color: "orange",
+    },
+    {
+      id: "№ 10480",
+      client: "АО «Техносфера»",
+      total: "230 000 ₽",
+      status: "В доставке",
+      color: "blue",
+    },
+    { id: "№ 10479", client: "ООО «Лето»", total: "7 400 ₽", status: "Отменён", color: "gray" },
+  ];
+
+export default function BadgeOrderListExample() {
+  return (
+    <ul className={styles.list} aria-label="Последние заказы">
+      {orders.map((order) => (
+        <li key={order.id} className={styles.item}>
+          <Typography.Root as="span" variant="body-m" truncate>
+            {order.id} · {order.client}
+          </Typography.Root>
+          <Typography.Root as="span" variant="body-s" tone="muted" className={styles.tabular}>
+            {order.total}
+          </Typography.Root>
+          <Badge.Root color={order.color}>{order.status}</Badge.Root>
+        </li>
+      ))}
+    </ul>
+  );
+}

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

@@ -0,0 +1,44 @@
+/** All ten palette hues in `soft` (default) and `solid`. Use to pick a category color; the text must read without the color. */
+import { Badge, type PaletteColor, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const colors: PaletteColor[] = [
+  "gray",
+  "blue",
+  "sky",
+  "teal",
+  "green",
+  "yellow",
+  "orange",
+  "red",
+  "pink",
+  "purple",
+];
+
+export default function BadgePaletteExample() {
+  return (
+    <div className={styles.matrix}>
+      <Typography.Root as="span" variant="caption" tone="muted">
+        soft
+      </Typography.Root>
+      <div className={styles.badges}>
+        {colors.map((color) => (
+          <Badge.Root key={color} color={color}>
+            {color}
+          </Badge.Root>
+        ))}
+      </div>
+      <Typography.Root as="span" variant="caption" tone="muted">
+        solid
+      </Typography.Root>
+      <div className={styles.badges}>
+        {colors.map((color) => (
+          <Badge.Root variant="solid" key={color} color={color}>
+            {color}
+          </Badge.Root>
+        ))}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,23 @@
+/** Five badge tiers: 16 · 20 · 24 · 28 · 32 px, default `m`. Use to pick a size that matches the text it sits next to. */
+import { Badge, type ControlSize, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const sizes: ControlSize[] = ["xs", "s", "m", "l", "xl"];
+
+export default function BadgeSizesExample() {
+  return (
+    <div className={styles.sizes}>
+      {sizes.map((size) => (
+        <div key={size} className={styles.sizeCell}>
+          <Badge.Root size={size} color="blue">
+            Бета
+          </Badge.Root>
+          <Typography.Root as="span" variant="caption" tone="muted">
+            {size}
+          </Typography.Root>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,45 @@
+/** Badge is static: the default look and `disabled` for every variant and with a dot. Use `disabled` for labels of inactive or unavailable items. */
+import { Badge, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function BadgeStatesExample() {
+  return (
+    <div className={styles.matrix}>
+      <Typography.Root as="span" variant="caption" tone="muted">
+        обычный
+      </Typography.Root>
+      <div className={styles.badges}>
+        <Badge.Root color="green">Оплачен</Badge.Root>
+        <Badge.Root variant="solid" color="green">
+          Оплачен
+        </Badge.Root>
+        <Badge.Root variant="outline" color="green">
+          Оплачен
+        </Badge.Root>
+        <Badge.Root color="green">
+          <Badge.Dot />
+          Активен
+        </Badge.Root>
+      </div>
+      <Typography.Root as="span" variant="caption" tone="muted">
+        disabled
+      </Typography.Root>
+      <div className={styles.badges}>
+        <Badge.Root color="green" disabled>
+          Оплачен
+        </Badge.Root>
+        <Badge.Root variant="solid" color="green" disabled>
+          Оплачен
+        </Badge.Root>
+        <Badge.Root variant="outline" color="green" disabled>
+          Оплачен
+        </Badge.Root>
+        <Badge.Root color="green" disabled>
+          <Badge.Dot />
+          Активен
+        </Badge.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,21 @@
+/** A typical set of status badges that reads the same on canvas, card and floating layers. Use as-is on any surface; soft fills need no adjustment. */
+import { Badge } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function BadgeSurfacesExample() {
+  return (
+    <div className={styles.badges}>
+      <Badge.Root>Черновик</Badge.Root>
+      <Badge.Root color="blue">Ревью</Badge.Root>
+      <Badge.Root color="green">Опубликован</Badge.Root>
+      <Badge.Root variant="outline" color="red">
+        Ошибка
+      </Badge.Root>
+      <Badge.Root color="yellow">
+        <Badge.Dot />
+        На паузе
+      </Badge.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,47 @@
+/** The three treatments (`soft` default, `solid`, `outline`) on the same hues, plus a leading `Badge.Dot`. Use to choose emphasis for labels in lists and tables. */
+
+import { Badge, type PaletteColor, Typography } from "prime-ui-kit";
+import { Fragment } from "react";
+
+import styles from "./examples.module.css";
+
+const variants = ["soft", "solid", "outline"] as const;
+const colors: PaletteColor[] = ["gray", "blue", "green", "orange", "red"];
+
+export default function BadgeVariantsExample() {
+  return (
+    <div className={styles.matrix}>
+      {variants.map((variant) => (
+        <Fragment key={variant}>
+          <Typography.Root as="span" variant="caption" tone="muted">
+            {variant}
+          </Typography.Root>
+          <div className={styles.badges}>
+            {colors.map((color) => (
+              <Badge.Root key={color} variant={variant} color={color}>
+                {color}
+              </Badge.Root>
+            ))}
+          </div>
+        </Fragment>
+      ))}
+      <Typography.Root as="span" variant="caption" tone="muted">
+        dot
+      </Typography.Root>
+      <div className={styles.badges}>
+        <Badge.Root color="green">
+          <Badge.Dot />
+          Активен
+        </Badge.Root>
+        <Badge.Root color="yellow">
+          <Badge.Dot />
+          На проверке
+        </Badge.Root>
+        <Badge.Root color="red">
+          <Badge.Dot />
+          Отклонён
+        </Badge.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/banner/COMPONENT.md

@@ -1,172 +1,170 @@
 # Banner
 
-## Canonical
+**Category:** feedback
 
-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 → use 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";
+```
+
+## Anatomy
+```
+Banner.Root                 tone fill, padding, container for the layout
+├─ Banner.Content           grid: [icon] [title / description] [actions]
+│  ├─ Banner.Icon           status icon on the first line
+│  ├─ Banner.Title          medium title
+│  ├─ Banner.Description    one step smaller text
+│  └─ Banner.Actions        buttons/links (and the dismiss button when there are actions)
+└─ Banner.CloseButton       optional custom close, top-right, centered on the first line
+```
+
+## API
+
+### Banner.Root
+`forwardRef` to `HTMLDivElement`. + native `<div>` props (`role`, `aria-label`, …). No role by default.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"soft" \| "solid" \| "outline"` | `"soft"` | Treatment, see Variants. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"info"` | Semantic color. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Padding, icon, title and description size. The built-in close/dismiss button takes it; pass it to action buttons yourself. |
+| `placement` | `"inset" \| "page"` | `"inset"` | `inset`: rounded block in the flow or a card. `page`: edge-to-edge strip without radius, content aligned to the page content column. |
+| `onDismiss` | `() => void` | — | Renders a close button (unless a `Banner.CloseButton` child exists) and calls this on click. With `Banner.Actions` the close becomes a square outline button at the end of the actions row. |
+| `labels` | `Partial<BannerLabels>` | see Accessibility | Built-in strings. |
+| `className` | `string` | — | Class on the root. |
+| `children` | `ReactNode` | — | Usually `Banner.Content` (+ `Banner.CloseButton`). |
+
+### Banner.Content
++ native `<div>` props. Layout of the message; below 36rem of the banner's own width (container query) actions move under the text.
+
+### Banner.Icon
+Polymorphic. + props of the `as` element.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `as` | `ElementType` | `"div"` | Element or icon component to render, e.g. a lucide icon: `<Banner.Icon as={Info} aria-hidden />`. |
+| `className` | `string` | — | Class. |
+| `children` | `ReactNode` | — | Icon content when `as` is a plain element. |
+
+### Banner.Title / Banner.Description
++ native `<span>` props. Title: tier text, medium. Description: one step smaller, secondary in `soft`/`outline`. Both are capped at the reading width.
+
+### Banner.Actions
++ native `<div>` props. Wrapping row with `--prime-space-2` gap; centered on the text block on wide banners.
+
+### Banner.CloseButton
+`forwardRef` to `HTMLButtonElement`. + native `<button>` props except `size`; `type` defaults to `"button"`. Must be a direct child of `Banner.Root`. Without children it renders a close icon and `aria-label={labels.dismiss}` (an explicit `aria-label` wins).
+
+## Variants
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `soft` | Tone soft fill, primary title, secondary description, tone-colored icon | Most messages | yes |
+| `solid` | Saturated tone fill, tone foreground text (neutral: inverse fill and text) | Urgent, must-see messages (payment failed, outage) | |
+| `outline` | Card fill with a hairline ring of the tone text color, tone icon | Calm notices inside content where a fill is too loud | |
+
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `info` | Info soft fill / info icon (sky, distinct from accent) | Neutral information, maintenance | yes |
+| `success` | Success soft fill / success icon | Completed operations | |
+| `warning` | Warning soft fill / warning icon | Something needs attention soon (trial ending) | |
+| `danger` | Danger soft fill / danger icon | Errors, failed payments, data loss risk | |
+| `accent` | Accent soft fill / accent icon | Product news, promotions | |
+| `neutral` | Muted fill, secondary icon; `solid` = inverse | Low-importance system notes | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | Padding 8, icon 14, title 12/16, description 12/16, radius 8 | Inside dense panels and tables | |
+| `s` | Padding 8 × 12, icon 16, title 13/20, description 12/16, radius 8 | Inside cards and side panels | |
+| `m` | Padding 12 × 16, icon 16, title 14/20, description 13/20, radius 12 | Default | yes |
+| `l` | Padding 16 × 20, icon 20, title 16/24, description 14/20, radius 12 | Page-level messages | |
+| `xl` | Padding 20 × 24, icon 20, title 16/24, description 14/20, radius 16 | Hero / onboarding messages | |
+
+### placement
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `inset` | Rounded block | In content flow or inside a card | yes |
+| `page` | No radius, edge to edge, text aligned to the page content column | Account-wide notices above the page / app shell | |
+
+**Combinations**
+- Recommended: `soft` + any tone for regular messages; `solid` + `danger`/`warning` for urgent ones; `outline` + `info`/`accent` inside cards.
+- Allowed but rare: `solid` + `accent` for a single promo strip.
+- Pointless: `solid` with `outline`-style action buttons of a different tone — keep actions neutral or matching.
+- Avoid: several `solid` banners on one screen; `placement="page"` inside a card.
+
+**Hierarchy:** at most one page-level banner at a time; one primary action per banner (solid button), the rest outline/ghost.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| variant / tone / size / placement | props | `data-variant`, `data-tone`, `data-size`, `data-placement` on Root |
+| dismissible | `onDismiss` or `Banner.CloseButton` | close button rendered |
+| hidden | parent state | the banner has no `open` prop: mount/unmount it |
+
+## Layout & spacing
+- `width: 100%`; spacing lives in item paddings, so missing parts leave no gaps.
+- Icon → text: tier gap (`--prime-space-2`…`--prime-space-4`); title → description: `--prime-space-1`; text → actions: `--prime-space-3`…`--prime-space-6`.
+- Narrow (< 36rem own width): actions move under the text with `--prime-space-3` above. Works from 320px.
+- Place a page banner as the first child above page content; an inset banner at the top of the section it refers to, separated by the section gap.
+
+## Accessibility
+- No role is set: add `role="status"` for polite updates, `role="alert"` for urgent errors, or `role="region"` + `aria-label` for a persistent announcement.
+- Mark the icon `aria-hidden`; the title must carry the meaning.
+- The close button has an accessible name from `labels.dismiss` or its own `aria-label`.
+
+| `labels` key | Default | Used for |
+|---|---|---|
+| `dismiss` | `"Закрыть"` | `aria-label` of the built-in close / dismiss button |
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [placement.tsx](examples/placement.tsx) | `placement="page"` above a page, `inset` in a card, narrow width with actions under the text | Choosing placement |
+| [variants.tsx](examples/variants.tsx) | `soft`, `solid`, `outline` × all six tones | Choosing variant and tone |
+| [sizes.tsx](examples/sizes.tsx) | `xs`…`xl` with actions and `onDismiss` | Matching density |
+| [dismiss.tsx](examples/dismiss.tsx) | `onDismiss` vs a custom `Banner.CloseButton`, parent-controlled visibility | Dismissible notices |
 
 ```tsx
 import { Banner } from "prime-ui-kit";
 
-export function Example() {
+export function MaintenanceBanner() {
   return (
-    <Banner.Root>
+    <Banner.Root tone="info" role="status">
       <Banner.Content>
-        <Banner.Title>Title</Banner.Title>
+        <Banner.Title>Плановые работы в ночь на субботу</Banner.Title>
+        <Banner.Description>С 02:00 до 04:00 отчёты доступны только для чтения.</Banner.Description>
       </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.
+## Mistakes
+- `<Banner.Root open={false}>` → there is no `open`; render it conditionally.
+- `tone="error"` → use `tone="danger"`.
+- `variant="ghost"` → not supported; use `outline`.
+- Action buttons without `size` in a non-`m` banner → pass the banner's `size` to them.
+- `Banner.CloseButton` inside `Banner.Content` → make it a direct child of Root.
+- A Banner for "Сохранено" after a click → use a Notification.
+
+## Related
+- [Notification](../notification/COMPONENT.md) — transient toasts.
+- [EmptyPage](../empty-page/COMPONENT.md) — empty states.
+- [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md) — actions.

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

@@ -0,0 +1,48 @@
+/** There is no `open` prop: the parent mounts and unmounts the banner. `onDismiss` adds the close button itself; `Banner.CloseButton` (a direct child of Root) is for a custom accessible name. Use it for dismissible notices. */
+import { MailWarning, Sparkles } from "lucide-react";
+import { Banner, Button } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function BannerDismissExample() {
+  const [auto, setAuto] = React.useState(true);
+  const [custom, setCustom] = React.useState(true);
+
+  return (
+    <div className={styles.stack}>
+      {auto ? (
+        <Banner.Root tone="warning" variant="soft" onDismiss={() => setAuto(false)}>
+          <Banner.Content>
+            <Banner.Icon as={MailWarning} aria-hidden />
+            <Banner.Title>Подтвердите email, чтобы получать уведомления</Banner.Title>
+          </Banner.Content>
+        </Banner.Root>
+      ) : null}
+      {custom ? (
+        <Banner.Root tone="accent" variant="soft">
+          <Banner.Content>
+            <Banner.Icon as={Sparkles} aria-hidden />
+            <Banner.Title>Тёмная тема</Banner.Title>
+            <Banner.Description>Включается в настройках профиля.</Banner.Description>
+          </Banner.Content>
+          <Banner.CloseButton aria-label="Скрыть объявление" onClick={() => setCustom(false)} />
+        </Banner.Root>
+      ) : null}
+      {!auto || !custom ? (
+        <Button.Root
+          variant="outline"
+          tone="neutral"
+          className={styles.restore}
+          size="s"
+          onClick={() => {
+            setAuto(true);
+            setCustom(true);
+          }}
+        >
+          Вернуть баннеры
+        </Button.Root>
+      ) : null}
+    </div>
+  );
+}