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

The default slot accepts plain text strings only. HTML elements or components slotted inside are outside the supported API: they keep their own browser and page styles instead of following the typography role.

<!-- INCORRECT -->
<mds-text typography="paragraph">
  <strong>Attenzione:</strong> questa operazione e' <em>irreversibile</em>.
</mds-text>

<!-- CORRECT -->
<mds-text typography="paragraph">Attenzione: questa operazione e' irreversibile.</mds-text>
<mds-text typography="paragraph" tag="strong">Attenzione:</mds-text>

Do Not Mix text Prop and Slotted Content

When text is set, the component renders that string and ignores the slot entirely. Do not provide both - the slotted content is silently discarded.

<!-- INCORRECT -->
<mds-text text="Titolo dal prop">Titolo dallo slot</mds-text>

<!-- CORRECT -->
<!-- Use either the prop (preferred for dynamic / animated content) -->
<mds-text text="Titolo dal prop"></mds-text>
<!-- or the slot (convenient for static markup) -->
<mds-text>Titolo dallo slot</mds-text>

Do Not Use animation="yugop" Without the text Prop

The yugop animation requires the text prop because it watches prop changes to retrigger. Slotted content is not observed; changing it will not re-run the animation.

<!-- INCORRECT -->
<mds-text animation="yugop">Testo animato dallo slot</mds-text>

<!-- CORRECT -->
<mds-text animation="yugop" text="Testo animato dal prop"></mds-text>

Do Not Apply an Invalid variant for the Chosen typography

variant is specific to the typography role: only paragraph, detail, and caption accept variant="read". Applying variant="read" to heading or label roles silently has no visual effect and adds misleading markup.

<!-- INCORRECT -->
<mds-text typography="h2" variant="read">Impostazioni</mds-text>
<mds-text typography="label" variant="read">Nome</mds-text>

<!-- CORRECT -->
<mds-text typography="h2">Impostazioni</mds-text>
<mds-text typography="paragraph" variant="read">Testo editoriale lungo.</mds-text>

Do Not Use Raw HTML Headings Instead of <mds-text>

Replace raw <h1>-<h6>, <p>, <span>, <label>, and <code> styled with generic utilities with <mds-text> in Magma-managed views (or apply the typography utilities of agents/typography.md). Generic sizes and weights bypass the design-token typography ramp, causing visual inconsistency across themes and sizes.

<!-- INCORRECT -->
<h2 class="text-2xl font-bold">Riepilogo ordine</h2>
<p class="text-sm text-fg-muted">Totale: 128,00 EUR</p>

<!-- CORRECT -->
<mds-text typography="h2">Riepilogo ordine</mds-text>
<mds-text typography="caption">Totale: 128,00 EUR</mds-text>

Do Not Reach Into Shadow DOM to Style Internal Elements

The component exposes five --mds-text-* CSS custom properties for customization. Do not pierce the shadow DOM via ::part() or >>> selectors targeting the internal .text element - that implementation detail is not a documented part and may change.

/* INCORRECT */
mds-text >>> .text {
  letter-spacing: 0.1em;
}

/* CORRECT - set via host; the host styles cascade into the shadow text node */
mds-text {
  letter-spacing: 0.1em;
  --mds-text-selection-background: rgb(var(--label-sky-09));
}

Do Not Confuse truncate="word" and truncate="all"

truncate="word" forces single-line truncation. truncate="all" enables multi-line clamping controlled by --mds-text-line-clamp. Using "word" when you want multi-line clamp will collapse the text to one line unexpectedly.

<!-- INCORRECT - collapses to one line when two lines were intended -->
<mds-text typography="paragraph" truncate="word" style="--mds-text-line-clamp: 2;">
  Testo lungo che dovrebbe mostrare due righe prima del troncamento.
</mds-text>

<!-- CORRECT -->
<mds-text typography="paragraph" truncate="all" style="--mds-text-line-clamp: 2;">
  Testo lungo che dovrebbe mostrare due righe prima del troncamento.
</mds-text>