Alert
Persistent feedback beside the content it concerns.
Installation
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
import { Alert } from '@commenda/pathfinder/alert';
<Alert
tone="info"
title="Review your filing"
description="Review the filing details before submitting."
/>;API reference
| Prop | Type | Behavior |
|---|---|---|
titleConditional | string | At least one required |
descriptionConditional | string | At least one required |
tone | FeedbackTone | neutral |
actionConfig | FeedbackAction | Secondary button |
secondaryActionConfig | FeedbackAction | Optional link |
dismissConfig | DismissConfigView fields | Omit for a persistent callout |
openConditional | boolean | Controlled / uncontrolled; true initially |
defaultOpen | boolean | Controlled / uncontrolled; true initially |
onOpenChangeConditional | (open: boolean) => void | Required with open; requests closure |
announcement | FeedbackAnnouncement | auto maps tone to live-region priority |
className | string | Additional classes for the component root. |
dismissConfigObject fields
| Field | Type | Requirement |
|---|---|---|
label | string | Optional |
onDismiss | (() => void) | Optional |
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
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
Tones
Actions
Dismissible
Read the design guidance before using these components.
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-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.