Common incorrect uses of <mds-icon>. 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 <img> or Inline <svg> Instead of <mds-icon>

Using a raw <img src="...svg"> or a hardcoded <svg> literal bypasses the shared path management and cache (in memory and IndexedDB) and the shared theming surface. Use <mds-icon name="..."> with the slug so the icon is cached and takes its color from CSS.

<!-- INCORRECT -->
<img src="/assets/img/svg/mi/baseline/add.svg" alt="">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="..."/></svg>

<!-- CORRECT -->
<mds-icon name="mi/baseline/add"></mds-icon>

Do Not Slot <mds-icon> to Add an Icon to Another Component

<mds-icon> has no slot and accepts no children. Other Magma components expose an icon prop that renders the SVG through the shared service with correct positioning. Slotting <mds-icon> into the default slot of another component is stripped or misaligned.

<!-- INCORRECT -->
<mds-button>
  <mds-icon name="mi/baseline/add"></mds-icon>
  Aggiungi
</mds-button>

<!-- CORRECT -->
<mds-button label="Aggiungi" icon="mi/baseline/add" variant="primary" tone="weak"></mds-button>

Do Not Configure the Path with a Bare Relative Value

setSvgPath (on IconsSetService or the element) treats an absolute path (starting with /) as relative to window.location.origin, and accepts full URLs. A bare relative value like assets/svg/ is accepted but resolved against the current page URL (or the <base href>, when the page has one) on each request, so it silently breaks on nested routes (e.g. /users/42/). Always pass an absolute path or a full URL. Only an empty/whitespace value, or one that is not a URL (e.g. http://), throws (Svg path not recognize ...).

// FRAGILE - resolved relative to the current page, breaks on nested routes
IconsSetService.setSvgPath('assets/svg/');

// CORRECT - absolute path (prefixed with the origin)
IconsSetService.setSvgPath('/assets/svg/');

// CORRECT - full URL (for example a CDN)
IconsSetService.setSvgPath('https://cdn.example.com/svg/');

Do Not Rely on <mds-icon> for an Accessible Label

<mds-icon> renders its inner element with aria-hidden="true". An icon used as the sole indicator inside an interactive control or next to no visible text provides no accessible name by itself. The surrounding control must carry the accessible name.

<!-- INCORRECT - button has no accessible name -->
<button>
  <mds-icon name="mi/baseline/delete"></mds-icon>
</button>

<!-- CORRECT - use mds-button with aria-label -->
<mds-button
  icon="mi/baseline/delete"
  aria-label="Elimina elemento"
  variant="error"
  tone="text"
></mds-button>

Do Not Pierce the Shadow DOM to Style the SVG

The only supported styling surface is ::part(svg) and the inherited CSS fill set on the host. Using >>>, /deep/, or descendant selectors on .icon or internal class names couples code to the Shadow DOM structure and breaks on minor releases.

/* INCORRECT */
mds-icon >>> .icon svg path {
  fill: red;
}
mds-icon .icon {
  transform: rotate(45deg);
}

/* CORRECT */
mds-icon {
  fill: rgb(var(--magma-danger-fg));
}
mds-icon::part(svg) {
  transform: rotate(45deg);
}

Do Not Add .svg Extension to a Slug

The slug passed to name must not include the .svg extension - the service appends it when building the fetch URL. Adding the extension causes a double-.svg path (mi/baseline/close.svg.svg) that returns a 404.

<!-- INCORRECT -->
<mds-icon name="mi/baseline/close.svg"></mds-icon>

<!-- CORRECT -->
<mds-icon name="mi/baseline/close"></mds-icon>

Do Not Override Size with Fixed width and height HTML Attributes

<mds-icon> is a custom element - HTML width and height attributes have no effect on it. Size is controlled by the CSS width property on the host (height follows from aspect-ratio: 1). Use a Tailwind width utility or a custom CSS rule.

<!-- INCORRECT - attributes are ignored -->
<mds-icon name="mi/baseline/star" width="32" height="32"></mds-icon>

<!-- CORRECT - CSS width drives the size -->
<mds-icon name="mi/baseline/star" class="w-1200"></mds-icon>