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

Plain Note with Body Text

The minimal form: a sticky-note block with only body content in the default slot. variant defaults to 'yellow'; omit it when yellow suits the context.

<mds-note>
  <mds-text typography="detail">Ricordare di aggiornare le credenziali prima del 30 giugno.</mds-text>
</mds-note>

Note with a Title

Use the named title slot for the heading and the default slot for the body. Both slots accept text, HTML elements, and components.

<mds-note variant="blue">
  <mds-text typography="h5" slot="title">Nota riunione del 5 giugno</mds-text>
  <mds-text typography="detail">Confermare la disponibilita' di sala entro venerdi'.</mds-text>
  <mds-text typography="detail">Invitare anche il responsabile del progetto Synbee.</mds-text>
</mds-note>

Color Variant for Category

Choose variant based on the note’s category, not on aesthetic preference; a label color never communicates state (agents/variants.md). All twelve label colors are available.

<!-- Category: reminders -->
<mds-note variant="yellow">
  <mds-text typography="detail">Scadenza domani: inviare il report trimestrale.</mds-text>
</mds-note>

<!-- Category: approvals -->
<mds-note variant="orange">
  <mds-text typography="detail">Approvazione in attesa - contattare il responsabile.</mds-text>
</mds-note>

<!-- Category: review notes -->
<mds-note variant="sky">
  <mds-text typography="detail">Questo blocco e' in sola lettura fino al completamento della revisione.</mds-text>
</mds-note>

<!-- Category: configuration -->
<mds-note variant="green">
  <mds-text typography="detail">Configurazione del modulo fatture: usare il profilo standard.</mds-text>
</mds-note>

Dismissible Note via deletable

Set deletable to expose the close button. The component emits mdsNoteDelete when the button is activated but does not remove itself - the host application is responsible for removal.

<mds-note variant="amaranth" deletable>
  <mds-text typography="h5" slot="title">Attenzione</mds-text>
  <mds-text typography="detail">Questo avviso sparira' una volta confermata l'azione.</mds-text>
</mds-note>

document.querySelector('mds-note').addEventListener('mdsNoteDelete', () => {
  document.querySelector('mds-note').remove();
});

Styling Customization via CSS Custom Properties

Customize the note only through the documented --mds-note-* CSS custom properties. Set them on the host or a parent selector; use Magma color tokens via rgb(var(--<token>)) so dark mode and high-contrast modes keep working.

.featured-note mds-note {
  --mds-note-background: rgb(var(--label-orchid-09));
  --mds-note-color: rgb(var(--label-orchid-02));
  --mds-note-fold-size: 28px;
}

Multiple Notes in a Grid

Place several notes in a layout container; each note is independent and carries its own variant and deletable state.

<div style="display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 1rem;">
  <mds-note variant="yellow" deletable>
    <mds-text typography="h6" slot="title">Da fare</mds-text>
    <mds-text typography="detail">Revisionare il capitolato prima di lunedi'.</mds-text>
  </mds-note>
  <mds-note variant="lime">
    <mds-text typography="h6" slot="title">Completato</mds-text>
    <mds-text typography="detail">Migrazione database eseguita con successo.</mds-text>
  </mds-note>
  <mds-note variant="red" deletable>
    <mds-text typography="h6" slot="title">Bloccante</mds-text>
    <mds-text typography="detail">Servizio di autenticazione non raggiungibile in produzione.</mds-text>
  </mds-note>
</div>