Common incorrect uses of <mds-button-group>. 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 Nest Raw <button> Elements Inside the Group

The group is part of the Magma component system and is designed to host <mds-button> (and sibling mds-* action) components. Raw <button> elements bypass theming, focus styles, and accessibility defaults.

<!-- INCORRECT -->
<mds-button-group>
  <button class="btn">Salva</button>
  <button class="btn">Annulla</button>
</mds-button-group>

<!-- CORRECT -->
<mds-button-group>
  <mds-button label="Salva" variant="primary" tone="strong"></mds-button>
  <mds-button label="Annulla" variant="dark" tone="outline"></mds-button>
</mds-button-group>

Do Not Wrap the Group in an Anchor

<mds-button-group> contains interactive controls; nesting the whole group inside <a> creates nested interactives, breaks keyboard semantics, and fails accessibility audits. Use the href prop on individual <mds-button> elements instead.

<!-- INCORRECT -->
<a href="/azioni">
  <mds-button-group>
    <mds-button label="Vai" variant="primary"></mds-button>
  </mds-button-group>
</a>

<!-- CORRECT -->
<mds-button-group>
  <mds-button label="Vai" href="/azioni" variant="primary"></mds-button>
</mds-button-group>

Do Not Omit aria-label on Icon-Only Buttons Inside a Group

Grouping icon-only buttons does not remove the requirement for an accessible name on each child. Without it mds-button falls back to the last segment of the icon slug (“undo”), which names the icon, not the action.

<!-- INCORRECT -->
<mds-button-group>
  <mds-button icon="mi/baseline/undo" variant="dark" tone="text"></mds-button>
  <mds-button icon="mi/baseline/redo" variant="dark" tone="text"></mds-button>
</mds-button-group>

<!-- CORRECT -->
<mds-button-group>
  <mds-button icon="mi/baseline/undo" aria-label="Annulla" variant="dark" tone="text"></mds-button>
  <mds-button icon="mi/baseline/redo" aria-label="Ripristina" variant="dark" tone="text"></mds-button>
</mds-button-group>

Do Not Nest <mds-button-group> Inside Another Group

The component is a flat layout primitive; nesting groups creates redundant flex containers that break the consistent spacing and group visual coherence. Keep the hierarchy flat.

<!-- INCORRECT -->
<mds-button-group>
  <mds-button-group>
    <mds-button label="Salva" variant="primary" tone="strong"></mds-button>
    <mds-button label="Bozza" variant="primary" tone="outline"></mds-button>
  </mds-button-group>
  <mds-button label="Annulla" variant="dark" tone="text"></mds-button>
</mds-button-group>

<!-- CORRECT -->
<mds-button-group>
  <mds-button label="Salva" variant="primary" tone="strong"></mds-button>
  <mds-button label="Bozza" variant="primary" tone="outline"></mds-button>
  <mds-button label="Annulla" variant="dark" tone="text"></mds-button>
</mds-button-group>

Do Not Override Spacing with Inline Styles

The component manages its own gap via a design-token-backed CSS value. Setting inline gap, margin, or padding on the host or child buttons breaks the token contract and may produce inconsistent spacing across themes.

/* INCORRECT */
mds-button-group {
  gap: 16px;
}
mds-button-group mds-button {
  margin-right: 8px;
}

/* CORRECT - let the component handle spacing; style only what it exposes */
mds-button-group {
  /* no gap or margin overrides needed */
}