Common incorrect uses of <mds-progress>. 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 a Raw <progress> Element

Replacing <mds-progress> with the native element loses the Magma theme, the step-announcement system, and automatic aria-valuenow wiring.

<!-- INCORRECT -->
<progress value="40" max="100"></progress>

<!-- CORRECT -->
<mds-progress progress="0.4" aria-label="Avanzamento operazione"></mds-progress>

Do Not Pass progress as a Percentage Integer

progress is a fractional value between 0 and 1, not a percentage. Passing 40 instead of 0.4 pins the bar at 100% fill and sets aria-valuenow to 4000.

<!-- INCORRECT -->
<mds-progress progress="40"></mds-progress>

<!-- CORRECT -->
<mds-progress progress="0.4" aria-label="Avanzamento caricamento"></mds-progress>

Do Not Omit an Accessible Name

Without aria-label (or aria-labelledby) and without aria-hidden="true", the progressbar role has no text label and screen readers can only announce the numeric value with no context.

<!-- INCORRECT -->
<mds-progress progress="0.6"></mds-progress>

<!-- CORRECT - informative bar with a label -->
<mds-progress progress="0.6" aria-label="Invio email in corso"></mds-progress>

<!-- CORRECT - purely decorative, no label needed -->
<mds-progress progress="0.6" aria-hidden="true"></mds-progress>

Do Not Use direction="radial" Without a Width Constraint

The radial variant sizes itself from the host’s width. Without an explicit width the ring expands to fill the container, often breaking the layout.

<!-- INCORRECT -->
<mds-progress progress="0.5" direction="radial"></mds-progress>

<!-- CORRECT -->
<mds-progress progress="0.5" direction="radial" style="width: 80px;" aria-label="Completamento"></mds-progress>

Do Not Use typography on Bar Directions

The typography prop controls the type scale of the centered percentage label rendered only when direction="radial". Setting it on horizontal or vertical bars has no visual effect and misleads readers.

<!-- INCORRECT -->
<mds-progress progress="0.5" direction="horizontal" typography="label"></mds-progress>

<!-- CORRECT -->
<mds-progress progress="0.5" direction="radial" typography="label" style="width: 64px;" aria-label="Avanzamento"></mds-progress>

Do Not Pierce the Shadow DOM to Style the Fill

::part(progress) is the supported way to reach the fill element; >>> or undocumented class names are not. Prefer the --mds-progress-* CSS custom properties for the most common overrides.

/* INCORRECT */
mds-progress >>> .progress {
  background: hotpink;
}

/* CORRECT - use the CSS custom property */
mds-progress {
  --mds-progress-color: rgb(var(--magma-accent-emphasis-hover));
}

/* CORRECT - use the documented part only when a property is insufficient */
mds-progress::part(progress) {
  border-radius: var(--magma-radius-none);
}