Common incorrect uses of <mds-table-header-cell>. 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 Outside mds-table-header

<mds-table-header-cell> is a compound child component and relies on traversing the DOM to locate its sibling cells and the <mds-table-body> for sorting. Using it outside <mds-table-header> breaks both the layout and the sort logic.

<!-- INCORRECT -->
<div class="table-head">
  <mds-table-header-cell label="Nome" sortable></mds-table-header-cell>
</div>

<!-- CORRECT -->
<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Nome" sortable></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body><!-- rows --></mds-table-body>
</mds-table>

Do Not Let the Cells Sort a Table with Pages

By default a sortable header cell reorders the rows in the DOM. On a table that shows one page of a larger set that sorts the page on screen, not the data: the first row is not the first of the set.

<!-- INCORRECT -->
<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Numero" sortable></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body><!-- one page of rows --></mds-table-body>
</mds-table>
<mds-paginator pages="12"></mds-paginator>

<!-- CORRECT - the back end sorts, after mdsTableHeaderCellSort -->
<mds-table sorting="external">
  <mds-table-header>
    <mds-table-header-cell label="Numero" sortable sort-key="number"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body><!-- one page of rows --></mds-table-body>
</mds-table>
<mds-paginator pages="12"></mds-paginator>

Do Not Use sortable="false" to Disable Sorting

sortable is a boolean attribute. Stencil reads the exact string "false" as false, but the attribute stays on the element, where attribute selectors and any code that tests for its presence still read it as set. Remove the attribute entirely to produce a non-sortable header cell.

<!-- INCORRECT -->
<mds-table-header-cell label="Stato" sortable="false"></mds-table-header-cell>

<!-- CORRECT -->
<mds-table-header-cell label="Stato"></mds-table-header-cell>

Do Not Slot Content Instead of Using the label Prop

The component renders its label through the label prop; there is no documented slot. Placing text or elements as children of the host puts them in an unsupported slot and they will not appear.

<!-- INCORRECT -->
<mds-table-header-cell sortable>
  <span>Cognome</span>
</mds-table-header-cell>

<!-- CORRECT -->
<mds-table-header-cell label="Cognome" sortable></mds-table-header-cell>

Do Not Pierce Shadow DOM to Style the Sort Button

The sort button is an internal <mds-button> inside the shadow root. Use the documented ::part(action) instead of undocumented selectors.

/* INCORRECT */
mds-table-header-cell >>> .action {
  background-color: red;
}

/* CORRECT */
mds-table-header-cell::part(action) {
  /* use only documented part-level overrides */
}

Do Not Wrap the Cell in a Native <th>

<mds-table-header-cell> already carries role="columnheader" and manages aria-sort. Wrapping it inside a native <th> doubles the ARIA semantics and produces invalid table structure.

<!-- INCORRECT -->
<thead>
  <tr>
    <th><mds-table-header-cell label="Nome"></mds-table-header-cell></th>
  </tr>
</thead>

<!-- CORRECT -->
<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Nome"></mds-table-header-cell>
  </mds-table-header>
</mds-table>