Callout

Overview

.callout is a tinted remark about the thing it sits beside — one field, one form, one panel. It is shape only: a flex row with a tinted background, which the caller tints by setting the --_tint custom property. There are no variant classes, because the tint is what carries the meaning.

A callout is not a page-level status surface. A message about the whole page belongs in <ui-statusbar> or toast(), both driven from the notifications store. A strip prepended above a page's content displaces that content as it appears, and it bypasses the store's rules about which message is current. Put the remark next to what it is about, or route it through the store.

Controls are optional. A callout may carry the buttons that address the thing it describes, and it may carry none at all — an icon and one sentence is a complete callout.

Callout or card?

They look alike and answer different questions, so the choice is worth stating. <article> — Card represents a thing: one document, one job, one member. It has a title, a meta line, optional actions and often a stretched link to the thing itself. A callout represents nothing; it is a remark about something else on the page, and on its own it does not make sense.

The difference that decides it is colour. A card is deliberately neutral, because its content varies and the surface must not editorialise. A callout is tinted, and the tint is part of the message. That is also why a callout is not a card variant: it keeps almost none of the card's declarations, and the two share their tokens rather than their rules.

If you would give it a heading, it is a card. If it only makes sense next to something else, it is a callout.

Anatomy

Any block element with class="callout". Use <aside> when the remark is genuinely tangential to the surrounding content and <div> when it is part of the flow of the panel it sits in.

• The row — display: flex with align-items: center and a --size-2 gap, so a leading <ui-icon> needs no spacing markup of its own.
• The box — --size-2 --size-3 padding, --radius-2 corners and --font-size-0 text. Smaller and tighter than a card, because a remark should not outweigh what it is about.
• The tint — background is --_tint mixed at 12% with transparent. Unset, --_tint falls back to --text-2, which gives a neutral grey box.
• .callout-actions — an inline-flex cluster for the controls, when there are any.
• A text block between the two — when a bordered callout holds an icon, a block of text and an action cluster, give the block flex: 1 and min-width: 0. space-between otherwise spreads the three apart and leaves a gap after the icon, and without min-width: 0 long words cannot wrap inside a flex child.

The primitive styles the box and not its contents. A <p> inside a callout keeps the browser's default margins, so a caller that wraps its text in one sets margin: 0 itself. This is deliberate: a callout with several lines often wants margins of its own, and a blanket reset here would only be overridden.

Usage

The smallest callout is the class and one sentence.

Tint

The caller sets --_tint to any colour. There is no closed set of names to choose from, which is why Modifiers lists the callout as having no variants. Use the page's semantic aliases rather than raw palette values, and set the property inline for a one-off or in a class when several callouts share a meaning.

--success, --error and --info come from the application's own token layer; ui.css names them with literal fallbacks so the library still renders in a page that defines none of them.

.bordered and the action cluster

.bordered adds an outline mixed from the same tint and switches the row to justify-content: space-between, which pushes a trailing .callout-actions to the far edge. Use it when the callout carries controls, so the controls have a side of their own; without it they sit immediately after the text.

The cluster takes as many controls as the case needs. That is the difference from a statusbar item, which supports at most one action: a remark that needs two answers — do the work, or record that it is handled — belongs here rather than there.

Long text and the icon

align-items: center centres a leading icon against the whole box, which is what a one-line callout wants. When the text wraps to several lines, the icon reads better on the first line: set align-items: start on your own class, and nudge the icon down by about 0.15em so it sits on the text's baseline rather than the top of its line box.

Accessibility

• A callout is not a live region. It describes something already on the screen, so it is read in document order like any other content. A message that appears in response to what the user just did, and that they must not miss, belongs in toast() or <ui-statusbar>, which own role="alert" and role="status". Adding role="alert" here would announce the remark every time the surrounding view re-renders.
• Do not rely on the tint. The colour is a reinforcement, never the message. Every callout says in words what it is about, and a leading icon is decorative (aria-hidden="true") unless it carries information the text omits — see Accessibility § Color.
• Place it where it belongs in the reading order — immediately before or after the element it describes, so that a screen-reader user meets the remark and the thing at the same point. A callout far from its subject is a page-level message, and those go through the notifications store.
• Use <aside> only for genuinely tangential content. It carries role="complementary", which makes it a landmark; several of them on a page each need a distinct aria-label. For a remark that is part of the flow, a <div> adds no landmark and is the better element.
• The controls are ordinary buttons. Give each one a label that names what it does to the thing the callout is about, and do not rely on position to say which subject they apply to.

Cross-system

See Cross-system reference § Feedback. Other systems draw the same box under the name Alert — Bootstrap's .alert and shadcn's Alert are the closest equivalents, and Material Design 2's Banner was the same pattern before Material 3 dropped it. Radix has no inline alert of its own; its Alert Dialog is an interruption, which is <ui-dialog alertdialog> here. The name alert is avoided in this library because it reads as the ARIA role, and a callout is not a live region.

See also

• <article> — Card — for a thing rather than a remark about one.
• <ui-statusbar> and Notifications store — for a message about the page.
• toast() — for a transient announcement.
• Status messages — inline success and error feedback on a form, and which surface a form error belongs on.
• Modifiers — why the tint is a --_ property and not a set of variant classes.