Correct and idiomatic ways to use the <mds-banner> component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in agents/variants.md and the shared component rules in agents/conventions.md.

Informational Banner

The baseline usage. Provide variant="info" and place the body copy in the default slot. The component derives role="status" and aria-live="polite" automatically from the variant.

<mds-banner variant="info">
  <mds-text typography="detail">
    Il sistema e in manutenzione programmata dalle 22:00 alle 23:00.
  </mds-text>
</mds-banner>

Status Variants

Pick the variant that matches the message’s semantic weight. error and warning set role="alert" with assertive live region; the others use role="status" with polite announcement.

<!-- Esito positivo -->
<mds-banner variant="success">
  <mds-text typography="detail">Dati salvati correttamente.</mds-text>
</mds-banner>

<!-- Avviso non bloccante -->
<mds-banner variant="warning">
  <mds-text typography="detail">La sessione scadra tra 5 minuti.</mds-text>
</mds-banner>

<!-- Errore bloccante -->
<mds-banner variant="error">
  <mds-text typography="detail">Impossibile completare l'operazione. Riprovare.</mds-text>
</mds-banner>

Banner with Headline

Use the headline prop to add a title above the body text. The headline is also used as the banner’s accessible label (aria-label).

<mds-banner variant="warning" headline="Licenza in scadenza">
  <mds-text typography="detail">
    La licenza del servizio scadra tra 7 giorni. Rinnova ora per non interrompere il servizio.
  </mds-text>
</mds-banner>

Banner with Icon

Set icon to a Magma icon slug. The icon is decorative (aria-hidden="true"). The colored badge wrapping the icon is shown by default; add hide-cockade for a flatter look.

<!-- Con cockade (default) -->
<mds-banner variant="info" icon="mi/baseline/info" headline="Aggiornamento disponibile">
  <mds-text typography="detail">E disponibile una nuova versione dell'applicazione.</mds-text>
</mds-banner>

<!-- Senza cockade -->
<mds-banner variant="success" icon="mi/baseline/check-circle" hide-cockade>
  <mds-text typography="detail">Operazione completata.</mds-text>
</mds-banner>

Dismissible Banner

Set deletable to show a close button. The button emits mdsBannerClose when activated. Listen for the event to remove the banner from the DOM or update application state.

<mds-banner variant="info" deletable id="promo-banner">
  <mds-text typography="detail">
    Scopri le nuove funzioni premium disponibili nel tuo piano.
  </mds-text>
</mds-banner>

<script>
  document.querySelector('#promo-banner').addEventListener('mdsBannerClose', () => {
    document.querySelector('#promo-banner').remove();
  });
</script>

Banner with Action Buttons

Slot <mds-button> elements with slot="action" to add inline controls. The action region is shown only while at least one [slot="action"] child is present, and it follows the actions added or removed after the first render. Match the button variant to the banner variant for visual consistency.

<mds-banner variant="warning" headline="Abbonamento scaduto">
  <mds-text typography="detail">
    La licenza di questo servizio e scaduta. Il servizio continua a funzionare
    ma non puoi utilizzare le funzioni premium.
  </mds-text>
  <mds-button slot="action" variant="warning" tone="outline">Annulla</mds-button>
  <mds-button slot="action" variant="warning" tone="strong">Rinnova abbonamento</mds-button>
</mds-banner>

Tone for Visual Emphasis

tone controls emphasis without changing the semantic variant. strong paints the status tint on the whole banner, weak (default) keeps a neutral raised surface and colours only the icon, and box adds a solid box shadow for high-contrast placements. mds-banner accepts only weak, strong, and box - not outline or text.

<!-- Bassa enfasi (default) -->
<mds-banner variant="error" tone="weak">
  <mds-text typography="detail">Errore di validazione nei campi del modulo.</mds-text>
</mds-banner>

<!-- Alta enfasi -->
<mds-banner variant="error" tone="strong">
  <mds-text typography="detail">Account bloccato per attivita sospetta. Contatta il supporto.</mds-text>
</mds-banner>

Dark and Light Decorative Variants

variant="dark" and variant="light" are neutral, decorative banners without an ARIA live region (role="presentation"). Use them for non-critical UI chrome - announcements or promotional content that does not require immediate attention.

<mds-banner variant="dark" tone="strong" headline="Novita del mese">
  <mds-text typography="detail">
    Tre nuovi moduli sono stati aggiunti alla piattaforma.
  </mds-text>
  <mds-button slot="action" variant="light" tone="text">Scopri</mds-button>
</mds-banner>

AI Variant

Use variant="ai" to mark banners that present AI-generated content or AI-powered suggestions. The variant emits a polite role="status" live announcement.

<mds-banner variant="ai" icon="mi/baseline/auto-awesome" headline="Suggerimento IA">
  <mds-text typography="detail">
    L'analisi ha rilevato tre anomalie nel documento caricato.
  </mds-text>
  <mds-button slot="action" variant="ai" tone="outline">Visualizza dettagli</mds-button>
</mds-banner>

Dismissible Banner inside mds-modal

When deletable is set and the banner lives inside an <mds-modal>, activating the close button emits mdsBannerClose and also closes the modal automatically - no extra JavaScript needed.

<mds-modal opened>
  <mds-banner variant="warning" deletable headline="Attenzione">
    <mds-text typography="detail">
      Stai per eliminare tutti i dati. L'azione non e reversibile.
    </mds-text>
    <mds-button slot="action" variant="warning" tone="outline">Annulla</mds-button>
    <mds-button slot="action" variant="warning" tone="strong">Elimina</mds-button>
  </mds-banner>
</mds-modal>

CSS Custom Property Customization

Override appearance only through the documented --mds-banner-* custom properties. Set them on the host or a parent selector; use semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working.

.featured-notice mds-banner {
  --mds-banner-background: rgb(var(--magma-accent-emphasis));
  --mds-banner-color: rgb(var(--magma-accent-on-emphasis));
  --mds-banner-headline-color: rgb(var(--magma-accent-on-emphasis));
  --mds-banner-radius: var(--magma-radius-sm);
  --mds-banner-shadow: 0 4px 16px rgb(var(--magma-shadow-ink) / 0.15);
}