Common incorrect uses of <mds-pref-animation>. 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 Turn Off with mode="false" or Remove the Attribute to Reset

mode is a string union (reduce | system | no-preference), not a boolean. A value outside the union, such as "false" or "none", does not disable the component: it has no entry in the component’s mode table, so applying it fails with an error, after the value has already been stored in localStorage (later loads fail too). Without mode, the component restores the persisted choice or falls back to system.

<!-- INCORRECT - not a valid mode value -->
<mds-pref-animation mode="false"></mds-pref-animation>
<mds-pref-animation mode="none"></mds-pref-animation>

<!-- CORRECT - use an explicit valid mode -->
<mds-pref-animation mode="system"></mds-pref-animation>

Do Not Listen to Raw change Events

<mds-pref-animation> emits mdsPrefChange; no native change event is fired.

<!-- INCORRECT -->
<mds-pref id="prefs">
  <mds-pref-animation></mds-pref-animation>
</mds-pref>

<script>
  document.getElementById('prefs').addEventListener('change', handler);
</script>

<!-- CORRECT -->
<script>
  document.getElementById('prefs').addEventListener('mdsPrefChange', handler);
</script>

Do Not Hand-Roll Animation Preference Handling on <html>

The component already applies pref-animation-reduce, pref-animation-system, or pref-animation-no-preference to <html> and persists the choice in localStorage. Duplicating this logic conflicts with the component’s state and causes double-writes.

/* INCORRECT - duplicates the component's own logic */
html.custom-reduce-motion * {
  animation: none !important;
}

<!-- CORRECT - rely on the class the component sets -->
<!-- The component sets pref-animation-reduce on <html>;
     target that class in your own CSS if needed -->

/* Extend, do not replace */
html.pref-animation-reduce .my-widget {
  transition: none;
}