Common incorrect uses of <mds-stepper-bar-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 Outside <mds-stepper-bar>

<mds-stepper-bar-item> is a compound child - its state (done, current, index) is resolved by the parent. Using it standalone leaves isDone, isCurrent and index at their defaults and produces broken visual output.

<!-- INCORRECT -->
<mds-stepper-bar-item icon="mi/baseline/person" label="Dati personali"></mds-stepper-bar-item>

<!-- CORRECT -->
<mds-stepper-bar items-done="1">
  <mds-stepper-bar-item icon="mi/baseline/person" icon-checked="mi/baseline/done" label="Dati personali"></mds-stepper-bar-item>
  <mds-stepper-bar-item icon="mi/baseline/location-on" icon-checked="mi/baseline/done" label="Indirizzo"></mds-stepper-bar-item>
</mds-stepper-bar>

Do Not Set done="false" or current="false" as Strings

done and current are boolean props. Stencil reads "false" as false and, since both are 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. To turn them off, remove the attribute or let the parent manage state via items-done.

<!-- INCORRECT -->
<mds-stepper-bar-item done="false" current="false" icon="mi/baseline/payment" label="Pagamento"></mds-stepper-bar-item>

<!-- CORRECT -->
<mds-stepper-bar-item icon="mi/baseline/payment" label="Pagamento"></mds-stepper-bar-item>

Do Not Override State Manually When the Parent Manages It

done and current are driven by <mds-stepper-bar>’s items-done prop. Setting them on individual items and also setting items-done creates conflicting state that the parent overwrites when it loads and whenever items-done changes.

<!-- INCORRECT -->
<mds-stepper-bar items-done="2">
  <mds-stepper-bar-item done current icon="mi/baseline/person" label="Dati personali"></mds-stepper-bar-item>
  <mds-stepper-bar-item icon="mi/baseline/location-on" label="Indirizzo"></mds-stepper-bar-item>
</mds-stepper-bar>

<!-- CORRECT -->
<mds-stepper-bar items-done="2">
  <mds-stepper-bar-item icon="mi/baseline/person" icon-checked="mi/baseline/done" label="Dati personali"></mds-stepper-bar-item>
  <mds-stepper-bar-item icon="mi/baseline/location-on" icon-checked="mi/baseline/done" label="Indirizzo"></mds-stepper-bar-item>
</mds-stepper-bar>

Do Not Wrap Items in Extra HTML Elements

Each item numbers itself among its own siblings, and the parent’s track lays out its direct children: a wrapper <div> or <li> turns every wrapped item into “Step 1” and breaks the track layout and scroll alignment.

<!-- INCORRECT -->
<mds-stepper-bar items-done="1">
  <div>
    <mds-stepper-bar-item icon="mi/baseline/person" label="Dati personali"></mds-stepper-bar-item>
  </div>
  <div>
    <mds-stepper-bar-item icon="mi/baseline/location-on" label="Indirizzo"></mds-stepper-bar-item>
  </div>
</mds-stepper-bar>

<!-- CORRECT -->
<mds-stepper-bar items-done="1">
  <mds-stepper-bar-item icon="mi/baseline/person" icon-checked="mi/baseline/done" label="Dati personali"></mds-stepper-bar-item>
  <mds-stepper-bar-item icon="mi/baseline/location-on" icon-checked="mi/baseline/done" label="Indirizzo"></mds-stepper-bar-item>
</mds-stepper-bar>

Do Not Use Undocumented ::part() Targets to Style the Icon or Progress

The only documented shadow part is badge. Targeting internals such as ::part(icon) or ::part(progress) couples code to the private Shadow DOM structure and will break on minor releases. Use the --mds-stepper-bar-item-* CSS custom properties instead.

/* INCORRECT */
mds-stepper-bar-item::part(icon) {
  background-color: purple;
}
mds-stepper-bar-item::part(progress) {
  height: 6px;
}

/* CORRECT */
mds-stepper-bar-item {
  --mds-stepper-bar-item-icon-background-current: rgb(var(--magma-accent-emphasis));
  --mds-stepper-bar-item-progress-thickness: 6px;
}

Do Not Omit label or icon

Both are required props. An item without label has no accessible or visual description; an item without icon leaves the icon area empty and breaks the progress-line layout.

<!-- INCORRECT -->
<mds-stepper-bar items-done="1">
  <mds-stepper-bar-item label="Dati personali"></mds-stepper-bar-item>
  <mds-stepper-bar-item icon="mi/baseline/location-on"></mds-stepper-bar-item>
</mds-stepper-bar>

<!-- CORRECT -->
<mds-stepper-bar items-done="1">
  <mds-stepper-bar-item icon="mi/baseline/person" label="Dati personali"></mds-stepper-bar-item>
  <mds-stepper-bar-item icon="mi/baseline/location-on" label="Indirizzo"></mds-stepper-bar-item>
</mds-stepper-bar>