Common incorrect uses of <mds-file>. 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 Expect the Component to Perform the Download

<mds-file> is a display card, not a download trigger: it has no href. It emits mdsFileDownload and the consumer must wire the actual download logic to that event.

<!-- INCORRECT - expecting the component to handle the download itself -->
<mds-file filename="report.pdf" href="/files/report.pdf"></mds-file>

<!-- CORRECT - consumer listens to the event and handles the download -->
<mds-file filename="report.pdf" id="card-report"></mds-file>

<script>
  document.getElementById('card-report').addEventListener('mdsFileDownload', (e) => {
    window.location.href = '/files/' + e.detail.filename;
  });
</script>

Do Not Set format Manually

format is an internal reflected attribute automatically derived from the filename and suffix. Setting it directly has no guaranteed effect because the component overwrites it during componentWillLoad and on every filename change. Use suffix to control type detection.

<!-- INCORRECT -->
<mds-file filename="archivio" format="document"></mds-file>

<!-- CORRECT - use suffix to override file-type detection -->
<mds-file filename="archivio" suffix="pdf"></mds-file>

Do Not Pierce Shadow DOM to Style the Preview Panel

The supported customization surface is --mds-file-preview-* CSS custom properties. Targeting internal elements with >>>, /deep/, or undocumented selectors couples your code to the Shadow DOM structure and will break on minor releases.

/* INCORRECT */
mds-file >>> .preview {
  background-color: blue;
}

/* CORRECT */
mds-file {
  --mds-file-preview-icon-background: rgb(var(--magma-accent-surface-subtle));
  --mds-file-preview-icon-color: rgb(var(--magma-accent-fg));
}

Do Not Wrap <mds-file> in a Native Anchor or Button

The host is already focusable (tabindex="0") and emits its own interaction event. Wrapping it in <a> or <button> creates nested interactive controls and breaks keyboard semantics.

<!-- INCORRECT -->
<a href="/download/report.pdf">
  <mds-file filename="report.pdf"></mds-file>
</a>

<!-- CORRECT - use the mdsFileDownload event to trigger navigation or download -->
<mds-file filename="report.pdf" id="file-report"></mds-file>

<script>
  document.getElementById('file-report').addEventListener('mdsFileDownload', () => {
    window.location.href = '/download/report.pdf';
  });
</script>

Do Not Use a Raw <div> or <li> as a File Row When <mds-file> Exists

<mds-file> handles format detection, theming, accessibility focus, download persistence, and localization. Rolling a custom file row loses all of these affordances.

<!-- INCORRECT -->
<div class="file-row" onclick="download('report.pdf')">
  <img src="pdf-icon.svg" alt="PDF" />
  <span>report.pdf</span>
</div>

<!-- CORRECT -->
<mds-file filename="report.pdf"></mds-file>