Common incorrect uses of <mds-accordion-timer-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-accordion-timer-item> is a compound child and relies on <mds-accordion-timer> to assign uuid, write progress, and drive selection. Standalone use produces a static, non-advancing disclosure with no progress bar updates.

<!-- INCORRECT -->
<mds-accordion-timer-item description="Dettagli">
  <mds-text>Contenuto.</mds-text>
</mds-accordion-timer-item>

<!-- CORRECT -->
<mds-accordion-timer>
  <mds-accordion-timer-item description="Dettagli">
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

Do Not Mix with mds-accordion-item

<mds-accordion-timer-item> and <mds-accordion-item> are siblings in different compound families and must not be placed in the same parent. The timer accordion indexes only mds-accordion-timer-item children; a mixed-in mds-accordion-item is left out of the rotation and toggles on its own.

<!-- INCORRECT -->
<mds-accordion-timer>
  <mds-accordion-item label="Primo">
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-item>
  <mds-accordion-timer-item description="Secondo">
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

<!-- CORRECT -->
<mds-accordion-timer>
  <mds-accordion-timer-item description="Primo">
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-timer-item>
  <mds-accordion-timer-item description="Secondo">
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

Do Not Set progress or uuid Manually

Both props are reserved for the parent’s runtime orchestration. Setting them by hand breaks the timer’s internal state tracking and produces incorrect progress bar rendering.

<!-- INCORRECT -->
<mds-accordion-timer>
  <mds-accordion-timer-item description="Primo" uuid="0" progress="50">
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

<!-- CORRECT -->
<mds-accordion-timer>
  <mds-accordion-timer-item description="Primo">
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

Do Not Mark More Than One Item selected

The parent does not enforce single selection at load: every item marked selected renders open, and the last one drives the timer until the first change closes the others.

<!-- INCORRECT -->
<mds-accordion-timer>
  <mds-accordion-timer-item description="Primo" selected>
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-timer-item>
  <mds-accordion-timer-item description="Secondo" selected>
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

<!-- CORRECT -->
<mds-accordion-timer>
  <mds-accordion-timer-item description="Primo" selected>
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-timer-item>
  <mds-accordion-timer-item description="Secondo">
    <mds-text>Contenuto.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

Do Not Pierce Shadow Parts for Styling

The documented customization surface is --mds-accordion-timer-item-* CSS custom properties plus the four shadow parts (content, icon, label, progress). Targeting undocumented internals couples code to the implementation and will break on minor releases.

/* INCORRECT */
mds-accordion-timer-item >>> .action {
  font-weight: bold;
}
mds-accordion-timer-item::part(spinner) {
  color: red;
}

/* CORRECT */
mds-accordion-timer-item {
  --mds-accordion-timer-item-color: rgb(var(--magma-accent-fg));
  --mds-accordion-timer-item-progress-bar-color: rgb(var(--magma-accent-fg));
}
mds-accordion-timer-item::part(label) {
  font-weight: 600;
}

Do Not Omit description

description is a required prop. It is the only text source for the header label and the accessible name of the content region. Omitting it leaves the button unlabelled and fails accessibility audits.

<!-- INCORRECT -->
<mds-accordion-timer>
  <mds-accordion-timer-item>
    <mds-text>Contenuto senza titolo.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

<!-- CORRECT -->
<mds-accordion-timer>
  <mds-accordion-timer-item description="Titolo della sezione">
    <mds-text>Contenuto della sezione.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>