components / alert

Alert

Inline system message with tone-aware surfaces, optional actions, and dismiss handling for in-flow messaging.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Alert handles inline feedback that should stay in the document flow instead of floating like a toast or blocking like a dialog.
  • Use it when the product needs clear, structured messaging with optional follow-up action.

Aliases

inline alert, notice

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Alert when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Alert contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Alert label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Alert behind decorative copy or overloaded surface treatments.
  • Do not stretch Alert into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Alert for persistent inline status, warnings, and success messages near the affected content.
  • Use the actions slot when the user can fix or continue from the message directly.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use Alert for transient feedback that can safely disappear; use Toast instead.
  • Do not use Alert when the user must stop and decide before continuing; use Dialog instead.

Anti-patterns

  • Using Alert as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy alert usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

message shell

root

Carries tone, border, and background treatment.

supporting icon slot

icon

Optional semantic cue before the copy.

message heading

title

Short summary of the status or issue.

supporting copy

description

Clarifies impact or next steps.

follow-up actions

actions

Optional action area for repair or progression.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
tone'brand' | 'success' | 'warning' | 'danger''brand'Chooses the semantic message tone.
titlestring—Primary alert heading.
descriptionstring—Supporting alert copy.
dismissiblebooleanfalseShows a dismiss affordance when true.
onDismiss(detail: { id?: string }) => void—Callback fired when the dismiss affordance is activated.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Events

NamePayloadDescription
dismiss{ id?: string }Fires when the user dismisses the component or one of its items.

Slots

NameDescription
iconOptional icon or symbol reinforcing the tone.
actionsOptional inline follow-up actions.
defaultOptional custom body content when the title/description pair is not enough.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • brand: Informational or product-state messaging.
  • success: Positive confirmation with lower urgency.
  • warning: Needs attention but does not necessarily block progress.
  • danger: High-risk or blocking issue state.

Sizes

  • default: Alert uses one structural size and relies on content length and tone.

States

  • dismissed: Optional removed state after the user dismisses the alert.

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Stays in the normal document flow so the message remains associated with nearby content.

Keyboard

  • Dismiss buttons and action buttons remain keyboard reachable as ordinary controls.

Screen readers

  • Visible title and description communicate the message; use surrounding context to decide if the alert should also receive live-region treatment.

Caveats

  • This component is for inline messaging, not assertive global live announcements.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-alert-bg
#d7e9ff
--dk-alert-fg
#000f4d
--dk-alert-border
#2072e4
--dk-alert-border-width
1px
--dk-alert-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-alert-padding
clamp(1.778rem, 1.6296rem + 0.658vw, 2.222rem)
--dk-alert-gap
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

icon

--dk-alert-icon-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

title

--dk-alert-title-color
inherit
--dk-alert-title-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-alert-title-weight
700

description

--dk-alert-description-color
inherit
--dk-alert-description-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

actions

--dk-alert-actions-gap
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

dismiss

--dk-alert-dismiss-size
44px

Implementation notes

  • Alert is a flow-preserving message surface; stronger interruption belongs to overlays.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: inline notice

A neutral inline alert with one clear message.

Copy snippet

<Alert tone="brand" title="Review required" description="This workspace needs one more sign-off." />

Common patterns

1 example

common

Common: inline repair action

Add actions when the user can resolve the issue immediately.

Copy snippet

<Alert tone="warning" title="Missing details" description="Add the ship date before publishing."><svelte:fragment slot="actions"><Button size="sm">Add date</Button></svelte:fragment></Alert>

Edge cases

1 example

edge

Edge: dismissible status

Use dismiss only when hiding the message is safe.

Copy snippet

<Alert tone="success" title="Changes saved" dismissible={true} />
  • If the message matters later, also leave a durable trace elsewhere in the UI.

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

neutral

pass

tone=neutral

  • Contrast: 90.8 Lc, 90.8 Lc
  • Target: 44px
  • Layout: 0 / 280, 360
  • Helper: 3/2

brand

pass

tone=brand

  • Contrast: 89.9 Lc, 89.9 Lc
  • Target: 44px
  • Layout: 0 / 280, 360
  • Helper: 3/2

success

pass

tone=success

  • Contrast: 39.9 Lc, 39.9 Lc
  • Target: 44px
  • Layout: 0 / 280, 360
  • Helper: 3/2

warning

pass

tone=warning

  • Contrast: 59.8 Lc, 59.8 Lc
  • Target: 44px
  • Layout: 0 / 280, 360
  • Helper: 3/2

danger

pass

tone=danger

  • Contrast: 80.5 Lc, 80.5 Lc
  • Target: 44px
  • Layout: 0 / 280, 360
  • Helper: 3/2