Common incorrect uses of <mds-spinner>. 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 Set running="false" to Hide the Spinner

The component’s styles key on the presence of running (:host([running])). Stencil reads "false" as false and, since running is reflected, removes the attribute at the first render, so this happens to work; but the markup says the opposite of what it does, and on a prop that is not reflected the attribute stays in the DOM, where [attr] selectors still match it. Remove the attribute entirely - or set the prop to undefined - to stop and hide the spinner.

<!-- INCORRECT -->
<mds-spinner running="false"></mds-spinner>

<!-- CORRECT -->
<mds-spinner></mds-spinner>

Do Not Show Spinner Without running and Expect It to Animate

The spinner renders as invisible (opacity: 0, transform: scale(0)) and with the animation paused when running is absent. Toggling CSS visibility or opacity from outside will not start the animation - you must set the running attribute.

<!-- INCORRECT -->
<mds-spinner style="opacity: 1; transform: none;"></mds-spinner>

<!-- CORRECT -->
<mds-spinner running></mds-spinner>

Do Not Add ARIA Roles or Labels to the Spinner Itself

The spinner is decorative - it has no semantic content and must not become a labelled landmark or a status region. Screen readers should be informed of loading state through a parent container with aria-busy / aria-live, not through attributes placed on <mds-spinner>.

<!-- INCORRECT -->
<mds-spinner running role="status" aria-label="Caricamento"></mds-spinner>

<!-- CORRECT -->
<div role="status" aria-live="polite" aria-label="Caricamento">
  <mds-spinner running></mds-spinner>
</div>

Do Not Add a Separate Spinner Alongside mds-button

mds-button controls its own internal <mds-spinner> through the await prop. An extra spinner next to the button leaves the button clickable while the operation runs; await shows the button’s own spinner and blocks interaction.

<!-- INCORRECT -->
<mds-button label="Salva" variant="primary"></mds-button>
<mds-spinner running></mds-spinner>

<!-- CORRECT -->
<mds-button label="Salva" await variant="primary"></mds-button>

Do Not Pierce Shadow DOM to Change the SVG Colour

The only documented customization surface is the color CSS property on the host (inherited by the internal stroke) and the --mds-spinner-duration CSS custom property. Targeting internals via >>> or undocumented selectors couples your code to the implementation and will break on minor releases.

/* INCORRECT */
mds-spinner >>> .await-icon svg {
  stroke: red;
}

/* CORRECT */
mds-spinner {
  color: rgb(var(--magma-danger-text-default));
}

Do Not Override --mds-spinner-duration to Pause or Stop the Animation

Setting an extremely long or infinite duration is not a supported way to pause the spinner. Use the running attribute to start and stop the animation - the component manages animation-play-state itself.

/* INCORRECT */
mds-spinner {
  --mds-spinner-duration: 9999s;
}

<!-- CORRECT - remove the attribute to stop -->
<mds-spinner></mds-spinner>