Common incorrect uses of <mds-kpi-item>. 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 mds-kpi-item Outside mds-kpi

<mds-kpi-item> is a compound child designed to be a direct slot child of <mds-kpi>. Using it standalone strips the list semantics that <mds-kpi> provides and breaks the expected visual layout.

<!-- INCORRECT -->
<mds-kpi-item label="1.240" description="Pratiche elaborate"></mds-kpi-item>

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

Do Not Slot HTML Content for the Label or Description

<mds-kpi-item> has no default slot - all text content is driven by the label and description props. Slotting child nodes produces no output because the component renders nothing from its slot.

<!-- INCORRECT -->
<mds-kpi>
  <mds-kpi-item>
    <span>1.240</span>
    <small>Pratiche elaborate</small>
  </mds-kpi-item>
</mds-kpi>

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

Do Not Slot <mds-icon> to Add an Icon

The icon prop passes the slug to the internal <mds-icon> instance. Slotting an <mds-icon> directly has no effect because the component has no named slot for icons.

<!-- INCORRECT -->
<mds-kpi>
  <mds-kpi-item label="98%" description="Soddisfazione clienti">
    <mds-icon name="mi/baseline/thumb-up"></mds-icon>
  </mds-kpi-item>
</mds-kpi>

<!-- CORRECT -->
<mds-kpi>
  <mds-kpi-item
    label="98%"
    description="Soddisfazione clienti"
    icon="mi/baseline/thumb-up"
  ></mds-kpi-item>
</mds-kpi>

Do Not Set threshold="0" to Disable Animation - Omit It

threshold defaults to 0, so setting it explicitly to "0" is a no-op. More importantly, threshold="false" or threshold="none" is parsed to NaN, which the IntersectionObserver rejects with an error at runtime.

<!-- INCORRECT -->
<mds-kpi-item label="3.500" description="Utenti" threshold="false"></mds-kpi-item>
<mds-kpi-item label="3.500" description="Utenti" threshold="none"></mds-kpi-item>

<!-- CORRECT - omit threshold entirely for no animation (defaults to 0) -->
<mds-kpi-item label="3.500" description="Utenti"></mds-kpi-item>

Do Not Pierce Shadow DOM to Style Internal Elements

The supported customization surface is --mds-kpi-item-* CSS custom properties and the three documented shadow parts (icon-container, icon, content). Reaching inside the shadow DOM via >>> or undocumented class names couples your code to the implementation and will break on minor releases.

/* INCORRECT */
mds-kpi-item >>> .info {
  background: white;
}
mds-kpi-item >>> .value {
  font-size: 3rem;
}

/* CORRECT */
mds-kpi-item {
  --mds-kpi-item-info-background: rgb(var(--magma-surface-overlay));
}
mds-kpi-item::part(content) {
  padding: calc(var(--spacing) * 600);
}

Do Not Leave Icon-Only Items Without an Accessible Name

When both label and description are omitted the component’s aria-label resolves to "undefined: undefined", which is meaningless to screen-reader users. Supply an explicit aria-label on the host when the item carries no text props (the component keeps it at first render, but writes its own name back at its next re-render).

<!-- INCORRECT -->
<mds-kpi>
  <mds-kpi-item icon="mi/baseline/star"></mds-kpi-item>
</mds-kpi>

<!-- CORRECT -->
<mds-kpi>
  <mds-kpi-item
    icon="mi/baseline/star"
    aria-label="Valutazione eccellente"
  ></mds-kpi-item>
</mds-kpi>