# Alert

Persistent section-level feedback banner for success, warning, info, and error states.

[All components](https://rickylabs.github.io/netscript/design-system/components/) · [Theme builder](https://rickylabs.github.io/netscript/create/) · [Implementation source](https://github.com/rickylabs/netscript/blob/main/packages/fresh-ui/registry/components/ui/alert.tsx)

## Live preview

[Open live alert preview](https://rickylabs.github.io/netscript/assets/fresh-ui/preview/?component=alert&theme=studio-utility)

## Install

```bash
netscript ui:add alert
```

## Usage and examples

The preview runs this JSX with the installed components. Import any composed primitives from your UI directory.

```tsx
import { useState } from 'preact/hooks';
import { Alert } from '@app/components/ui/alert.tsx';

export function Example() {
  const [value, setValue] = useState('standard');
  const [open, setOpen] = useState(false);
  const [notice, report] = useState('');
  return (<><div><Alert variant="warning" title="Awaiting payment">Three orders need your attention.</Alert></div><p role="status">{notice}</p></>);
}
```

## Props

Generated from native `deno doc --json --private` over the shipped implementation. Compound component props retain their owning interface; native attributes pass through where declared.

| Owner | Prop | Type | Optional | Description |
| --- | --- | --- | --- | --- |
| `AlertProps` | `children` | `Renderable` | Yes |  |
| `AlertProps` | `class` | `string` | Yes |  |
| `AlertProps` | `icon` | `Renderable` | Yes | False hides the decorative glyph; custom content replaces the default. |
| `AlertProps` | `title` | `Renderable` | Yes | Omitted uses the localized tone label; false/null keeps it visually hidden. |
| `AlertProps` | `toneLabel` | `string` | Yes | Localized default tone name, including the visually hidden fallback. |
| `AlertProps` | `description` | `Renderable` | Yes | Explicit description takes precedence over legacy children. |
| `AlertProps` | `action` | `Renderable` | Yes |  |
| `AlertProps` | `variant` | `AlertVariant` | Yes |  |
| `AlertProps` | `emphasis` | `AlertEmphasis` | Yes |  |
| `AlertProps` | `close` | `boolean` | Yes |  |
| `AlertProps` | `closeLabel` | `string` | Yes |  |
| `AlertProps` | `open` | `boolean` | Yes |  |
| `AlertProps` | `defaultOpen` | `boolean` | Yes |  |
| `AlertProps` | `onOpenChange` | `(open: boolean) => void` | Yes | A dismissal request; a controlled owner may refuse by leaving open unchanged. |

```typescript
type AlertVariant = "neutral" | "info" | "success" | "warning" | "destructive" | "important"
type AlertEmphasis = "subtle" | "strong"
```

## Keyboard

| Key | Action |
| --- | --- |
| `Tab/Shift+Tab` | Traverse supplied action controls and optional close button in native order; hidden banners are skipped. |
| `Enter/Space` | Activate the close button; request open=false without moving focus on mount. |

## Tokens

Semantic contract roles: `border/default`, `border/width`, `destructive/border`, `destructive/subtle`, `destructive/text`, `important/border`, `important/subtle`, `important/text`, `info/border`, `info/subtle`, `info/text`, `marker/default`, `radius/card`, `size/icon/md`, `space/card/padding`, `space/control/gap`, `space/control/padding-x`, `space/stack/gap`, `success/border`, `success/subtle`, `success/text`, `surface/surface`, `text/fg`, `text/muted`, `warning/border`, `warning/subtle`, `warning/text`.

CSS custom properties referenced directly: `--ns-alert-border`, `--ns-alert-fill`, `--ns-alert-rule`, `--ns-alert-text`, `--ns-border`, `--ns-border-width`, `--ns-card-padding`, `--ns-control-gap`, `--ns-destructive`, `--ns-destructive-border`, `--ns-destructive-subtle`, `--ns-destructive-text`, `--ns-fg`, `--ns-font-sans`, `--ns-hover`, `--ns-important-border`, `--ns-important-subtle`, `--ns-important-text`, `--ns-info-border`, `--ns-info-subtle`, `--ns-info-text`, `--ns-leading-body`, `--ns-leading-strong`, `--ns-marker`, `--ns-radius-card`, `--ns-radius-control`, `--ns-ring`, `--ns-space-4`, `--ns-space-6`, `--ns-success`, `--ns-success-border`, `--ns-success-subtle`, `--ns-success-text`, `--ns-surface`, `--ns-text-body`, `--ns-tracking-body`, `--ns-tracking-strong`, `--ns-warning`, `--ns-warning-border`, `--ns-warning-subtle`, `--ns-warning-text`, `--ns-weight-body`, `--ns-weight-label`.

## Contract and compatibility

Accessibility pattern: [WAI-ARIA guidance](https://www.w3.org/WAI/ARIA/apg/patterns/alert/)

- Native DOM attributes pass through where the implementation accepts them.
- Original four tone names and default info live-region role remain compatible; warning/destructive default to alert, other tones to status.
- Closed banners remain mounted with native hidden and explicit display:none; visibility is independent of caller hidden. No automatic focus management.
- Strong emphasis is a CSS leading rule. Optional named content slots accept Renderable values; 0 remains valid content.
- Every banner has a visible tone or custom title by default; title=false/null opts into visually hidden tone text. Title uses body size and Medium label weight.

Design contract values marked planned are not implementation props. The props above describe what ships today.