Alert

A message that stays on the page with the content it is about.

In Content first

See it live

Start Storybook to see it live: npm run storybook

Live from StorybookOpen Alert in StorybookSee it in dark

When to use it

In Content first: A note or warning inside an article.

• Use it when: People need to read a standing notice or how to recover, on this page, tied to what they are doing.
• Not when: A short confirmation that can go away by itself, or one notice for the whole site.

Instead:

• Toast: Short, non-blocking, goes away.
• Dialog: Needs an answer before going on.
• Site banner: One full-width notice for the whole site.

Variants

What each variant is for in any design system, then what Content first decided and why. Each sample is the live story with that variant set.

defaultvariantUsed in Content first

Start Storybook to see it live

What it is for

A notice that stays on the page: information or a heads-up.

✓A note people should read but need not fix.

✕Something failed and must be fixed.

In Content first

A note or a warning inside an article.

Because

What is the main content?Long-form text · content.q1

destructivevariantUsed in Content first

Start Storybook to see it live

What it is for

Something failed or will be lost, and people must act to recover.

✓An error, with what went wrong and how to fix it.

✕A plain note dressed as danger for emphasis.

In Content first

A failed save or sign-up: calm, take the blame, offer the way forward.

Because

How many signals carry each meaning?Two: color and word · accessibility.countHow many tones does it use?One per moment · voice.count

How Content first uses it

An error message

Use color.status.danger and a plain sentence

Not Color alone

The sentence says what to fix; color only draws the eye.

Why it works this way

Alert looks the way it does because of 3 answers about this product. Each card is one answer, in three steps: the answer, what it decided for Alert, and what would move if it changed.

What is the main content?content.q1

1The answer

Long-form text

The content is long-form text.

2So Alert

• ✓uses default: A note or a warning inside an article.

3If it changed

2

Alert decisions would reopen

and 38 answers that follow from it: One idea at a time, Read start to end, Rarely, and 35 more.

How many signals carry each meaning?accessibility.count

1The answer

Two: color and word

Status is rare; color and a word are enough.

2So Alert

• ✓uses destructive: A failed save or sign-up: calm, take the blame, offer the way forward.

It also shapes Badge: neutral Badge: info Badge: success Badge: warning Badge: danger

3If it changed

1

Alert decision would reopen

No other answer follows from it.

How many tones does it use?voice.count

1The answer

One per moment

Warm by default, calmer for errors.

2So Alert

• ✓uses destructive: A failed save or sign-up: calm, take the blame, offer the way forward.

It also shapes Toast: danger Badge: danger

3If it changed

1

Alert decision would reopen

No other answer follows from it.

Words

• Write to one person: "you", not "users".
• Short sentences with room to breathe.
• Explain why before asking for anything.
• Use: Read, Save for later, You, Next issue. Avoid: Click here, Submit, Users, Content.

The labels components use, from the voice tokens:

• content.action.commit: Save
• content.action.cancel: Not now
• content.action.destroy: Remove
• content.action.retry: Try again
• content.action.empty-action: Browse guides

See Voice and tone for the whole voice.

Accessibility and keyboard

Test before you ship:

• An error that appears after an action is announced (role alert); a standing note is not. undefined
• The tone also shows as an icon and words, never color alone. undefined

Use it in code

npx open-ds add alert

The component reads only component keys and semantic tokens, so it follows the brand and mode on <html>.

Tokens it reads

Alert reads 15 tokens of its own, each an alias of a semantic token. Each row is one part: its own token, the semantic it aliases, and the value it ends at. Change a semantic and every component that reads it follows; override one of Alert's tokens to change Alert alone.

Changes with theme

Content first decides what changes when you switch theme. Here a switch changes colors only, so the marked rows differ between light and dark; everything else holds steady.

Part	Its token and the semantic it aliases	Value
Alert
Gap y	component.alert.gap-ycomponent-spacing-map.hairlinevar(--alert-gap-y)	space.2:0.125rem
Corner	component.alert.radiusradius.containervar(--alert-radius)	radius.12:0.75rem
Padding, left and right	component.alert.padding-xspace.inset.containervar(--alert-padding-x)	space.24:1.5rem
Padding, top and bottom	component.alert.padding-ycomponent-spacing-map.x3var(--alert-padding-y)	space.20:1.25rem
Text size	component.alert.font-sizetype.body.font-sizevar(--alert-font-size)	font.size.18:1.125rem
Gap x	component.alert.gap-xcomponent-spacing-map.x3var(--alert-gap-x)	space.20:1.25rem
Icon size	component.alert.icon-sizesize.iconvar(--alert-icon-size)	size.16:1rem
Default
Fill Changes with theme	component.alert.default.backgroundcolor.surface.defaultvar(--alert-default-background)	Lightstone.light.0:#FFFFFFDarkstone.dark.50:#1F1B16
Text Changes with theme	component.alert.default.labelcolor.text.primaryvar(--alert-default-label)	Lightstone.light.900:#1F1B16Darkstone.dark.900:#FFFDF8
Destructive
Fill Changes with theme	component.alert.destructive.backgroundcolor.surface.defaultvar(--alert-destructive-background)	Lightstone.light.0:#FFFFFFDarkstone.dark.50:#1F1B16
Text Changes with theme	component.alert.destructive.labelcolor.status.dangervar(--alert-destructive-label)	Lightred.light.600:#C42B2BDarkred.dark.600:#F28B8B
Title
Weight	component.alert.title.font-weighttype.label.font-weightvar(--alert-title-font-weight)	font.weight.600:600
Description
Gap	component.alert.description.gapspace.gap.tightvar(--alert-description-gap)	space.8:0.5rem
Text size	component.alert.description.font-sizetype.body.font-sizevar(--alert-description-font-size)	font.size.18:1.125rem
Text Changes with theme	component.alert.description.labelcolor.text.mutedvar(--alert-description-label)	Lightstone.light.600:#61594DDarkstone.dark.400:#A39A8B
From the system
Edge Changes with theme	color.border.default straight from the system, through --border	Lightstone.light.200 · #E4DDD0Darkstone.dark.100 · #2E2A24