Prepared Docs

Callout from @prepared911/ui-core is a variant-driven inline message block. The component renders icons, titles, descriptions, and optional actions or dismiss affordances; it also owns the default semantic role for each variant.

What the component handles

Variant visuals. Each CalloutType (Note, Info, Success, Warning, Error) has a matching color, icon, and tone.
Semantic role. Note and Info use role="note", Success and Warning use role="status", and Error uses role="alert".
Accessible name. The root receives a localized variant label unless ariaLabel overrides it.
Decorative icon. The variant icon is aria-hidden; the variant meaning is carried by the title and description.
Dismiss button. When dismissible, the close button is a native <button> with an accessible label.
CTA affordance. ctaButton renders as a Button with proper keyboard and focus semantics.

What you must provide

A role override only when needed. Use the role prop when the default variant role does not match how the message appears or should be announced.
A specific accessible name when needed. Use ariaLabel when the localized variant label is not enough context.
Scannable copy. Title in a short declarative phrase, description as one or two sentences. Save long explanations for linked docs.
Non-color severity cue. The variant icon plus the title wording must make severity clear for color-blind or grayscale users.
Action verbs, not buttons. CTA labels read as actions ("Retry sync", "Review changes")—not "Click here" or "Continue".

Keyboard behavior

Tab / Shift+Tab reach the CTA and dismiss button in visual order.
Enter / Space activate the focused button.
Escape: not handled by the callout; if a dismiss shortcut is desired, attach it to the container that owns the callout.

Semantics and roles

Do not add an external live-region wrapper by default; the Callout root already owns its role.
Use role="note" for supporting context, role="status" for polite updates, and role="alert" for urgent failures.
The dismiss button has the localized accessible name "Dismiss."
Icon inside the callout renders with aria-hidden="true".

Focus management

Callout does not move focus when it appears. Keep focus on the initiating control for status updates. For validation failures, move focus to the first invalid field or to the form-owned error summary rather than wrapping Callout in another live region.

Known caveats

Callouts vs Snackbars. Callouts stay put; Snackbar auto-dismiss. Use a callout for persistent guidance, a snackbar for transient confirmation.
Over-use. Three callouts stacked on a page dilute signal. Keep one primary callout per region and escalate remaining messages into a modal or a dedicated status view.

Callout / API and Development

Card / Usage

What the component handles

What you must provide

What the component handles

Variant visuals. Each CalloutType (Note, Info, Success, Warning, Error) has a matching color, icon, and tone.
Semantic role. Note and Info use role="note", Success and Warning use role="status", and Error uses role="alert".
Accessible name. The root receives a localized variant label unless ariaLabel overrides it.
Decorative icon. The variant icon is aria-hidden; the variant meaning is carried by the title and description.
Dismiss button. When dismissible, the close button is a native <button> with an accessible label.
CTA affordance. ctaButton renders as a Button with proper keyboard and focus semantics.

What you must provide

A role override only when needed. Use the role prop when the default variant role does not match how the message appears or should be announced.
A specific accessible name when needed. Use ariaLabel when the localized variant label is not enough context.
Scannable copy. Title in a short declarative phrase, description as one or two sentences. Save long explanations for linked docs.
Non-color severity cue. The variant icon plus the title wording must make severity clear for color-blind or grayscale users.
Action verbs, not buttons. CTA labels read as actions ("Retry sync", "Review changes")—not "Click here" or "Continue".

Keyboard behavior

Tab / Shift+Tab reach the CTA and dismiss button in visual order.
Enter / Space activate the focused button.
Escape: not handled by the callout; if a dismiss shortcut is desired, attach it to the container that owns the callout.

Semantics and roles

Do not add an external live-region wrapper by default; the Callout root already owns its role.
Use role="note" for supporting context, role="status" for polite updates, and role="alert" for urgent failures.
The dismiss button has the localized accessible name "Dismiss."
Icon inside the callout renders with aria-hidden="true".

Focus management

Known caveats

Callouts vs Snackbars. Callouts stay put; Snackbar auto-dismiss. Use a callout for persistent guidance, a snackbar for transient confirmation.
Over-use. Three callouts stacked on a page dilute signal. Keep one primary callout per region and escalate remaining messages into a modal or a dedicated status view.

Callout / API and Development

Card / Usage

What the component handles

What you must provide