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

Default Informational Note

The simplest form. Omit variant to get the info default - a neutral, blue-tinted container that draws attention to a usage note without implying correctness or incorrectness.

<mds-usage>
  <mds-text>
    Utilizzare sempre il colore primario del tema per le azioni principali.
  </mds-text>
</mds-usage>

Recommended Pattern (variant="do")

Use variant="do" to mark a component usage or design pattern as explicitly recommended. The container adopts success styling and the content region carries role="insertion" for assistive technology.

<mds-usage variant="do">
  <mds-button label="Salva" variant="primary" tone="strong"></mds-button>
</mds-usage>

Discouraged Pattern (variant="dont")

Use variant="dont" to mark a usage as explicitly forbidden or inadvisable. The container adopts error styling and the content region carries role="deletion".

<mds-usage variant="dont">
  <button style="background: blue; color: white;">Salva</button>
</mds-usage>

Cautionary Note (variant="warn")

Use variant="warn" when a pattern is not forbidden but requires care - for example when a prop combination is valid but has side effects, or when a rare edge case exists. The container adopts warning styling and carries role="deletion".

<mds-usage variant="warn">
  <mds-text>
    Impostare type="button" su ogni pulsante all'interno di un form
    per evitare invii accidentali.
  </mds-text>
</mds-usage>

Custom Header Label via alias

When the auto-generated, localized header (“Consentito”, “Non consentito”, etc.) is not specific enough for the context, pass alias to replace it with a custom string. The locale dictionary is bypassed entirely.

<mds-usage variant="do" alias="Struttura consigliata">
  <mds-text>Usare mds-card con header, content e footer separati.</mds-text>
</mds-usage>

<mds-usage variant="dont" alias="Struttura da evitare">
  <mds-text>Non annidare mds-card all'interno di un'altra mds-card.</mds-text>
</mds-usage>

Custom Header Icon via icon

Each variant has its own header icon. When a custom alias names a more specific category, pass icon with a slug that illustrates it; the variant still drives the colors, the label fallback and the content role. Keep the icon coherent with the variant.

<mds-usage variant="do" alias="Struttura consigliata" icon="mi/baseline/account-tree">
  <mds-text>Usare mds-card con header, content e footer separati.</mds-text>
</mds-usage>

Side-by-Side Do / Dont Pair

Pair a do block with a dont block to illustrate a correct and an incorrect approach in the same documentation section. No extra wrapper is needed - use a CSS grid or flex container.

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 1rem;">
  <mds-usage variant="do">
    <mds-button label="Conferma" variant="primary" tone="strong"></mds-button>
  </mds-usage>

  <mds-usage variant="dont">
    <mds-button label="Conferma" tone="strong" style="--mds-button-background: green;"></mds-button>
  </mds-usage>
</div>

Rich Slotted Content

The default slot accepts any HTML or Magma components. Use this to annotate a fully composed UI fragment rather than a single element.

<mds-usage variant="do" alias="Composizione corretta di mds-card">
  <mds-card>
    <mds-card-header slot="header">
      <mds-text typography="h5">Titolo scheda</mds-text>
    </mds-card-header>
    <mds-card-content slot="content">
      <mds-text>Contenuto principale della scheda.</mds-text>
    </mds-card-content>
    <mds-card-footer slot="footer">
      <mds-button label="Azione" variant="primary"></mds-button>
    </mds-card-footer>
  </mds-card>
</mds-usage>

CSS Custom Property Overrides

Customize the container appearance through the three documented --mds-usage-* CSS custom properties. Set them on the host or a parent selector and use the semantic color roles via rgb(var(--magma-<role>)) to keep dark mode working.

.docs-callout mds-usage {
  --mds-usage-border-color: rgb(var(--magma-accent-ai-border));
  --mds-usage-header-background: rgb(var(--magma-accent-ai-emphasis));
  --mds-usage-header-color: rgb(var(--magma-accent-ai-on-emphasis));
}