Common incorrect uses of <mds-horizontal-scroll>. 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 Set controls to a Boolean

controls is a ViewportType string prop, not a boolean. Setting it without a value (or as "") gives an empty string, which renders no arrows at all - the opposite of what a bare boolean attribute suggests. Always supply an explicit string value.

<!-- INCORRECT -->
<mds-horizontal-scroll controls>
  <!-- slotted items -->
</mds-horizontal-scroll>

<!-- CORRECT -->
<mds-horizontal-scroll controls="desktop">
  <!-- slotted items -->
</mds-horizontal-scroll>

Do Not Wrap Slotted Items in an Extra Div

Adding a single wrapper <div> around all children collapses the scroll track to one item. The component’s arrow and snap logic iterates over the direct slot children - each scrollable item must be a direct child, not grandchildren inside a wrapper.

<!-- INCORRECT -->
<mds-horizontal-scroll>
  <div>
    <mds-card class="min-w-[320px]">...</mds-card>
    <mds-card class="min-w-[320px]">...</mds-card>
  </div>
</mds-horizontal-scroll>

<!-- CORRECT -->
<mds-horizontal-scroll>
  <mds-card class="min-w-[320px]">...</mds-card>
  <mds-card class="min-w-[320px]">...</mds-card>
</mds-horizontal-scroll>

Do Not Set controls="none" as Boolean False

controls has no boolean semantic. Removing arrow buttons is done with controls="none", not by writing controls="false" or disabled. The string "false" is not a ViewportType: the arrows end up hidden only because no breakpoint rule matches it, and a type check rejects it.

<!-- INCORRECT -->
<mds-horizontal-scroll controls="false">
  <!-- slotted items -->
</mds-horizontal-scroll>

<!-- CORRECT -->
<mds-horizontal-scroll controls="none">
  <!-- slotted items -->
</mds-horizontal-scroll>

Do Not Use a Raw <div> Scroll Container Instead

Replacing <mds-horizontal-scroll> with a manually styled <div style="overflow-x: auto"> loses the managed arrow buttons, the dot indicator, scroll-snap wiring, and the controls breakpoint logic. Use the component.

<!-- INCORRECT -->
<div style="overflow-x: auto; display: flex; gap: 16px;">
  <mds-card class="min-w-[320px]">...</mds-card>
  <mds-card class="min-w-[320px]">...</mds-card>
</div>

<!-- CORRECT -->
<mds-horizontal-scroll>
  <mds-card class="min-w-[320px]">...</mds-card>
  <mds-card class="min-w-[320px]">...</mds-card>
</mds-horizontal-scroll>

Do Not Pierce the Shadow DOM to Style Internal Elements

The navigation buttons and dot indicator live inside the shadow DOM. Targeting them via >>>, /deep/, or undocumented class names (.navigation, .dot) will break on future releases. Use --mds-horizontal-scroll-* CSS custom properties instead.

/* INCORRECT */
mds-horizontal-scroll >>> .dot {
  background: red;
}
mds-horizontal-scroll >>> .navigation {
  border-radius: 0;
}

/* CORRECT */
mds-horizontal-scroll {
  --mds-horizontal-scroll-dot-background: rgb(var(--magma-accent-emphasis));
}
mds-horizontal-scroll::part(content) {
  padding-block: calc(var(--spacing) * 800);
}

Do Not Provide Slotted Items Without a Fixed Width

Slotted items without a declared width collapse to zero or stretch unpredictably. Always give direct children an explicit min-width or width so the container has measurable items to snap and scroll among.

<!-- INCORRECT: card has no fixed width, items will collapse -->
<mds-horizontal-scroll>
  <mds-card>...</mds-card>
  <mds-card>...</mds-card>
</mds-horizontal-scroll>

<!-- CORRECT: each card has a declared minimum width -->
<mds-horizontal-scroll>
  <mds-card class="min-w-[320px]">...</mds-card>
  <mds-card class="min-w-[320px]">...</mds-card>
</mds-horizontal-scroll>