Correct and idiomatic ways to use the <mds-emoji> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Basic Mascot Display

Drop the component anywhere to render the default mascot, Mia. The element is a square and sizes itself to the value applied via CSS width / height (it has its own default). No props are required for a static illustration.

<mds-emoji></mds-emoji>

Choosing a Mascot with name

The name prop selects between the two available mascots. Use "mia" (default) for the AI-branded identity and "simi" for the human-like character. Changing name at runtime swaps the mascot without a page reload.

<!-- Mia - the AI mascot (default) -->
<mds-emoji name="mia"></mds-emoji>

<!-- Simi - the human-like mascot -->
<mds-emoji name="simi"></mds-emoji>

Sizing via CSS

Control the rendered size with CSS width and height on the host - the SVG fills 100% of the host’s box. The component keeps a 1:1 aspect ratio automatically.

<mds-emoji name="mia" style="width: 128px; height: 128px;"></mds-emoji>

.mascot-hero mds-emoji {
  width: 240px;
  height: 240px;
}

Mouse-Following Interaction

Call startFollowMouse() to activate the 3D head-rotation that tracks the pointer. The feature is off by default. Call stopFollowMouse() to deactivate it cleanly.

<mds-emoji id="mascot" name="mia"></mds-emoji>

<script>
  const emoji = document.querySelector('#mascot');
  emoji.startFollowMouse();

  // later, e.g. when leaving a focused section:
  emoji.stopFollowMouse();
</script>

Idle Blinking

Start the automatic random-interval blink loop with startBlinking(). The blink is suppressed while another animation owns the eyes and resumes automatically afterwards.

<mds-emoji id="mascot" name="simi"></mds-emoji>

<script>
  const emoji = document.querySelector('#mascot');
  emoji.startBlinking();
</script>

Expressing Agreement or Confirmation

Call agree() after a successful form submission or confirmed action. The emoji nods and briefly smiles. The returned Promise resolves when the animation completes.

<mds-emoji id="mascot" name="mia"></mds-emoji>
<mds-button id="save-btn" label="Salva" variant="primary" tone="strong"></mds-button>

<script>
  const emoji = document.querySelector('#mascot');
  document.querySelector('#save-btn').addEventListener('click', async () => {
    await fetch('/api/save');
    emoji.agree();
  });
</script>

Expressing a Smile

Call smile() for lighter positive feedback - a bounce and closed-eyes smile without the full nod. Useful on hover or focus of a featured element.

<mds-emoji id="mascot" name="mia"></mds-emoji>

<script>
  const emoji = document.querySelector('#mascot');
  document.querySelector('.feature-card').addEventListener('mouseenter', () => {
    emoji.smile();
  });
</script>

Expressing Disagreement or Errors

Call disagree() on validation failure or destructive confirmation. An optional turnHappyDelay number (in milliseconds) delays the return to the neutral face - useful when you want the serious expression to linger while an error message is visible.

<mds-emoji id="mascot" name="mia"></mds-emoji>

<script>
  const emoji = document.querySelector('#mascot');

  formEl.addEventListener('submit', async (e) => {
    e.preventDefault();
    const ok = await submitForm();
    if (!ok) {
      emoji.disagree(2000); // stay serious for 2 s while the error banner is visible
    }
  });
</script>

Thinking State During Async Operations

Call startThinking() while a request is in flight - the emoji raises a thinking hand and shifts its gaze. Call stopThinking() when the operation settles. Both methods accept an optional duration (seconds) for the transition animation.

<mds-emoji id="mascot" name="mia"></mds-emoji>

<script>
  const emoji = document.querySelector('#mascot');

  async function caricaDati() {
    await emoji.startThinking();
    const data = await fetch('/api/data').then((r) => r.json());
    await emoji.stopThinking();
    return data;
  }
</script>

Chaining Expressions

Because every method returns a Promise<void>, you can await one before triggering the next. Without awaiting they still never overlap, but each call takes the face over and cuts the previous expression short.

<mds-emoji id="mascot" name="simi"></mds-emoji>

<script>
  const emoji = document.querySelector('#mascot');

  async function onSave() {
    await emoji.startThinking(0.4); // mostri caricamento
    await fetch('/api/salva');
    await emoji.stopThinking(0.4);
    await emoji.agree();           // conferma riuscita
  }
</script>

CSS Customization - Animation Timing

Tune the mouse-follow responsiveness by overriding the documented --mds-emoji-expression-* custom properties on the host or a parent selector. The initial values are reasonable for most placements; reduce them for snappier feedback.

.mascot-container mds-emoji {
  --mds-emoji-expression-follow-mouse-head-duration: 150ms;
  --mds-emoji-expression-follow-mouse-traits-duration: 100ms;
  --mds-emoji-expression-max-rotation: 10deg;
}

CSS Customization - Mascot Colors

Override per-mascot color tokens to adapt the character to a custom brand palette. Use the semantic color roles (rgb(var(--magma-<role>))) so dark mode and named themes keep working; Simi’s skin tones are data, so hex values are fine there.

/* Theming Mia for a custom brand */
mds-emoji[name='mia'] {
  --mds-emoji-mia-head-color: rgb(var(--magma-accent-surface-hover));
  --mds-emoji-mia-eyes-color: rgb(var(--magma-accent-emphasis-hover));
  --mds-emoji-mia-mouth-color: rgb(var(--magma-accent-emphasis));
  --mds-emoji-mia-hands-color: rgb(var(--magma-accent-emphasis));
}

/* Theming Simi */
mds-emoji[name='simi'] {
  --mds-emoji-simi-skin: #f5c8a0;
  --mds-emoji-simi-skin-dark: #c8895e;
  --mds-emoji-simi-skin-light: #fdebd8;
}

CSS Customization - Parallax Offsets

Increase or decrease the per-layer offset values to control how pronounced the parallax depth effect is when the emoji follows the mouse. Set all offsets to 0 to flatten the effect entirely.

/* Subtle parallax - small offsets for compact placements */
.compact mds-emoji {
  --mds-emoji-offset-eyes: 0.5px;
  --mds-emoji-offset-mouth: 0.5px;
  --mds-emoji-offset-eyebrows: 4px;
  --mds-emoji-offset-head: 0;
}

/* Dramatic parallax - large offsets for hero sections */
.hero mds-emoji {
  --mds-emoji-offset-eyes: 3px;
  --mds-emoji-offset-mouth: 3px;
  --mds-emoji-offset-eyebrows: 20px;
  --mds-emoji-perspective: 250px;
}