Common incorrect uses of <mds-modal>. 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 opened="false" to Close the Modal

A false boolean is an absent attribute (agents/conventions.md). The runtime does parse the string "false" as false, so the modal stays closed, but the attribute is still on the element until the first render, so [opened] attribute selectors and any code that reads the attribute see it set. Remove the attribute; from JavaScript set the prop to undefined (false works too: the component turns it into undefined).

<!-- INCORRECT -->
<mds-modal id="dialogo" opened="false"></mds-modal>

<!-- CORRECT -->
<mds-modal id="dialogo"></mds-modal>

Do Not Put Content in the window Slot Without Replacing the Entire Chrome

The window slot completely bypasses the built-in surface, header/footer regions, and close button. Do not use it to add a header element while expecting the default content area and close button to still render - they will not.

<!-- INCORRECT: only the slotted header renders; default slot and close button are suppressed -->
<mds-modal id="modal">
  <header slot="window" class="p-400">Titolo</header>
  <div>Contenuto del dialogo</div>
</mds-modal>

<!-- CORRECT: use slot="top" for a sticky header, default slot for body -->
<mds-modal id="modal">
  <header slot="top" class="p-400 bg-surface-overlay">Titolo</header>
  <div class="p-400">Contenuto del dialogo</div>
</mds-modal>

Do Not Reach Into Shadow Parts to Style the Window

The only supported customization surface is --mds-modal-* CSS custom properties and the documented shadow parts (dialog, window, action-close). Targeting internal shadow selectors couples your code to implementation details that will break on minor releases.

/* INCORRECT */
mds-modal >>> .window-content {
  padding: 0;
}
mds-modal::part(window) > div {
  border: 2px solid red;
}

/* CORRECT */
mds-modal {
  --mds-modal-window-background: rgb(var(--magma-surface-overlay));
  --mds-modal-window-radius: var(--magma-radius-xl);
  --mds-modal-window-distance: calc(var(--spacing) * 400);
}

Do Not Listen for Native click on the Backdrop to Close

mds-modal emits mdsModalClose when it closes (and mdsModalHide when the animation finishes). Listening for a raw click on the host or backdrop is fragile - the event target varies by browser and shadow DOM boundary, and your handler ignores interaction="strict".

// INCORRECT
document.getElementById('modal').addEventListener('click', (e) => {
  if (e.target === e.currentTarget) modal.opened = undefined;
});

// CORRECT
document.getElementById('modal').addEventListener('mdsModalClose', () => {
  modal.opened = undefined;
});

Do Not Use <dialog> Directly When <mds-modal> Is Available

Using a raw <dialog> element bypasses the system’s managed animation, body-scroll locking, touch-swipe dismissal, and design-token theming. Always use <mds-modal> for overlays in a Magma application.

<!-- INCORRECT -->
<dialog id="raw-dialog">
  <p>Contenuto del dialogo</p>
  <button>Chiudi</button>
</dialog>

<!-- CORRECT -->
<mds-modal id="modal">
  <div class="p-400">
    <mds-text>Contenuto del dialogo</mds-text>
  </div>
</mds-modal>