Common incorrect uses of <mds-kpi>. 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 Place Raw HTML in the Default Slot

The default slot of <mds-kpi> is meant exclusively for mds-kpi-item elements. Arbitrary HTML has no styled placement inside the grid and breaks the list semantics the component exposes to assistive technology.

<!-- INCORRECT -->
<mds-kpi>
  <div class="metric">
    <h2>1.240</h2>
    <p>Pratiche aperte</p>
  </div>
</mds-kpi>

<!-- CORRECT -->
<mds-kpi>
  <mds-kpi-item label="1.240" description="Pratiche aperte"></mds-kpi-item>
</mds-kpi>

Do Not Use mds-kpi-item Outside mds-kpi

<mds-kpi-item> is a compound child and relies on the grid context and CSS custom property cascade provided by its parent. Using it as a standalone element loses the responsive layout and the shared animation-speed variables.

<!-- INCORRECT -->
<mds-kpi-item label="387" description="In lavorazione"></mds-kpi-item>

<!-- CORRECT -->
<mds-kpi>
  <mds-kpi-item label="387" description="In lavorazione"></mds-kpi-item>
</mds-kpi>

Do Not Set threshold="0" Explicitly to Disable Animation

threshold defaults to 0, which means static rendering. Writing threshold="0" is redundant: it changes nothing. Simply omit the attribute.

<!-- INCORRECT -->
<mds-kpi-item label="56" description="Scadute" threshold="0"></mds-kpi-item>

<!-- CORRECT -->
<mds-kpi-item label="56" description="Scadute"></mds-kpi-item>

Do Not Slot mds-icon to Display an Icon

The icon prop on <mds-kpi-item> renders the glyph in its own styled container above the value. mds-kpi-item renders no slot, so an <mds-icon> or any other element slotted into it is not displayed.

<!-- INCORRECT -->
<mds-kpi>
  <mds-kpi-item label="75" description="Allenatori">
    <mds-icon name="mi/baseline/directions-walk"></mds-icon>
  </mds-kpi-item>
</mds-kpi>

<!-- CORRECT -->
<mds-kpi>
  <mds-kpi-item
    icon="mi/baseline/directions-walk"
    label="75"
    description="Allenatori"
  ></mds-kpi-item>
</mds-kpi>

Do Not Override the Animation Speed by Targeting Internal Text Components

<mds-kpi-item> forwards --mds-kpi-text-animation-speed and --mds-kpi-text-animation-placeholder-char to its internal <mds-text> elements. Setting --mds-text-animation-speed from outside has no effect: the item sets it on its inner texts from its own variables. Use the published --mds-kpi-* or --mds-kpi-item-* variables instead.

/* INCORRECT */
mds-kpi-item {
  --mds-text-animation-speed: 0.05;
}

/* CORRECT */
mds-kpi {
  --mds-kpi-text-animation-speed: 0.05;
}