prime-ui-kit 0.0.1

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

@@ -0,0 +1,47 @@
+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 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.Footer
+            primary={
+              <Button.Root variant="primary" type="button">
+                Send invite
+              </Button.Root>
+            }
+            secondary={
+              <Modal.Close>
+                <Button.Root variant="neutral" mode="stroke">
+                  Cancel
+                </Button.Root>
+              </Modal.Close>
+            }
+          />
+        }
+        icon={<Icon name="field.email" tone="subtle" />}
+        title="Invite teammate"
+      >
+        <Input.Root label="Email address" 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/pattern-close-behavior.tsx

@@ -0,0 +1,56 @@
+import { Button } from "@/components/button/Button";
+import { Modal } from "@/components/modal/Modal";
+import { Icon } from "@/icons";
+
+/** Default dismiss vs `closeOnEscape` / `closeOnOverlayClick` disabled; mirrors `playground/snippets/modal/states.tsx`. */
+export default function ModalPatternCloseBehaviorExample() {
+  return (
+    <>
+      <Modal.Root>
+        <Modal.Trigger>
+          <Button.Root variant="neutral" mode="stroke">
+            Standard dismiss
+          </Button.Root>
+        </Modal.Trigger>
+        <Modal.Panel
+          closeAriaLabel="Close"
+          description="Escape and a direct backdrop click close the dialog (click target must be the overlay)."
+          icon={<Icon name="field.email" />}
+          title="Default behavior"
+        >
+          <p>Try Escape and clicking the dimmed area outside the panel.</p>
+        </Modal.Panel>
+      </Modal.Root>
+
+      <Modal.Root closeOnEscape={false} closeOnOverlayClick={false}>
+        <Modal.Trigger>
+          <Button.Root variant="error" mode="lighter">
+            <Button.Icon>
+              <Icon name="status.locked" />
+            </Button.Icon>
+            Explicit actions only
+          </Button.Root>
+        </Modal.Trigger>
+        <Modal.Panel
+          description="With both flags false, only buttons dismiss the dialog."
+          footer={
+            <Modal.Footer
+              primary={
+                <Modal.Close>
+                  <Button.Root variant="neutral" mode="stroke">
+                    OK
+                  </Button.Root>
+                </Modal.Close>
+              }
+            />
+          }
+          icon={<Icon name="status.locked" />}
+          showClose={false}
+          title="Strict mode"
+        >
+          <p>Escape and backdrop clicks do nothing.</p>
+        </Modal.Panel>
+      </Modal.Root>
+    </>
+  );
+}

package/src/components/modal/examples/pattern-controlled.tsx

@@ -0,0 +1,41 @@
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { Modal } from "@/components/modal/Modal";
+import { Icon } from "@/icons";
+
+/** Controlled `open` / `onOpenChange` without `Modal.Trigger`; mirrors `playground/snippets/modal/controlled.tsx`. */
+export default function ModalPatternControlledExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", flexWrap: "wrap", gap: "var(--prime-sys-spacing-x2)" }}>
+      <Button.Root variant="primary" onClick={() => setOpen(true)}>
+        Open from outside
+      </Button.Root>
+      <Button.Root mode="stroke" variant="neutral" onClick={() => setOpen(false)}>
+        Close from outside
+      </Button.Root>
+
+      <Modal.Root open={open} onOpenChange={setOpen}>
+        <Modal.Panel
+          closeAriaLabel="Close"
+          description="Open and close are driven by `open` and `onOpenChange` on the root."
+          footer={
+            <Modal.Footer
+              primary={
+                <Modal.Close>
+                  <Button.Root variant="primary">Done</Button.Root>
+                </Modal.Close>
+              }
+            />
+          }
+          icon={<Icon name="action.copy" />}
+          title="Externally controlled"
+        >
+          <p>No in-tree trigger is required: the parent owns visibility.</p>
+        </Modal.Panel>
+      </Modal.Root>
+    </div>
+  );
+}

package/src/components/modal/examples/pattern-full-width-footer.tsx

@@ -0,0 +1,46 @@
+import { Button } from "@/components/button/Button";
+import { Modal } from "@/components/modal/Modal";
+import { Typography } from "@/components/typography/Typography";
+import { Icon } from "@/icons";
+
+/** Full-width footer actions via `Button.Root` `fullWidth`; mirrors `playground/snippets/modal/full-width.tsx`. */
+export default function ModalPatternFullWidthFooterExample() {
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root variant="neutral" mode="stroke">
+          Checkout
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel
+        description="Stack full-width buttons so the footer column matches the panel width on narrow layouts."
+        footer={
+          <div
+            style={{
+              display: "grid",
+              gap: "var(--prime-sys-spacing-x2)",
+              width: "100%",
+            }}
+          >
+            <Modal.Close>
+              <Button.Root variant="primary" fullWidth>
+                Pay now
+              </Button.Root>
+            </Modal.Close>
+            <Modal.Close>
+              <Button.Root variant="neutral" mode="stroke" fullWidth>
+                Back to cart
+              </Button.Root>
+            </Modal.Close>
+          </div>
+        }
+        icon={<Icon name="action.upload" />}
+        title="Confirm order"
+      >
+        <Typography.Root as="p" variant="body-default">
+          Review your cart before continuing to payment.
+        </Typography.Root>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}

package/src/components/modal/examples/pattern-portal-and-scroll.tsx

@@ -0,0 +1,84 @@
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { Modal } from "@/components/modal/Modal";
+import { Icon } from "@/icons";
+
+/** Custom `container` portal target and scrollable body via `bodyStyle`; mirrors `playground/snippets/modal/features.tsx`. */
+export default function ModalPatternPortalAndScrollExample() {
+  const [portalHost, setPortalHost] = React.useState<HTMLDivElement | null>(null);
+
+  const longLines = [
+    "Line 1: scrollable body inside the dialog while the page stays locked.",
+    "Line 2: scrollable body inside the dialog while the page stays locked.",
+    "Line 3: scrollable body inside the dialog while the page stays locked.",
+    "Line 4: scrollable body inside the dialog while the page stays locked.",
+    "Line 5: scrollable body inside the dialog while the page stays locked.",
+    "Line 6: scrollable body inside the dialog while the page stays locked.",
+    "Line 7: scrollable body inside the dialog while the page stays locked.",
+    "Line 8: scrollable body inside the dialog while the page stays locked.",
+  ];
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "var(--prime-sys-spacing-x3)" }}>
+      <div
+        ref={setPortalHost}
+        style={{
+          padding: "var(--prime-sys-spacing-x3)",
+          border: "1px dashed var(--prime-sys-color-border-default)",
+          borderRadius: "var(--prime-sys-shape-radius-s)",
+        }}
+      >
+        <p>
+          <code>Modal.Panel</code> <code>container</code> mounts the portal inside this box (useful
+          for tests or custom stacking).
+        </p>
+        {portalHost ? (
+          <Modal.Root>
+            <Modal.Trigger>
+              <Button.Root variant="neutral" mode="stroke">
+                Portal into host
+              </Button.Root>
+            </Modal.Trigger>
+            <Modal.Panel
+              closeAriaLabel="Close"
+              container={portalHost}
+              icon={<Icon name="nav.layoutGrid" />}
+              title="Custom container"
+            >
+              <p>Portal content is attached under the host element above.</p>
+            </Modal.Panel>
+          </Modal.Root>
+        ) : null}
+      </div>
+
+      <Modal.Root>
+        <Modal.Trigger>
+          <Button.Root variant="neutral" mode="stroke">
+            Long body (scroll)
+          </Button.Root>
+        </Modal.Trigger>
+        <Modal.Panel
+          bodyStyle={{ maxHeight: "10rem", overflowY: "auto" }}
+          closeAriaLabel="Close"
+          description="Cap the body height with `bodyStyle` (or `bodyClassName`) so only the panel scrolls."
+          footer={
+            <Modal.Footer
+              primary={
+                <Modal.Close>
+                  <Button.Root variant="primary">Close</Button.Root>
+                </Modal.Close>
+              }
+            />
+          }
+          icon={<Icon name="nav.itemDot" />}
+          title="Scroll inside panel"
+        >
+          {longLines.map((line) => (
+            <p key={line}>{line}</p>
+          ))}
+        </Modal.Panel>
+      </Modal.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,42 @@
+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 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.Footer
+            primary={
+              <Button.Root variant="error" type="button">
+                Delete permanently
+              </Button.Root>
+            }
+            secondary={
+              <Modal.Close>
+                <Button.Root variant="neutral" mode="stroke">
+                  Cancel
+                </Button.Root>
+              </Modal.Close>
+            }
+          />
+        }
+        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,54 @@
+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 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.Footer
+            primary={
+              <Modal.Close>
+                <Button.Root variant="primary" type="button">
+                  Save changes
+                </Button.Root>
+              </Modal.Close>
+            }
+            secondary={
+              <Modal.Close>
+                <Button.Root variant="neutral" mode="stroke">
+                  Cancel
+                </Button.Root>
+              </Modal.Close>
+            }
+          />
+        }
+        icon={<Icon name="nav.layoutGrid" tone="subtle" />}
+        title="Edit account name"
+      >
+        <Input.Root label="Account name">
+          <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,40 @@
+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 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.Footer
+            primary={
+              <Modal.Close>
+                <Button.Root 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,73 @@
+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 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.Footer
+            primary={
+              <Button.Root variant="primary" type="submit" form="modal-ticket-form">
+                Submit ticket
+              </Button.Root>
+            }
+            secondary={
+              <Modal.Close>
+                <Button.Root variant="neutral" mode="stroke">
+                  Cancel
+                </Button.Root>
+              </Modal.Close>
+            }
+          />
+        }
+        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">
+            <Input.Wrapper>
+              <Input.Field name="subject" placeholder="Short summary" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Select.Root placeholder="Area">
+            <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}>Message</Label.Root>
+            <Textarea.Root id={messageId} placeholder="Steps, expected result, actual result" />
+          </div>
+        </form>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}

package/src/components/notification/COMPONENT.md

@@ -0,0 +1,156 @@
+# Notification
+
+**Default `size`:** use **`m`** for the notification card size unless the surface explicitly needs **`s`** or **`l`**.
+
+## Canonical
+
+- **`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`**.
+
+## Extended
+
+### About
+
+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 (playground + `examples/`)
+
+Live demos in the playground use **`playground/snippets/notification/*.tsx`** (see **`playground/sections/NotificationSection.tsx`**). The table below lists the same scenarios with package-oriented copies under **`examples/`** (aligned 1:1 with those snippets).
+
+| Scenario | Approach |
+|----------|----------|
+| Sizes | Static **`NotificationCard`** row for **`s`** / **`m`** / **`l`** with **`persistent`** and **`closable: false`** so only scale differs. → [`examples/sizes.tsx`](examples/sizes.tsx) |
+| Variants (`type`) | Four **`type`** values on static cards; **`persistent: true`** shows accent border and glow pulse (default live **`notify()`** is **`persistent: false`**). → [`examples/variants.tsx`](examples/variants.tsx) |
+| States | Static **`persistent`** vs **`closable: false`**, plus buttons for timed toast, hover-pause stack, and **`notify`** with **`persistent`**. → [`examples/states.tsx`](examples/states.tsx) |
+| Positions | Six **`NotificationPosition`** values; **`position`** in **`notify`** options. → [`examples/positions.tsx`](examples/positions.tsx) |
+| Controlled store | **`useNotificationStore()`** — **`items`**, **`notify`**, **`dismiss(id)`** per row. → [`examples/controlled.tsx`](examples/controlled.tsx) |
+| Composition | **`icon`**, **`badge`**, **`description`**, **`action`**; static card plus live **`notify`** (e.g. lucide **`Bell`**). → [`examples/composition.tsx`](examples/composition.tsx) |
+| Stack / timing | Burst stack (**`max`** per stack), hover expand + pause, **`dismissAll`**, short vs long **`duration`**. → [`examples/features.tsx`](examples/features.tsx) |
+
+**Additional examples:** interactive **`type`** buttons → [`examples/error-success.tsx`](examples/error-success.tsx); **`action`** + **`LinkButton`** trigger → [`examples/action-toast.tsx`](examples/action-toast.tsx). Deprecated aliases: [`examples/toast-queue.tsx`](examples/toast-queue.tsx) → **`features`**, [`examples/notification-store.tsx`](examples/notification-store.tsx) → **`controlled`**.
+
+### Minimal example
+
+```tsx
+import { NotificationProvider, useNotifications } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <NotificationProvider>
+      <Notifier />
+    </NotificationProvider>
+  );
+}
+
+function Notifier() {
+  const { notify } = useNotifications();
+  return (
+    <button type="button" onClick={() => notify({ type: "info", title: "Hello" })}>
+      Notify
+    </button>
+  );
+}
+```
+
+### 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).
+- 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`**.
+- Stacks are keyed by **`position`** and **`type`**; **`max`** (default `5`) caps depth per stack—older items in that stack are dropped when exceeded.
+- **`type`** `error` and **`warning`** use **`role="alert"`** and **`aria-live="assertive"`**; other types use **`role="status"`** and **`aria-live="polite"`**.
+- Close control uses **`aria-label="Dismiss notification"`**; default type icons are **`aria-hidden`** inside the icon wrapper.
+- Each stack list has **`aria-label`** `Notifications at <position>`.
+- Nested **`NotificationProvider`** instances each render their own portal and zones—usually one root provider is enough.
+- **`NotificationCard`** is not connected to the store by itself; supply **`item`**, **`paused`**, and **`onDismiss`** and keep **`item`** fields consistent with **`NotificationRecord`**.
+
+## API
+
+### NotificationProvider
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Subtree where notification hooks are used |
+| position | `NotificationPosition` | `"top-right"` | No | Default **`position`** for **`notify`** when omitted in options |
+| max | `number` | `5` | No | Maximum items per stack (same **`position`** + **`type`**) |
+
+### NotificationOptions (`notify` payload)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"success" \| "error" \| "warning" \| "info"` | — | Yes | Semantics, default icon, and stack grouping |
+| title | `string` | — | Yes | Primary heading |
+| description | `string` | — | No | Secondary text |
+| size | `"s" \| "m" \| "l"` | `"m"` | No | Card scale |
+| position | `NotificationPosition` | provider default | No | Corner or edge anchor |
+| duration | `number` | `5000` | No | Auto-dismiss delay in ms (ignored for closing when **`persistent`**; see Rules when `<= 0`) |
+| persistent | `boolean` | `false` | No | Disable timer and progress UI |
+| icon | `React.ReactNode` | type default | No | Custom leading icon |
+| badge | `string \| number` | — | No | Label next to the title |
+| closable | `boolean` | `true` | No | Show dismiss button |
+| action | `{ label: string; onClick: () => void }` | — | No | Secondary action rendered as neutral stroke **`Button.Root`** |
+
+`notify` returns the new record’s **`id`** (`string`).
+
+### NotificationRecord
+
+All **`NotificationOptions`** fields plus required **`id`**, **`position`**, **`size`**, **`duration`**, **`persistent`**, **`closable`**, and **`createdAt`** (`number`, ms). Defaults are filled when the record is created inside **`notify`**.
+
+### NotificationCard
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| item | `NotificationRecord` | — | Yes | Card data |
+| paused | `boolean` | — | Yes | Pause countdown (e.g. expanded stack) |
+| onDismiss | `(id: string) => void` | — | Yes | Called to remove the toast (timer or UI) |
+| stackDepth | `number` | `0` | No | Stack index for layout / `data-*` |
+| stackExpanded | `boolean` | `false` | No | Whether the parent stack is expanded |
+| className | `string` | — | No | Extra class on the root `article` |
+
+### useNotifications()
+
+| Field | Type | Description |
+|------|------|-------------|
+| notify | `(options: NotificationOptions) => string` | Enqueue a notification |
+| dismiss | `(id: string) => void` | Dismiss one by id |
+| dismissAll | `() => void` | Dismiss all active |
+
+### useNotificationStore()
+
+Same **`notify`**, **`dismiss`**, and **`dismissAll`** as above, plus **`items`**: `NotificationRecord[]` (active only, excluding items in the exit-animation phase).
+
+## Related
+
+- [Banner](../banner/COMPONENT.md)
+- [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.