prime-ui-kit 0.3.1 → 0.3.2

package/src/components/link-button/examples/disabled.tsx

@@ -0,0 +1,18 @@
+import { LinkButton } from "prime-ui-kit";
+
+/**
+ * Disabled link is a <code>span</code> with <code>role="link"</code> — no <code>href</code>, anchor props are not applied.
+ * Do not use for “still focusable”; use <code>aria-disabled</code> on a real control pattern if that is required.
+ */
+export default function LinkButtonDisabledExample() {
+  return (
+    <div>
+      <LinkButton.Root href="/available" size="m">
+        Available route
+      </LinkButton.Root>
+      <LinkButton.Root href="/ignored-when-disabled" size="m" disabled>
+        Coming soon
+      </LinkButton.Root>
+    </div>
+  );
+}

package/src/components/link-button/examples/external.tsx

@@ -0,0 +1,18 @@
+import { LinkButton } from "prime-ui-kit";
+
+/** External URL opened in a new tab: always set <code>rel="noopener noreferrer"</code> with <code>target="_blank"</code>. */
+export default function LinkButtonExternalExample() {
+  return (
+    <p>
+      Documentation in a separate tab:{" "}
+      <LinkButton.Root
+        href="https://example.com/docs"
+        target="_blank"
+        rel="noopener noreferrer"
+        size="m"
+      >
+        Open help
+      </LinkButton.Root>
+    </p>
+  );
+}

package/src/components/link-button/examples/footer-legal.tsx

@@ -0,0 +1,22 @@
+import { LinkButton } from "prime-ui-kit";
+
+/** Dense footer legal row: smaller control tier keeps the strip compact. */
+export default function LinkButtonFooterLegalExample() {
+  return (
+    <footer>
+      <nav aria-label="Legal">
+        <LinkButton.Root href="/privacy" size="s">
+          Privacy
+        </LinkButton.Root>
+        <span aria-hidden> · </span>
+        <LinkButton.Root href="/terms" size="s">
+          Terms
+        </LinkButton.Root>
+        <span aria-hidden> · </span>
+        <LinkButton.Root href="/cookies" size="s">
+          Cookie policy
+        </LinkButton.Root>
+      </nav>
+    </footer>
+  );
+}

package/src/components/link-button/examples/inline-text-link.tsx

@@ -0,0 +1,14 @@
+import { LinkButton } from "prime-ui-kit";
+
+/** Inline link inside body copy: same line as surrounding text, default control tier. */
+export default function LinkButtonInlineTextLinkExample() {
+  return (
+    <p>
+      Need more detail? See{" "}
+      <LinkButton.Root href="/docs/billing" size="m">
+        billing documentation
+      </LinkButton.Root>{" "}
+      for proration rules.
+    </p>
+  );
+}

package/src/components/link-button/examples/navigation-cluster.tsx

@@ -0,0 +1,24 @@
+import { LinkButton } from "prime-ui-kit";
+
+/** Horizontal cluster of primary nav targets; named <code>nav</code> + text separators (layout can move to page grid/flex). */
+export default function LinkButtonNavigationClusterExample() {
+  return (
+    <nav aria-label="Product sections">
+      <LinkButton.Root href="/product/overview" size="m">
+        Overview
+      </LinkButton.Root>
+      <span aria-hidden> · </span>
+      <LinkButton.Root href="/product/pricing" size="m">
+        Pricing
+      </LinkButton.Root>
+      <span aria-hidden> · </span>
+      <LinkButton.Root href="/product/security" size="m">
+        Security
+      </LinkButton.Root>
+      <span aria-hidden> · </span>
+      <LinkButton.Root href="/product/changelog" size="m">
+        Changelog
+      </LinkButton.Root>
+    </nav>
+  );
+}

package/src/components/modal/COMPONENT.md

@@ -15,7 +15,7 @@ Centered overlay dialog with a portal, backdrop, focus trap, scroll lock, and op
 - **`Modal.Root`** — holds open state (controlled via **`open`** / **`onOpenChange`** or uncontrolled via **`defaultOpen`**), and options **`closeOnEscape`** / **`closeOnOverlayClick`**. Renders **`children`** only (no DOM wrapper).
 - **`Modal.Trigger`** — optional; **`React.Children.only`**: pass **exactly one** React element; its **`onClick`** is merged to call **`onOpen`** when the event is not **`defaultPrevented`**.
 - **`Modal.Panel`** — when open: **`createPortal`** (default container `document.body`), fullscreen **`role="presentation"`** overlay, then **`role="dialog"`** with **`aria-modal="true"`**. If **`title`** is set, renders an internal header (**`h2`**, optional description, optional built-in close icon button), wraps **`children`** in an internal body, and optional **`footer`**. Without **`title`**, **`children`** render directly inside the dialog surface—supply **`aria-label`** or **`aria-labelledby`** (and **`aria-describedby`** when needed).
-- **`Modal.Close`** — same single-child contract as **`Trigger`**; merges **`onClick`** to **`onClose`** when not **`defaultPrevented`**. Typical placement: a control inside **`footer`**.
+- **`Modal.Close`** — same single-child contract as **`Trigger`**; merges **`onClick`** to **`onClose`** when not **`defaultPrevented`**. Typical placement: a control inside **`footer`** (for example **Cancel** or **Save** when saving should dismiss the dialog).
 - **Order:** **`Modal.Root`** → **`Modal.Trigger`** (if any) and **`Modal.Panel`** as siblings (or only **`Modal.Panel`** in controlled flows).
 
 ### Minimal example
@@ -37,6 +37,77 @@ export function Example() {
 }
 ```
 
+### Canonical example (full shell)
+
+Use this when you want the complete header row (**`title`**, **`description`**, **`icon`**), a form field in the body, and a **`footer`** where at least one control is wrapped in **`Modal.Close`** (here: **Cancel**). The header still shows the built-in icon close button by default (`showClose`).
+
+```tsx
+import { Button, Icon, Input, Modal } from "prime-ui-kit";
+
+export function InviteTeammateModal() {
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root size="m" variant="neutral" mode="stroke">
+          Open workspace invite
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel
+        title="Invite teammate"
+        description="We will send one invitation email. The recipient can accept or decline."
+        icon={<Icon name="field.email" tone="subtle" />}
+        footer={
+          <>
+            <Modal.Close>
+              <Button.Root size="m" variant="neutral" mode="stroke">
+                Cancel
+              </Button.Root>
+            </Modal.Close>
+            <Button.Root size="m" variant="primary" type="button">
+              Send invite
+            </Button.Root>
+          </>
+        }
+      >
+        <Input.Root label="Email address" size="m" hint="Work email preferred">
+          <Input.Wrapper>
+            <Input.Field autoComplete="email" placeholder="name@company.com" type="email" />
+          </Input.Wrapper>
+        </Input.Root>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}
+```
+
+Source of truth (stays in sync with the snippet above): `examples/canonical-maximal.tsx`.
+
+### Examples (source)
+
+Runnable demos live next to this file (workspace imports use `@/`; published consumers use `prime-ui-kit`):
+
+| File | Intent |
+|------|--------|
+| `examples/canonical-maximal.tsx` | Full shell: title, description, icon, one field, footer with **`Modal.Close`** + primary |
+| `examples/scenario-confirm-delete.tsx` | Destructive confirmation; **`variant="error"`** on primary action |
+| `examples/scenario-edit-entity.tsx` | Rename / edit field; **Save** wrapped in **`Modal.Close`** to dismiss after save |
+| `examples/scenario-legal-consent.tsx` | Terms-style copy; **`closeOnOverlayClick={false}`**; single **I agree** closes via **`Modal.Close`** |
+| `examples/scenario-multi-field-form.tsx` | **`Input`**, **`Select`**, **`Textarea`** in the body; submit button uses **`form`** |
+
+Playground composition demos (Russian copy, broader variants): `playground/snippets/modal/composition.tsx`.
+
+### Extended usage
+
+- **Controlled dialogs:** omit **`Modal.Trigger`**; pass **`open`** and **`onOpenChange`** to **`Modal.Root`**. Keep **`Modal.Panel`** as a sibling; it portals only when **`open`** is true.
+- **Dismiss on primary action:** wrap the confirming button in **`Modal.Close`** when the action should close the dialog immediately (see **edit entity** example). If you must await an API call, keep the dialog open until success, then call **`onOpenChange(false)`** from the parent.
+- **Consent / wizard steps:** set **`closeOnOverlayClick={false}`** (and optionally **`closeOnEscape={false}`**) when accidental dismiss would lose legal or multi-step state; still provide an explicit **`Modal.Close`** (or header close) path where appropriate.
+- **Long body content:** constrain scroll to the body via **`bodyStyle`** / **`bodyClassName`** (see `playground/snippets/modal/features.tsx`); overlay scroll lock remains active.
+- **Headless dialog surface:** omit **`title`** on **`Modal.Panel`** and supply **`aria-label`** or **`aria-labelledby`** / **`aria-describedby`** yourself; inner body wrapper is not used, so **`bodyClassName`** / **`bodyStyle`** do not apply.
+
+### Note for LLMs
+
+When generating **Modal** markup for this library: (1) **`Modal.Trigger`** and **`Modal.Close`** each require **exactly one** child element—no fragments or multiple nodes. (2) Prefer **`Modal.Panel`** with **`title`** (and usually **`description`**) so **`aria-labelledby`** / **`aria-describedby`** are wired automatically. (3) Put **Cancel** / **Dismiss** in **`footer`** inside **`Modal.Close`** unless the design relies only on the header icon. (4) Do not wrap kit components to restyle them; use **`size`**, **`variant`**, **`mode`**, and documented props only. (5) For copy-paste starting points, mirror **`examples/canonical-maximal.tsx`** first, then adapt from the scenario files.
+
 ## Rules
 
 - **Shell tokens:** overlay padding, panel padding, gaps between header/body/footer, and max width use **`--prime-sys-size-modal-*`** (semantic `size.modal` in `tokens/semantic.ts`). Title/description text tiers may still follow control typography tokens where the chrome matches **`size`** `m`.

package/src/components/modal/examples/canonical-maximal.tsx

@@ -0,0 +1,43 @@
+import { Button } from "@/components/button/Button";
+import { Input } from "@/components/input/Input";
+import { Modal } from "@/components/modal/Modal";
+import { Icon } from "@/icons";
+
+/**
+ * Maximal shell: `title`, `description`, `icon`, body field, `footer` with `Modal.Close` plus primary action.
+ * Copy this structure when you need the full header/body/footer pattern.
+ */
+export default function ModalCanonicalMaximalExample() {
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root size="m" variant="neutral" mode="stroke">
+          Open workspace invite
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel
+        description="We will send one invitation email. The recipient can accept or decline."
+        footer={
+          <>
+            <Modal.Close>
+              <Button.Root size="m" variant="neutral" mode="stroke">
+                Cancel
+              </Button.Root>
+            </Modal.Close>
+            <Button.Root size="m" variant="primary" type="button">
+              Send invite
+            </Button.Root>
+          </>
+        }
+        icon={<Icon name="field.email" tone="subtle" />}
+        title="Invite teammate"
+      >
+        <Input.Root label="Email address" size="m" hint="Work email preferred">
+          <Input.Wrapper>
+            <Input.Field autoComplete="email" placeholder="name@company.com" type="email" />
+          </Input.Wrapper>
+        </Input.Root>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}

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

@@ -0,0 +1,13 @@
+.fieldStack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+  width: 100%;
+}
+
+.labeledControl {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+  width: 100%;
+}

package/src/components/modal/examples/scenario-confirm-delete.tsx

@@ -0,0 +1,38 @@
+import { Button } from "@/components/button/Button";
+import { Modal } from "@/components/modal/Modal";
+import { Typography } from "@/components/typography/Typography";
+import { Icon } from "@/icons";
+
+/** Blocking confirmation before destructive action; dismiss via header, overlay, Escape, or Cancel. */
+export default function ModalConfirmDeleteExample() {
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root size="m" variant="error" mode="stroke">
+          Delete project
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel
+        description="This removes the project, its boards, and history. Connected integrations will stop receiving events."
+        footer={
+          <>
+            <Modal.Close>
+              <Button.Root size="m" variant="neutral" mode="stroke">
+                Cancel
+              </Button.Root>
+            </Modal.Close>
+            <Button.Root size="m" variant="error" type="button">
+              Delete permanently
+            </Button.Root>
+          </>
+        }
+        icon={<Icon name="action.close" tone="subtle" />}
+        title="Delete “Northwind rollout”?"
+      >
+        <Typography.Root as="p" variant="body-default">
+          You can export an archive first from Project settings. This action cannot be undone.
+        </Typography.Root>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}

package/src/components/modal/examples/scenario-edit-entity.tsx

@@ -0,0 +1,50 @@
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { Input } from "@/components/input/Input";
+import { Modal } from "@/components/modal/Modal";
+import { Icon } from "@/icons";
+
+/** Short edit flow: pre-filled field, save keeps the dialog open only if you handle state (here: close on save click). */
+export default function ModalEditEntityExample() {
+  const [name, setName] = React.useState("Acme Corp");
+
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root size="m" variant="neutral" mode="stroke">
+          Rename account
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel
+        description="The new name appears on invoices and in the member directory."
+        footer={
+          <>
+            <Modal.Close>
+              <Button.Root size="m" variant="neutral" mode="stroke">
+                Cancel
+              </Button.Root>
+            </Modal.Close>
+            <Modal.Close>
+              <Button.Root size="m" variant="primary" type="button">
+                Save changes
+              </Button.Root>
+            </Modal.Close>
+          </>
+        }
+        icon={<Icon name="nav.layoutGrid" tone="subtle" />}
+        title="Edit account name"
+      >
+        <Input.Root label="Account name" size="m">
+          <Input.Wrapper>
+            <Input.Field
+              onChange={(e) => setName(e.target.value)}
+              value={name}
+              autoComplete="organization"
+            />
+          </Input.Wrapper>
+        </Input.Root>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}

package/src/components/modal/examples/scenario-legal-consent.tsx

@@ -0,0 +1,36 @@
+import { Button } from "@/components/button/Button";
+import { Modal } from "@/components/modal/Modal";
+import { Typography } from "@/components/typography/Typography";
+import { Icon } from "@/icons";
+
+/** Disclosure + explicit accept; primary action is wrapped in `Modal.Close` so accepting dismisses the dialog. */
+export default function ModalLegalConsentExample() {
+  return (
+    <Modal.Root closeOnOverlayClick={false}>
+      <Modal.Trigger>
+        <Button.Root size="m" variant="neutral" mode="stroke">
+          Review terms
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel
+        description="Please read the following before continuing to use the service."
+        footer={
+          <Modal.Close>
+            <Button.Root size="m" variant="primary" type="button">
+              I agree
+            </Button.Root>
+          </Modal.Close>
+        }
+        icon={<Icon name="status.locked" tone="subtle" />}
+        title="Terms and data processing"
+      >
+        <Typography.Root as="p" variant="body-default">
+          By continuing, you agree to our Terms of Service and acknowledge our Privacy Policy. We
+          process account data to provide the product, send essential notices, and improve
+          reliability. You may withdraw consent where applicable by contacting support or adjusting
+          settings.
+        </Typography.Root>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}

package/src/components/modal/examples/scenario-multi-field-form.tsx

@@ -0,0 +1,75 @@
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { Input } from "@/components/input/Input";
+import { Label } from "@/components/label/Label";
+import { Modal } from "@/components/modal/Modal";
+import { Select } from "@/components/select/Select";
+import { Textarea } from "@/components/textarea/Textarea";
+import { Icon } from "@/icons";
+
+import styles from "./examples.module.css";
+
+/** Several fields in the modal body; footer mirrors the canonical pattern (cancel + submit). */
+export default function ModalMultiFieldFormExample() {
+  const messageId = React.useId();
+
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root size="m" variant="neutral" mode="stroke">
+          New support ticket
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel
+        description="Include enough detail for our team to reproduce or route the issue."
+        footer={
+          <>
+            <Modal.Close>
+              <Button.Root size="m" variant="neutral" mode="stroke">
+                Cancel
+              </Button.Root>
+            </Modal.Close>
+            <Button.Root size="m" variant="primary" type="submit" form="modal-ticket-form">
+              Submit ticket
+            </Button.Root>
+          </>
+        }
+        icon={<Icon name="nav.itemDot" tone="subtle" />}
+        title="Contact support"
+      >
+        <form
+          className={styles.fieldStack}
+          id="modal-ticket-form"
+          onSubmit={(e) => e.preventDefault()}
+        >
+          <Input.Root label="Subject" size="m">
+            <Input.Wrapper>
+              <Input.Field name="subject" placeholder="Short summary" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Select.Root placeholder="Area" size="m">
+            <Select.Trigger>
+              <Select.Value />
+            </Select.Trigger>
+            <Select.Content>
+              <Select.Item value="billing">Billing</Select.Item>
+              <Select.Item value="product">Product bug</Select.Item>
+              <Select.Item value="account">Account access</Select.Item>
+            </Select.Content>
+          </Select.Root>
+          <div className={styles.labeledControl}>
+            <Label.Root htmlFor={messageId} size="m">
+              Message
+            </Label.Root>
+            <Textarea.Root
+              id={messageId}
+              placeholder="Steps, expected result, actual result"
+              size="m"
+            />
+          </div>
+        </form>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}

package/src/components/notification/COMPONENT.md

@@ -1,23 +1,42 @@
 # Notification
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default `size`:** use **`m`** for the notification card size unless the surface explicitly needs **`s`** or **`l`**.
 
-## About
+## Canonical
 
-Toast notifications: `NotificationProvider` keeps a queue, hooks expose `notify` / `dismiss` / `dismissAll`, and cards render in a portal with stacked groups per corner and semantic type.
+- **`NotificationProvider`** — wraps the tree that calls hooks; mounts a **portal** with fixed **zones** per viewport corner/edge. Each **`notify`** item is grouped by **`position`** and **`type`** into separate stacks (**`max`** per stack, default **`5`**).
+- **`useNotifications`** — **`notify`**, **`dismiss`**, **`dismissAll`** only; throws outside the provider.
+- **`useNotificationStore`** — same methods plus **`items`** (**`NotificationRecord[]`**, active only, no exit-animation rows).
+- **`NotificationCard`** — **`article`** with live region semantics, icon, title, optional badge/description/**`action`** (neutral stroke **`Button.Root`**), optional close, progress track unless **`persistent`**.
+- **Stacks** — Framer Motion list; hover expands stack and **pauses** countdowns until collapse. **`error`** / **`warning`** → **`role="alert"`**, **`aria-live="assertive"`**; **`success`** / **`info`** → **`status`**, **`polite`**.
 
-- **Use** for short, non-blocking feedback after actions (save, send, background job finished) when you do not need to trap focus.
-- **Use** when the message should appear above the page chrome and auto-dismiss or offer a single secondary action.
-- **Use** `useNotificationStore` when the UI must read `items` (e.g. custom lists or bulk dismiss).
-- **Use** `NotificationCard` alone only for static previews or fully custom wiring; live toasts go through the provider and `notify`.
-- **Do not use** for errors that require a blocking decision, long forms, or primary workflow inside the toast—prefer [Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md), or [Banner](../banner/COMPONENT.md).
-- **Do not use** multiple nested `NotificationProvider`s unless you intentionally want several portals and duplicate zones.
+## Extended
 
-## Composition
+### About
 
-- **`NotificationProvider`** — wraps the tree that calls hooks; provides context and mounts a **portal** with a fixed viewport. Each screen **position** gets a **zone**; inside a zone, notifications are split into **stacks by `type`** (`success`, `error`, `warning`, `info`).
-- **`NotificationStack` / `NotificationStackItem`** (internal) — ordered list with Framer Motion; hovering expands the stack and sets **`paused`** on cards so countdown timers stop until collapse.
-- **`NotificationCard`** — root is an `article` with a live region role, leading icon, title row (optional **badge**), optional description, optional **action** (`Button.Root`), optional close control, and a progress track unless **`persistent`**.
+Toast notifications for short, non-blocking feedback after actions (save, send, job finished) when focus must not be trapped.
+
+- **When to use** — confirmations or lightweight errors that do not need a blocking dialog.
+- **When to use** — one optional secondary **`action`** (e.g. undo, open detail) alongside auto-dismiss.
+- **When to use** — **`useNotificationStore`** when the UI must reflect **`items`** (counters, bulk dismiss, custom chrome).
+- **When not to use** — blocking decisions, long forms, or primary workflow inside the toast; prefer [Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md), or [Banner](../banner/COMPONENT.md).
+- **When not to use** — multiple nested **`NotificationProvider`**s unless you intentionally want several portals.
+
+### Composition
+
+- **`NotificationProvider`** → context + **`NotificationToaster`** (portal, zones, **`NotificationStack`** per **`position`** + **`type`**).
+- **`NotificationStack` / `NotificationStackItem`** (internal) — ordered list; peek/collapse behavior and **`paused`** passed to **`NotificationCard`**.
+- **`NotificationCard`** — public for static previews or fully custom wiring; live toasts should use **`notify`**.
+
+### Scenarios (see `examples/`)
+
+| Scenario | Approach |
+|----------|----------|
+| Toast queue / stack cap | Same **`position`** + **`type`** share one stack; **`max`** drops oldest; stagger **`notify`** with timeouts. Hover expands stack and pauses timers. → [`examples/toast-queue.tsx`](examples/toast-queue.tsx) |
+| Positions | Set **`NotificationProvider`** default **`position`** or pass **`position`** per **`notify`**. Six anchors: **`top-*`** / **`bottom-*`** × **`left` \| `center` \| `right`**. → [`examples/positions.tsx`](examples/positions.tsx) |
+| Action button | **`action: { label, onClick }`** — rendered as kit **`Button.Root`** (neutral stroke). → [`examples/action-toast.tsx`](examples/action-toast.tsx) |
+| Error / success semantics | **`type: "error"`** / **`"warning"`** vs **`"success"`** / **`"info"`** — icons, grouping, and live-region assertiveness differ. → [`examples/error-success.tsx`](examples/error-success.tsx) |
+| Reading the store | **`useNotificationStore`** — **`items`**, **`notify`**, **`dismiss`**, **`dismissAll`** for UI tied to queue length. → [`examples/notification-store.tsx`](examples/notification-store.tsx) |
 
 ### Minimal example
 
@@ -42,11 +61,11 @@ function Notifier() {
 }
 ```
 
-## Rules
+### Rules
 
 - Call **`useNotifications`** or **`useNotificationStore`** only under **`NotificationProvider`**; both hooks throw if context is missing.
 - **`notify`** returns a string **`id`**; pass it to **`dismiss`** or use **`dismissAll`** for every active toast.
-- **`useNotificationStore`** exposes the same methods plus **`items`**: `NotificationRecord[]` of non-dismissing entries only (no internal closing-animation flag).
+- **`useNotificationStore`** exposes the same methods plus **`items`**: **`NotificationRecord[]`** of non-dismissing entries only (no internal closing-animation flag).
 - Options passed to **`notify`** are merged with defaults: **`size`** `"m"`, **`position`** from the provider, **`duration`** `5000` ms, **`persistent`** `false`, **`closable`** `true`.
 - With **`persistent`**, there is no auto-dismiss, no progress bar, and duration does not drive closing; users or **`dismiss`** / **`dismissAll`** must close the card. Visually, **`persistent`** also turns on the accent-tinted **border** and (unless **`prefers-reduced-motion`**) the **`notification-glow`** shadow pulse — default **`notify()`** uses **`persistent: false`**, so live toasts look flatter unless you opt in.
 - If **`duration <= 0`**, the countdown effect does not run—time-based auto-dismiss does not occur; close via **`dismiss`** or the close button when **`closable`**.
@@ -118,3 +137,14 @@ Same **`notify`**, **`dismiss`**, and **`dismissAll`** as above, plus **`items`*
 - [Button](../button/COMPONENT.md)
 - [Drawer](../drawer/COMPONENT.md)
 - [Modal](../modal/COMPONENT.md)
+
+## LLM note
+
+- Imports: **`NotificationProvider`**, **`useNotifications`**, **`useNotificationStore`**, **`NotificationCard`**, types **`NotificationOptions`**, **`NotificationRecord`**, **`NotificationPosition`**, **`NotificationType`**, **`NotificationSize`**, **`NotificationAction`** from **`"prime-ui-kit"`**.
+- **`notify`** requires **`type`** and **`title`**; optional **`description`**, **`size`**, **`position`**, **`duration`**, **`persistent`**, **`icon`**, **`badge`**, **`closable`**, **`action`**.
+- **`action`** is not a React node — it is **`{ label: string; onClick: () => void }`**; the kit renders **`Button.Root`** (neutral stroke) inside the card.
+- Stack key = **`position` + `type`**; **`max`** applies per stack, not globally.
+- **`persistent: true`** removes the progress bar and auto-dismiss; closing is manual or via **`dismiss`** / **`dismissAll`**.
+- **`duration <= 0`** disables timer-based dismissal (still closable if **`closable`**).
+- Do not nest **`NotificationProvider`** without a reason; one app root is typical.
+- For static **`NotificationCard`**, build a full **`NotificationRecord`** (including **`id`**, **`position`**, **`size`**, **`duration`**, **`persistent`**, **`closable`**, **`createdAt`**) and wire **`onDismiss`** yourself.

package/src/components/notification/examples/action-toast.tsx

@@ -0,0 +1,84 @@
+import {
+  Button,
+  LinkButton,
+  NotificationProvider,
+  Typography,
+  useNotifications,
+} from "prime-ui-kit";
+
+/**
+ * action uses kit Button.Root inside the card; page triggers may use Button or LinkButton.
+ */
+function ActionToastDemo() {
+  const { notify } = useNotifications();
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <Typography.Root variant="body-small" tone="muted">
+        Secondary action in the toast is always neutral stroke Button.Root from the kit.
+      </Typography.Root>
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-s)",
+          alignItems: "center",
+        }}
+      >
+        <Button.Root
+          type="button"
+          variant="primary"
+          mode="filled"
+          size="m"
+          onClick={() =>
+            notify({
+              type: "info",
+              title: "Export ready",
+              description: "Your CSV is prepared.",
+              action: {
+                label: "Download",
+                onClick: () =>
+                  notify({
+                    type: "success",
+                    title: "Started",
+                    description: "In a real app, the file would download.",
+                  }),
+              },
+            })
+          }
+        >
+          Toast with action
+        </Button.Root>
+        <LinkButton.Root
+          href="#"
+          size="m"
+          onClick={(event) => {
+            event.preventDefault();
+            notify({
+              type: "info",
+              title: "From LinkButton",
+              description: "Any control can call notify under the provider.",
+            });
+          }}
+        >
+          Fire via LinkButton
+        </LinkButton.Root>
+      </div>
+    </div>
+  );
+}
+
+export default function ActionToastExample() {
+  return (
+    <NotificationProvider>
+      <ActionToastDemo />
+    </NotificationProvider>
+  );
+}