Common incorrect uses of <mds-pref-theme-item>. 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 the Item Outside Its Parent

<mds-pref-theme-item> is a compound child that must be a direct slot child of <mds-pref-theme>. Used standalone it emits selection events that are never handled, and it never receives coordinated deselection of siblings.

<!-- INCORRECT -->
<mds-pref-theme-item name="cool" label="Freddo" scheme="all"></mds-pref-theme-item>

<!-- CORRECT -->
<mds-pref-theme name="default" scheme="all">
  <mds-pref-theme-item name="cool" label="Freddo" scheme="all"></mds-pref-theme-item>
</mds-pref-theme>

Do Not Set selected Manually to Coordinate Multi-Item State

Setting selected on one item does not deselect the others - the parent is the only actor that can coordinate the whole group. When it loads it marks only the item matching the active theme, overwriting the selected in the markup; a value set later from script leaves several items marked. Drive initial selection through the parent’s name prop or by letting the user click.

<!-- INCORRECT - the parent overwrites both on load and marks "default" -->
<mds-pref-theme name="default" scheme="all">
  <mds-pref-theme-item name="default" label="Predefinito" scheme="all"></mds-pref-theme-item>
  <mds-pref-theme-item name="cool" label="Freddo" scheme="all" selected></mds-pref-theme-item>
  <mds-pref-theme-item name="warm" label="Caldo" scheme="all" selected></mds-pref-theme-item>
</mds-pref-theme>

<!-- CORRECT - set the active theme on the parent; it marks the matching child -->
<mds-pref-theme name="cool" scheme="all">
  <mds-pref-theme-item name="default" label="Predefinito" scheme="all"></mds-pref-theme-item>
  <mds-pref-theme-item name="cool" label="Freddo" scheme="all"></mds-pref-theme-item>
  <mds-pref-theme-item name="warm" label="Caldo" scheme="all"></mds-pref-theme-item>
</mds-pref-theme>

Do Not Listen for Native click Instead of the Component Event

A raw click carries no detail: you have to read name back from the element, and you lose the scheme. Listen for the documented mdsPrefThemeItemSelect event instead, whose detail carries { name, scheme }.

<!-- INCORRECT -->
<script>
  document.querySelector('mds-pref-theme-item').addEventListener('click', (e) => {
    applyTheme(e.target.getAttribute('name'));
  });
</script>

<!-- CORRECT -->
<script>
  document.querySelector('mds-pref-theme-item').addEventListener('mdsPrefThemeItemSelect', (e) => {
    applyTheme(e.detail.name);
  });
</script>

Do Not Pierce Shadow DOM to Style the Inner Button

The supported customization surface is the five --mds-pref-theme-item-* CSS custom properties. Targeting internal selectors or ::part() names not present in this component’s public API couples your code to the implementation and will break on minor releases.

/* INCORRECT */
mds-pref-theme-item >>> mds-button {
  font-weight: bold;
}
mds-pref-theme-item .theme-preview {
  border: 2px solid red;
}

/* CORRECT */
mds-pref-theme-item[name="warm"] {
  --mds-pref-theme-item-color-variant-primary: rgb(var(--magma-accent-emphasis-hover));
  --mds-pref-theme-item-color-background: rgb(var(--magma-wash-strong));
}

Do Not Use an Invalid scheme Value

scheme only accepts "all", "light", or "dark". Other strings are not validated: when the item is picked the parent stores them and writes no pref-theme-scheme-* class on <html>, so the theme is not constrained to the mode you meant.

<!-- INCORRECT -->
<mds-pref-theme-item name="cool" scheme="light-only"></mds-pref-theme-item>
<mds-pref-theme-item name="warm" scheme="night"></mds-pref-theme-item>

<!-- CORRECT -->
<mds-pref-theme-item name="cool" scheme="light"></mds-pref-theme-item>
<mds-pref-theme-item name="warm" scheme="dark"></mds-pref-theme-item>