<!-- Protocore Design System — Notification -->
# Notification

- **Category:** Feedback (`feedback`)
- **Slug:** `feedback/notification`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { Notification } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/feedback/notification

> A standalone tone-ruled notification card with an optional icon, loading state, action, and close button.

## When to use it

**Notification** is a *persistent* notification card you place in the layout — a feed item, an inbox row, an in-panel status card. It is the durable sibling of the [Toast](/feedback/toast), which slides in, auto-dismisses, and disappears. If the message should stack in a corner and time out, use a Toast; if it lives in the page until the user deals with it, use a Notification.

It differs from a [Banner](/feedback/banner) (full-width, page- or section-level) by being a self-contained card you can render in a list, and from a [Callout](/feedback/callout) (a note in the reading flow) by being a status object with an icon, action, and dismiss.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `action` | `ReactNode` | no | — | Trailing action slot (e.g. a Button). |
| `children` | `ReactNode` | no | — | Body copy (also accepted via `children`). |
| `className` | `string` | no | — | — |
| `closeLabel` | `string` | no | `Close` | Accessible label for the close button. |
| `icon` | `ReactNode` | no | — | Leading icon. Ignored while `loading`. |
| `loading` | `boolean` | no | `false` | Show a spinner in the icon slot (e.g. an in-flight action). |
| `onClose` | `(() => void)` | no | — | Called when the close button is activated; its presence also shows the button. |
| `style` | `CSSProperties` | no | — | — |
| `title` | `ReactNode` | no | — | Mono UPPERCASE headline line. |
| `tone` | `enum` | no | `neutral` | Status tone; drives the tint left rule and icon color. |
| `withCloseButton` | `boolean` | no | `false` | Show a × close button. |

## Examples

### Basics

A `tone`, a mono UPPERCASE `title`, and sans body copy as children. The tone paints a 2px left rule and tints the leading icon.

```tsx
import { Notification } from "@protocore/pds";

export default function Basics() {
  return (
    <Notification tone="info" title="Deploy queued">
      Build #482 is waiting for an available runner.
    </Notification>
  );
}
```

### Tones and icons

Each status tone sets the left rule. Add a leading `icon` to reinforce it — `danger` and `warning` are announced assertively, so the icon backs up an already-urgent message.

```tsx
import { Notification, VStack } from "@protocore/pds";
import { CheckCircle2, AlertTriangle } from "lucide-react";

export default function Tones() {
  return (
    <VStack gap={3}>
      <Notification tone="success" icon={<CheckCircle2 size={16} />} title="Upgrade complete">
        All validators are running protocol v2.4.
      </Notification>
      <Notification tone="danger" icon={<AlertTriangle size={16} />} title="Consensus stalled">
        No block has finalised in the last 3 epochs.
      </Notification>
    </VStack>
  );
}
```

## Do & don't

**Do**

- Use it for durable, in-layout notifications the user resolves or dismisses.
- Give it a single, clear `action` when there's something to do.
- Use `loading` for an in-flight task, then swap to a tone on completion.
- Reserve `danger`/`warning` for urgent items; they announce assertively.

**Don't**

- For fleeting action confirmations, use a Toast.
- For a full-width page notice, use a Banner.
- Lead with one primary action, not several.
- Reserve urgent tones for urgent items, not routine information.

## Accessibility

**Keyboard**

| Keys | Action |
| --- | --- |
| `Tab` | Reaches the action control, then the close (×) button, when present. |
| `Enter / Space` | Activates the focused action or close button. |

**Notes**

- The root is `role="status"` (polite) for `neutral`/`info`/`success`, and `role="alert"` (assertive) for `warning`/`danger`, matching the urgency of the tone.
- The title (mono UPPERCASE) and body (sans) carry the message; the tone rule and icon are reinforcement, never the sole signal.
- The leading `icon` and the loading spinner are decorative and `aria-hidden`.
- The dismiss control is the shared [CloseButton](/utilities/close-button) with an accessible label (`closeLabel`, default "Close").

## Related

`toast`, `banner`, `callout`, `inline-message`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/