Common incorrect uses of <mds-pref-theme>. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind colour utilities, raw native event listening) live in agents/anti-patterns.md - they apply here too but are not repeated.

Do Not Use the Component Outside <mds-pref>

<mds-pref-theme> is a compound sub-part designed to slot inside <mds-pref>. As a standalone widget it still applies and persists the theme, but it leaves the panel: <mds-pref> can no longer forward size changes to it, nor lock the <mds-pref-mode> item that its scheme forbids.

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

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

Do Not Put Plain Text or Arbitrary HTML in the Default Slot

The default slot is reserved exclusively for <mds-pref-theme-item> elements. Any other content bypasses the component’s internal selection management and will not trigger theme application.

<!-- INCORRECT -->
<mds-pref>
  <mds-pref-theme name="default" scheme="all">
    <button>Predefinito</button>
    <span>Estate</span>
  </mds-pref-theme>
</mds-pref>

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

Do Not Use an Invalid Theme Name

The name prop must match the pattern ^[a-z]+(-[a-z]+)*$ (lowercase letters and hyphens only). Any other value - including uppercase, underscores, or spaces - throws a runtime error when the component tries to apply the theme class on <html>.

<!-- INCORRECT -->
<mds-pref-theme name="My Theme" scheme="all">...</mds-pref-theme>
<mds-pref-theme name="my_theme" scheme="all">...</mds-pref-theme>
<mds-pref-theme name="MyTheme" scheme="all">...</mds-pref-theme>

<!-- CORRECT -->
<mds-pref-theme name="warm" scheme="all">...</mds-pref-theme>

Do Not Listen for the Native change Event

<mds-pref-theme> emits mdsPrefThemeChange - a documented custom event with a typed { name, scheme } detail. Listening for the native change event will not fire because theme selection is handled entirely inside shadow DOM.

<!-- INCORRECT -->
<script>
  document.querySelector('mds-pref-theme').addEventListener('change', (e) => {
    console.log(e.target.value); // undefined - wrong event, wrong detail shape
  });
</script>

<!-- CORRECT -->
<script>
  document.querySelector('mds-pref-theme').addEventListener('mdsPrefThemeChange', (e) => {
    console.log(e.detail.name, e.detail.scheme);
  });
</script>

Do Not Give the Parent and the Child Different Sizes

<mds-pref> forwards its own size to all mds-pref-* children only when that prop changes after load, not from the initial markup, and then it overwrites theirs. A size on <mds-pref-theme> that differs from the parent’s renders the child’s value at load and flips to the parent’s on its next change: give the children one size.

<!-- INCORRECT -->
<mds-pref size="sm">
  <mds-pref-theme size="md" name="default" scheme="all">
    <mds-pref-theme-item label="Predefinito" name="default" scheme="all"></mds-pref-theme-item>
  </mds-pref-theme>
</mds-pref>

<!-- CORRECT -->
<mds-pref>
  <mds-pref-theme size="sm" name="default" scheme="all">
    <mds-pref-theme-item label="Predefinito" name="default" scheme="all"></mds-pref-theme-item>
  </mds-pref-theme>
</mds-pref>