Zetta v1.6

Components · Data display & feedback

Alert

Inline semantic message for communicating system state within a page context. Split from zetta-feedback-v1_4.md (removed in v1.5) in v1.4.

Preview

Heads up
A new version of the design system is available.
Saved
Your changes have been published.
Review needed
Two fields are missing required values.

Build with the skill

No package to install — hand this to your AI to generate or migrate the component in your stack.

Prompt for your AI 
Apply the Zetta "Alert" component to this project using the zetta-design-md skill.

WHEN TO USE
- Migrating or fixing existing code (the common case): audit the current implementation against the `alert` spec and CORRECT every deviation — replace off-spec values, don't only add new ones.
- New component: build it to the `alert` spec in this project's stack.

AUDIT & FIX (when the component already exists)
Compare it to the skill's spec and fix, don't just append: hardcoded colors/hex, off-scale radius, wrong fonts, dark/navy fills, shadows used in place of borders (or missing borders), brand lime used as a CTA or interaction (must be primary indigo), and any missing or wrong hover / focus / active / disabled / invalid state or missing 2px focus ring. Replace each with the correct Zetta token.

ALWAYS
- Pull the authoritative spec and tokens from the skill — never guess or hardcode values.
- Use this project's own component conventions and framework idioms.
- Honor the Zetta guardrails (brand = identity only, primary = interaction, shadows for overlays) and verify in Light, Dark, and Accessibility.

Anatomy & rules

┌──────────────────────────────────────────────────────┐
│  [icon]  Title text                         [✕ close] │
│          Body description text                        │
│          [Action link or button]                      │
└──────────────────────────────────────────────────────┘
  ↑ semantic fill + border
State Visual
Default Semantic fill, icon, title, optional body and action
Dismissed Not rendered (removed from DOM)
With action Action button/link applies its own states
With dismiss Dismiss button applies button-icon states

When to use

  • System status messages that persist while the user works: "Your session expires in 5 minutes."
  • Form-level errors or warnings after submission.
  • Informational messages about a page state: "Read-only mode — contact admin to edit."

When not to use

  • Ephemeral feedback after an action — use Toast.
  • Critical blocking errors — use Modal.
  • Field-level validation — use Field error state.

Do

  • Use the semantic variant that matches the message type.
  • Keep title under 10 words. Keep body under 2 sentences.
  • Pair icon with text — never rely on color alone.

Don't

  • Don't stack more than 2 alerts on a single page.
  • Don't use alert for loading states — use Skeleton or Spinner.
  • Title: short noun phrase or brief statement. "Session expiring soon." "Access restricted."
  • Body: one or two sentences max. State the consequence and, if relevant, the action.
  • Action label: verb phrase. "Renew session", "Request access", "Learn more".
  • Dismiss button aria-label: "Dismiss [appearance] alert".

Keyboard

Key Behavior
Tab Move focus to action or dismiss button
Enter / Space Activate focused button

Accessibility

  • role="alert" for danger and warning variants — announced immediately by screen readers.
  • role="status" for success and info variants — polite announcement.
  • role="region" with aria-label for neutral persistent alerts.
  • Icon: aria-hidden="true" — text label carries the semantic meaning.
  • Dismiss button: aria-label="Dismiss alert".

Spec

Values and token references resolved straight from the Zetta spec.

alert
textColor
{colors.ink}
borderWidth
1px
borderRadius
{rounded.base}
iconSize
20px
padding
{spacing.md}
gap
12px
titleFontSize
14px
titleFontWeight
500
bodyFontSize
13px
bodyFontWeight
400
alert-neutral
backgroundColor
{colors.surface-secondary}
borderColor
{colors.hairline}
iconColor
{colors.muted}
alert-success
backgroundColor
{colors.success-bg}
borderColor
{colors.success}
iconColor
{colors.success-text}
alert-warning
backgroundColor
{colors.warning-bg}
borderColor
{colors.warning}
iconColor
{colors.warning-text}
alert-danger
backgroundColor
{colors.danger-bg}
borderColor
{colors.danger}
iconColor
{colors.danger-text}
alert-info
backgroundColor
{colors.info-bg}
borderColor
{colors.info}
iconColor
{colors.info-text}