Common incorrect uses of <mds-pref-mode>. 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 <mds-pref-mode> Outside <mds-pref>

<mds-pref-mode> is a compound child: <mds-pref> forwards size changes to it and locks the mode item that a scheme-constrained <mds-pref-theme> forbids (it sets lockedScheme). As a standalone widget it still applies and persists the mode, but nothing coordinates it with the theme.

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

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

Do Not Set transition="false" to Disable the Overlay

transition is a string enum, not a boolean. "false" is not a valid value: it only happens to fall through to the no-overlay branch, with no guarantee across releases. Use transition="none" to opt out of the overlay animation.

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

<!-- CORRECT -->
<mds-pref-mode transition="none"></mds-pref-mode>

Do Not Listen for Native change Events Instead of mdsPrefChange

The component does not emit or bubble native change events out of the shadow DOM. Always listen for the documented mdsPrefChange custom event.

<!-- INCORRECT -->
<script>
  document.querySelector('mds-pref-mode').addEventListener('change', handler);
</script>

<!-- CORRECT -->
<script>
  document.querySelector('mds-pref-mode').addEventListener('mdsPrefChange', handler);
</script>

Do Not Override Mode Classes on <html> Directly

The component manages pref-mode-light, pref-mode-dark, and pref-mode-system classes on <html> itself. Adding or removing these by hand races with the component and will be overwritten on the next mode change. Drive the mode exclusively through the mode prop.

<!-- INCORRECT -->
<script>
  document.documentElement.classList.add('pref-mode-dark');
</script>

<!-- CORRECT -->
<mds-pref>
  <mds-pref-mode mode="dark"></mds-pref-mode>
</mds-pref>

Do Not Size Only One Child of the Panel

<mds-pref> forwards its own size to its preference children only when that prop changes after load, not from the initial markup, so in markup each child carries its own size. Setting it on <mds-pref-mode> alone when siblings exist produces inconsistent tab sizes across the panel.

<!-- INCORRECT -->
<mds-pref>
  <mds-pref-mode size="sm"></mds-pref-mode>
  <mds-pref-contrast></mds-pref-contrast>
</mds-pref>

<!-- CORRECT -->
<mds-pref>
  <mds-pref-mode size="sm"></mds-pref-mode>
  <mds-pref-contrast size="sm"></mds-pref-contrast>
</mds-pref>

Do Not Target the Injected Overlay to Customize It

The overlay element is injected into document.body at runtime with inline styles, which win over a class selector anyway. Do not target it by class name or adjust its properties through JavaScript. Use the documented --mds-pref-mode-overlay-* CSS custom properties instead.

/* INCORRECT */
.mds-pref-mode-overlay {
  background-color: black;
  z-index: 99999;
}

/* CORRECT */
mds-pref-mode {
  --mds-pref-mode-overlay-show-duration: 400ms;
  --mds-pref-mode-overlay-z-index: 9000;
}