Common incorrect uses of <mds-entity>. 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 Put the Name as a Plain Text String in the Default Slot

The default slot accepts HTML elements and components, and the component applies truncation to slotted nodes. Passing a bare string bypasses <mds-text> typography tokens and truncation utilities; the result may overflow or render with inconsistent styles.

<!-- INCORRECT -->
<mds-entity src="/avatars/mario-rossi.png">
  Mario Rossi
</mds-entity>

<!-- CORRECT -->
<mds-entity src="/avatars/mario-rossi.png">
  <mds-text truncate="word" typography="h6">Mario Rossi</mds-text>
</mds-entity>

Do Not Use await="false" to Cancel the Loading State

await is a boolean attribute: turn it off by removing it (or setting the prop to undefined), as for every boolean (agents/anti-patterns.md). The runtime happens to read the string "false" as false, but the attribute stays in the markup until the component renders, and HTML, [await] selectors and hasAttribute() read a present attribute as set.

<!-- INCORRECT -->
<mds-entity await="false" src="/avatars/mario-rossi.png">
  <mds-text truncate="word" typography="h6">Mario Rossi</mds-text>
</mds-entity>

<!-- CORRECT -->
<mds-entity src="/avatars/mario-rossi.png">
  <mds-text truncate="word" typography="h6">Mario Rossi</mds-text>
</mds-entity>

Do Not Put Non-Button Elements in the action Slot

The action slot is sized and spaced for icon-only <mds-button> elements. Projecting arbitrary elements (raw <button>, <a>, large widgets) breaks the fixed square dimensions applied by ::slotted([slot='action']).

<!-- INCORRECT -->
<mds-entity src="/avatars/mario-rossi.png">
  <mds-text truncate="word" typography="h6">Mario Rossi</mds-text>
  <button slot="action">Modifica</button>
</mds-entity>

<!-- CORRECT -->
<mds-entity src="/avatars/mario-rossi.png">
  <mds-text truncate="word" typography="h6">Mario Rossi</mds-text>
  <mds-button slot="action" icon="mdi/pencil" variant="primary" tone="strong" title="Modifica"></mds-button>
</mds-entity>

Do Not Combine src, icon, and initials Expecting All Three to Show

The component resolves to a single avatar representation. Setting all three does not create a layered avatar: the inner mds-avatar lets icon hide the image, initials hide the icon and src hide the initials, so the chip renders none of them.

<!-- INCORRECT (expects image, icon, and initials to all appear) -->
<mds-entity src="/avatars/mario-rossi.png" icon="mi/baseline/person" initials="mr">
  <mds-text truncate="word" typography="h6">Mario Rossi</mds-text>
</mds-entity>

<!-- CORRECT - provide the most specific source available -->
<mds-entity src="/avatars/mario-rossi.png">
  <mds-text truncate="word" typography="h6">Mario Rossi</mds-text>
</mds-entity>

Do Not Apply an Invalid tone Value

<mds-entity> uses ToneMinimalVariantType, which accepts only strong and weak. Passing other tone values like outline or text is a type error and is silently ignored: the avatar renders with the strong colours.

<!-- INCORRECT -->
<mds-entity icon="mi/baseline/business" variant="primary" tone="outline">
  <mds-text truncate="word" typography="h6">Divisione Commerciale</mds-text>
</mds-entity>

<!-- CORRECT -->
<mds-entity icon="mi/baseline/business" variant="primary" tone="strong">
  <mds-text truncate="word" typography="h6">Divisione Commerciale</mds-text>
</mds-entity>

Do Not Pierce the Shadow DOM to Style the Avatar

The component exposes a ::part(avatar) surface for styling the inner <mds-avatar>, but the part is the limit: the nodes inside it are not API. Use --mds-entity-icon-background, --mds-entity-icon-color, and other --mds-entity-* custom properties for color customization; do not target undocumented internals.

/* INCORRECT */
mds-entity::part(avatar) .inner-circle {
  background: hotpink;
}
mds-entity >>> mds-avatar {
  width: 80px;
}

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