Common incorrect uses of <mds-pref>. 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 Place Non-Pref Children in the Default Slot

The default slot accepts only mds-pref-animation, mds-pref-consumption, mds-pref-contrast, mds-pref-language, mds-pref-mode and mds-pref-theme children. Other elements are outside the documented content: they render as extra rows of the panel and take part in no coordination.

<!-- INCORRECT -->
<mds-pref>
  <div class="custom-section">Tema</div>
  <mds-pref-mode></mds-pref-mode>
</mds-pref>

<!-- CORRECT -->
<mds-pref>
  <mds-pref-mode></mds-pref-mode>
</mds-pref>

Do Not Use mds-pref-* Children Outside <mds-pref>

Each control applies and stores its own preference, but the coordination between the controls of a panel lives in the parent: a scheme-constrained mds-pref-theme item locks the matching mds-pref-mode item only inside <mds-pref>, and only the parent forwards size changes. Group the controls of a panel in <mds-pref>.

<!-- INCORRECT -->
<mds-pref-mode></mds-pref-mode>
<mds-pref-theme>
  <mds-pref-theme-item name="default"></mds-pref-theme-item>
  <mds-pref-theme-item name="cool"></mds-pref-theme-item>
</mds-pref-theme>

<!-- CORRECT -->
<mds-pref>
  <mds-pref-mode></mds-pref-mode>
  <mds-pref-theme>
    <mds-pref-theme-item name="default"></mds-pref-theme-item>
    <mds-pref-theme-item name="cool"></mds-pref-theme-item>
  </mds-pref-theme>
</mds-pref>

Do Not Set controller="false" to Turn Off Controller Mode

controller is a boolean attribute, and a false boolean is an absent attribute (agents/conventions.md). The runtime parses the string "false" as false, so the panel shows, but the attribute is still on the element until the first render, so [controller] attribute selectors (the one that hides the panel included) and any code that reads the attribute see it set. Remove the attribute entirely to switch back to visible mode.

<!-- INCORRECT -->
<mds-pref controller="false">
  <mds-pref-mode></mds-pref-mode>
</mds-pref>

<!-- CORRECT -->
<mds-pref>
  <mds-pref-mode></mds-pref-mode>
</mds-pref>

Do Not Listen for the Native change Event to Detect Preference Changes

The controls fire no native change event. Use the documented mdsPrefChange event emitted by each mds-pref-* child; note that a child emits it on page load too, with only the preference name in detail.

<!-- INCORRECT -->
<script>
  document.querySelector('mds-pref').addEventListener('change', (e) => {
    console.log(e);
  });
</script>

<!-- CORRECT -->
<script>
  document.querySelector('mds-pref-mode').addEventListener('mdsPrefChange', (e) => {
    console.log(e.detail.preference);
  });
</script>