Common incorrect uses of <mds-zero>. 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 Put Text in the Default Slot

The default slot is reserved for the illustration or image. Text placed there is not constrained by the contents max-width, is not centered consistently, and falls outside the structured three-zone layout. Put headings and descriptions in slot="content".

<!-- INCORRECT -->
<mds-zero>
  <mds-text typography="h5">Nessun elemento</mds-text>
  <mds-text typography="detail">Crea il primo elemento per iniziare.</mds-text>
</mds-zero>

<!-- CORRECT -->
<mds-zero>
  <mds-text typography="h5" slot="content">Nessun elemento</mds-text>
  <mds-text typography="detail" slot="content">Crea il primo elemento per iniziare.</mds-text>
</mds-zero>

Do Not Put the Illustration in slot="content"

Placing an image or <mds-img> inside slot="content" wraps it in the max-width-constrained, centered-text zone. The default slot renders above that zone with full layout freedom and is the correct home for illustrations.

<!-- INCORRECT -->
<mds-zero>
  <mds-img src="./assets/illustrations/empty.svg" slot="content"></mds-img>
  <mds-text typography="h5" slot="content">Nessun documento</mds-text>
</mds-zero>

<!-- CORRECT -->
<mds-zero>
  <mds-img src="./assets/illustrations/empty.svg"></mds-img>
  <mds-text typography="h5" slot="content">Nessun documento</mds-text>
</mds-zero>

Do Not Put the CTA in slot="content"

A button placed in slot="content" ends up inside the centered-text block rather than the footer zone; it loses the auto-centering and the correct spacing the actions zone provides. Use slot="action" for any interactive control.

<!-- INCORRECT -->
<mds-zero>
  <mds-img src="./assets/illustrations/empty.svg"></mds-img>
  <mds-text typography="h5" slot="content">Nessun progetto</mds-text>
  <mds-button label="Nuovo progetto" variant="primary" slot="content"></mds-button>
</mds-zero>

<!-- CORRECT -->
<mds-zero>
  <mds-img src="./assets/illustrations/empty.svg"></mds-img>
  <mds-text typography="h5" slot="content">Nessun progetto</mds-text>
  <mds-button label="Nuovo progetto" variant="primary" slot="action"></mds-button>
</mds-zero>

Do Not Use a Raw <button> or <a> in the Action Slot

The action slot is designed for <mds-button>. A raw <button> or <a> will not inherit Magma theming, focus styles, or size tokens. Use <mds-button> with href if link behavior is needed.

<!-- INCORRECT -->
<mds-zero>
  <mds-img src="./assets/illustrations/empty.svg"></mds-img>
  <mds-text typography="h5" slot="content">Nessun report</mds-text>
  <button slot="action" class="btn-primary">Crea report</button>
</mds-zero>

<!-- CORRECT -->
<mds-zero>
  <mds-img src="./assets/illustrations/empty.svg"></mds-img>
  <mds-text typography="h5" slot="content">Nessun report</mds-text>
  <mds-button slot="action" label="Crea report" variant="primary" tone="strong"></mds-button>
</mds-zero>

Do Not Pierce Shadow DOM to Style Internal Zones

::part(contents) and ::part(actions) are the documented customization surface for the wrapper zones. Do not target internal class names (.contents, .actions) via >>> or /deep/ - those are implementation details that can change without notice.

/* INCORRECT */
mds-zero >>> .contents {
  max-width: 600px;
}

/* CORRECT */
mds-zero {
  --mds-zero-contents-max-width: 600px;
}
/* or, for layout overrides: */
mds-zero::part(contents) {
  align-items: flex-start;
}