# Alert

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/alert
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=299-2

```tsx
import { Alert } from '@commenda/pathfinder/alert';
<Alert
  tone="info"
  title="Review your filing"
  description="Review the filing details before submitting."
/>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { Alert } from '@commenda/pathfinder/alert';
<Alert
  tone="info"
  title="Review your filing"
  description="Review the filing details before submitting."
/>;
```

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `title` | `string` | conditional | At least one required |
| `description` | `string` | conditional | At least one required |
| `tone` | `FeedbackTone` | optional | neutral |
| `actionConfig` | `FeedbackAction` | optional | Secondary button |
| `secondaryActionConfig` | `FeedbackAction` | optional | Optional link |
| `dismissConfig` | `DismissConfig` | optional | Omit for a persistent callout |
| `open` | `boolean` | conditional | Controlled / uncontrolled; true initially |
| `defaultOpen` | `boolean` | optional | Controlled / uncontrolled; true initially |
| `onOpenChange` | `((open: boolean) => void)` | conditional | Required with open; requests closure |
| `announcement` | `FeedbackAnnouncement` | optional | auto maps tone to live-region priority |
| `className` | `string` | optional | Additional classes for the component root. |

### dismissConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |
| `onDismiss` | `(() => void)` | No |  |

Never auto-dismiss. Title says what happened; description says what to do. Keep copy concise without truncating essential instructions. Field errors remain on fields; an alert may summarize them. onOpenChange requests closure immediately; onDismiss runs after the 200 ms collapse only when the owner allows closure. The application owns focus restoration after removing a focused alert.

### Actions [#actions]

`FeedbackAction` requires a label and exactly one of `onClick` (command) or `href` (native navigation). Commands support `disabled`, `disabledReason`, `loadingConfig`, and `leadingIcon`; navigation supports `target`, `rel`, and `leadingIcon`. The application owns async work and retry state.

## Examples [#examples]

### Tones [#tones]


```tsx
<>
  {(['neutral', 'info', 'success', 'warning', 'error'] as const).map((tone) => (
    <Alert
      key={tone}
      tone={tone}
      title="Review your filing"
      description="Review the filing details before submitting."
    />
  ))}
</>;
```


### Actions [#actions-1]


```tsx
<Alert
  tone="info"
  title="Review your filing"
  description="Review the filing details before submitting."
  actionConfig={{ label: 'Review filing', onClick: onReviewFiling }}
  secondaryActionConfig={{ label: 'Learn more', href: '#usage' }}
/>;
```


### Dismissible [#dismissible]


```tsx
<Alert
  tone="info"
  title="Review your filing"
  description="Review the filing details before submitting."
  dismissConfig={{}}
/>;
```


Read the [design guidance](/docs/components/alert#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Alert and Banner — 299:2 [#alert-and-banner--2992]

- **ALERT-01:** Persistent, contextual feedback beside the form, table or figure it concerns. Never auto-dismiss. No dismissConfig produces a callout that stays until the owner removes it. Field errors remain on fields; form alerts summarize them.
- **ALERT-02:** Title states what happened without a period; description states the next step. Aim for two lines, but never clip essential text. At most a secondary small Button for recovery plus a link for more information. Passing confirmations use Toast.
- **ALERT-03:** Neutral is a state, info is news, success is completion, warning is an approaching issue, error is a current problem. Auto announcement maps warnings/errors to alert and info/success to status; neutral stays nonurgent. The explicit announcement prop can override this for the actual event.
- **ALERT-04:** Tinted background and 0.5 px border, radius 8, padding 12 vertical/16 start/12 end, gap 10; icon 16, Label/13 Strong title, Copy/13 body, gap 2. Close uses plain IconButton xs on tinted surfaces.
- **BANNER-01:** Whole-account or product context only; place beneath the breadcrumb across the content card. One at a time, one concise message, one link. The application owns placement and prioritization. Wrap on narrow screens rather than truncate.
- **BANNER-02:** Announcement is the sixth banner tone from node 917:314: blue 100/background, blue 300 bottom border, centered blue 900 copy, no icon or title, optional secondary small Button.
- **FEEDBACK-DISMISS-01:** Dismissal fades and collapses space over 200 ms, ease-out. onOpenChange requests closure immediately; onDismiss follows the collapse after an accepted close. A controlled owner can reject the request. The owner restores focus if needed.
- **FEEDBACK-ACTION-01:** Commands use Button; navigation uses native anchors. Require a label and exactly one of onClick or href. Components choose action appearance; callers own loading, disabled reasons and async behavior.