Common incorrect uses of <mds-usage>. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in agents/anti-patterns.md - they apply here too but are not repeated.

Do Not Use variant as the Shared Tone/Variant Ladder

<mds-usage> does not use the system-wide variant ladder (primary, secondary, error, etc.). Its variant prop is component-specific (do, dont, info, warn). Passing a system variant silently falls back to the base info-like styling and the info icon, with an empty header label (the locale has no entry for it).

<!-- INCORRECT -->
<mds-usage variant="error">
  <mds-text>Non consentito.</mds-text>
</mds-usage>

<!-- CORRECT -->
<mds-usage variant="dont">
  <mds-text>Non consentito.</mds-text>
</mds-usage>

Do Not Use an icon That Contradicts the variant

icon replaces only the glyph: colors, label and content role still follow the variant. An icon that means the opposite (a tick on a dont block, a cross on a do block) sends two conflicting signals. To change the meaning, change the variant; use icon only to make the same meaning more specific.

<!-- INCORRECT -->
<mds-usage variant="dont" icon="mi/baseline/check-circle">
  <mds-text>Non annidare mds-card all'interno di un'altra mds-card.</mds-text>
</mds-usage>

<!-- CORRECT -->
<mds-usage variant="dont">
  <mds-text>Non annidare mds-card all'interno di un'altra mds-card.</mds-text>
</mds-usage>

Do Not Omit the Slot Content

<mds-usage> renders a labeled container; without slotted content the block displays only the colored header strip with no body - producing a visually broken annotation. Always provide meaningful content in the default slot.

<!-- INCORRECT -->
<mds-usage variant="do"></mds-usage>

<!-- CORRECT -->
<mds-usage variant="do">
  <mds-text>Usare sempre il colore del tema per i pulsanti primari.</mds-text>
</mds-usage>

Do Not Put the Label in the Default Slot

The default slot is the body of the block. Placing a heading or label string there makes it look like body text, not a header. Use the alias prop to supply a custom header label.

<!-- INCORRECT -->
<mds-usage variant="do">
  Struttura consigliata
</mds-usage>

<!-- CORRECT -->
<mds-usage variant="do" alias="Struttura consigliata">
  <mds-text>Comporre mds-card con i suoi sotto-componenti dedicati.</mds-text>
</mds-usage>

Do Not Pierce the Shadow DOM to Restyle the Header

::part(header), ::part(icon), and ::part(label) are the only documented extension points for shadow internals. Targeting undocumented class names or using >>> couples code to implementation details that may change. For color overrides, use the documented --mds-usage-* CSS custom properties instead.

/* INCORRECT */
mds-usage >>> .header {
  background: rgb(var(--magma-accent-ai-emphasis));
}

/* CORRECT */
mds-usage {
  --mds-usage-header-background: rgb(var(--magma-accent-ai-emphasis));
  --mds-usage-header-color: rgb(var(--magma-accent-ai-on-emphasis));
}

Do Not Use <mds-usage> as a General-Purpose Card

<mds-usage> is a documentation/Storybook annotation primitive - it is not a card, callout, or alert for production UIs. For in-app status messages use mds-banner, mds-note, or mds-toast.

<!-- INCORRECT - using mds-usage as a production alert -->
<mds-usage variant="warn">
  <mds-text>La sessione sta per scadere.</mds-text>
</mds-usage>

<!-- CORRECT - use the appropriate production component -->
<mds-banner variant="warning" tone="weak">La sessione sta per scadere.</mds-banner>