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

Basic Benchmark via label and value

The canonical form. Set label for the caption text and value (0-100) for the fill. label is reflected as an attribute; value is not, so a value set from JavaScript does not show up in attribute selectors.

<mds-benchmark-bar label="Soddisfazione clienti" value="72"></mds-benchmark-bar>

Multiple Bars in a List

Render several bars together to compare metrics. Each bar stands on its own; no parent wrapper is required.

<mds-benchmark-bar label="Qualita del servizio" value="85"></mds-benchmark-bar>
<mds-benchmark-bar label="Tempi di risposta" value="61"></mds-benchmark-bar>
<mds-benchmark-bar label="Risoluzione al primo contatto" value="44"></mds-benchmark-bar>

Alias to Replace the Numeric Value

Use alias when you need to display a formatted or qualitative string instead of the raw number. The alias also becomes the accessible aria-valuetext announced to screen readers.

<!-- Show a grade label instead of the raw score -->
<mds-benchmark-bar
  label="Punteggio complessivo"
  value="68"
  alias="Buono"
></mds-benchmark-bar>

<!-- Show a ratio string -->
<mds-benchmark-bar
  label="Attivita completate"
  value="33"
  alias="1 di 3"
></mds-benchmark-bar>

Variant for Semantic Color

variant controls the color theme of the progress bar. Pick the value that matches the meaning of the metric, not the color you want.

<!-- Neutral / default -->
<mds-benchmark-bar label="Utilizzo CPU" value="55" variant="dark"></mds-benchmark-bar>

<!-- Primary brand emphasis -->
<mds-benchmark-bar label="Avanzamento progetto" value="70" variant="primary"></mds-benchmark-bar>

<!-- Status: healthy -->
<mds-benchmark-bar label="Uptime mensile" value="99" variant="success"></mds-benchmark-bar>

<!-- Status: under threshold -->
<mds-benchmark-bar label="Scorte disponibili" value="18" variant="warning"></mds-benchmark-bar>

<!-- Status: critical -->
<mds-benchmark-bar label="Errori rilevati" value="82" variant="error"></mds-benchmark-bar>

Size

size controls the height of the progress bar. Use sm for dense lists, lg / xl for hero metrics.

<mds-benchmark-bar label="Piccolo" value="40" size="sm"></mds-benchmark-bar>
<mds-benchmark-bar label="Medio (default)" value="40" size="md"></mds-benchmark-bar>
<mds-benchmark-bar label="Grande" value="40" size="lg"></mds-benchmark-bar>
<mds-benchmark-bar label="Extra grande" value="40" size="xl"></mds-benchmark-bar>

Typography Scale

typography applies to both the label caption and the value text. Use option for compact contexts where the default label scale is too heavy.

<!-- Default scale -->
<mds-benchmark-bar label="Punteggio" value="76" typography="label"></mds-benchmark-bar>

<!-- Compact / denser scale -->
<mds-benchmark-bar label="Punteggio" value="76" typography="option"></mds-benchmark-bar>

Styling Customization via ::part(progress-bar)

The inner progress bar is exposed as the progress-bar shadow part. Use it to apply targeted overrides when the documented variant colors are insufficient - for example, to enforce a brand-specific fill in a narrow context.

.hero-metric mds-benchmark-bar::part(progress-bar) {
  --mds-progress-color: rgb(var(--magma-accent-ai-fg));
}