Common incorrect uses of <mds-emoji>. 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 an Unknown name Value

Only "mia" and "simi" are valid values for the name prop. Any other string falls outside the EmojiNames type: no mascot is rendered and the component throws a TypeError in the console.

<!-- INCORRECT -->
<mds-emoji name="luigi"></mds-emoji>
<mds-emoji name="robot"></mds-emoji>

<!-- CORRECT -->
<mds-emoji name="mia"></mds-emoji>
<mds-emoji name="simi"></mds-emoji>

Do Not Put Content in the Component - It Has No Slots

<mds-emoji> renders a self-contained SVG through its shadow root and exposes no slots. Any child nodes placed between the tags are ignored entirely.

<!-- INCORRECT -->
<mds-emoji name="mia">
  <span>Ciao!</span>
</mds-emoji>

<!-- CORRECT - place sibling elements outside the component -->
<div class="mascot-wrapper">
  <mds-emoji name="mia"></mds-emoji>
  <p>Ciao!</p>
</div>

Do Not Trigger Expressions Without Awaiting a Running Animation

agree(), smile(), disagree(), and startThinking() each take the face over: they stop whatever is playing (a thinking pose included) and start from the neutral face. Firing them without awaiting the previous call cuts the earlier expression short.

<!-- INCORRECT - the second call cuts the first one short -->
<script>
  emoji.startThinking(); // starts thinking
  emoji.agree();         // takes over: the thinking pose is dropped at once
</script>

<!-- CORRECT - await each expression before chaining the next -->
<script type="module">
  const emoji = document.querySelector('mds-emoji');
  await emoji.startThinking(0.5);
  await fetch('/api/salva');
  await emoji.stopThinking(0.5);
  await emoji.agree();
</script>

Do Not Use stopThinking() to Cancel Mid-Expression

stopThinking() is the paired counterpart to startThinking(). Calling it to interrupt agree(), smile(), or disagree() has no effect: stopThinking() returns at once unless the emoji is thinking. An expression runs to completion unless another expression takes the face over.

<!-- INCORRECT - stopThinking() won't cut short an agree() animation -->
<script>
  emoji.agree();
  emoji.stopThinking(); // no-op
</script>

<!-- CORRECT - let the animation complete (await it), or accept that expressions run to completion -->
<script type="module">
  const emoji = document.querySelector('mds-emoji');
  await emoji.agree();
  // now the emoji is idle and ready for the next call
</script>

Do Not Pierce Shadow DOM to Animate SVG Parts Directly

The internal SVG elements (eyes, mouth, head, etc.) are part of the shadow DOM and are managed by GSAP inside the component. Querying them from outside and applying CSS transforms or animations creates conflicting tweens and breaks the component’s state machine.

/* INCORRECT */
mds-emoji >>> #eyes-default {
  transform: scaleY(0.5);
}

<!-- CORRECT - use the documented imperative methods instead -->
<script>
  const emoji = document.querySelector('mds-emoji');
  emoji.startBlinking(); // let the component own eye animations
</script>

Do Not Set Per-Layer Offsets with Unitless Numbers

The --mds-emoji-offset-* custom properties are declared as <length> values. Unitless numbers are not valid lengths and will be ignored, leaving the parallax effect at the CSS @property initial value.

/* INCORRECT - unitless values are invalid <length> */
mds-emoji {
  --mds-emoji-offset-eyes: 3;
  --mds-emoji-offset-mouth: 2;
}

/* CORRECT - always supply a length unit */
mds-emoji {
  --mds-emoji-offset-eyes: 3px;
  --mds-emoji-offset-mouth: 2px;
}

Do Not Set --mds-emoji-expression-max-rotation Without an Angle Unit

--mds-emoji-expression-max-rotation is declared as <angle>. A bare number is invalid and the property falls back to the initial value of 16deg, so the constraint you intended is silently ignored.

/* INCORRECT */
mds-emoji {
  --mds-emoji-expression-max-rotation: 8;
}

/* CORRECT */
mds-emoji {
  --mds-emoji-expression-max-rotation: 8deg;
}