Alerts | CAAT Design System — Component Contract

Live Demo

Info Alert

Rendered

System Maintenance Scheduled

Our member portal will undergo scheduled maintenance on Saturday, May 16 from 2:00 AM – 6:00 AM ET. Contribution submissions will be temporarily unavailable.

Success Alert

Rendered

Enrollment Confirmed

Your enrollment in the CAAT DBplus pension plan has been successfully processed. You will receive a confirmation package within 5 business days.

Warning Alert

Rendered

Contribution Deadline Approaching

Your employer's Q2 contribution remittance is due by June 30, 2026. Late submissions may result in interest charges as outlined in the participation agreement.

Error / Danger Alert

Rendered

Form Validation Errors

Please correct the following before submitting your beneficiary designation:

Date of birth is required for each beneficiary
Allocation percentages must total 100%

Dismissible Alert

Rendered

New Feature Available

You can now view your projected retirement income directly from your member dashboard.

States

The alert variants are static (no interaction states). The only interactive element is the dismiss button on dismissible alerts, which implements default, hover, and focus. The static is-* classes mirror the live pseudo-class states.

Dismiss button

Default

Close button at rest.

Hover

Close button hovered.

Focus

Close button focused.

Code sample

HTML

<!-- Info alert -->
<div class="caat-alert caat-alert--info" role="alert" aria-live="polite">
  <i class="bi bi-info-circle-fill caat-alert__icon" aria-hidden="true"></i>
  <div class="caat-alert__body">
    <strong>Heading</strong>
    <p>Message body text.</p>
  </div>
</div>

<!-- Dismissible danger alert -->
<div class="caat-alert caat-alert--danger" role="alert" aria-live="assertive">
  <i class="bi bi-x-octagon-fill caat-alert__icon" aria-hidden="true"></i>
  <div class="caat-alert__body">
    <strong>Error Heading</strong>
    <p>Error description.</p>
  </div>
  <button type="button" class="caat-alert__close" aria-label="Dismiss alert">
    <i class="bi bi-x-lg" aria-hidden="true"></i>
  </button>
</div>

1. Summary

Component name	caat/components/alert
Purpose	Communicate time-sensitive or contextually important messages to CAAT Pension Plan members and employers — including system announcements, action confirmations, deadline warnings, and form validation errors.
Status	New
Variants	Info, Success, Warning, Danger (Error)
Options	Dismissible toggle, optional icon override, optional heading
AEM resource type	`caat/components/alert`
AEM category	CAAT Components – Feedback

2. Design Tokens

Alerts consume the semantic --caat-color-feedback-* tokens (each aliases an alert primitive in tokens.css); the icon inherits the variant's text colour.

Token	Role
`--caat-color-feedback-info-bg` / `-border` / `-text`	Info variant surface, border, and text/icon
`--caat-color-feedback-success-bg` / `-border` / `-text`	Success variant surface, border, and text/icon
`--caat-color-feedback-warning-bg` / `-border` / `-text`	Warning variant surface, border, and text/icon
`--caat-color-feedback-danger-bg` / `-border` / `-text`	Danger variant surface, border, and text/icon
`--caat-color-text-link`	Links within the alert body
`--caat-radius`	Alert container corner radius
`--caat-font-primary`	Font family

3. Authoring Fields

Field	Type	Required	Notes
Alert Type	Dropdown (info \| success \| warning \| danger)	Yes	Determines colour scheme, default icon, and `aria-live` value.
Heading	Text field	Yes	Rendered as `<strong>` within the alert body. Max 80 characters.
Body	Rich text (limited)	Yes	Supports paragraphs, lists, inline links. No images or embeds.
Dismissible	Toggle (boolean)	No	Default: off. Adds close button and wires JS dismiss behaviour.
Icon Override	Icon picker	No	Replaces the default icon for the selected alert type.

4. Validation Rules

Alert Type is mandatory; component will not render without it.
Heading max length: 80 characters. Exceeding triggers an author-facing warning.
Body is required; component must not render an empty alert container.
Body rich text: only <p>, <ul>, <ol>, <li>, <a>, <strong>, <em> elements permitted.
If Dismissible is true, the component must render the close button and include the dismiss JS.

5. Content Guidance

Guideline	Detail
Tone	Clear, concise, supportive. Avoid jargon. Pension-plan members range widely in financial literacy.
Heading	Use action-oriented language. State what happened or what's needed — e.g., "Contribution Deadline Approaching" rather than "Alert".
Body length	1–3 sentences ideal. Use a list for multiple error items.
Use Info for	System announcements, scheduled maintenance, new features.
Use Success for	Completed actions — enrollment confirmed, form submitted, payment received.
Use Warning for	Upcoming deadlines, expiring sessions, incomplete profiles.
Use Danger for	Validation errors, failed transactions, critical account issues.
Don't	Stack more than 2 alerts on a page. Avoid danger alerts for non-critical issues.

6. Semantic HTML

HTL / Markup contract

<!-- Non-destructive alert (info, success, warning) -->
<div class="caat-alert caat-alert--{type}"
     role="alert"
     aria-live="polite"
     data-caat-alert>
  <i class="bi bi-{icon} caat-alert__icon" aria-hidden="true"></i>
  <div class="caat-alert__body">
    <strong>{heading}</strong>
    {bodyRichText}
  </div>
  <!-- If dismissible -->
  <button type="button" class="caat-alert__close" aria-label="Dismiss alert">
    <i class="bi bi-x-lg" aria-hidden="true"></i>
  </button>
</div>

<!-- Error/Danger alert -->
<div class="caat-alert caat-alert--danger"
     role="alert"
     aria-live="assertive"
     data-caat-alert>
  <i class="bi bi-x-octagon-fill caat-alert__icon" aria-hidden="true"></i>
  <div class="caat-alert__body">
    <strong>{heading}</strong>
    {bodyRichText}
  </div>
</div>

Key decisions

role="alert" ensures assistive technology announces the content.
aria-live="polite" for info/success/warning — doesn't interrupt current task.
aria-live="assertive" for danger/error — immediately announces to screen readers.
Icon uses aria-hidden="true" as meaning is conveyed by text and colour.
Close button uses aria-label="Dismiss alert" for screen-reader clarity.

7. CSS Contract

Selector	Purpose
`.caat-alert`	Base container — flex layout, padding, border-radius, border-left accent.
`.caat-alert--info`	Info colour scheme (blue background, border, icon).
`.caat-alert--success`	Success colour scheme (green background, border, icon).
`.caat-alert--warning`	Warning colour scheme (amber/yellow background, border, icon).
`.caat-alert--danger`	Danger colour scheme (red background, border, icon).
`.caat-alert__icon`	Icon sizing and colour via variant token.
`.caat-alert__body`	Text container — flex-grow, typography settings.
`.caat-alert__close`	Dismiss button — positioned end, transparent background, hover state.

Sample CSS

.caat-alert {
  display: flex;
  align-items: flex-start;
  gap: 0.75rem;
  padding: 1rem 1.25rem;
  border-radius: var(--caat-alert-border-radius);
  border-left: 4px solid;
}

.caat-alert--info {
  background: var(--caat-alert-info-bg);
  border-color: var(--caat-alert-info-border);
}
.caat-alert--info .caat-alert__icon { color: var(--caat-alert-info-icon); }

.caat-alert--success {
  background: var(--caat-alert-success-bg);
  border-color: var(--caat-alert-success-border);
}
.caat-alert--success .caat-alert__icon { color: var(--caat-alert-success-icon); }

.caat-alert--warning {
  background: var(--caat-alert-warning-bg);
  border-color: var(--caat-alert-warning-border);
}
.caat-alert--warning .caat-alert__icon { color: var(--caat-alert-warning-icon); }

.caat-alert--danger {
  background: var(--caat-alert-danger-bg);
  border-color: var(--caat-alert-danger-border);
}
.caat-alert--danger .caat-alert__icon { color: var(--caat-alert-danger-icon); }

.caat-alert__icon {
  font-size: var(--caat-alert-icon-size);
  flex-shrink: 0;
  margin-top: 0.125rem;
}

.caat-alert__body { flex: 1; }

.caat-alert__close {
  background: none;
  border: none;
  padding: 0.25rem;
  cursor: pointer;
  opacity: 0.6;
  transition: opacity 0.2s ease;
}
.caat-alert__close:hover { opacity: 1; }

8. Accessibility

Requirement	Implementation
ARIA role	`role="alert"` on the container element.
Live region	`aria-live="polite"` for info/success/warning; `aria-live="assertive"` for danger.
Colour contrast	Text meets WCAG 2.1 AA (4.5:1). Icon colour meets 3:1 against background.
Colour not sole indicator	Each variant uses a distinct icon shape + text label alongside colour.
Dismiss focus management	On dismiss, focus moves to the next focusable element or the element that triggered the alert. Alert container is removed from DOM.
Close button	`aria-label="Dismiss alert"`. Keyboard accessible via `Enter` / `Space`.
Reduced motion	Dismiss animation respects `prefers-reduced-motion: reduce`.

9. SEO

Transient / structural UI with no indexable content of its own — no SEO markup required. Ensure any content this component wraps or reveals stays server-rendered and crawlable.

10. Analytics

Analytics are captured through the shared data-analytics-component attribute on the component root (emitted automatically) and reported to the central data layer. Event names and payloads follow the organisation's standard analytics schema — defined centrally with the analytics team, not invented per component — so no bespoke tracking is specified here.

11. AEM Notes

Resource type: caat/components/alert
Component group: CAAT Components – Feedback
Proxy: Create as a proxy component under /apps/caat/components/alert.
Policies: Configure allowed alert types per template via content policies (e.g., landing pages may restrict danger alerts).
Sling Model: com.caat.core.models.AlertModel — exposes type, heading, body, dismissible, iconOverride.
HTL: alert.html — uses data-sly-attribute to set variant class and aria-live value dynamically.
Client library: caat.components.alert (categories: caat.site).
Style System: Not applicable — type selection via dedicated dropdown rather than style tab.

12. Dialog Model (YAML)

Simplified model — shows field intent and Granite UI resource types, not the literal cq:dialog node tree (e.g. select options are authored as child items nodes).

title: Alert
description: Contextual feedback message for members.
fields:
  - name: alertType
    label: Alert Type
    type: select
    required: true
    options:
      - value: info
        label: Information
      - value: success
        label: Success
      - value: warning
        label: Warning
      - value: danger
        label: Danger / Error
    helpText: Determines colour, icon, and screen-reader announcement priority.

  - name: heading
    label: Heading
    type: textfield
    required: true
    maxLength: 80
    helpText: Brief action-oriented summary (e.g., "Contribution Deadline Approaching").

  - name: body
    label: Body
    type: richtext
    required: true
    allowedElements: [p, ul, ol, li, a, strong, em]
    helpText: Supporting detail. Keep to 1–3 sentences or a short list.

  - name: dismissible
    label: Dismissible
    type: checkbox
    required: false
    defaultValue: false
    helpText: Adds a close button. Use for non-critical informational alerts only.

  - name: iconOverride
    label: Icon Override
    type: iconpicker
    required: false
    helpText: Leave empty to use the default icon for the selected alert type.

13. QA Acceptance Checklist

14. Definition of Done

Area	Done means
Design	Figma component matches this contract. All four variants documented with light/dark tokens. Icon + text + colour used together — no reliance on colour alone.
Development	AEM proxy component created. HTL template emits semantic HTML per Section 6. CSS uses design tokens exclusively. JS implements dismiss behaviour and fires analytics events. Unit tests pass.
QA	All items in the QA Acceptance Checklist (Section 13) pass. Manual accessibility audit completed. Cross-browser tested (Chrome, Firefox, Safari, Edge).
Launch	Component deployed to AEM production. Content authors trained on appropriate alert type selection. Documentation published. Analytics dashboards confirmed receiving events.