Section message

A section message tells the user something about one part of the page. It sits in the content and stays until it's resolved or dismissed.

Stable

Figma

Overview

Usage

API

Accessibility

Heads up Two-factor authentication will be required for all admins next month.

<tk-section-message>
  <span slot="title">Heads up</span>
  Two-factor authentication will be required for all admins next month.
</tk-section-message>

Anatomy

Part	What it is
`tk-section-message`	the element; a tinted block with rounded corners (`message` part)
`icon` slot and part	the leading intent icon; decorative
`title` slot and part	an optional title; a heading or a `<span>`
default slot (`body` part)	the message: one or two short sentences, required
`actions` slot and part	optional actions under the message
dismiss button	the ✕, only with `dismissible`

Variants

New members get access in about an hour.

Drafts are saved for 30 days.

Your calendar is connected.

Vacation mode is on. You won't get alerts.

We couldn't save your changes. Try again.

<tk-section-message>New members get access in about an hour.</tk-section-message>
<tk-section-message tone="neutral">Drafts are saved for 30 days.</tk-section-message>
<tk-section-message tone="success">Your calendar is connected.</tk-section-message>
<tk-section-message tone="warning">Vacation mode is on. You won't get alerts.</tk-section-message>
<tk-section-message tone="error">We couldn't save your changes. Try again.</tk-section-message>

info (default): information or advice.
neutral: a quiet note of low importance.
success: an action completed.
warning: a caution before or during an action.
error: an action failed or something needs fixing.

Each tone has its own icon shape, a triangle for warning and circles for the rest. Say the intent in the text too; color alone doesn't tell everyone. In high contrast the block also gets a 1px border.

Icon

Prices include VAT.

Saved to your reading list.

<tk-section-message hide-icon>Prices include VAT.</tk-section-message>
<tk-section-message tone="success">
  <tk-icon slot="icon" name="bookmark"></tk-icon>
  Saved to your reading list.
</tk-section-message>

hide-icon removes the icon.
A tk-icon in slot="icon" replaces it. It's hidden from screen readers like the default one.

Actions

Turn on notifications You won't get alerts until notifications are enabled for this browser. Enable

Not now

<tk-section-message tone="warning">
  <span slot="title">Turn on notifications</span>
  You won't get alerts until notifications are enabled for this browser.
  <tk-button slot="actions" size="small">Enable</tk-button>
  <tk-link slot="actions" treatment="quiet" href="/settings">Not now</tk-link>
</tk-section-message>

Put a secondary or ghost tk-button or a quiet tk-link in slot="actions". Don't use outline; its border disappears on the neutral tint.
Use at most one main and one secondary action. If you need more, use a dialog or a page.

Dismiss

Upload failed The file is larger than 25 MB.

<tk-section-message tone="error" dismissible>
  <span slot="title">Upload failed</span>
  The file is larger than 25 MB.
</tk-section-message>

dismissible adds a ✕ named by dismiss-label. Clicking it fires a cancelable tk-dismiss event, and the message hides itself unless you call preventDefault().

Don't make a message dismissible if the user must resolve it. A notice about a failed action can be dismissible.
The ✕ disappears with the message, so move focus somewhere sensible after it closes.

When to use

Use a section message for a note tied to part of the page: a caution in a settings section, a confirmation after connecting a service, an error summary above a form.
Use the error text of a Field for a problem with one field. A form-level summary of several errors is a section message; each field still shows its own.
Use a Banner for a message about the whole app.
Use a Toast for a short confirmation that goes away on its own.
Use a Dialog when the user must act before going on. A section message never blocks and never takes focus.

Content

Title: three or four words that name the event, such as "Upload failed". The body doesn't repeat it.
Body: one or two sentences: what happened and what to do next.
Action: a specific verb, such as "Update card". Never "OK".

Do / Don't

✅ Do	❌ Don't
Place it in the content, next to what it's about	Use it as an app-wide strip or a floating toast
Set `live` when you add the message after an action	Announce a message that was there on load
Keep actions quiet, one main action at most	Stack several buttons; use a dialog or a page
Use a dialog when the user must act first	Make a must-act message dismissible
Use a real heading for the title	Style plain text to look like a heading

Banner: a message about the whole app.
Toast: a short message that disappears on its own.
Dialog: a message that blocks until the user acts.
Badge: a small status label with the same tones.
Button and Link: what goes in actions.

API

Attributes

Attribute	Type	Default	What it does
`tone`	`info` \| `neutral` \| `success` \| `warning` \| `error`	`info`	intent: tint and icon
`live`	`off` \| `polite` \| `assertive`	`off`	announce a message added after load
`dismissible`	boolean	`false`	shows the ✕
`dismiss-label`	string	`"Dismiss"`	accessible name of the ✕
`hide-icon`	boolean	`false`	removes the intent icon

Slots

Slot	Content
default	the message, required
`title`	a heading (`<h2>`–`<h6>`) or a `<span>`
`icon`	replaces the intent icon; hidden from screen readers
`actions`	links and buttons under the message

Events

Event	What it means
`tk-dismiss`	the ✕ was clicked; cancelable, and the message hides unless you prevent it

CSS

Parts: message, icon, title, body, actions.

Tokens

Tone	Fill	Text	Icon	Border (high contrast)
`neutral`	`surface/sunken`	`text/secondary`	`icon/secondary`	`border/default`
`info` · `success` · `warning` · `error`	`surface/{tone}`	`text/{tone}`	`icon/{tone}`	`border/{tone}`

Corners are radius-16, padding space-16. Values per theme: Color.

Accessibility

Built in:

It's not announced by default; a message present on load is read in page order.
live="polite" gives it role="status"; live="assertive" gives it role="alert".
It never takes focus. The ✕ has an accessible name, and the intent icon is hidden.
Text is at least 4.5:1 and the icon at least 3:1 in every tone and theme.

Your part:

Pick live by how the message appears: off on page load, polite for info, success, or neutral added after an action, assertive for warning or error added after an action.
Use a real heading in title, at the right level for the page.
Say the intent in words.

Anatomy

Variants

Icon

Actions

Dismiss

When to use

Content

Do / Don't

Related

API

Attributes

Slots

Events

CSS

Tokens

Accessibility