Common incorrect uses of <mds-policy-ai>. 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 Slot Custom Content Into the Component

<mds-policy-ai> has no public slots. All customization is done through the headline, description, and href props. Placing children inside the element has no effect - the shadow DOM ignores them entirely.

<!-- INCORRECT -->
<mds-policy-ai>
  <p>Contenuto generato con intelligenza artificiale.</p>
</mds-policy-ai>

<!-- CORRECT -->
<mds-policy-ai
  description="Contenuto generato con intelligenza artificiale."
></mds-policy-ai>

Do Not Use variant to Choose a Color - Use It to Choose a Surface

variant is not a color knob. It selects the entire rendering surface (icon, chip, card, banner), each carrying a distinct placement intent. Choosing a value because it looks lighter or darker will produce the wrong layout for the context.

<!-- INCORRECT - choosing "icon" because the space is small while also expecting the description on the page: the icon shows it only in a hover tooltip -->
<mds-policy-ai
  variant="icon"
  description="Questo testo e' stato generato con AI e potrebbe contenere inesattezze. Verifica le informazioni."
></mds-policy-ai>

<!-- CORRECT - "card" renders the description body as intended in compact contexts -->
<mds-policy-ai
  variant="card"
  description="Questo testo e' stato generato con AI e potrebbe contenere inesattezze. Verifica le informazioni."
></mds-policy-ai>

Do Not Pierce the Shadow DOM to Restyle Inner Components

The shadow parts chip, icon, card, and banner are the documented customization surface. Reaching into undocumented internals with >>>, /deep/, or class selectors will break on any minor release.

/* INCORRECT */
mds-policy-ai >>> mds-chip {
  background-color: red;
}

/* CORRECT - target the part and set the inner component's own CSS custom property */
mds-policy-ai::part(banner) {
  --mds-banner-radius: var(--magma-radius-xl);
}

Do Not Wrap in a Native <a> to Override the Policy Link

The component manages its own href routing on every variant. Nesting it inside an <a> creates overlapping interactive controls, breaks keyboard navigation, and does not override the internal link - it adds a second, outer link on top.

<!-- INCORRECT -->
<a href="https://example.com/policy-ai">
  <mds-policy-ai variant="chip"></mds-policy-ai>
</a>

<!-- CORRECT - override the href prop to point to the tenant-specific page -->
<mds-policy-ai
  variant="chip"
  href="https://example.com/policy-ai"
></mds-policy-ai>

Do Not Use headline on the Card Variant - It Has No Effect There

The card variant does not render a headline - only description is shown. Passing headline to a card is silently ignored. Use variant="banner" when both a title and a body are required.

<!-- INCORRECT - headline is ignored by variant="card" -->
<mds-policy-ai
  variant="card"
  headline="Contenuto generato con AI"
  description="Questo estratto e' stato generato automaticamente."
></mds-policy-ai>

<!-- CORRECT - use banner when both headline and description must appear -->
<mds-policy-ai
  variant="banner"
  headline="Contenuto generato con AI"
  description="Questo estratto e' stato generato automaticamente."
></mds-policy-ai>