Common incorrect uses of <mds-pref-contrast>. 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 Pass an Invalid mode Value

mode accepts only "more", "system", or "no-preference". Passing any other string (e.g. a legacy name or a boolean) matches no contrast entry: applying it fails with an error when the component tries to apply the CSS class, after the value has already been stored in localStorage (later loads fail too).

<!-- INCORRECT (not a valid ContrastModeType) -->
<mds-pref-contrast mode="high"></mds-pref-contrast>
<mds-pref-contrast mode="true"></mds-pref-contrast>

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

Do Not Listen for the Native change Event

The component emits the documented mdsPrefChange event; there is no native change event bubbling out of the shadow DOM. Listening for change on the host element will never fire.

<!-- INCORRECT -->
<mds-pref-contrast id="cp"></mds-pref-contrast>
<script>
  document.getElementById('cp').addEventListener('change', handler);
</script>

<!-- CORRECT -->
<mds-pref-contrast id="cp"></mds-pref-contrast>
<script>
  document.getElementById('cp').addEventListener('mdsPrefChange', handler);
</script>

Do Not Write @media (prefers-contrast: more) Overrides in App Code

The design system manages high-contrast tokens automatically through the pref-contrast-more class (and pref-contrast-system, which follows the OS) applied to <html> by <mds-pref-contrast>: the semantic roles are promoted under both. Hand-rolling media query overrides duplicates that logic and breaks when the user picks system (OS-driven) vs. more (explicit choice), because the two code paths diverge.

/* INCORRECT */
@media (prefers-contrast: more) {
  .my-card {
    border: 2px solid black;
  }
}

/* CORRECT - paint with a role: it is promoted under high contrast, explicit or OS-driven */
.my-card {
  border: 1px solid rgb(var(--magma-border-default));
}

Do Not Set mode="false" to Reset the Preference

Boolean idioms do not apply here. mode is a string union - setting it to "false" is not a valid value and will not clear the preference. Leave the mode attribute out of the markup to let the component fall back to the last persisted value; unsetting it at runtime (removing the attribute or setting the prop to undefined) fails like an invalid value.

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

<!-- CORRECT (omit mode) -->
<mds-pref-contrast></mds-pref-contrast>