Common incorrect uses of <mds-pref-language-item>. 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 the Item Outside Its Parent

<mds-pref-language-item> is a compound child and relies on <mds-pref-language> for selection management, dropdown layout, and language persistence. Using it standalone leaves the click handler dangling and the selection state unmanaged.

<!-- INCORRECT -->
<mds-pref-language-item code="it"></mds-pref-language-item>

<!-- CORRECT -->
<mds-pref-language>
  <mds-pref-language-item code="it"></mds-pref-language-item>
</mds-pref-language>

Do Not Set the Display Label Manually

The item derives its label from the code prop via the bundled dictionary. Attempting to pass display text in the default slot or as an attribute is not supported and will be ignored by the render function.

<!-- INCORRECT -->
<mds-pref-language-item code="it">Italiano</mds-pref-language-item>

<!-- CORRECT -->
<mds-pref-language-item code="it"></mds-pref-language-item>

Do Not Use an Undocumented or Misspelled Language Code

code must exactly match a key in the bundled dictionary (e.g. "it", "en", "fr"). An unknown code throws Language code not found: <code> when the item loads or its code changes. Use the two-letter BCP 47 tag, not a locale variant like "it-IT".

<!-- INCORRECT -->
<mds-pref-language-item code="it-IT"></mds-pref-language-item>
<mds-pref-language-item code="italian"></mds-pref-language-item>

<!-- CORRECT -->
<mds-pref-language-item code="it"></mds-pref-language-item>

Do Not Manage the selected Prop by Hand Across Items

The parent marks only the item matching the active language when it loads, overwriting the selected written in the markup, and clears every sibling on each pick. If you toggle selected yourself from script, several items can show as selected at once, out of step with the stored preference.

<!-- INCORRECT -->
<mds-pref-language>
  <mds-pref-language-item code="it" selected></mds-pref-language-item>
  <mds-pref-language-item code="en" selected></mds-pref-language-item>
</mds-pref-language>

<!-- CORRECT -->
<mds-pref-language set="it">
  <mds-pref-language-item code="it"></mds-pref-language-item>
  <mds-pref-language-item code="en"></mds-pref-language-item>
</mds-pref-language>

Do Not Listen for Native click to Detect Language Selection

The component emits mdsPrefLanguageItemSelect (or the parent emits mdsPrefLanguageChange). A native click carries no detail, so it skips the event payload that carries the selected language code, and it does not tell you that the parent has committed the pick.

<!-- INCORRECT -->
<script>
  document.querySelector('mds-pref-language-item').addEventListener('click', () => {
    // no language code available here
  });
</script>

<!-- CORRECT -->
<script>
  document.querySelector('mds-pref-language').addEventListener('mdsPrefLanguageChange', (e) => {
    console.log('Lingua selezionata:', e.detail.language);
  });
</script>

Do Not Set selected="false" to Deselect

selected is a boolean attribute: a false boolean is written by removing the attribute (agents/conventions.md), or by setting the prop to false from script. Stencil does parse "false" as false, but the attribute stays in the markup until the component hydrates and its reflection removes it, so a [selected] selector or any code reading the attribute sees it set in the meantime. Inside <mds-pref-language> the parent owns selected anyway.

<!-- INCORRECT -->
<mds-pref-language-item code="it" selected="false"></mds-pref-language-item>

<!-- CORRECT -->
<mds-pref-language-item code="it"></mds-pref-language-item>