Common incorrect uses of <mds-tree>. 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 Non-mds-tree-item Elements Directly in <mds-tree>

The default slot of <mds-tree> accepts only <mds-tree-item> elements. Placing raw HTML or other components as direct children breaks depth seeding and compound communication.

<!-- INCORRECT -->
<mds-tree>
  <li>Voce uno</li>
  <li>Voce due</li>
</mds-tree>

<!-- CORRECT -->
<mds-tree>
  <mds-tree-item label="Voce uno"></mds-tree-item>
  <mds-tree-item label="Voce due"></mds-tree-item>
</mds-tree>

Do Not Slot <mds-tree-item> Outside <mds-tree>

<mds-tree-item> is a compound child and depends on <mds-tree> for depth seeding and prop cascading. Using it standalone produces undefined indentation and no toggle coordination.

<!-- INCORRECT -->
<div class="menu">
  <mds-tree-item label="Impostazioni">
    <mds-tree-item label="Profilo"></mds-tree-item>
  </mds-tree-item>
</div>

<!-- CORRECT -->
<mds-tree>
  <mds-tree-item label="Impostazioni">
    <mds-tree-item label="Profilo"></mds-tree-item>
  </mds-tree-item>
</mds-tree>

Do Not Use the action Slot on <mds-tree> Itself

The action slot is defined on <mds-tree-item>, not on <mds-tree>. Placing content with slot="action" on the root container has no effect; the slot is silently discarded.

<!-- INCORRECT -->
<mds-tree>
  <mds-button slot="action" icon="mi/baseline/add" title="Aggiungi"></mds-button>
  <mds-tree-item label="Documenti"></mds-tree-item>
</mds-tree>

<!-- CORRECT -->
<mds-tree>
  <mds-tree-item label="Documenti">
    <mds-button
      slot="action"
      icon="mi/baseline/add"
      variant="dark"
      tone="text"
      title="Aggiungi"
    ></mds-button>
  </mds-tree-item>
</mds-tree>

Do Not Listen for Native click or change to Detect Expand/Collapse

A native click tells you neither which item changed nor whether it opened or closed. Use the documented events emitted by <mds-tree-item>: mdsTreeItemCollapse when an item closes, mdsTreeItemExpand when an item marked async is asked to open.

<!-- INCORRECT -->
<mds-tree id="albero">
  <mds-tree-item label="Sezione A">
    <mds-tree-item label="Voce 1"></mds-tree-item>
  </mds-tree-item>
</mds-tree>

<script>
  // unreliable - a click says nothing about the expanded state
  document.getElementById('albero').addEventListener('click', handler);
</script>

<!-- CORRECT -->
<script>
  document.getElementById('albero').addEventListener('mdsTreeItemCollapse', (event) => {
    console.log('collassato:', event.detail.element.label);
  });
</script>

Do Not Set expanded="false" to Collapse

Stencil reads the exact string "false" as false, but the attribute stays on the element, where attribute selectors and presence checks (hasAttribute('expanded')) still read the tree as expanded. Remove the attribute (or set the prop to undefined) to collapse.

<!-- INCORRECT -->
<mds-tree expanded="false">
  <mds-tree-item label="Sezione"></mds-tree-item>
</mds-tree>

<!-- CORRECT -->
<mds-tree>
  <mds-tree-item label="Sezione"></mds-tree-item>
</mds-tree>

Do Not Use Undocumented ::part() Targets or >>> to Style Internals

The supported customization surface for <mds-tree> is the --mds-tree-* CSS custom properties. Shadow-DOM piercing (>>>, /deep/) is not supported and <mds-tree> exposes no ::part(). Coupling to internal selectors will break on minor releases.

/* INCORRECT */
mds-tree >>> .header {
  background: red;
}

/* CORRECT */
mds-tree {
  --mds-tree-label-hover-background: rgb(var(--magma-wash-base));
  --mds-tree-branch-border-color: rgb(var(--magma-border-muted));
}

Do Not Wrap <mds-tree-item> in an Extra Div to Add Spacing

Inserting wrapper elements breaks the compound slot protocol - <mds-tree> communicates with items via querySelectorAll and slot assignment, and wrappers interrupt both. Use the documented CSS custom properties for spacing instead.

<!-- INCORRECT -->
<mds-tree>
  <div style="margin-bottom: 8px;">
    <mds-tree-item label="Categoria A"></mds-tree-item>
  </div>
  <div style="margin-bottom: 8px;">
    <mds-tree-item label="Categoria B"></mds-tree-item>
  </div>
</mds-tree>

<!-- CORRECT -->
<mds-tree>
  <mds-tree-item label="Categoria A"></mds-tree-item>
  <mds-tree-item label="Categoria B"></mds-tree-item>
</mds-tree>