Correct and idiomatic ways to use the <mds-kpi> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Basic KPI Panel

The canonical form. Place one or more mds-kpi-item elements as direct children. mds-kpi provides the responsive grid; mds-kpi-item owns every visible value.

<mds-kpi>
  <mds-kpi-item label="1.240" description="Pratiche aperte"></mds-kpi-item>
  <mds-kpi-item label="387" description="In lavorazione"></mds-kpi-item>
  <mds-kpi-item label="56" description="Scadute"></mds-kpi-item>
</mds-kpi>

KPI Item with Icon

Set icon to an icon slug to display a glyph above the value. Use slugs from the Magma icon library - mi/baseline/* for Material Icons or an mgg/ Maggioli slug.

<mds-kpi>
  <mds-kpi-item
    icon="mi/baseline/folder-open"
    label="1.240"
    description="Pratiche aperte"
  ></mds-kpi-item>
  <mds-kpi-item
    icon="mi/baseline/pending-actions"
    label="387"
    description="In lavorazione"
  ></mds-kpi-item>
  <mds-kpi-item
    icon="mi/baseline/warning"
    label="56"
    description="Scadute"
  ></mds-kpi-item>
</mds-kpi>

Scroll-Triggered Animation

Set threshold to a value between 0 (exclusive) and 1 to activate the scramble/reveal animation when the item scrolls into the viewport. A threshold of 0.5 triggers once at least half the element is visible. Omit threshold (or leave it at the default 0) for static rendering.

<mds-kpi>
  <mds-kpi-item
    icon="mi/baseline/groups"
    label="4.512"
    description="Dipendenti"
    threshold="0.5"
  ></mds-kpi-item>
  <mds-kpi-item
    icon="mi/baseline/location-city"
    label="38"
    description="Sedi operative"
    threshold="0.5"
  ></mds-kpi-item>
  <mds-kpi-item
    icon="mi/baseline/stars"
    label="12"
    description="Anni di attivita"
    threshold="0.5"
  ></mds-kpi-item>
</mds-kpi>

Tuning the Animation Speed Globally

Use --mds-kpi-text-animation-speed on the <mds-kpi> host to slow down or speed up the scramble effect for all children at once. The default is 0.15. The placeholder character during the scramble phase is controlled by --mds-kpi-text-animation-placeholder-char (default: a space).

.hero-section mds-kpi {
  --mds-kpi-text-animation-speed: 0.08;
  --mds-kpi-text-animation-placeholder-char: '-';
}

Styling Individual Items

Customize a single <mds-kpi-item> through its own CSS custom properties. Use the semantic color roles via rgb(var(--magma-<role>)) (agents/color.md) so dark mode keeps working.

.progetto-kpi mds-kpi-item {
  --mds-kpi-item-icon-color: rgb(var(--magma-accent-emphasis));
  --mds-kpi-item-info-background: rgb(var(--magma-surface-overlay));
}

Targeting Shadow Parts

When a CSS custom property is not enough, target the documented shadow parts of <mds-kpi-item> - icon, icon-container, and content - via ::part(). Use this only when deeper visual control is required.

mds-kpi-item::part(icon) {
  width: 30%;
}

mds-kpi-item::part(content) {
  text-align: left;
}