Common incorrect uses of <mds-header-bar>. 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-header-bar Standalone Outside mds-header

<mds-header-bar> is a structural sub-component of mds-header. Used alone, the hamburger click has no mds-header ancestor to call setOpened on, so the drawer never opens. Always place it inside <mds-header> unless you have fully replaced drawer management with mdsHeaderBarOpen listeners.

<!-- INCORRECT -->
<mds-header-bar>
  <mds-text typography="h6">Portale</mds-text>
</mds-header-bar>

<!-- CORRECT -->
<mds-header>
  <mds-header-bar>
    <mds-text typography="h6">Portale</mds-text>
  </mds-header-bar>
</mds-header>

Do Not Put Navigation Links in the Default Slot

The default slot is the branding region (left side). Navigation actions must go in the nav named slot so the component can apply responsive visibility rules and wrap them in the <nav> element for landmark semantics.

<!-- INCORRECT -->
<mds-header-bar>
  <mds-img src="./logo.svg"></mds-img>
  <mds-button variant="dark" tone="text">Servizi</mds-button>
  <mds-button variant="primary" tone="strong">Accedi</mds-button>
</mds-header-bar>

<!-- CORRECT -->
<mds-header-bar>
  <mds-img src="./logo.svg"></mds-img>
  <mds-button slot="nav" variant="dark" tone="text">Servizi</mds-button>
  <mds-button slot="nav" variant="primary" tone="strong">Accedi</mds-button>
</mds-header-bar>

Do Not Set Both menu and nav to none Without a Replacement

Setting both to none hides all interactive regions and leaves a branding-only bar with no way to navigate, which is rarely the intended result. If the design truly needs a pure branding strip, be explicit about it and confirm it is intentional; otherwise keep at least one region visible.

<!-- INCORRECT (navigation is invisible and unreachable) -->
<mds-header-bar menu="none" nav="none">
  <mds-img src="./logo.svg"></mds-img>
  <mds-button slot="nav" variant="dark" tone="text">Servizi</mds-button>
</mds-header-bar>

<!-- CORRECT (at least one region stays visible) -->
<mds-header-bar menu="none" nav="all">
  <mds-img src="./logo.svg"></mds-img>
  <mds-button slot="nav" variant="dark" tone="text">Servizi</mds-button>
</mds-header-bar>

Do Not Pierce Shadow DOM to Style the Hamburger or Nav

The only documented customization hooks are --mds-header-bar-hamburger-color (CSS custom property) and the shadow parts content, actions, nav, hamburger. Targeting undocumented internal classes couples your code to implementation details that can change at any minor release.

/* INCORRECT */
mds-header-bar >>> .menu {
  fill: red;
}
mds-header-bar::part(icon) {
  fill: blue;
}

/* CORRECT */
mds-header-bar {
  --mds-header-bar-hamburger-color: rgb(var(--magma-accent-fg));
}
mds-header-bar::part(hamburger) {
  background-color: rgb(var(--magma-wash-base));
}

Do Not Listen to click on the Hamburger Instead of mdsHeaderBarOpen

A click listener on the host fires for every click inside the bar (logo, nav buttons), not only on the hamburger. Use the documented mdsHeaderBarOpen event, which bubbles and fires only when the hamburger is pressed.

<!-- INCORRECT -->
<mds-header-bar id="bar">...</mds-header-bar>
<script>
  document.getElementById('bar').addEventListener('click', handleMenu);
</script>

<!-- CORRECT -->
<mds-header-bar id="bar">...</mds-header-bar>
<script>
  document.getElementById('bar').addEventListener('mdsHeaderBarOpen', handleMenu);
</script>

Do Not Set menu or nav to an Undocumented String Value

The accepted values for both props are 'all' | 'desktop' | 'mobile' | 'none'. Strings outside that set are not validated: any value other than none shows the region on every viewport, as all does, producing unexpected layout.

<!-- INCORRECT -->
<mds-header-bar menu="always" nav="never">...</mds-header-bar>
<mds-header-bar menu="true" nav="false">...</mds-header-bar>

<!-- CORRECT -->
<mds-header-bar menu="all" nav="none">...</mds-header-bar>