Common incorrect uses of <mds-file-preview>. 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 Pass a Label Instead of a Real Filename

filename drives automatic icon, badge, and description inference. Passing a cosmetic label without an extension produces the generic fallback icon and a default badge, losing all format-aware information.

<!-- INCORRECT -->
<mds-file-preview filename="Contratto"></mds-file-preview>

<!-- CORRECT -->
<mds-file-preview filename="contratto-2024.pdf"></mds-file-preview>

Do Not Set variant Without message

variant colours the status layout that is only rendered when message is set. Setting variant alone has no visual effect and misleads readers of the code into thinking the card is themed.

<!-- INCORRECT -->
<mds-file-preview filename="report.pdf" variant="error"></mds-file-preview>

<!-- CORRECT -->
<mds-file-preview
  filename="report.pdf"
  message="File danneggiato"
  variant="error"
></mds-file-preview>

Do Not Listen for Native click to Handle Downloads

The component emits mdsFileDownload with the file detail when the card is clicked. Attaching an outer click handler bypasses the detail payload and also fires for clicks on the delete button.

<!-- INCORRECT -->
<div onclick="handleClick()">
  <mds-file-preview filename="documento.docx" downloadable></mds-file-preview>
</div>

<!-- CORRECT -->
<mds-file-preview filename="documento.docx" downloadable></mds-file-preview>

// INCORRECT - native click on a wrapper
document.querySelector('div').addEventListener('click', handleClick);

// CORRECT - documented mdsFileDownload event
document.querySelector('mds-file-preview').addEventListener('mdsFileDownload', (e) => {
  download(e.detail.filename);
});

Do Not Remove the Element Yourself Without Listening to mdsFileDelete

deletable makes the delete button visible but leaves removal to the consumer. Removing the element from a click listener on the host - rather than mdsFileDelete - fires on any click inside the card, not only on the delete button, and bypasses the detail payload.

<!-- INCORRECT -->
<mds-file-preview filename="allegato.zip" deletable onclick="this.remove()"></mds-file-preview>

<!-- CORRECT -->
<mds-file-preview filename="allegato.zip" deletable></mds-file-preview>

document.querySelector('mds-file-preview').addEventListener('mdsFileDelete', (e) => {
  e.detail.target.remove();
});

Do Not Wrap mds-file-preview in an Anchor to Add Download

Wrapping a card in <a href="..."> nests an already-interactive card (and its delete button, when deletable) inside a link, which fails accessibility audits. Use downloadable and handle mdsFileDownload instead.

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

<!-- CORRECT -->
<mds-file-preview filename="documento.pdf" downloadable></mds-file-preview>

Do Not Use suffix to Pass a Free-Form String

suffix accepts only values from the documented ExtensionSuffixType union (e.g. "pdf", "docx", "jpg"). Passing an unsupported string silently falls back to the default icon and loses format inference.

<!-- INCORRECT -->
<mds-file-preview filename="report" suffix="documento-word"></mds-file-preview>

<!-- CORRECT -->
<mds-file-preview filename="report" suffix="docx"></mds-file-preview>

Customize via Documented Vars and the card Part Only

The only documented shadow part is card. Targeting inner selectors via ::part(), >>>, or attribute hacks couples code to internal Shadow DOM structure and will break on minor releases.

/* INCORRECT */
mds-file-preview::part(icon) {
  width: 48px;
}
mds-file-preview >>> .file-name {
  font-size: 1rem;
}

/* CORRECT */
mds-file-preview {
  --mds-file-preview-icon-color: rgb(var(--magma-accent-fg));
  --mds-file-preview-background-color: rgb(var(--magma-accent-surface-subtle));
}
mds-file-preview::part(card) {
  padding: calc(var(--spacing) * 600);
}