Common incorrect uses of <mds-badge>. 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 Put HTML in the Default Slot

The default slot is deprecated and accepts plain text only; nested elements are stripped or break layout. Use the label prop instead.

<!-- INCORRECT -->
<mds-badge>
  <strong>Urgente</strong>
</mds-badge>

<!-- CORRECT -->
<mds-badge label="Urgente" variant="error" tone="strong"></mds-badge>

Do Not Use the Slot When label Is Available

Slotted text still works as a legacy fallback but will be removed in a future release. The label prop is the documented API going forward.

<!-- INCORRECT -->
<mds-badge>Approvato</mds-badge>

<!-- CORRECT -->
<mds-badge label="Approvato" variant="success" tone="weak"></mds-badge>

Do Not Apply a tone Value Outside the Allowed Set

<mds-badge> uses ToneSmartVariantType, which allows only strong, weak, and outline. Values like text or box are not accepted: no tone style matches them, so the badge renders as with strong, not with the weak default.

<!-- INCORRECT -->
<mds-badge label="Bozza" variant="warning" tone="text"></mds-badge>
<mds-badge label="Bozza" variant="warning" tone="box"></mds-badge>

<!-- CORRECT -->
<mds-badge label="Bozza" variant="warning" tone="outline"></mds-badge>

Do Not Use Legacy ghost or quiet Tone Values

tone="ghost" and tone="quiet" are Magma 1 names: on <mds-badge> Magma 2.0 renamed them to outline and weak (the codemod applies the rename). Neither old name is valid any more.

<!-- INCORRECT (Magma 1.x naming) -->
<mds-badge label="Archiviato" tone="ghost" variant="dark"></mds-badge>

<!-- CORRECT (Magma 2.x) -->
<mds-badge label="Archiviato" tone="outline" variant="dark"></mds-badge>

Do Not Pick a Variant for Its Color Alone

variant carries semantic meaning - status variants (error, warning, success, info) communicate state; label variants (green, blue, violet, etc.) communicate category. Do not choose a variant just because its color looks right.

<!-- INCORRECT: using "error" to get a red tag for a topic, not an error state -->
<mds-badge label="Ruby" variant="error" tone="weak"></mds-badge>

<!-- CORRECT: use a decorative label variant for non-state tags -->
<mds-badge label="Ruby" variant="red" tone="weak"></mds-badge>

Do Not Customize via Undocumented Selectors

The supported customization surface is --mds-badge-* CSS custom properties. Targeting shadow-DOM internals via >>>, /deep/, or undocumented ::part() names couples your code to implementation details that can change on any release.

/* INCORRECT */
mds-badge >>> span {
  font-weight: bold;
  letter-spacing: 0.1em;
}

/* CORRECT */
mds-badge {
  --mds-badge-background: rgb(var(--label-violet-09));
  --mds-badge-color: rgb(var(--label-violet-02));
  --mds-badge-radius: var(--magma-radius-full);
}

Do Not Use <mds-badge> for Interactive Controls

<mds-badge> is purely presentational - it emits no events and has no focus management. For a selectable or dismissible tag, use mds-chip instead.

<!-- INCORRECT: listening to a click on a non-interactive component -->
<mds-badge label="Rimuovi" variant="error" onclick="removeTag()"></mds-badge>

<!-- CORRECT: use mds-chip for interactive tag behavior -->
<mds-chip label="Rimuovi" variant="error" deletable></mds-chip>