Avatar

A person or entity, as an image, initials, or a fallback glyph. It falls back on its own — image → initials → derived initials → a person icon — and picks a deterministic colour from the name so the same person keeps the same tile everywhere.

Live preview Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
<md-avatar initials="AC" name="Acme Corp" shape="rounded" label="Acme Corp"></md-avatar>
<md-avatar label="Unknown user"></md-avatar>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdAvatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
      <MdAvatar name="Grace Hopper" label="Grace Hopper"></MdAvatar>
      <MdAvatar initials="AC" name="Acme Corp" shape="rounded" label="Acme Corp"></MdAvatar>
      <MdAvatar label="Unknown user"></MdAvatar>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
<md-avatar initials="AC" name="Acme Corp" shape="rounded" label="Acme Corp"></md-avatar>
<md-avatar label="Unknown user"></md-avatar>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
  <md-avatar initials="AC" name="Acme Corp" shape="rounded" label="Acme Corp"></md-avatar>
  <md-avatar label="Unknown user"></md-avatar>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
<md-avatar initials="AC" name="Acme Corp" shape="rounded" label="Acme Corp"></md-avatar>
<md-avatar label="Unknown user"></md-avatar>

Install

Already installed? See the Installation guide for one-time package setup (core + tokens, fonts). Each tab below shows two patterns for using md-avatar in your project: Option A registers every AWC UI component at once (simplest), Option B imports only this component for tree-shake-friendly bundles.

HTML React Angular Vue Svelte

Copy

<!-- ─── Option A: global registration (all components) ─── -->
<script type="module">
  import '@awc-ui/core/define';
</script>


<!-- ─── Option B: single import (tree-shake only md-avatar) ─── -->
<script type="module">
  import '@awc-ui/core/components/md-avatar';
</script>


<md-avatar></md-avatar>

Copy

// ─── Option A: typed React wrapper (registers all components) ───
//   Importing from '@awc-ui/react' calls defineCustomElements() as a
//   side effect, so every md-* element becomes available in the browser.
import { MdAvatar } from '@awc-ui/react';

export function Example() {
  return <MdAvatar></MdAvatar>;
}


// ─── Option B: single import (tree-shake to only md-avatar) ───
//   Skip the wrapper and use the raw custom element. Smallest bundle,
//   but you lose typed props/events on JSX.
import '@awc-ui/core/components/md-avatar';

export function ExampleTreeShaken() {
  return <md-avatar></md-avatar>;
}

Copy

// ─── Option A: schema module (any md-* element accepted) ───
//   Pair with `defineCustomElements(window)` in main.ts.
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@Component({
  standalone: true,
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `<md-avatar></md-avatar>`,
})
export class ExampleComponent {}


// ─── Option B: typed directive (tree-shake friendly) ───
//   Pair with `import '@awc-ui/core/components/md-avatar'` in main.ts.
import { Component } from '@angular/core';
import { MdAvatar } from '@awc-ui/angular';

@Component({
  standalone: true,
  imports: [MdAvatar],
  template: `<md-avatar></md-avatar>`,
})
export class ExampleTreeShakenComponent {}

Copy

<!-- ─── Option A: typed Vue wrapper (registers all components) ─── -->
<script setup lang="ts">
import { MdAvatar } from '@awc-ui/vue';
</script>

<template>
  <MdAvatar></MdAvatar>
</template>


<!-- ─── Option B: single import (tree-shake to only md-avatar) ─── -->
<script setup lang="ts">
import '@awc-ui/core/components/md-avatar';
</script>

<template>
  <md-avatar></md-avatar>
</template>

Copy

<!-- ─── Option A: global registration (done once in main entry) ─── -->
<!-- main.ts:                                                          -->
<!--   import { defineCustomElements } from '@awc-ui/svelte';        -->
<!--   defineCustomElements(window);                                   -->

<md-avatar></md-avatar>


<!-- ─── Option B: single import (tree-shake to only md-avatar) ─── -->
<script lang="ts">
  import '@awc-ui/core/components/md-avatar';
</script>

<md-avatar></md-avatar>

When to use

Not a Material Design 3 component

M3 has no avatar page. Everything below is house rules, derived from this component’s behaviour rather than from m3.material.io.

• Representing a person, team, or organisation in a list, table, comment, app bar, or org chart.
• Anywhere a photo may be missing and initials should stand in.

When not to use

Situation	Use instead
A decorative or content image	Plain <img>
An icon-only action	md-icon-button
A removable person token	md-chip with variant="input"
Presence state on its own	md-status-dot
A count marker	md-badge
A logo in an app bar	Plain <img> in the md-app-bar slot

The fallback chain

src (if it loads) → initials → initials derived from name → a generic person icon. A 404 emits mdError and falls through automatically.

Set	You get
src that loads	The <img>, exposed as CSS part image
src that 404s, plus initials	mdError, then the explicit initials
src that 404s, plus name	mdError, then initials derived from name
Neither initials nor name	The default slot, or the built-in person glyph

You do not need your own onerror

The chain is built in. Writing an onerror handler that swaps the src fights the component.

Photo → derived initials → explicit initials → icon

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-avatar src="https://i.pravatar.cc/80?img=11" alt="Loads" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar src="https://broken.invalid/nope.png" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar src="https://broken.invalid/nope.png" initials="JD" label="John Doe"></md-avatar>
<md-avatar src="https://broken.invalid/nope.png" label="Unknown user"></md-avatar>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdAvatar src="https://i.pravatar.cc/80?img=11" alt="Loads" name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
      <MdAvatar src="https://broken.invalid/nope.png" name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
      <MdAvatar src="https://broken.invalid/nope.png" initials="JD" label="John Doe"></MdAvatar>
      <MdAvatar src="https://broken.invalid/nope.png" label="Unknown user"></MdAvatar>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-avatar src="https://i.pravatar.cc/80?img=11" alt="Loads" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar src="https://broken.invalid/nope.png" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar src="https://broken.invalid/nope.png" initials="JD" label="John Doe"></md-avatar>
<md-avatar src="https://broken.invalid/nope.png" label="Unknown user"></md-avatar>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-avatar src="https://i.pravatar.cc/80?img=11" alt="Loads" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar src="https://broken.invalid/nope.png" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar src="https://broken.invalid/nope.png" initials="JD" label="John Doe"></md-avatar>
  <md-avatar src="https://broken.invalid/nope.png" label="Unknown user"></md-avatar>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-avatar src="https://i.pravatar.cc/80?img=11" alt="Loads" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar src="https://broken.invalid/nope.png" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar src="https://broken.invalid/nope.png" initials="JD" label="John Doe"></md-avatar>
<md-avatar src="https://broken.invalid/nope.png" label="Unknown user"></md-avatar>

Photo avatars

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; gap: 20px; align-items: center;">
  <md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar src="https://i.pravatar.cc/80?img=32" alt="" name="Grace Hopper" label="Grace Hopper"></md-avatar>
  <md-avatar src="https://i.pravatar.cc/80?img=15" alt="" name="Alan Turing" shape="rounded" label="Alan Turing"></md-avatar>
</div>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', gap: '20px', alignItems: 'center' }}>
        <MdAvatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
        <MdAvatar src="https://i.pravatar.cc/80?img=32" alt="" name="Grace Hopper" label="Grace Hopper"></MdAvatar>
        <MdAvatar src="https://i.pravatar.cc/80?img=15" alt="" name="Alan Turing" shape="rounded" label="Alan Turing"></MdAvatar>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; gap: 20px; align-items: center;">
  <md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar src="https://i.pravatar.cc/80?img=32" alt="" name="Grace Hopper" label="Grace Hopper"></md-avatar>
  <md-avatar src="https://i.pravatar.cc/80?img=15" alt="" name="Alan Turing" shape="rounded" label="Alan Turing"></md-avatar>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; gap: 20px; align-items: center;">
    <md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar src="https://i.pravatar.cc/80?img=32" alt="" name="Grace Hopper" label="Grace Hopper"></md-avatar>
    <md-avatar src="https://i.pravatar.cc/80?img=15" alt="" name="Alan Turing" shape="rounded" label="Alan Turing"></md-avatar>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; gap: 20px; align-items: center;">
  <md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar src="https://i.pravatar.cc/80?img=32" alt="" name="Grace Hopper" label="Grace Hopper"></md-avatar>
  <md-avatar src="https://i.pravatar.cc/80?img=15" alt="" name="Alan Turing" shape="rounded" label="Alan Turing"></md-avatar>
</div>

Derived initials, explicit initials, and a counter

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; gap: 20px; align-items: center;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar name="Grace Brewster Murray Hopper" label="Grace Hopper"></md-avatar>
  <md-avatar initials="AT" label="Alan Turing"></md-avatar>
  <md-avatar initials="+5" color-from-name="false" label="Five more"></md-avatar>
</div>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', gap: '20px', alignItems: 'center' }}>
        <MdAvatar name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
        <MdAvatar name="Grace Brewster Murray Hopper" label="Grace Hopper"></MdAvatar>
        <MdAvatar initials="AT" label="Alan Turing"></MdAvatar>
        <MdAvatar initials="+5" colorFromName="false" label="Five more"></MdAvatar>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; gap: 20px; align-items: center;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar name="Grace Brewster Murray Hopper" label="Grace Hopper"></md-avatar>
  <md-avatar initials="AT" label="Alan Turing"></md-avatar>
  <md-avatar initials="+5" color-from-name="false" label="Five more"></md-avatar>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; gap: 20px; align-items: center;">
    <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar name="Grace Brewster Murray Hopper" label="Grace Hopper"></md-avatar>
    <md-avatar initials="AT" label="Alan Turing"></md-avatar>
    <md-avatar initials="+5" color-from-name="false" label="Five more"></md-avatar>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; gap: 20px; align-items: center;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar name="Grace Brewster Murray Hopper" label="Grace Hopper"></md-avatar>
  <md-avatar initials="AT" label="Alan Turing"></md-avatar>
  <md-avatar initials="+5" color-from-name="false" label="Five more"></md-avatar>
</div>

Sizes

size is not a closed enum

The three presets get editor autocomplete, but any CSS length works, and a unitless number is treated as pixels. size="72" and size="72px" are the same thing.

Value	Result
small	24×24
medium	Default. 40×40
large	56×56
72	72px
4rem, clamp(28px, 4vw, 72px)	Any CSS length

Presets and arbitrary lengths Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-avatar size="small" name="Ada Lovelace" label="Small"></md-avatar>
<md-avatar size="medium" name="Ada Lovelace" label="Medium"></md-avatar>
<md-avatar size="large" name="Ada Lovelace" label="Large"></md-avatar>
<md-avatar size="72" name="Ada Lovelace" label="72px"></md-avatar>
<md-avatar size="4rem" name="Ada Lovelace" label="4rem"></md-avatar>
<md-avatar size="clamp(28px, 4vw, 72px)" name="Ada Lovelace" label="Fluid"></md-avatar>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdAvatar size="small" name="Ada Lovelace" label="Small"></MdAvatar>
      <MdAvatar size="medium" name="Ada Lovelace" label="Medium"></MdAvatar>
      <MdAvatar size="large" name="Ada Lovelace" label="Large"></MdAvatar>
      <MdAvatar size="72" name="Ada Lovelace" label="72px"></MdAvatar>
      <MdAvatar size="4rem" name="Ada Lovelace" label="4rem"></MdAvatar>
      <MdAvatar size="clamp(28px, 4vw, 72px)" name="Ada Lovelace" label="Fluid"></MdAvatar>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-avatar size="small" name="Ada Lovelace" label="Small"></md-avatar>
<md-avatar size="medium" name="Ada Lovelace" label="Medium"></md-avatar>
<md-avatar size="large" name="Ada Lovelace" label="Large"></md-avatar>
<md-avatar size="72" name="Ada Lovelace" label="72px"></md-avatar>
<md-avatar size="4rem" name="Ada Lovelace" label="4rem"></md-avatar>
<md-avatar size="clamp(28px, 4vw, 72px)" name="Ada Lovelace" label="Fluid"></md-avatar>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-avatar size="small" name="Ada Lovelace" label="Small"></md-avatar>
  <md-avatar size="medium" name="Ada Lovelace" label="Medium"></md-avatar>
  <md-avatar size="large" name="Ada Lovelace" label="Large"></md-avatar>
  <md-avatar size="72" name="Ada Lovelace" label="72px"></md-avatar>
  <md-avatar size="4rem" name="Ada Lovelace" label="4rem"></md-avatar>
  <md-avatar size="clamp(28px, 4vw, 72px)" name="Ada Lovelace" label="Fluid"></md-avatar>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-avatar size="small" name="Ada Lovelace" label="Small"></md-avatar>
<md-avatar size="medium" name="Ada Lovelace" label="Medium"></md-avatar>
<md-avatar size="large" name="Ada Lovelace" label="Large"></md-avatar>
<md-avatar size="72" name="Ada Lovelace" label="72px"></md-avatar>
<md-avatar size="4rem" name="Ada Lovelace" label="4rem"></md-avatar>
<md-avatar size="clamp(28px, 4vw, 72px)" name="Ada Lovelace" label="Fluid"></md-avatar>

Shapes

circle is the default and the right choice for people. Keep one shape per entity type.

Circle, rounded and square

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-avatar shape="circle" src="https://i.pravatar.cc/80?img=11" alt="Circle" name="Ada Lovelace"></md-avatar>
<md-avatar shape="rounded" src="https://i.pravatar.cc/80?img=11" alt="Rounded" name="Ada Lovelace"></md-avatar>
<md-avatar shape="square" src="https://i.pravatar.cc/80?img=11" alt="Square" name="Ada Lovelace"></md-avatar>
<md-avatar shape="circle" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar shape="rounded" name="Acme Corp" label="Acme Corp"></md-avatar>
<md-avatar shape="square" name="Beta Industries" label="Beta Industries"></md-avatar>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdAvatar shape="circle" src="https://i.pravatar.cc/80?img=11" alt="Circle" name="Ada Lovelace"></MdAvatar>
      <MdAvatar shape="rounded" src="https://i.pravatar.cc/80?img=11" alt="Rounded" name="Ada Lovelace"></MdAvatar>
      <MdAvatar shape="square" src="https://i.pravatar.cc/80?img=11" alt="Square" name="Ada Lovelace"></MdAvatar>
      <MdAvatar shape="circle" name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
      <MdAvatar shape="rounded" name="Acme Corp" label="Acme Corp"></MdAvatar>
      <MdAvatar shape="square" name="Beta Industries" label="Beta Industries"></MdAvatar>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-avatar shape="circle" src="https://i.pravatar.cc/80?img=11" alt="Circle" name="Ada Lovelace"></md-avatar>
<md-avatar shape="rounded" src="https://i.pravatar.cc/80?img=11" alt="Rounded" name="Ada Lovelace"></md-avatar>
<md-avatar shape="square" src="https://i.pravatar.cc/80?img=11" alt="Square" name="Ada Lovelace"></md-avatar>
<md-avatar shape="circle" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar shape="rounded" name="Acme Corp" label="Acme Corp"></md-avatar>
<md-avatar shape="square" name="Beta Industries" label="Beta Industries"></md-avatar>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-avatar shape="circle" src="https://i.pravatar.cc/80?img=11" alt="Circle" name="Ada Lovelace"></md-avatar>
  <md-avatar shape="rounded" src="https://i.pravatar.cc/80?img=11" alt="Rounded" name="Ada Lovelace"></md-avatar>
  <md-avatar shape="square" src="https://i.pravatar.cc/80?img=11" alt="Square" name="Ada Lovelace"></md-avatar>
  <md-avatar shape="circle" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar shape="rounded" name="Acme Corp" label="Acme Corp"></md-avatar>
  <md-avatar shape="square" name="Beta Industries" label="Beta Industries"></md-avatar>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-avatar shape="circle" src="https://i.pravatar.cc/80?img=11" alt="Circle" name="Ada Lovelace"></md-avatar>
<md-avatar shape="rounded" src="https://i.pravatar.cc/80?img=11" alt="Rounded" name="Ada Lovelace"></md-avatar>
<md-avatar shape="square" src="https://i.pravatar.cc/80?img=11" alt="Square" name="Ada Lovelace"></md-avatar>
<md-avatar shape="circle" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar shape="rounded" name="Acme Corp" label="Acme Corp"></md-avatar>
<md-avatar shape="square" name="Beta Industries" label="Beta Industries"></md-avatar>

Initials & the name palette

color-from-name is on by default. It hashes a seed into one of seven palette slots, so the same person is the same colour on every screen. The seed is the first non-empty of initials, name, label — so an avatar with only initials, or only label, still gets a palette tile. Turn it off for a uniform look — never randomise it per render, because the determinism is the feature.

Seven palette slots, then the same name with color-from-name off Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
<md-avatar name="Alan Turing" label="Alan Turing"></md-avatar>
<md-avatar name="Katherine Johnson" label="Katherine Johnson"></md-avatar>
<md-avatar name="Linus Torvalds" label="Linus Torvalds"></md-avatar>
<md-avatar name="Barbara Liskov" label="Barbara Liskov"></md-avatar>
<md-avatar name="Donald Knuth" label="Donald Knuth"></md-avatar>
<md-avatar name="Ada Lovelace" color-from-name="false" label="Uniform"></md-avatar>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdAvatar name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
      <MdAvatar name="Grace Hopper" label="Grace Hopper"></MdAvatar>
      <MdAvatar name="Alan Turing" label="Alan Turing"></MdAvatar>
      <MdAvatar name="Katherine Johnson" label="Katherine Johnson"></MdAvatar>
      <MdAvatar name="Linus Torvalds" label="Linus Torvalds"></MdAvatar>
      <MdAvatar name="Barbara Liskov" label="Barbara Liskov"></MdAvatar>
      <MdAvatar name="Donald Knuth" label="Donald Knuth"></MdAvatar>
      <MdAvatar name="Ada Lovelace" colorFromName="false" label="Uniform"></MdAvatar>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
<md-avatar name="Alan Turing" label="Alan Turing"></md-avatar>
<md-avatar name="Katherine Johnson" label="Katherine Johnson"></md-avatar>
<md-avatar name="Linus Torvalds" label="Linus Torvalds"></md-avatar>
<md-avatar name="Barbara Liskov" label="Barbara Liskov"></md-avatar>
<md-avatar name="Donald Knuth" label="Donald Knuth"></md-avatar>
<md-avatar name="Ada Lovelace" color-from-name="false" label="Uniform"></md-avatar>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
  <md-avatar name="Alan Turing" label="Alan Turing"></md-avatar>
  <md-avatar name="Katherine Johnson" label="Katherine Johnson"></md-avatar>
  <md-avatar name="Linus Torvalds" label="Linus Torvalds"></md-avatar>
  <md-avatar name="Barbara Liskov" label="Barbara Liskov"></md-avatar>
  <md-avatar name="Donald Knuth" label="Donald Knuth"></md-avatar>
  <md-avatar name="Ada Lovelace" color-from-name="false" label="Uniform"></md-avatar>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
<md-avatar name="Alan Turing" label="Alan Turing"></md-avatar>
<md-avatar name="Katherine Johnson" label="Katherine Johnson"></md-avatar>
<md-avatar name="Linus Torvalds" label="Linus Torvalds"></md-avatar>
<md-avatar name="Barbara Liskov" label="Barbara Liskov"></md-avatar>
<md-avatar name="Donald Knuth" label="Donald Knuth"></md-avatar>
<md-avatar name="Ada Lovelace" color-from-name="false" label="Uniform"></md-avatar>

Initials are sliced from name in the string’s own script, so non-Latin names work — but a two-character slice is often meaningless in CJK. Pass initials explicitly there.

Custom content

The default slot replaces the whole image / initials / icon stack.

Turn color-from-name off before you set a container colour

The palette rule that color-from-name switches on is :host(.md-avatar--palette-N), which out-specifies the :host rule that reads --md-avatar-container-color / --md-avatar-label-color. So an override on a palette-tinted avatar is silently ignored — and every avatar with a seed (initials, name, or even just label) is palette-tinted. Pair the override with color-from-name="false", as the demos below do.

Slotted SVG, emoji and custom text

🚀 AW

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-avatar label="Starred" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-tertiary-container); --md-avatar-label-color: var(--md-sys-color-on-tertiary-container);">
  <svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" aria-hidden="true"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>
</md-avatar>
<md-avatar label="Team emoji" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-secondary-container);">🚀</md-avatar>
<md-avatar shape="rounded" label="Custom mark" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-primary); --md-avatar-label-color: var(--md-sys-color-on-primary);">
  <span style="font-weight: 700; font-size: 14px;">AW</span>
</md-avatar>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdAvatar label="Starred" colorFromName="false" style={{ '--md-avatar-container-color': 'var(--md-sys-color-tertiary-container)', '--md-avatar-label-color': 'var(--md-sys-color-on-tertiary-container)' }}>
        <svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" aria-hidden="true"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>
      </MdAvatar>
      <MdAvatar label="Team emoji" colorFromName="false" style={{ '--md-avatar-container-color': 'var(--md-sys-color-secondary-container)' }}>🚀</MdAvatar>
      <MdAvatar shape="rounded" label="Custom mark" colorFromName="false" style={{ '--md-avatar-container-color': 'var(--md-sys-color-primary)', '--md-avatar-label-color': 'var(--md-sys-color-on-primary)' }}>
        <span style={{ fontWeight: '700', fontSize: '14px' }}>AW</span>
      </MdAvatar>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-avatar label="Starred" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-tertiary-container); --md-avatar-label-color: var(--md-sys-color-on-tertiary-container);">
  <svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" aria-hidden="true"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>
</md-avatar>
<md-avatar label="Team emoji" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-secondary-container);">🚀</md-avatar>
<md-avatar shape="rounded" label="Custom mark" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-primary); --md-avatar-label-color: var(--md-sys-color-on-primary);">
  <span style="font-weight: 700; font-size: 14px;">AW</span>
</md-avatar>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-avatar label="Starred" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-tertiary-container); --md-avatar-label-color: var(--md-sys-color-on-tertiary-container);">
    <svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" aria-hidden="true"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>
  </md-avatar>
  <md-avatar label="Team emoji" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-secondary-container);">🚀</md-avatar>
  <md-avatar shape="rounded" label="Custom mark" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-primary); --md-avatar-label-color: var(--md-sys-color-on-primary);">
    <span style="font-weight: 700; font-size: 14px;">AW</span>
  </md-avatar>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-avatar label="Starred" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-tertiary-container); --md-avatar-label-color: var(--md-sys-color-on-tertiary-container);">
  <svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" aria-hidden="true"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>
</md-avatar>
<md-avatar label="Team emoji" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-secondary-container);">🚀</md-avatar>
<md-avatar shape="rounded" label="Custom mark" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-primary); --md-avatar-label-color: var(--md-sys-color-on-primary);">
  <span style="font-weight: 700; font-size: 14px;">AW</span>
</md-avatar>

Avatar groups

Stack with a negative inline margin and a descending z-index. Each tile is opaque, so the front avatar fully covers the one behind — the classic “bite-mark” pattern. Over imagery, add a surface-coloured ring instead.

Stacked group, and the outlined variant for busy backgrounds Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: inline-flex; align-items: center;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 4;"></md-avatar>
  <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
  <md-avatar name="Grace Hopper" label="Grace Hopper" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
  <md-avatar initials="+5" color-from-name="false" label="5 more members" style="z-index: 1;"></md-avatar>
</div>

<div style="display: inline-flex; align-items: center;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 4;"></md-avatar>
  <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
  <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
  <md-avatar initials="+5" color-from-name="false" label="5 more members" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
</div>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'inline-flex', alignItems: 'center' }}>
        <MdAvatar name="Ada Lovelace" label="Ada Lovelace" style={{ marginInlineEnd: '-12px', zIndex: '4' }}></MdAvatar>
        <MdAvatar name="Linus Torvalds" label="Linus Torvalds" style={{ marginInlineEnd: '-12px', zIndex: '3' }}></MdAvatar>
        <MdAvatar name="Grace Hopper" label="Grace Hopper" style={{ marginInlineEnd: '-12px', zIndex: '2' }}></MdAvatar>
        <MdAvatar initials="+5" colorFromName="false" label="5 more members" style={{ zIndex: '1' }}></MdAvatar>
      </div>

      <div style={{ display: 'inline-flex', alignItems: 'center' }}>
        <MdAvatar name="Ada Lovelace" label="Ada Lovelace" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface)', '--md-avatar-outline-width': '2px', marginInlineEnd: '-8px', zIndex: '4' }}></MdAvatar>
        <MdAvatar name="Linus Torvalds" label="Linus Torvalds" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface)', '--md-avatar-outline-width': '2px', marginInlineEnd: '-8px', zIndex: '3' }}></MdAvatar>
        <MdAvatar name="Grace Hopper" label="Grace Hopper" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface)', '--md-avatar-outline-width': '2px', marginInlineEnd: '-8px', zIndex: '2' }}></MdAvatar>
        <MdAvatar initials="+5" colorFromName="false" label="5 more members" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface)', '--md-avatar-outline-width': '2px', zIndex: '1' }}></MdAvatar>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: inline-flex; align-items: center;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 4;"></md-avatar>
  <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
  <md-avatar name="Grace Hopper" label="Grace Hopper" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
  <md-avatar initials="+5" color-from-name="false" label="5 more members" style="z-index: 1;"></md-avatar>
</div>

<div style="display: inline-flex; align-items: center;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 4;"></md-avatar>
  <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
  <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
  <md-avatar initials="+5" color-from-name="false" label="5 more members" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: inline-flex; align-items: center;">
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 4;"></md-avatar>
    <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
    <md-avatar name="Grace Hopper" label="Grace Hopper" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
    <md-avatar initials="+5" color-from-name="false" label="5 more members" style="z-index: 1;"></md-avatar>
  </div>

  <div style="display: inline-flex; align-items: center;">
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 4;"></md-avatar>
    <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
    <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
    <md-avatar initials="+5" color-from-name="false" label="5 more members" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: inline-flex; align-items: center;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 4;"></md-avatar>
  <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
  <md-avatar name="Grace Hopper" label="Grace Hopper" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
  <md-avatar initials="+5" color-from-name="false" label="5 more members" style="z-index: 1;"></md-avatar>
</div>

<div style="display: inline-flex; align-items: center;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 4;"></md-avatar>
  <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
  <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
  <md-avatar initials="+5" color-from-name="false" label="5 more members" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
</div>

Outlined and blended groups

Outlined — a surface-coloured ring separates each tile

Blended — the ring picks up the surface behind the group

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: grid; gap: 20px;">
  <div>
    <p style="margin: 0 0 8px; font: 500 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Outlined — a surface-coloured ring separates each tile</p>
    <div style="display: inline-flex; align-items: center; padding: 8px; border-radius: 12px; background: linear-gradient(135deg, var(--md-sys-color-primary-container), var(--md-sys-color-tertiary-container));">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 4;"></md-avatar>
      <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
      <md-avatar initials="+5" color-from-name="false" label="Five more" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
    </div>
  </div>
  <div>
    <p style="margin: 0 0 8px; font: 500 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Blended — the ring picks up the surface behind the group</p>
    <div style="display: inline-flex; align-items: center; padding: 8px; border-radius: 12px; background: var(--md-sys-color-surface-container-highest);">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
      <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
    </div>
  </div>
</div>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gap: '20px' }}>
        <div>
          <p style={{ margin: '0 0 8px', font: '500 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>Outlined — a surface-coloured ring separates each tile</p>
          <div style={{ display: 'inline-flex', alignItems: 'center', padding: '8px', borderRadius: '12px', background: 'linear-gradient(135deg, var(--md-sys-color-primary-container), var(--md-sys-color-tertiary-container))' }}>
            <MdAvatar name="Ada Lovelace" label="Ada Lovelace" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface)', '--md-avatar-outline-width': '2px', marginInlineEnd: '-8px', zIndex: '4' }}></MdAvatar>
            <MdAvatar name="Linus Torvalds" label="Linus Torvalds" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface)', '--md-avatar-outline-width': '2px', marginInlineEnd: '-8px', zIndex: '3' }}></MdAvatar>
            <MdAvatar name="Grace Hopper" label="Grace Hopper" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface)', '--md-avatar-outline-width': '2px', marginInlineEnd: '-8px', zIndex: '2' }}></MdAvatar>
            <MdAvatar initials="+5" colorFromName="false" label="Five more" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface)', '--md-avatar-outline-width': '2px', zIndex: '1' }}></MdAvatar>
          </div>
        </div>
        <div>
          <p style={{ margin: '0 0 8px', font: '500 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>Blended — the ring picks up the surface behind the group</p>
          <div style={{ display: 'inline-flex', alignItems: 'center', padding: '8px', borderRadius: '12px', background: 'var(--md-sys-color-surface-container-highest)' }}>
            <MdAvatar name="Ada Lovelace" label="Ada Lovelace" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface-container-highest)', '--md-avatar-outline-width': '2px', marginInlineEnd: '-8px', zIndex: '3' }}></MdAvatar>
            <MdAvatar name="Linus Torvalds" label="Linus Torvalds" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface-container-highest)', '--md-avatar-outline-width': '2px', marginInlineEnd: '-8px', zIndex: '2' }}></MdAvatar>
            <MdAvatar name="Grace Hopper" label="Grace Hopper" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-surface-container-highest)', '--md-avatar-outline-width': '2px', zIndex: '1' }}></MdAvatar>
          </div>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: grid; gap: 20px;">
  <div>
    <p style="margin: 0 0 8px; font: 500 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Outlined — a surface-coloured ring separates each tile</p>
    <div style="display: inline-flex; align-items: center; padding: 8px; border-radius: 12px; background: linear-gradient(135deg, var(--md-sys-color-primary-container), var(--md-sys-color-tertiary-container));">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 4;"></md-avatar>
      <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
      <md-avatar initials="+5" color-from-name="false" label="Five more" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
    </div>
  </div>
  <div>
    <p style="margin: 0 0 8px; font: 500 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Blended — the ring picks up the surface behind the group</p>
    <div style="display: inline-flex; align-items: center; padding: 8px; border-radius: 12px; background: var(--md-sys-color-surface-container-highest);">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
      <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
    </div>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: grid; gap: 20px;">
    <div>
      <p style="margin: 0 0 8px; font: 500 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Outlined — a surface-coloured ring separates each tile</p>
      <div style="display: inline-flex; align-items: center; padding: 8px; border-radius: 12px; background: linear-gradient(135deg, var(--md-sys-color-primary-container), var(--md-sys-color-tertiary-container));">
        <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 4;"></md-avatar>
        <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
        <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
        <md-avatar initials="+5" color-from-name="false" label="Five more" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
      </div>
    </div>
    <div>
      <p style="margin: 0 0 8px; font: 500 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Blended — the ring picks up the surface behind the group</p>
      <div style="display: inline-flex; align-items: center; padding: 8px; border-radius: 12px; background: var(--md-sys-color-surface-container-highest);">
        <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
        <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
        <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
      </div>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: grid; gap: 20px;">
  <div>
    <p style="margin: 0 0 8px; font: 500 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Outlined — a surface-coloured ring separates each tile</p>
    <div style="display: inline-flex; align-items: center; padding: 8px; border-radius: 12px; background: linear-gradient(135deg, var(--md-sys-color-primary-container), var(--md-sys-color-tertiary-container));">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 4;"></md-avatar>
      <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
      <md-avatar initials="+5" color-from-name="false" label="Five more" style="--md-avatar-outline-color: var(--md-sys-color-surface); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
    </div>
  </div>
  <div>
    <p style="margin: 0 0 8px; font: 500 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Blended — the ring picks up the surface behind the group</p>
    <div style="display: inline-flex; align-items: center; padding: 8px; border-radius: 12px; background: var(--md-sys-color-surface-container-highest);">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 3;"></md-avatar>
      <md-avatar name="Linus Torvalds" label="Linus Torvalds" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; margin-inline-end: -8px; z-index: 2;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="--md-avatar-outline-color: var(--md-sys-color-surface-container-highest); --md-avatar-outline-width: 2px; z-index: 1;"></md-avatar>
    </div>
  </div>
</div>

In a real app the group comes from data: cap the visible members and roll the rest into a +N tile whose color-from-name is off, so the counter never borrows a person’s colour.

HTML React Angular Vue Svelte

Copy

<div id="team" style="display: inline-flex; align-items: center;"></div>

<script type="module">
const members = [
  { name: 'Ada Lovelace', photo: '/u/ada.jpg' },
  { name: 'Linus Torvalds' },
  { name: 'Grace Hopper' },
  { name: 'Alan Turing' },
  { name: 'Barbara Liskov' },
];
const MAX = 3;
const visible = members.slice(0, MAX);
const remaining = members.length - visible.length;
const team = document.getElementById('team');

visible.forEach((m, i) => {
  const a = document.createElement('md-avatar');
  if (m.photo) a.src = m.photo;
  a.name = m.name;
  a.label = m.name;
  a.style.marginInlineEnd = '-12px';
  a.style.zIndex = String(visible.length - i + 1);
  team.append(a);
});

if (remaining > 0) {
  const more = document.createElement('md-avatar');
  more.initials = '+' + remaining;
  more.colorFromName = false;
  more.label = remaining + ' more members';
  team.append(more);
}
</script>

Copy

import { MdAvatar } from '@awc-ui/react';

const MAX = 3;

type Member = { name: string; photo?: string };

export function AvatarGroup({ members }: { members: Member[] }) {
const visible = members.slice(0, MAX);
const remaining = members.length - visible.length;

return (
  <div style={{ display: 'inline-flex', alignItems: 'center' }}>
    {visible.map((m, i) => (
      <MdAvatar
        key={m.name}
        src={m.photo ?? ''}
        name={m.name}
        label={m.name}
        style={{ marginInlineEnd: '-12px', zIndex: visible.length - i + 1 }}
      />
    ))}
    {remaining > 0 && (
      <MdAvatar
        initials={'+' + remaining}
        colorFromName={false}
        label={remaining + ' more members'}
      />
    )}
  </div>
);
}

Copy

import { Component, Input } from '@angular/core';

interface Member { name: string; photo?: string; }

@Component({
selector: 'app-avatar-group',
template: `
  <div style="display: inline-flex; align-items: center;">
    <md-avatar
      *ngFor="let m of visible; let i = index"
      [src]="m.photo || ''"
      [name]="m.name"
      [label]="m.name"
      [style.margin-inline-end]="'-12px'"
      [style.z-index]="visible.length - i + 1"
    ></md-avatar>
    <md-avatar
      *ngIf="remaining > 0"
      [initials]="'+' + remaining"
      [colorFromName]="false"
      [label]="remaining + ' more members'"
    ></md-avatar>
  </div>
`,
})
export class AvatarGroupComponent {
@Input() members: Member[] = [];
readonly max = 3;
get visible() { return this.members.slice(0, this.max); }
get remaining() { return this.members.length - this.visible.length; }
}

Copy

<script setup lang="ts">
import { computed } from 'vue';

interface Member { name: string; photo?: string }

const props = defineProps<{ members: Member[] }>();
const MAX = 3;
const visible = computed(() => props.members.slice(0, MAX));
const remaining = computed(() => props.members.length - visible.value.length);
</script>

<template>
<div style="display: inline-flex; align-items: center;">
  <md-avatar
    v-for="(m, i) in visible"
    :key="m.name"
    :src="m.photo || ''"
    :name="m.name"
    :label="m.name"
    :style="{ marginInlineEnd: '-12px', zIndex: visible.length - i + 1 }"
  />
  <md-avatar
    v-if="remaining > 0"
    :initials="'+' + remaining"
    color-from-name="false"
    :label="remaining + ' more members'"
  />
</div>
</template>

Copy

<script lang="ts">
interface Member { name: string; photo?: string }

export let members: Member[] = [];
const MAX = 3;

$: visible = members.slice(0, MAX);
$: remaining = members.length - visible.length;
</script>

<div style="display: inline-flex; align-items: center;">
{#each visible as m, i (m.name)}
  <md-avatar
    src={m.photo || ''}
    name={m.name}
    label={m.name}
    style="margin-inline-end: -12px; z-index: {visible.length - i + 1};"
  />
{/each}
{#if remaining > 0}
  <md-avatar
    initials={'+' + remaining}
    color-from-name="false"
    label={remaining + ' more members'}
  />
{/if}
</div>

With a status dot

The avatar does not position a dot for you. Wrap both in a position: relative host.

Presence via md-status-dot

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<span style="position: relative; display: inline-block;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-status-dot state="online" label="Online"></md-status-dot>
</span>
<span style="position: relative; display: inline-block;">
  <md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
  <md-status-dot state="away" label="Away"></md-status-dot>
</span>
<span style="position: relative; display: inline-block;">
  <md-avatar name="Alan Turing" label="Alan Turing"></md-avatar>
  <md-status-dot state="offline" label="Offline"></md-status-dot>
</span>

Copy

import { MdAvatar, MdStatusDot } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <span style={{ position: 'relative', display: 'inline-block' }}>
        <MdAvatar name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
        <MdStatusDot state="online" label="Online"></MdStatusDot>
      </span>
      <span style={{ position: 'relative', display: 'inline-block' }}>
        <MdAvatar name="Grace Hopper" label="Grace Hopper"></MdAvatar>
        <MdStatusDot state="away" label="Away"></MdStatusDot>
      </span>
      <span style={{ position: 'relative', display: 'inline-block' }}>
        <MdAvatar name="Alan Turing" label="Alan Turing"></MdAvatar>
        <MdStatusDot state="offline" label="Offline"></MdStatusDot>
      </span>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<span style="position: relative; display: inline-block;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-status-dot state="online" label="Online"></md-status-dot>
</span>
<span style="position: relative; display: inline-block;">
  <md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
  <md-status-dot state="away" label="Away"></md-status-dot>
</span>
<span style="position: relative; display: inline-block;">
  <md-avatar name="Alan Turing" label="Alan Turing"></md-avatar>
  <md-status-dot state="offline" label="Offline"></md-status-dot>
</span>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <span style="position: relative; display: inline-block;">
    <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-status-dot state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-block;">
    <md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
    <md-status-dot state="away" label="Away"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-block;">
    <md-avatar name="Alan Turing" label="Alan Turing"></md-avatar>
    <md-status-dot state="offline" label="Offline"></md-status-dot>
  </span>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<span style="position: relative; display: inline-block;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-status-dot state="online" label="Online"></md-status-dot>
</span>
<span style="position: relative; display: inline-block;">
  <md-avatar name="Grace Hopper" label="Grace Hopper"></md-avatar>
  <md-status-dot state="away" label="Away"></md-status-dot>
</span>
<span style="position: relative; display: inline-block;">
  <md-avatar name="Alan Turing" label="Alan Turing"></md-avatar>
  <md-status-dot state="offline" label="Offline"></md-status-dot>
</span>

In a list

md-list-item reuses this component for its leading slot and runs the same fallback chain via leading-avatar, leading-avatar-name and leading-avatar-label.

Avatars inside md-list-item

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-list label="Team" style="inline-size: 100%; max-inline-size: 420px;">
  <md-list-item type="button" headline="Ada Lovelace" supporting-text="ada@example.com" leading-avatar="https://i.pravatar.cc/80?img=47" leading-avatar-alt="Ada Lovelace"></md-list-item>
  <md-list-item type="button" headline="Grace Hopper" supporting-text="grace@example.com" leading-avatar-name="Grace Hopper"></md-list-item>
  <md-list-item type="button" headline="Alan Turing" supporting-text="alan@example.com" leading-avatar-name="Alan Turing"></md-list-item>
</md-list>

Copy

import { MdList, MdListItem } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdList label="Team" style={{ inlineSize: '100%', maxInlineSize: '420px' }}>
        <MdListItem type="button" headline="Ada Lovelace" supportingText="ada@example.com" leadingAvatar="https://i.pravatar.cc/80?img=47" leadingAvatarAlt="Ada Lovelace"></MdListItem>
        <MdListItem type="button" headline="Grace Hopper" supportingText="grace@example.com" leadingAvatarName="Grace Hopper"></MdListItem>
        <MdListItem type="button" headline="Alan Turing" supportingText="alan@example.com" leadingAvatarName="Alan Turing"></MdListItem>
      </MdList>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-list label="Team" style="inline-size: 100%; max-inline-size: 420px;">
  <md-list-item type="button" headline="Ada Lovelace" supporting-text="ada@example.com" leading-avatar="https://i.pravatar.cc/80?img=47" leading-avatar-alt="Ada Lovelace"></md-list-item>
  <md-list-item type="button" headline="Grace Hopper" supporting-text="grace@example.com" leading-avatar-name="Grace Hopper"></md-list-item>
  <md-list-item type="button" headline="Alan Turing" supporting-text="alan@example.com" leading-avatar-name="Alan Turing"></md-list-item>
</md-list>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-list label="Team" style="inline-size: 100%; max-inline-size: 420px;">
    <md-list-item type="button" headline="Ada Lovelace" supporting-text="ada@example.com" leading-avatar="https://i.pravatar.cc/80?img=47" leading-avatar-alt="Ada Lovelace"></md-list-item>
    <md-list-item type="button" headline="Grace Hopper" supporting-text="grace@example.com" leading-avatar-name="Grace Hopper"></md-list-item>
    <md-list-item type="button" headline="Alan Turing" supporting-text="alan@example.com" leading-avatar-name="Alan Turing"></md-list-item>
  </md-list>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-list label="Team" style="inline-size: 100%; max-inline-size: 420px;">
  <md-list-item type="button" headline="Ada Lovelace" supporting-text="ada@example.com" leading-avatar="https://i.pravatar.cc/80?img=47" leading-avatar-alt="Ada Lovelace"></md-list-item>
  <md-list-item type="button" headline="Grace Hopper" supporting-text="grace@example.com" leading-avatar-name="Grace Hopper"></md-list-item>
  <md-list-item type="button" headline="Alan Turing" supporting-text="alan@example.com" leading-avatar-name="Alan Turing"></md-list-item>
</md-list>

When the person’s name is already the adjacent text, the avatar is decorative. Hide it by leaving label, alt and name empty — the component then renders role="presentation" and aria-hidden="true" itself. Do not write aria-hidden="true" on a labelled avatar: render() sets that attribute from the resolved accessible name, so an author-set value is removed on the first render whenever any of the three is present.

Events

Event	Cancelable	Detail	Fires
mdLoad	yes	{ src: string }	The image finished loading
mdError	yes	{ src: string }	The image failed; the component falls back

Both are plain @Event() declarations, so they carry Stencil’s defaults — bubbles, composed and cancelable. Nothing inside the component reads defaultPrevented, though, so cancelling one changes nothing; it is a side-effect of the default, not a control point.

interface MdAvatarEventDetail {
  /** The `src` that was being resolved when the event fired. */
  src: string;
}

Both events bubble and cross shadow boundaries, so one listener on a container covers a whole list. Press Reload both below: the first avatar re-fetches and emits mdLoad; the second 404s and emits mdError. The fallback is automatic but not yet painted when your listener runs — mdError is emitted synchronously from the image’s error handler and the re-render is queued, so the initials appear a tick later. Report the failure; don’t try to repair it.

mdLoad and mdError — one listener on the container

Reload both

Waiting for image events…

Show code for each technology

HTML React Angular Vue Svelte

Copy

<div id="roster">
<md-avatar src="/u/ada.jpg" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
<md-avatar src="/u/grace.jpg" name="Grace Hopper" label="Grace Hopper"></md-avatar>
</div>

<script type="module">
const roster = document.getElementById('roster');

roster.addEventListener('mdLoad', (e) => {
  console.log('loaded', e.detail.src);
});

roster.addEventListener('mdError', (e) => {
  // The avatar falls back on its own — just report it.
  console.warn('avatar missing', e.detail.src);
});
</script>

Copy

import { MdAvatar } from '@awc-ui/react';

type Member = { name: string; photo: string };

export function Roster({ members }: { members: Member[] }) {
const onLoad = (e: CustomEvent<{ src: string }>) => {
  console.log('loaded', e.detail.src);
};

const onError = (e: CustomEvent<{ src: string }>) => {
  // The avatar falls back on its own — just report it.
  console.warn('avatar missing', e.detail.src);
};

return (
  <div>
    {members.map((m) => (
      <MdAvatar
        key={m.name}
        src={m.photo}
        name={m.name}
        label={m.name}
        onMdLoad={onLoad}
        onMdError={onError}
      />
    ))}
  </div>
);
}

Copy

import { Component, Input } from '@angular/core';

interface Member { name: string; photo: string; }

@Component({
selector: 'app-roster',
template: `
  <div>
    <md-avatar
      *ngFor="let m of members"
      [src]="m.photo"
      [name]="m.name"
      [label]="m.name"
      (mdLoad)="onLoad($event)"
      (mdError)="onError($event)"
    ></md-avatar>
  </div>
`,
})
export class RosterComponent {
@Input() members: Member[] = [];

onLoad(e: CustomEvent<{ src: string }>) {
  console.log('loaded', e.detail.src);
}

onError(e: CustomEvent<{ src: string }>) {
  // The avatar falls back on its own — just report it.
  console.warn('avatar missing', e.detail.src);
}
}

Copy

<script setup lang="ts">
interface Member { name: string; photo: string }

defineProps<{ members: Member[] }>();

function onLoad(e: CustomEvent<{ src: string }>) {
console.log('loaded', e.detail.src);
}

function onError(e: CustomEvent<{ src: string }>) {
// The avatar falls back on its own — just report it.
console.warn('avatar missing', e.detail.src);
}
</script>

<template>
<div>
  <md-avatar
    v-for="m in members"
    :key="m.name"
    :src="m.photo"
    :name="m.name"
    :label="m.name"
    @mdLoad="onLoad"
    @mdError="onError"
  />
</div>
</template>

Copy

<script lang="ts">
interface Member { name: string; photo: string }

export let members: Member[] = [];

function onLoad(e: CustomEvent<{ src: string }>) {
  console.log('loaded', e.detail.src);
}

function onError(e: CustomEvent<{ src: string }>) {
  // The avatar falls back on its own — just report it.
  console.warn('avatar missing', e.detail.src);
}
</script>

<div>
{#each members as m (m.name)}
  <md-avatar
    src={m.photo}
    name={m.name}
    label={m.name}
    on:mdLoad={onLoad}
    on:mdError={onError}
  />
{/each}
</div>

API Reference

tune

Properties

Property	Attribute	Type	Default	Reflects
src	src	string	''	—
alt	alt	string	''	—
name	name	string	''	—
initials	initials	string	''	—
size	size	MdAvatarSize	'medium'	Yes
shape	shape	MdAvatarShape	'circle'	Yes
label	label	string	''	—
colorFromName	color-from-name	boolean	true	Yes
loading	loading	'eager' | 'lazy'	'lazy'	—
crossorigin	crossorigin	'' | 'anonymous' | 'use-credentials'	''	—
density	density	0 | -1 | -2 | -3 | -4	0	Yes

view_in_ar

Slots

Slot	Description
(default)	—

palette

CSS Custom Properties

Override on the host element for per-instance theming:

Property	Description
--md-avatar-size	Square size of the host
--md-avatar-container-color	Container fill (initials/icon mode)
--md-avatar-container-shape	Border-radius override
--md-avatar-label-color	Initials / icon color
--md-avatar-label-font-family	Initials font family
--md-avatar-label-font-size	Initials font size
--md-avatar-label-font-weight	Initials font weight
--md-avatar-icon-size	Icon glyph size
--md-avatar-outline-color	Optional outline color
--md-avatar-outline-width	Optional outline width (default 0)
--md-avatar-label-letter-spacing	—

layers

CSS Shadow Parts

Style internal elements through shadow DOM with ::part():

Part	Description
image	The `<img>` element (image mode)
initials	The initials text element
icon	The fallback person icon

Accessibility

• Decide deliberately: either the avatar carries the identity (set label) or it is decorative beside the name. Both are correct; doing neither, or both, is not.
• The accessible name resolves as label → alt → name. When all three are empty the host renders role="presentation" and aria-hidden="true", which is exactly what you want next to a row that already says the name.
• When any of them is set, the host renders role="img" with that string as aria-label, and the inner <img> is aria-hidden so the name is announced once.
• alt describes the image; label is the accessible name of the avatar. They are not the same slot.
• The initials fallback must have adequate contrast. The built-in palette is designed for it — custom container colours need checking.
• The avatar is not focusable. If the whole row is interactive, put the affordance on the row.
• loading="lazy" is the default; use eager only above the fold.
• Set crossorigin for CDN images you intend to read from a canvas, or you get a tainted canvas.

Walk the four rows below with a screen reader: only the first three are announced at all, and the fourth — initials with no label, alt or name — is silent by construction.

How the accessible name resolves — label, alt, name, then silence

label

role="img", announced as "Ada Lovelace"

alt

no label — alt becomes the accessible name

name

no label or alt — name becomes the accessible name

none

Barbara Liskov — role="presentation", the avatar stays silent

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">label</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">role="img", announced as "Ada Lovelace"</span>
  </div>

  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">alt</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar src="https://i.pravatar.cc/80?img=32" alt="Grace Hopper"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">no label — alt becomes the accessible name</span>
  </div>

  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">name</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar name="Alan Turing"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">no label or alt — name becomes the accessible name</span>
  </div>

  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">none</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar initials="BL"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Barbara Liskov — role="presentation", the avatar stays silent</span>
  </div>
</div>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '6rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>label</span>
        <div style={{ display: 'flex', gap: '12px', alignItems: 'center', flexWrap: 'wrap' }}>
          <MdAvatar name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
          <span style={{ font: '400 13px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>role="img", announced as "Ada Lovelace"</span>
        </div>

        <span style={{ inlineSize: '6rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>alt</span>
        <div style={{ display: 'flex', gap: '12px', alignItems: 'center', flexWrap: 'wrap' }}>
          <MdAvatar src="https://i.pravatar.cc/80?img=32" alt="Grace Hopper"></MdAvatar>
          <span style={{ font: '400 13px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>no label — alt becomes the accessible name</span>
        </div>

        <span style={{ inlineSize: '6rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>name</span>
        <div style={{ display: 'flex', gap: '12px', alignItems: 'center', flexWrap: 'wrap' }}>
          <MdAvatar name="Alan Turing"></MdAvatar>
          <span style={{ font: '400 13px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>no label or alt — name becomes the accessible name</span>
        </div>

        <span style={{ inlineSize: '6rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>none</span>
        <div style={{ display: 'flex', gap: '12px', alignItems: 'center', flexWrap: 'wrap' }}>
          <MdAvatar initials="BL"></MdAvatar>
          <span style={{ font: '400 13px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>Barbara Liskov — role="presentation", the avatar stays silent</span>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">label</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">role="img", announced as "Ada Lovelace"</span>
  </div>

  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">alt</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar src="https://i.pravatar.cc/80?img=32" alt="Grace Hopper"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">no label — alt becomes the accessible name</span>
  </div>

  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">name</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar name="Alan Turing"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">no label or alt — name becomes the accessible name</span>
  </div>

  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">none</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar initials="BL"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Barbara Liskov — role="presentation", the avatar stays silent</span>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
    <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">label</span>
    <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
      <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">role="img", announced as "Ada Lovelace"</span>
    </div>

    <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">alt</span>
    <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
      <md-avatar src="https://i.pravatar.cc/80?img=32" alt="Grace Hopper"></md-avatar>
      <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">no label — alt becomes the accessible name</span>
    </div>

    <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">name</span>
    <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
      <md-avatar name="Alan Turing"></md-avatar>
      <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">no label or alt — name becomes the accessible name</span>
    </div>

    <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">none</span>
    <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
      <md-avatar initials="BL"></md-avatar>
      <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Barbara Liskov — role="presentation", the avatar stays silent</span>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">label</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">role="img", announced as "Ada Lovelace"</span>
  </div>

  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">alt</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar src="https://i.pravatar.cc/80?img=32" alt="Grace Hopper"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">no label — alt becomes the accessible name</span>
  </div>

  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">name</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar name="Alan Turing"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">no label or alt — name becomes the accessible name</span>
  </div>

  <span style="inline-size: 6rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">none</span>
  <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
    <md-avatar initials="BL"></md-avatar>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">Barbara Liskov — role="presentation", the avatar stays silent</span>
  </div>
</div>

initials alone does not name the avatar

initials seeds the palette but never the accessible name — only label, alt and name do. That is the mechanism behind the decorative row above, and it is why an avatar with only initials is safe to place beside text that already says who it is.

RTL, density & i18n

RTL — the avatar itself is symmetric and needs nothing. What moves is everything attached to it: an md-status-dot anchors with inset-inline-end / inset-block-end, and a group stacked with margin-inline-end lays itself out from the right. Write both with logical properties and the same markup works in both directions. See RTL.

<span style="position: relative; display: inline-flex;">
  <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-status-dot state="online" label="Online"></md-status-dot>
</span>

Same markup, dir=ltr vs dir=rtl

ltr

rtl

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">ltr</span>
  <div dir="ltr" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
      <md-status-dot state="online" label="Online"></md-status-dot>
    </span>
    <div style="display: inline-flex; align-items: center;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
      <md-avatar name="Alan Turing" label="Alan Turing" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="z-index: 1;"></md-avatar>
    </div>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">rtl</span>
  <div dir="rtl" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
      <md-status-dot state="online" label="Online"></md-status-dot>
    </span>
    <div style="display: inline-flex; align-items: center;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
      <md-avatar name="Alan Turing" label="Alan Turing" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="z-index: 1;"></md-avatar>
    </div>
  </div>
</div>

Copy

import { MdAvatar, MdStatusDot } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>ltr</span>
        <div dir="ltr" style={{ display: 'flex', gap: '24px', alignItems: 'center', flexWrap: 'wrap' }}>
          <span style={{ position: 'relative', display: 'inline-flex' }}>
            <MdAvatar name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
            <MdStatusDot state="online" label="Online"></MdStatusDot>
          </span>
          <div style={{ display: 'inline-flex', alignItems: 'center' }}>
            <MdAvatar name="Ada Lovelace" label="Ada Lovelace" style={{ marginInlineEnd: '-12px', zIndex: '3' }}></MdAvatar>
            <MdAvatar name="Alan Turing" label="Alan Turing" style={{ marginInlineEnd: '-12px', zIndex: '2' }}></MdAvatar>
            <MdAvatar name="Grace Hopper" label="Grace Hopper" style={{ zIndex: '1' }}></MdAvatar>
          </div>
        </div>

        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>rtl</span>
        <div dir="rtl" style={{ display: 'flex', gap: '24px', alignItems: 'center', flexWrap: 'wrap' }}>
          <span style={{ position: 'relative', display: 'inline-flex' }}>
            <MdAvatar name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
            <MdStatusDot state="online" label="Online"></MdStatusDot>
          </span>
          <div style={{ display: 'inline-flex', alignItems: 'center' }}>
            <MdAvatar name="Ada Lovelace" label="Ada Lovelace" style={{ marginInlineEnd: '-12px', zIndex: '3' }}></MdAvatar>
            <MdAvatar name="Alan Turing" label="Alan Turing" style={{ marginInlineEnd: '-12px', zIndex: '2' }}></MdAvatar>
            <MdAvatar name="Grace Hopper" label="Grace Hopper" style={{ zIndex: '1' }}></MdAvatar>
          </div>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">ltr</span>
  <div dir="ltr" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
      <md-status-dot state="online" label="Online"></md-status-dot>
    </span>
    <div style="display: inline-flex; align-items: center;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
      <md-avatar name="Alan Turing" label="Alan Turing" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="z-index: 1;"></md-avatar>
    </div>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">rtl</span>
  <div dir="rtl" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
      <md-status-dot state="online" label="Online"></md-status-dot>
    </span>
    <div style="display: inline-flex; align-items: center;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
      <md-avatar name="Alan Turing" label="Alan Turing" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="z-index: 1;"></md-avatar>
    </div>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">ltr</span>
    <div dir="ltr" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
      <span style="position: relative; display: inline-flex;">
        <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
        <md-status-dot state="online" label="Online"></md-status-dot>
      </span>
      <div style="display: inline-flex; align-items: center;">
        <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
        <md-avatar name="Alan Turing" label="Alan Turing" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
        <md-avatar name="Grace Hopper" label="Grace Hopper" style="z-index: 1;"></md-avatar>
      </div>
    </div>

    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">rtl</span>
    <div dir="rtl" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
      <span style="position: relative; display: inline-flex;">
        <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
        <md-status-dot state="online" label="Online"></md-status-dot>
      </span>
      <div style="display: inline-flex; align-items: center;">
        <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
        <md-avatar name="Alan Turing" label="Alan Turing" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
        <md-avatar name="Grace Hopper" label="Grace Hopper" style="z-index: 1;"></md-avatar>
      </div>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">ltr</span>
  <div dir="ltr" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
      <md-status-dot state="online" label="Online"></md-status-dot>
    </span>
    <div style="display: inline-flex; align-items: center;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
      <md-avatar name="Alan Turing" label="Alan Turing" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="z-index: 1;"></md-avatar>
    </div>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">rtl</span>
  <div dir="rtl" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
      <md-status-dot state="online" label="Online"></md-status-dot>
    </span>
    <div style="display: inline-flex; align-items: center;">
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" style="margin-inline-end: -12px; z-index: 3;"></md-avatar>
      <md-avatar name="Alan Turing" label="Alan Turing" style="margin-inline-end: -12px; z-index: 2;"></md-avatar>
      <md-avatar name="Grace Hopper" label="Grace Hopper" style="z-index: 1;"></md-avatar>
    </div>
  </div>
</div>

The dot and the stack are the directional parts

The dot places itself with logical insets, and the built-in --md-status-dot-inset-end hook is logical too. Reach past it for a physical right and the pip lands on the wrong corner the moment the page flips — both rows below are under dir="rtl".

dir=rtl — logical insets vs a hard-coded physical right

correct

logical insets — the pip follows the text direction

wrong

a physical right: pinned to the wrong corner

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div dir="rtl" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 4.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">correct</span>
  <div style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="آدا لوفلايس" label="آدا لوفلايس"></md-avatar>
      <md-status-dot state="online" label="متصل"></md-status-dot>
    </span>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">logical insets — the pip follows the text direction</span>
  </div>

  <span style="inline-size: 4.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">wrong</span>
  <div style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="آلان تورنغ" label="آلان تورنغ"></md-avatar>
      <md-status-dot state="busy" label="مشغول" style="inset-inline-end: auto; right: -2px;"></md-status-dot>
    </span>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">a physical right: pinned to the wrong corner</span>
  </div>
</div>

Copy

import { MdAvatar, MdStatusDot } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div dir="rtl" style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>correct</span>
        <div style={{ display: 'flex', gap: '24px', alignItems: 'center', flexWrap: 'wrap' }}>
          <span style={{ position: 'relative', display: 'inline-flex' }}>
            <MdAvatar name="آدا لوفلايس" label="آدا لوفلايس"></MdAvatar>
            <MdStatusDot state="online" label="متصل"></MdStatusDot>
          </span>
          <span style={{ font: '400 13px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>logical insets — the pip follows the text direction</span>
        </div>

        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>wrong</span>
        <div style={{ display: 'flex', gap: '24px', alignItems: 'center', flexWrap: 'wrap' }}>
          <span style={{ position: 'relative', display: 'inline-flex' }}>
            <MdAvatar name="آلان تورنغ" label="آلان تورنغ"></MdAvatar>
            <MdStatusDot state="busy" label="مشغول" style={{ insetInlineEnd: 'auto', right: '-2px' }}></MdStatusDot>
          </span>
          <span style={{ font: '400 13px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>a physical right: pinned to the wrong corner</span>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div dir="rtl" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 4.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">correct</span>
  <div style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="آدا لوفلايس" label="آدا لوفلايس"></md-avatar>
      <md-status-dot state="online" label="متصل"></md-status-dot>
    </span>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">logical insets — the pip follows the text direction</span>
  </div>

  <span style="inline-size: 4.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">wrong</span>
  <div style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="آلان تورنغ" label="آلان تورنغ"></md-avatar>
      <md-status-dot state="busy" label="مشغول" style="inset-inline-end: auto; right: -2px;"></md-status-dot>
    </span>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">a physical right: pinned to the wrong corner</span>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div dir="rtl" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
    <span style="inline-size: 4.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">correct</span>
    <div style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
      <span style="position: relative; display: inline-flex;">
        <md-avatar name="آدا لوفلايس" label="آدا لوفلايس"></md-avatar>
        <md-status-dot state="online" label="متصل"></md-status-dot>
      </span>
      <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">logical insets — the pip follows the text direction</span>
    </div>

    <span style="inline-size: 4.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">wrong</span>
    <div style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
      <span style="position: relative; display: inline-flex;">
        <md-avatar name="آلان تورنغ" label="آلان تورنغ"></md-avatar>
        <md-status-dot state="busy" label="مشغول" style="inset-inline-end: auto; right: -2px;"></md-status-dot>
      </span>
      <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">a physical right: pinned to the wrong corner</span>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div dir="rtl" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 4.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">correct</span>
  <div style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="آدا لوفلايس" label="آدا لوفلايس"></md-avatar>
      <md-status-dot state="online" label="متصل"></md-status-dot>
    </span>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">logical insets — the pip follows the text direction</span>
  </div>

  <span style="inline-size: 4.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">wrong</span>
  <div style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="آلان تورنغ" label="آلان تورنغ"></md-avatar>
      <md-status-dot state="busy" label="مشغول" style="inset-inline-end: auto; right: -2px;"></md-status-dot>
    </span>
    <span style="font: 400 13px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">a physical right: pinned to the wrong corner</span>
  </div>
</div>

Every density rung

Default through -4 across all three presets — and an explicit size that ignores them

default

-1

-2

-3

-4

48px

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">default</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-1</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-2</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-3</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-4</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">48px</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
    <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
  </div>
</div>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>default</span>
        <div style={{ display: 'flex', gap: '16px', alignItems: 'center', flexWrap: 'wrap' }}>
          <MdAvatar size="small" name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
          <MdAvatar name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
          <MdAvatar size="large" name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
        </div>

        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>-1</span>
        <div style={{ display: 'flex', gap: '16px', alignItems: 'center', flexWrap: 'wrap' }}>
          <MdAvatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-1"></MdAvatar>
          <MdAvatar name="Ada Lovelace" label="Ada Lovelace" density="-1"></MdAvatar>
          <MdAvatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-1"></MdAvatar>
        </div>

        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>-2</span>
        <div style={{ display: 'flex', gap: '16px', alignItems: 'center', flexWrap: 'wrap' }}>
          <MdAvatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-2"></MdAvatar>
          <MdAvatar name="Ada Lovelace" label="Ada Lovelace" density="-2"></MdAvatar>
          <MdAvatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-2"></MdAvatar>
        </div>

        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>-3</span>
        <div style={{ display: 'flex', gap: '16px', alignItems: 'center', flexWrap: 'wrap' }}>
          <MdAvatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-3"></MdAvatar>
          <MdAvatar name="Ada Lovelace" label="Ada Lovelace" density="-3"></MdAvatar>
          <MdAvatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-3"></MdAvatar>
        </div>

        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>-4</span>
        <div style={{ display: 'flex', gap: '16px', alignItems: 'center', flexWrap: 'wrap' }}>
          <MdAvatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-4"></MdAvatar>
          <MdAvatar name="Ada Lovelace" label="Ada Lovelace" density="-4"></MdAvatar>
          <MdAvatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-4"></MdAvatar>
        </div>

        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>48px</span>
        <div style={{ display: 'flex', gap: '16px', alignItems: 'center', flexWrap: 'wrap' }}>
          <MdAvatar size="48px" name="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
          <MdAvatar size="48px" name="Ada Lovelace" label="Ada Lovelace" density="-2"></MdAvatar>
          <MdAvatar size="48px" name="Ada Lovelace" label="Ada Lovelace" density="-4"></MdAvatar>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">default</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-1</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-2</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-3</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-4</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">48px</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
    <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">default</span>
    <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
      <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
      <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
      <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    </div>

    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-1</span>
    <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
      <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
      <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
    </div>

    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-2</span>
    <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
      <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
      <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
    </div>

    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-3</span>
    <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
      <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
      <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
    </div>

    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-4</span>
    <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
      <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
      <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
      <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
    </div>

    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">48px</span>
    <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
      <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
      <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
      <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">default</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-1</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-1"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-2</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-3</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-3"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-4</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="small" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
    <md-avatar name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
    <md-avatar size="large" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
  </div>

  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">48px</span>
  <div style="display: flex; gap: 16px; align-items: center; flex-wrap: wrap;">
    <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace" density="-2"></md-avatar>
    <md-avatar size="48px" name="Ada Lovelace" label="Ada Lovelace" density="-4"></md-avatar>
  </div>
</div>

Below -2, check the initials, not the touch target

The avatar is not focusable, so the 48px touch rule never applies to it — but each rung shrinks the tile and its initials with it, and every preset bottoms out at a floor (medium at 28px, small at 18px). At -3 and -4 a two-character initial is genuinely small; if the row is interactive, the hit area belongs to the row, not the avatar.

Density and direction together

dir=rtl under data-density=-2 — then a local -4 rung, then an explicit 40px size

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div dir="rtl" data-density="-2" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap; padding: 12px; border-radius: 12px; background: var(--md-sys-color-surface-container-low);">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="آدا لوفلايس" label="آدا لوفلايس"></md-avatar>
    <md-status-dot state="online" label="متصل"></md-status-dot>
  </span>
  <div style="display: inline-flex; align-items: center;">
    <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" style="margin-inline-end: -10px; z-index: 3;"></md-avatar>
    <md-avatar name="آلان تورنغ" label="آلان تورنغ" style="margin-inline-end: -10px; z-index: 2;"></md-avatar>
    <md-avatar name="غريس هوبر" label="غريس هوبر" style="z-index: 1;"></md-avatar>
  </div>
  <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" density="-4"></md-avatar>
  <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" size="40px"></md-avatar>
</div>

Copy

import { MdAvatar, MdStatusDot } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div dir="rtl" data-density="-2" style={{ display: 'flex', gap: '24px', alignItems: 'center', flexWrap: 'wrap', padding: '12px', borderRadius: '12px', background: 'var(--md-sys-color-surface-container-low)' }}>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="آدا لوفلايس" label="آدا لوفلايس"></MdAvatar>
          <MdStatusDot state="online" label="متصل"></MdStatusDot>
        </span>
        <div style={{ display: 'inline-flex', alignItems: 'center' }}>
          <MdAvatar name="آدا لوفلايس" label="آدا لوفلايس" style={{ marginInlineEnd: '-10px', zIndex: '3' }}></MdAvatar>
          <MdAvatar name="آلان تورنغ" label="آلان تورنغ" style={{ marginInlineEnd: '-10px', zIndex: '2' }}></MdAvatar>
          <MdAvatar name="غريس هوبر" label="غريس هوبر" style={{ zIndex: '1' }}></MdAvatar>
        </div>
        <MdAvatar name="آدا لوفلايس" label="آدا لوفلايس" density="-4"></MdAvatar>
        <MdAvatar name="آدا لوفلايس" label="آدا لوفلايس" size="40px"></MdAvatar>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div dir="rtl" data-density="-2" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap; padding: 12px; border-radius: 12px; background: var(--md-sys-color-surface-container-low);">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="آدا لوفلايس" label="آدا لوفلايس"></md-avatar>
    <md-status-dot state="online" label="متصل"></md-status-dot>
  </span>
  <div style="display: inline-flex; align-items: center;">
    <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" style="margin-inline-end: -10px; z-index: 3;"></md-avatar>
    <md-avatar name="آلان تورنغ" label="آلان تورنغ" style="margin-inline-end: -10px; z-index: 2;"></md-avatar>
    <md-avatar name="غريس هوبر" label="غريس هوبر" style="z-index: 1;"></md-avatar>
  </div>
  <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" density="-4"></md-avatar>
  <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" size="40px"></md-avatar>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div dir="rtl" data-density="-2" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap; padding: 12px; border-radius: 12px; background: var(--md-sys-color-surface-container-low);">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="آدا لوفلايس" label="آدا لوفلايس"></md-avatar>
      <md-status-dot state="online" label="متصل"></md-status-dot>
    </span>
    <div style="display: inline-flex; align-items: center;">
      <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" style="margin-inline-end: -10px; z-index: 3;"></md-avatar>
      <md-avatar name="آلان تورنغ" label="آلان تورنغ" style="margin-inline-end: -10px; z-index: 2;"></md-avatar>
      <md-avatar name="غريس هوبر" label="غريس هوبر" style="z-index: 1;"></md-avatar>
    </div>
    <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" density="-4"></md-avatar>
    <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" size="40px"></md-avatar>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div dir="rtl" data-density="-2" style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap; padding: 12px; border-radius: 12px; background: var(--md-sys-color-surface-container-low);">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="آدا لوفلايس" label="آدا لوفلايس"></md-avatar>
    <md-status-dot state="online" label="متصل"></md-status-dot>
  </span>
  <div style="display: inline-flex; align-items: center;">
    <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" style="margin-inline-end: -10px; z-index: 3;"></md-avatar>
    <md-avatar name="آلان تورنغ" label="آلان تورنغ" style="margin-inline-end: -10px; z-index: 2;"></md-avatar>
    <md-avatar name="غريس هوبر" label="غريس هوبر" style="z-index: 1;"></md-avatar>
  </div>
  <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" density="-4"></md-avatar>
  <md-avatar name="آدا لوفلايس" label="آدا لوفلايس" size="40px"></md-avatar>
</div>

Density — density="-1…-4" (or a data-density ancestor) shrinks the preset sizes by driving --md-sys-density-scale. An explicit CSS length in size writes --md-avatar-size directly and is unaffected — that is the last avatar above, sitting at 40px inside a -2 container.

A local rung wins over the inherited global one, because :host([density='-1']) … :host([density='-4']) land the custom property directly on the host. density="0" is not a rung. There is deliberately no [density="0"] rule anywhere in the token layer — reflected props write density="0" onto nearly every element, so such a rule would pin density-0 on everything and break global inheritance. Absence of a rung means “inherit whatever the ancestor says”, so density="0" inside data-density="-2" still renders at -2. To opt a single avatar out of an inherited rung, pin its size to a CSS length. See Density.

i18n — initials derived from name follow the string’s own script via Intl.Segmenter, so non-Latin names work; check that a two-character slice is meaningful in your locales (it usually isn’t for CJK — pass initials there). Translate label and alt.

Theming

Custom property	Purpose	Default
--md-avatar-size	Box size	40px, tapers with density
--md-avatar-container-color	Tile background	Name-derived palette slot
--md-avatar-container-shape	Corner radius	Per shape
--md-avatar-label-color	Initials colour	Palette slot label
--md-avatar-label-font-family / -font-size / -font-weight / -letter-spacing	Initials typography	Font size is 40% of the box
--md-avatar-icon-size	Fallback glyph	60% of the box
--md-avatar-outline-color / --md-avatar-outline-width	Ring	none
--md-avatar-palette-1-container … -7-container (and -label)	Name-derived palette	Tonal set

Themed instances — note color-from-name=false on the branded tile

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-avatar name="Ada Lovelace" label="Ringed" style="--md-avatar-outline-color: var(--md-sys-color-primary); --md-avatar-outline-width: 3px;"></md-avatar>
<md-avatar name="Ada Lovelace" label="Branded" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-primary); --md-avatar-label-color: var(--md-sys-color-on-primary);"></md-avatar>
<md-avatar name="Ada Lovelace" label="Squared" shape="rounded" style="--md-avatar-container-shape: 6px; --md-avatar-size: 56px;"></md-avatar>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdAvatar name="Ada Lovelace" label="Ringed" style={{ '--md-avatar-outline-color': 'var(--md-sys-color-primary)', '--md-avatar-outline-width': '3px' }}></MdAvatar>
      <MdAvatar name="Ada Lovelace" label="Branded" colorFromName="false" style={{ '--md-avatar-container-color': 'var(--md-sys-color-primary)', '--md-avatar-label-color': 'var(--md-sys-color-on-primary)' }}></MdAvatar>
      <MdAvatar name="Ada Lovelace" label="Squared" shape="rounded" style={{ '--md-avatar-container-shape': '6px', '--md-avatar-size': '56px' }}></MdAvatar>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-avatar name="Ada Lovelace" label="Ringed" style="--md-avatar-outline-color: var(--md-sys-color-primary); --md-avatar-outline-width: 3px;"></md-avatar>
<md-avatar name="Ada Lovelace" label="Branded" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-primary); --md-avatar-label-color: var(--md-sys-color-on-primary);"></md-avatar>
<md-avatar name="Ada Lovelace" label="Squared" shape="rounded" style="--md-avatar-container-shape: 6px; --md-avatar-size: 56px;"></md-avatar>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-avatar name="Ada Lovelace" label="Ringed" style="--md-avatar-outline-color: var(--md-sys-color-primary); --md-avatar-outline-width: 3px;"></md-avatar>
  <md-avatar name="Ada Lovelace" label="Branded" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-primary); --md-avatar-label-color: var(--md-sys-color-on-primary);"></md-avatar>
  <md-avatar name="Ada Lovelace" label="Squared" shape="rounded" style="--md-avatar-container-shape: 6px; --md-avatar-size: 56px;"></md-avatar>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-avatar name="Ada Lovelace" label="Ringed" style="--md-avatar-outline-color: var(--md-sys-color-primary); --md-avatar-outline-width: 3px;"></md-avatar>
<md-avatar name="Ada Lovelace" label="Branded" color-from-name="false" style="--md-avatar-container-color: var(--md-sys-color-primary); --md-avatar-label-color: var(--md-sys-color-on-primary);"></md-avatar>
<md-avatar name="Ada Lovelace" label="Squared" shape="rounded" style="--md-avatar-container-shape: 6px; --md-avatar-size: 56px;"></md-avatar>

--md-avatar-container-color and --md-avatar-label-color are read only by the base :host rule, which the palette rule out-specifies — so they take effect only when color-from-name is false (or the seed is empty). Everything else in the table above (--md-avatar-size, -container-shape, -outline-*, -icon-size, the typography hooks) is unaffected by the palette; the palette itself is retinted through --md-avatar-palette-N-container / -label.

The name-derived palette is tuned per theme, so check any override in both.

CSS parts — image (the <img>), initials (the text span) and icon (the built-in person glyph). Each is reachable from the light DOM with ::part(), which is how you restyle the inside without touching the tokens.

CSS parts — initials, image and icon restyled from the light DOM

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<style>
  .avatar-parts-demo md-avatar::part(initials) {
  font-variant-numeric: tabular-nums;
  letter-spacing: .06em;
  }
  .avatar-parts-demo md-avatar::part(image) {
  filter: grayscale(1) contrast(1.05);
  }
  .avatar-parts-demo md-avatar::part(icon) {
  opacity: .55;
  }
</style>
<div class="avatar-parts-demo" style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap;">
  <md-avatar initials="18" name="Eighteen" label="18 open items"></md-avatar>
  <md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar label="Unknown user"></md-avatar>
</div>

Copy

import { MdAvatar } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <style>
        .avatar-parts-demo md-avatar::part(initials) {
        font-variant-numeric: tabular-nums;
        letter-spacing: .06em;
        }
        .avatar-parts-demo md-avatar::part(image) {
        filter: grayscale(1) contrast(1.05);
        }
        .avatar-parts-demo md-avatar::part(icon) {
        opacity: .55;
        }
      </style>
      <div className="avatar-parts-demo" style={{ display: 'flex', gap: '20px', alignItems: 'center', flexWrap: 'wrap' }}>
        <MdAvatar initials="18" name="Eighteen" label="18 open items"></MdAvatar>
        <MdAvatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" label="Ada Lovelace"></MdAvatar>
        <MdAvatar label="Unknown user"></MdAvatar>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<style>
  .avatar-parts-demo md-avatar::part(initials) {
  font-variant-numeric: tabular-nums;
  letter-spacing: .06em;
  }
  .avatar-parts-demo md-avatar::part(image) {
  filter: grayscale(1) contrast(1.05);
  }
  .avatar-parts-demo md-avatar::part(icon) {
  opacity: .55;
  }
</style>
<div class="avatar-parts-demo" style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap;">
  <md-avatar initials="18" name="Eighteen" label="18 open items"></md-avatar>
  <md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar label="Unknown user"></md-avatar>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <style>
    .avatar-parts-demo md-avatar::part(initials) {
    font-variant-numeric: tabular-nums;
    letter-spacing: .06em;
    }
    .avatar-parts-demo md-avatar::part(image) {
    filter: grayscale(1) contrast(1.05);
    }
    .avatar-parts-demo md-avatar::part(icon) {
    opacity: .55;
    }
  </style>
  <div class="avatar-parts-demo" style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap;">
    <md-avatar initials="18" name="Eighteen" label="18 open items"></md-avatar>
    <md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" label="Ada Lovelace"></md-avatar>
    <md-avatar label="Unknown user"></md-avatar>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<style>
  .avatar-parts-demo md-avatar::part(initials) {
  font-variant-numeric: tabular-nums;
  letter-spacing: .06em;
  }
  .avatar-parts-demo md-avatar::part(image) {
  filter: grayscale(1) contrast(1.05);
  }
  .avatar-parts-demo md-avatar::part(icon) {
  opacity: .55;
  }
</style>
<div class="avatar-parts-demo" style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap;">
  <md-avatar initials="18" name="Eighteen" label="18 open items"></md-avatar>
  <md-avatar src="https://i.pravatar.cc/80?img=11" alt="Ada Lovelace" label="Ada Lovelace"></md-avatar>
  <md-avatar label="Unknown user"></md-avatar>
</div>

md-avatar::part(initials) {
  font-variant-numeric: tabular-nums;
}

Related

md-status-dot · md-badge · md-chip · md-list-item · md-organization-chart · md-app-bar

AI / LLM Context

For AI Agents — md-avatar

Two artefacts to give your AI agent so it generates correct UI with this component. The per-component spec answers "how do I use this exact tag?". The main-llm spec answers "which tag should I pick in the first place?".

Per-component

md-avatar spec card

Identity · when to use / when NOT · decision cues · behavioural contract · do/don't · anti-patterns · full API. Paste into your agent when you're implementing with this component.

Copy specExpand view

Main-LLM spec

AWC UI Operator's Manual

System-prompt preamble · decision matrix · token reference · page recipes · anti-patterns. Paste into the system prompt at the start of a piece of work.

Open specExpand view

md-avatar readme.md

Copy readme

# md-avatar

<!-- llm:meta
tag: md-avatar
category: status
status: custom
m3-guidelines: none — M3 has no avatar page
form-associated: false
depends-on: none
used-by: md-list-item, md-organization-chart
-->

**A person or entity, as an image, initials, or a fallback glyph.**
It resolves one source from a fixed chain — image, then initials, then slotted
content, then a `person` icon — with a deterministic container colour hashed
from the identity.

> ⚠️ **Not a Material Design 3 component.** M3 has no avatar page, so the
> Do/Don't table below is house rules rather than sourced guidance.

> Setup, theming, density and i18n are configured once for the whole library —
> see [`main-llm.md`](../../../../../main-llm.md) at the repo root.

---

## When to use

- Representing a **person, team, or organisation** in a list, table, comment,
  app bar, or org chart.
- Anywhere a photo may be missing and initials should stand in.

## When NOT to use

| Situation | Use instead |
|---|---|
| A decorative or content image | `<img>` |
| An icon-only action | `md-icon-button` |
| A removable person token | `md-chip variant="input"` |
| Presence state on its own | `md-status-dot` |
| A count marker | `md-badge` |
| A logo in an app bar | Plain `<img>` in the `md-app-bar` slot |

## Decision cues

| Need | Setting |
|---|---|
| Photo | `src` (+ `alt`) |
| Initials from a full name | `name="Ada Lovelace"` → `AL` |
| Explicit initials | `initials="AL"` (bypasses `name` parsing) |
| Fixed preset size | `size="small\|medium\|large"` (24 / 40 / 56 px) |
| Arbitrary size | `size="72"` (unitless → px), `size="4rem"`, `size="clamp(28px,4vw,72px)"` |
| Squared corners | `shape="rounded"` (12px) or `shape="square"` (0) |
| One neutral colour instead of a name-derived tint | `color-from-name="false"` |
| Above-the-fold images | `loading="eager"` |
| Cross-origin images you read from a canvas | `crossorigin="anonymous"` |
| Custom fallback content (emoji, SVG, icon) | default slot, with `src` and `initials`/`name` all empty |

## API contract

```html
<md-avatar
  src="/u/ada.jpg"                       <!-- default: "" -->
  alt="Ada Lovelace"                     <!-- default: "" — describes the image -->
  name="Ada Lovelace"                    <!-- default: "" — initials are derived -->
  initials="AL"                          <!-- default: "" — overrides name parsing -->
  size="small|medium|large|72|4rem"      <!-- default: medium -->
  shape="circle|rounded|square"          <!-- default: circle -->
  label="Ada Lovelace"                   <!-- default: "" — accessible name -->
  color-from-name="true|false"           <!-- default: true -->
  loading="lazy|eager"                   <!-- default: lazy -->
  crossorigin="anonymous|use-credentials"<!-- default: "" (attribute omitted) -->
  density="-1|-2|-3|-4"                  <!-- default: 0 (uncompacted) -->
></md-avatar>
```

**Events** — `mdLoad` `{ src }` when the `<img>` loads, `mdError` `{ src }`
when it fails. Both are Stencil defaults: they bubble and are composed.

**Methods** — none.

**Slots** — `(default)`: the **fourth** step of the five-step fallback chain.
Rendered only when there is no usable image **and** no initials. Slotted content does
not replace an image or initials.

**Parts** — `image` (the `<img>`), `initials` (the letters), `icon` (the
built-in `person` glyph). Exactly one exists at a time.

### Behavioral contract worth knowing

- **Fallback chain, in order:** `src` (while it loads) → `initials` → initials
  derived from `name` → default slot → built-in `person` icon. An image that
  404s emits `mdError` and falls through automatically, so you don't need your
  own `onerror` handler. Changing `src` resets the failure flag and retries.
- **The component owns `role`, `aria-label` and `aria-hidden` on the host.**
  When `label`, `alt` or `name` is non-empty (checked in that order) it renders
  `role="img"` + `aria-label`. When all three are empty it renders
  `role="presentation"` + `aria-hidden="true"`. Attributes you set yourself are
  removed on the next render.
- Therefore, to make an avatar **decorative**, leave `label`, `alt` and `name`
  empty and use `initials` for the letters — adding your own `aria-hidden` does
  not work.
- The inner `<img>` is always `aria-hidden="true"` and `draggable="false"`;
  `alt` reaches AT through the host's `aria-label`, not through the image.
- `size` is **not** a closed enum. The three presets get autocomplete, any CSS
  length passes through, and a bare number is treated as pixels. A non-preset
  value is written to `--md-avatar-size` as an inline style on the host, so a
  stylesheet rule setting the same property still wins.
- Preset sizes are density-aware (`medium` is `max(28px, 40px + density × 3px)`);
  a custom `size` is a fixed length and ignores density entirely.
- `color-from-name` (default **on**) hashes `initials || name || label` into one
  of seven tonal palette slots, so the same person keeps the same colour across
  sessions and devices. With no seed, or with `color-from-name="false"`, the
  neutral surface tone is used. The palette applies to initials/slot/icon modes
  only — never over an image.
- Initials are cut to the first **3 grapheme clusters** and upper-cased with
  `toLocaleUpperCase()`. Derivation from `name` takes the first letter of the
  first and last whitespace-separated token (`"Ada Lovelace"` → `AL`,
  `"Cher"` → `C`).

---

## Do / Don't

House rules — no M3 avatar page exists.

| ✅ Do | ❌ Don't |
|---|---|
| Provide `name` even when you have `src` | Don't leave the fallback blank if the image fails |
| Give a meaningful `label` when the avatar is the only identifier | Don't repeat the name when it is already adjacent text — leave `label`/`alt`/`name` empty instead |
| Keep `color-from-name` on for recognisability | Don't randomise colours per render — the hash is the point |
| Use `loading="lazy"` in long lists | Don't eager-load a hundred avatars |
| Use presets for consistency | Don't scatter arbitrary sizes without a reason |
| Wrap in a `position: relative` element when attaching `md-status-dot` or `md-badge` | Don't expect the marker to place itself otherwise |
| Use `shape="circle"` for people | Don't mix shapes for the same entity type |
| Set `crossorigin` for CDN images you read from a canvas | Don't ignore CORS and get a tainted canvas |

---

## Patterns

```html
<!-- Photo with initials fallback -->
<md-avatar src="/u/ada.jpg" alt="Ada Lovelace" name="Ada Lovelace"></md-avatar>

<!-- Initials only -->
<md-avatar name="Grace Hopper" size="large"></md-avatar>

<!-- Explicit initials, squared corners -->
<md-avatar initials="AC" shape="rounded" label="Acme Corp"></md-avatar>

<!-- Custom sizes: unitless is px, any CSS length passes through -->
<md-avatar name="Ada" size="72"></md-avatar>
<md-avatar name="Ada" size="clamp(28px, 4vw, 72px)"></md-avatar>

<!-- Neutral tone instead of the name-derived tint -->
<md-avatar name="Ada Lovelace" color-from-name="false"></md-avatar>
```

```html
<!-- Custom fallback: the default slot only renders with no image and no initials -->
<md-avatar label="Team Nebula">
  <span>🚀</span>
</md-avatar>
```

```html
<!-- Presence marker: the wrapper supplies the positioning context -->
<span style="position: relative; display: inline-block;">
  <md-avatar name="Ada Lovelace"></md-avatar>
  <md-status-dot state="online" label="Online"></md-status-dot>
</span>
```

```html
<!-- Decorative: the row already says the name, so leave label/alt/name empty -->
<md-list label="Team">
  <md-list-item headline="Ada Lovelace">
    <md-avatar slot="leading" initials="AL"></md-avatar>
  </md-list-item>
</md-list>
```

```js
const avatar = document.querySelector('md-avatar');
avatar.addEventListener('mdError', (e) => console.warn('avatar failed', e.detail.src));
avatar.addEventListener('mdLoad', (e) => console.log('avatar loaded', e.detail.src));
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| Your own `onerror` fallback on a wrapper | Rely on the built-in chain | It already falls back and emits `mdError`. |
| `<md-avatar src>` with no `name`/`initials` | Provide a fallback identity | A failed image leaves a generic `person` glyph. |
| `aria-hidden="true"` on an avatar that has a `name` | Leave `label`/`alt`/`name` empty and pass `initials` | The component rewrites `aria-hidden` on every render. |
| Slotting an emoji next to `name="Ada"` and expecting to see it | Clear `name`/`initials` first | The default slot renders only when there are no initials and no image. |
| Randomising the palette per render | Let `color-from-name` hash it | Consistency is the feature. |
| Assuming `size` only takes three values | Any CSS length works | It is an open type. |
| `size="72px"` vs `size="72"` | Both work — unitless means px | No need to guess. |
| Eager-loading a long list | `loading="lazy"` | It is the default for a reason. |
| Expecting `alt` to reach the `<img>` | `alt` becomes the host's `aria-label` | The inner image is always `aria-hidden`. |
| Nesting an avatar inside a button for an action | Use `md-icon-button`, or make the row interactive | Avatars aren't controls and are never focusable. |
| Expecting a custom `size` to shrink under `data-density` | Use a preset, or scale the length yourself | Only the presets read `--md-sys-density-scale`. |

## Accessibility, RTL, density, i18n

**Accessibility**
- Decide deliberately: either the avatar **carries** the identity (set `label`,
  or rely on `alt`/`name`) or it is **decorative** (all three empty, letters via
  `initials`). The component picks `role="img"` or `role="presentation"` from
  that choice — you cannot override it with your own ARIA.
- Beside a name that is already in the text, choose the decorative form so the
  name isn't announced twice.
- The initials palette pairs container and label tokens from the same tonal
  family, so contrast holds; custom container colours need checking.
- The avatar is never focusable. If the whole row is interactive, put the
  affordance on the row.

**RTL** — the avatar is symmetric and needs nothing.

**Density** — `density="-1…-4"` (or an inherited `data-density` rung) shrinks
the three preset sizes through `--md-sys-density-scale`; label and icon sizes
follow because they are `calc()`ed from the box. Rung `0` is the uncompacted
default and has no rule of its own. To pin one instance back to full size under
a global rung, set `style="--md-sys-density-scale: 0"` on it. A custom `size`
length is unaffected either way.

**i18n** — initials are derived with `Intl.Segmenter` grapheme segmentation
when available, so non-Latin scripts, diacritics and emoji survive intact. The
first-and-last-token heuristic still assumes a Western name order — pass
`initials` explicitly for locales where it doesn't hold (CJK in particular).

## Related components

`md-status-dot` · `md-badge` · `md-chip` · `md-list-item` ·
`md-organization-chart` · `md-app-bar`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-avatar-size` | Box size (also where a non-preset `size` is written) | `max(28px, 40px + density × 3px)` (`medium`) |
| `--md-avatar-container-color` | Container fill when no palette applies | `--md-sys-color-surface-container-highest` |
| `--md-avatar-container-shape` | Corner radius | `50%` / `12px` / `0` per `shape` |
| `--md-avatar-label-color` | Initials colour | `--md-sys-color-on-surface-variant` |
| `--md-avatar-label-font-family` | Initials font | `--md-sys-typescale-title-medium-font-family` |
| `--md-avatar-label-font-size` | Initials size | `calc(size × 0.4)` |
| `--md-avatar-label-font-weight` | Initials weight | `--md-sys-typescale-title-medium-font-weight` |
| `--md-avatar-label-letter-spacing` | Initials tracking | `0.05em` |
| `--md-avatar-icon-size` | Fallback glyph box | `calc(size × 0.6)` |
| `--md-avatar-outline-color` | Ring colour | `transparent` |
| `--md-avatar-outline-width` | Ring width (inset, so it doesn't grow the box) | `0` |
| `--md-avatar-palette-1-container` … `-7-container` | Name-derived container tints | M3 container roles |
| `--md-avatar-palette-1-label` … `-7-label` | Matching label tints | M3 on-container roles |

**CSS parts** — `image`, `initials`, `icon`.

```css
md-avatar.ringed {
  --md-avatar-outline-color: var(--md-sys-color-outline);
  --md-avatar-outline-width: 2px;
}
```

<!-- Auto Generated Below -->


## Overview

`md-avatar` — a presentational identity tile that resolves the first
available source from a clear fallback chain:

  1. `src` (image)  → `<img>` is rendered.
     On error/empty, automatically falls through to step 2.
  2. `initials`     → explicit initials string (verbatim, max 3 chars).
  3. `name`         → auto-derived initials. Two tokens → first letter
                      of each; one token → first letter only. RTL- and
                      diacritic-safe via `Intl.Segmenter` when available.
  4. default slot   → caller-provided fallback (icon, emoji, SVG).
  5. person icon    → material-symbols fallback (always available).

## Properties

| Property        | Attribute         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Type                                            | Default    |
| --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ---------- |
| `alt`           | `alt`             | Alternative text for the image. When empty, the image is exposed to AT as decorative (`aria-hidden`); the host carries the accessible label instead (see `label`).                                                                                                                                                                                                                                                                                                                                                                                          | `string`                                        | `''`       |
| `colorFromName` | `color-from-name` | When `true` the avatar background is deterministically picked from a tonal palette using the initials/name as a hash seed. When `false`, the avatar uses the neutral on-surface tone.                                                                                                                                                                                                                                                                                                                                                                       | `boolean`                                       | `true`     |
| `crossorigin`   | `crossorigin`     | `<img>` `crossorigin` attribute (forwarded only when set).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `"" \| "anonymous" \| "use-credentials"`        | `''`       |
| `density`       | `density`         | Local density rung. Drives the same `--md-sys-density-scale` signal that a global `data-density` ancestor sets, so a local value simply overrides the inherited one. 0 = default, -4 = ultra-compact.                                                                                                                                                                                                                                                                                                                                                       | `-1 \| -2 \| -3 \| -4 \| 0`                     | `0`        |
| `initials`      | `initials`        | Explicit initials override. Bypasses the `name` parsing entirely. Truncated to the first 3 grapheme clusters at render time so a stray "WXYZ" can't blow out the layout.                                                                                                                                                                                                                                                                                                                                                                                    | `string`                                        | `''`       |
| `label`         | `label`           | Accessible label for the avatar. When empty:   - if `alt` is set, that is exposed instead   - if `name` is set, that is exposed instead   - otherwise the avatar is hidden from AT (`role="presentation"`)     so it doesn't add noise next to a labelled control.                                                                                                                                                                                                                                                                                          | `string`                                        | `''`       |
| `loading`       | `loading`         | `<img>` `loading` attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"eager" \| "lazy"`                             | `'lazy'`   |
| `name`          | `name`            | Full name. The component derives initials automatically:   - `"Ada Lovelace"` → `"AL"`   - `"Cher"`         → `"C"`   - `"  john   doe"` → `"JD"`  Honored only when `src` is not set (or fails to load) and `initials` is empty.                                                                                                                                                                                                                                                                                                                           | `string`                                        | `''`       |
| `shape`         | `shape`           | Container shape. - `circle`  — fully rounded (`50%`)             [default] - `rounded` — `--md-sys-shape-corner-medium` (12px) - `square`  — sharp corners (`0`)                                                                                                                                                                                                                                                                                                                                                                                            | `"circle" \| "rounded" \| "square"`             | `'circle'` |
| `size`          | `size`            | Avatar size. Accepts either a named preset or any CSS length.  Presets: - `small`   — 24×24 (typography: label-medium) - `medium`  — 40×40 (typography: title-medium)  [default] - `large`   — 56×56 (typography: title-large)  Custom values: - Unitless number → pixels (`size="72"` → 72px) - Any CSS length  → passes through (`size="4rem"`, `size="10vw"`,   `size="clamp(28px, 4vw, 72px)"`)  Custom values are wired through the existing `--md-avatar-size` CSS custom property, so per-instance overrides via `style` / class still win when set. | `"large" \| "medium" \| "small" \| string & {}` | `'medium'` |
| `src`           | `src`             | Image URL. When set, the avatar renders as an `<img>` element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `string`                                        | `''`       |


## Events

| Event     | Description                                                  | Type                            |
| --------- | ------------------------------------------------------------ | ------------------------------- |
| `mdError` | Image failed to load — component fell back to initials/icon. | `CustomEvent<{ src: string; }>` |
| `mdLoad`  | Image successfully loaded.                                   | `CustomEvent<{ src: string; }>` |


## Shadow Parts

| Part         | Description |
| ------------ | ----------- |
| `"icon"`     |             |
| `"image"`    |             |
| `"initials"` |             |


## Dependencies

### Used by

 - [md-list-item](../md-list-item)
 - [md-organization-chart](../md-organization-chart)

### Graph
```mermaid
graph TD;
  md-list-item --> md-avatar
  md-organization-chart --> md-avatar
  style md-avatar fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*

AWC UI Operator’s Manual

Copy spec

# main-llm.md — AWC UI build director

<!-- llm:meta
role: director
audience: llm
library: "@awc-ui/core"
component-count: 57
sub-component-count: 24
manual-count: 81
per-component-docs: ./packages/core/src/components/<tag>/readme.md
-->

**You are building a web app with AWC UI, a Material Design 3 web-component
library.** This file is the entry point and the only document you need before
writing UI code. Everything here is self-contained: tokens, recipes,
composition rules and the ship checklist. Per-component detail lives in
`./packages/core/src/components/<tag>/readme.md` — e.g.
[`md-button`](./packages/core/src/components/md-button/readme.md).

Your job, in order:

1. **Interview** the user (§1). Do not skip it and do not guess.
2. **Lock the configuration** their answers imply (§2) and bootstrap it (§3–§4).
3. **Route every UI need through the decision matrix** (§5) — never pick a
   component by name-similarity.
4. **Load the component's readme.md before writing a single line of its
   markup** (§6). The file is
   `./packages/core/src/components/<tag>/readme.md` — read it in full, do not
   skim it, and do not write the markup from memory of a similar library. Each
   one has a `When NOT to use`, a `Do / Don't` table sourced from
   [m3.material.io](https://m3.material.io), and an `Anti-patterns` table of
   mistakes models actually make. If you are about to use three components,
   load all three readmes first.
5. **Check what nests inside what** (§7) and start from a recipe (§8) rather
   than from a blank page.
6. **Apply the universal rules** (§9) — the API, content and accessibility
   rules every component is bound by, and the ones §10 checks you against.
7. **Run the ship checklist** (§10) before declaring done.

**Fail closed.** If you cannot satisfy a step — no component fits, a token
doesn't exist, an accessible name has nowhere to come from — say so and ask.
Do not invent an `md-*` tag, a prop, or a token. If it is not in this file or
in the component's manual, it does not exist.

---

## §1 — Interview the user

Ask these **one at a time**, in this order. Each answer closes off decisions
downstream, so don't batch them into a wall of questions. Skip a question only
if the user has already answered it unprompted.

If the user says "just pick sensible defaults", use the **bold** option and tell
them what you chose.

### 1.1 Scope and shape

1. **What is the app?** One or two sentences — domain, primary job, who uses it.
2. **What kind of surface is it?**
   - Internal tool / admin console / dashboard
   - Data-heavy CRUD application
   - Consumer-facing product
   - Marketing or content site
   - Mobile-first / PWA
3. **Which framework?** React · Angular · Vue · Svelte · **plain HTML** ·
   Next · Nuxt · SvelteKit · Astro
4. **Does it server-render?** (SSR/SSG, or **client-only SPA**)
5. **Roughly how many distinct screens**, and what are the top 3?

### 1.2 Look and feel

6. **Density** — how much information per screen?
   - `0` — **default**, comfortable, touch-friendly
   - `-1` / `-2` — compact; typical for admin consoles
   - `-3` / `-4` — ultra-compact; dense data tables, trading/ops screens
7. **Theme** — light only, dark only, or **both with a user toggle**?
   Does it follow the OS preference?
8. **Brand color** — a seed/primary color, or **stock MD3 palette**?
9. **Expressive motion** — keep **ripple and shape-morph on** (default), or turn
   them off for a flatter, more utilitarian feel?
10. **Shape language** — **rounded** (MD3 default) or squared?

### 1.3 Internationalization

11. **How many locales**, and which?
12. **Any RTL locales** (Arabic, Hebrew, Farsi, Urdu)? — this changes layout
    verification and directional-icon handling.
13. **Which i18n engine?** (i18next, vue-i18n, ngx-translate, Paraglide, custom)
    Components are engine-agnostic — you localize in the consumer layer.
14. **Locale-formatted values** — dates, numbers, currency? Which locale drives
    `Intl`?

### 1.4 Data and forms

15. **Is there significant tabular data?** How many rows, and is it
    server-paged? (Drives how you page `md-table` — it holds the state, you
    supply each page of rows.)
16. **Are there charts?** Which questions should they answer?
17. **How heavy are the forms?** Validation rules, async validation, multi-step?
18. **Rich text editing anywhere?** — ⚠️ **AWC UI has no RTE component.** If yes,
    you must integrate a third-party editor (TipTap, Lexical, Quill) and style
    it to the MD3 tokens yourself. Confirm this with the user explicitly.

### 1.5 Constraints

19. **Accessibility target** — **WCAG 2.1 AA** (what the library is tested to),
    or stricter?
20. **Browser/device support floor?**
21. **Anything already decided** you must not change — existing design system,
    router, state library, CSS approach?

---

## §2 — Map answers to configuration

| Answer | What you set |
|---|---|
| Admin console / data-heavy | `data-density="-1"` or `-2` on `<html>`; prefer `size="xs"`/`"sm"` on actions |
| Consumer / marketing | leave density alone (`0` is the default); larger button sizes (`md`/`lg`) for CTAs |
| Mobile-first | `md-navigation-bar` + `md-fab`; avoid `md-navigation-rail`, `md-transfer-list`, wide tables |
| Desktop-first | `md-navigation-rail` or `md-app-bar`; rail over bottom bar |
| Dark mode | `data-theme="dark"` on `<html>`; wire a toggle, and mirror OS via `prefers-color-scheme` |
| Both themes with toggle | persist the choice; set the attribute before first paint to avoid a flash |
| Brand color | override the `--md-sys-color-*` roles in your own stylesheet, loaded after the tokens (§4.2) |
| Flat / utilitarian | `data-ripple="off"` and `data-shape-morph="off"` on `<html>` |
| Any RTL locale | `dir="rtl"` on `<html>`; add `mirror-icon` to `md-button`s with directional glyphs; swap the glyph name yourself everywhere else (§4.5) |
| Multiple locales | build a dictionary in the consumer layer and feed component text props from it; never hardcode strings in markup |
| `Intl`-formatted values | pass a `locale` prop where a component exposes one; format everything else before it reaches the component |
| SSR | import from `@awc-ui/core/hydrate` on the server; use the client/server wrappers in `@awc-ui/react` |
| Heavy forms | components are form-associated via `ElementInternals` — use a real `<form>`, `md-button type="submit"`, and native `required` (§4.7) |
| Rich text | integrate a third-party editor; there is no `md-rich-text` |

### 2.1 Global switches — the complete set

All are attributes on `<html>` (or any ancestor; the nearest one wins).

```html
<html
  lang="en"
  dir="ltr"                  <!-- or rtl -->
  data-theme="dark"          <!-- omit for light -->
  data-density="-1"          <!-- -1 … -4; see below -->
  data-ripple="off"          <!-- default on -->
  data-shape-morph="off"     <!-- default on -->
>
```

**`data-density="0"` is inert.** No `[density="0"]` rule exists — density `0` is
simply the base values on `:root`, and a `0` rule would pin them onto every
element (reflected props write `density="0"` almost everywhere) and break global
inheritance. So the *overriding* range is `-1 … -4`. To escape an inherited rung
for one subtree, reset the scale directly:

```css
.opt-out-of-density { --md-sys-density-scale: 0; }
```

Per-component overrides beat the global one: a `density` prop, or
`ripple="off"` / `shape-morph="off"` on the element. **53 of the 57 top-level
components expose a `density` prop.** The four that don't: `md-divider`,
`md-ripple`, `md-sparkline`, `md-tabs`. (Nine sub-components also lack one —
they inherit density from the parent that owns their layout.)

---

## §3 — Install and bootstrap

```bash
npm install @awc-ui/core
```

**Register everything (recommended).** Two imports, once per app entry — one
defines every component, one loads the tokens. Both come from `@awc-ui/core`
itself, so this path needs no second package:

```ts
import { defineCustomElements } from '@awc-ui/core/loader';
import '@awc-ui/core/css/tokens.css';

defineCustomElements(window);
```

`@awc-ui/core/css/tokens.css` is the complete, self-contained token sheet —
light and dark colour roles, shape, elevation, motion, typescale, spacing and
z-index. It is the same set documented in §4.1.

**One-line alternative.** `@awc-ui/core/define` does both steps in a single
import. It loads the package's own token sheet, so it needs nothing else
installed:

```ts
import '@awc-ui/core/define'; // defines every component + loads the token sheet
```

`define` is client-only (it eval-guards `window`) and, because it imports CSS,
it needs a bundler. Never import it into a server graph.

**Per-component registration**, for size-sensitive bundles — load the token
sheet once yourself:

```ts
import '@awc-ui/core/css/tokens.css';
import '@awc-ui/core/components/md-button';
import '@awc-ui/core/components/md-text-field';
```

**Framework wrappers** — use these instead of raw elements; they handle
registration, typed props, and event binding. Below the version floor, drop to
the raw custom elements and the `loader` import above.

| Framework | Package | Requires |
|---|---|---|
| React / Next | `@awc-ui/react` | React 18+ |
| Angular | `@awc-ui/angular` (`AwcUiModule`) | Angular 17+ |
| Vue / Nuxt | `@awc-ui/vue` | Vue 3 |
| Svelte / SvelteKit | `@awc-ui/svelte` | Svelte 4+ |
| Plain HTML / Astro | `@awc-ui/core/loader` | — |

**SSR** — `@awc-ui/core/hydrate` renders Declarative Shadow DOM on the server.
`@awc-ui/react` ships matching client/server wrappers. Keep `define` and
`loader` out of the server graph; both are browser entries.

**Fonts** — components expect Roboto and Material Symbols Outlined to be
available. The library does **not** inject them. Every `icon="…"` prop renders a
Material Symbols glyph inside shadow DOM, so the font must be registered at the
**document** level (font registration crosses shadow boundaries; class rules do
not — the components declare the class rule inside their own roots):

```html
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap">
```

To swap the whole library to a different Material Symbols cut, set
`--md-sys-icon-font-family` on `:root` and load the matching `@font-face`.

---

## §4 — Global configuration reference

### 4.1 The token system

All AWC UI styling resolves to design tokens. **Never hardcode hex colours,
pixel radii, shadows, or font stacks** — they break theming, dark mode, density
and RTL in one stroke. Every value below is a real custom property defined by
`@awc-ui/tokens`; you may read them, and you may override them.

#### Color roles

Light is the default; `[data-theme="dark"]` swaps the palette. Every role has a
matching `on-` role for content drawn on top of it.

| Token | Light | Dark | Typical usage |
|---|---|---|---|
| `--md-sys-color-primary` | `#6750A4` | `#D0BCFF` | Filled buttons, active states |
| `--md-sys-color-on-primary` | `#FFFFFF` | `#381E72` | Text/icons on primary |
| `--md-sys-color-primary-container` | `#EADDFF` | `#4F378B` | FAB, selected segments |
| `--md-sys-color-on-primary-container` | `#21005D` | `#EADDFF` | Text on primary-container |
| `--md-sys-color-secondary` | `#625B71` | `#CCC2DC` | Secondary accents |
| `--md-sys-color-secondary-container` | `#E8DEF8` | `#4A4458` | Tonal buttons, chips |
| `--md-sys-color-tertiary` | `#7D5260` | `#EFB8C8` | Tertiary accents |
| `--md-sys-color-tertiary-container` | `#FFD8E4` | `#633B48` | Tertiary surfaces |
| `--md-sys-color-error` | `#B3261E` | `#F2B8B5` | Error / destructive |
| `--md-sys-color-on-error` | `#FFFFFF` | `#601410` | Content on error |
| `--md-sys-color-error-container` | `#F9DEDC` | `#8C1D18` | Error surfaces |
| `--md-sys-color-surface` | `#FFFBFE` | `#1C1B1F` | Page / card background |
| `--md-sys-color-on-surface` | `#1C1B1F` | `#E6E1E5` | Body text |
| `--md-sys-color-surface-variant` | `#E7E0EC` | `#49454F` | Muted fills |
| `--md-sys-color-on-surface-variant` | `#49454F` | `#CAC4D0` | Secondary text, icons |
| `--md-sys-color-surface-container-lowest` | `#FFFFFF` | `#0F0D13` | Lowest surface tier |
| `--md-sys-color-surface-container-low` | `#F7F2FA` | `#1D1B20` | Card / elevated button bg |
| `--md-sys-color-surface-container` | `#F3EDF7` | `#211F26` | Default container tier |
| `--md-sys-color-surface-container-high` | `#ECE6F0` | `#2B2930` | Dialog / menu surfaces |
| `--md-sys-color-surface-container-highest` | `#E6E0E9` | `#36343B` | Highest surface tier |
| `--md-sys-color-outline` | `#79747E` | `#938F99` | Borders (3:1 contrast) |
| `--md-sys-color-outline-variant` | `#CAC4D0` | `#49454F` | Dividers (low contrast) |
| `--md-sys-color-inverse-surface` | `#313033` | `#E6E1E5` | Snackbar, inverse chips |
| `--md-sys-color-inverse-on-surface` | `#F4EFF4` | `#313033` | Content on inverse-surface |
| `--md-sys-color-scrim` | `#000000` | `#000000` | Modal scrims |

**Semantic status roles** — beyond the baseline M3 palette, the library adds
`success`, `warning` and `info`, each with `on-`, `-container` and
`on-…-container` companions, in both themes, AA-verified. Used by `md-chip`,
`md-badge`, `md-meter`, `md-status-dot`.

| Token | Light | Dark |
|---|---|---|
| `--md-sys-color-success` | `#2E6B4F` | `#9DD5B0` |
| `--md-sys-color-success-container` | `#B8F0CE` | `#14512F` |
| `--md-sys-color-warning` | `#7A5900` | `#EFC148` |
| `--md-sys-color-warning-container` | `#FFDF9B` | `#5C4200` |
| `--md-sys-color-info` | `#38608F` | `#A2C9FE` |
| `--md-sys-color-info-container` | `#D3E4FF` | `#1E4975` |

#### Shape tokens

| Token | Value | Typical usage |
|---|---|---|
| `--md-sys-shape-corner-none` | `0px` | Square edges |
| `--md-sys-shape-corner-extra-small` | `4px` | Snackbar, small chips |
| `--md-sys-shape-corner-small` | `8px` | Cards (outlined), small surfaces |
| `--md-sys-shape-corner-medium` | `12px` | Cards (default), inputs |
| `--md-sys-shape-corner-large` | `16px` | Dialogs, large cards |
| `--md-sys-shape-corner-extra-large` | `28px` | Bottom sheets |
| `--md-sys-shape-corner-full` | `9999px` | Buttons, chips, FAB |

Partial-corner variants also exist for surfaces that meet an edge:
`--md-sys-shape-corner-extra-small-top`, `-large-top`, `-large-end`,
`-extra-large-top`. Their values are four-value `border-radius` shorthands
(e.g. `16px 16px 0px 0px`), so assign them to `border-radius`, not to a single
corner.

#### Elevation tokens

`-0` is the keyword `none`; `-1` through `-5` are complete `box-shadow` values,
and those five are **re-declared with deeper shadows under `[data-theme="dark"]`**
— so always use the token rather than copying its value.

| Token | When |
|---|---|
| `--md-sys-elevation-0` | `none` — resting cards, flat surfaces |
| `--md-sys-elevation-1` | Elevated buttons and cards at rest |
| `--md-sys-elevation-2` | Hover bump |
| `--md-sys-elevation-3` | FAB, menus, dialogs at rest |
| `--md-sys-elevation-4` – `-5` | Reserved for the most prominent surfaces |

#### Motion tokens

Durations come in four families of four: `short1…4` (50/100/150/200ms),
`medium1…4` (250/300/350/400ms), `long1…4` (450/500/550/600ms), and
`extra-long1…4` (700/800/900/1000ms).

| Token | Value | When |
|---|---|---|
| `--md-sys-motion-duration-short2` | `100ms` | Buttons, ripples, state layers |
| `--md-sys-motion-duration-medium2` | `300ms` | Dialogs, sheets, menus |
| `--md-sys-motion-duration-long2` | `500ms` | Large surface transitions |
| `--md-sys-motion-duration-extra-long1` | `700ms` | Ambient / chart entrances |
| `--md-sys-motion-easing-standard` | `cubic-bezier(0.2, 0, 0, 1)` | Small utility transitions |
| `--md-sys-motion-easing-standard-accelerate` | `cubic-bezier(0.3, 0, 1, 1)` | Exits |
| `--md-sys-motion-easing-standard-decelerate` | `cubic-bezier(0, 0, 0, 1)` | Entrances |
| `--md-sys-motion-easing-emphasized` | `cubic-bezier(0.2, 0, 0, 1)` | Expressive transitions |
| `--md-sys-motion-easing-emphasized-accelerate` | `cubic-bezier(0.3, 0, 0.8, 0.15)` | Expressive exits |
| `--md-sys-motion-easing-emphasized-decelerate` | `cubic-bezier(0.05, 0.7, 0.1, 1)` | Expressive entrances |
| `--md-sys-motion-easing-linear` | `linear` | Progress, indeterminate loops |

> `--md-sys-motion-easing-emphasized` deliberately equals the standard curve:
> the full M3 emphasized curve is a two-phase path interpolator that CSS cannot
> express. The accelerate and decelerate halves *are* expressible, and are the
> ones to reach for.

MD3 Expressive also ships spring pairs, each an easing plus its natural
duration: `--md-sys-motion-spring-{spatial,effects}-{fast,default,slow}-easing`
and `…-duration`. Spatial = position/size/shape; effects = colour/opacity.

#### State-layer opacities

| Token | Value |
|---|---|
| `--md-sys-state-hover-state-layer-opacity` | `0.08` |
| `--md-sys-state-focus-state-layer-opacity` | `0.12` |
| `--md-sys-state-pressed-state-layer-opacity` | `0.12` |
| `--md-sys-state-dragged-state-layer-opacity` | `0.16` |
| `--md-sys-state-disabled-container-opacity` | `0.12` |
| `--md-sys-state-disabled-content-opacity` | `0.38` |

#### Typography, spacing and layering

- **Typescale** — `--md-sys-typescale-<role>-<size>-*` for
  `display`/`headline`/`title`/`label`/`body` × `large`/`medium`/`small`. Each
  role exposes `-font-family`, `-font-size`, `-line-height`, `-font-weight`,
  `-letter-spacing`, plus a `-font` shorthand
  (e.g. `--md-sys-typescale-headline-medium-font: 400 28px/36px Roboto, sans-serif`).
  Use the shorthand on the `font` property for headings you write yourself.
- **Spacing** — a 4px scale that tightens with density:
  `--md-sys-spacing-inset-{xs,sm,md,lg,xl}` (internal padding, 4/8/12/16/24px)
  and `--md-sys-spacing-gap-{xs,sm,md,lg}` (between siblings, 4/8/12/16px), plus
  `--md-sys-spacing-row-height` (`56px` at density 0).
- **Layering** — `--md-sys-z-index-app-bar` (100), `-navigation` (200),
  `-bottom-sheet` (300), `-popup` (1000), `-dialog-scrim` (1001), `-tooltip`
  (1500), `-snackbar` (2000). Use these instead of inventing z-indexes, or your
  overlay will land under a menu.

### 4.2 Theming and rebranding

To rebrand, redefine the role variables **after** the tokens stylesheet — both
themes, or dark mode inherits your light brand colour:

```css
:root {
  --md-sys-color-primary: #00629E;
  --md-sys-color-on-primary: #FFFFFF;
  --md-sys-color-primary-container: #CFE5FF;
  --md-sys-color-on-primary-container: #001D33;
}
[data-theme="dark"] {
  --md-sys-color-primary: #9BCBFF;
  --md-sys-color-on-primary: #003354;
  --md-sys-color-primary-container: #004A78;
  --md-sys-color-on-primary-container: #CFE5FF;
}
```

Per-component knobs are `--md-<component>-*` custom properties, listed in each
manual's Theming section (`--md-button-container-color`,
`--md-card-container-shape`, …). Prefer those over `::part()`, and prefer
`::part()` over reaching into shadow internals, which are unstable and will
break on any release.

**Overriding a colour role forfeits the library's contrast testing.** Re-verify
AA (4.5:1 text, 3:1 borders and dividers) after any palette change. The Theme
Generator at <https://awc-ui.dev/theme-generator> takes a seed colour, emits both
palettes as `--md-sys-color-*` overrides, and runs the WCAG checks live — use it
rather than hand-picking container and `on-` pairs.

### 4.3 Density

`data-density` steps `-1 → -4`; each rung trims ~4px of padding and touch
target, driving `--md-sys-density-scale` and the spacing tokens. `-4` is the
floor. Set it globally, override locally with the `density` prop. Do not go
below `-2` on touch-primary surfaces — you will break the 48px target.

Two details that bite:

- **`density="0"` does nothing** — see §2 for why, and for the
  `--md-sys-density-scale: 0` escape hatch.
- **`md-table` accepts two vocabularies**: the semantic `compact` / `standard` /
  `comfortable` (row heights 36 / 52 / 60px) *and* the numeric rungs. They
  compose — `density="compact"` inside a `data-density="-2"` region condenses
  further.

### 4.4 Dark mode

Set `data-theme="dark"` on `<html>` (or any ancestor — the nearest wins). The
tokens swap automatically and inherit across every shadow boundary; no
per-component code. To mirror the OS, read `prefers-color-scheme` and write the
attribute **before first paint**, or the page flashes light.

### 4.5 RTL

Layout is written with CSS logical properties, so it flips with `dir="rtl"`
without extra work. Two things still need you:

- **Directional glyphs do not flip.** Material Symbols are not auto-mirrored.
  `md-button` has a `mirror-icon` prop that mirrors its own leading/trailing
  glyph — set it on buttons using arrows, chevrons, `send`, `reply`, and leave
  it off for `add`, `search`, `favorite`. **`mirror-icon` exists only on
  `md-button`.** Everywhere else — `md-icon-button icon="…"`, `md-list-item`
  leading/trailing icons, `md-app-bar leading-icon` — swap the glyph name
  yourself (`arrow_back` ↔ `arrow_forward`).
- **Icon props you supply yourself** — e.g. `md-transfer-list`'s
  `move-right-icon` / `move-left-icon` / `move-all-*-icon` — must be swapped by
  you when the direction flips.

Never write physical CSS (`margin-left`, `padding-right`, `left`) around these
components. Use `margin-inline-start`, `padding-inline-end`, `inset-inline-end`.

### 4.6 Internationalization

Components are **i18n-engine-agnostic by design**. Every user-visible string is
either slotted content or a prop. Localize in the consumer layer: resolve your
dictionary to plain strings, then pass them in. Do not add a translation engine
inside a component. `locale` props exist only where a component computes an
`Intl`-formatted value itself: `md-date-picker`, `md-number-field`,
`md-meter`, `md-dialog`, and the charts (`md-bar-chart`, `md-line-chart`,
`md-area-chart`, `md-pie-chart`). `md-time-picker` has no
`locale` prop — it takes `format="12h" | "24h"` instead.

Templated strings keep their placeholder tokens when translated — translate
around the braces, don't remove them:

```html
<md-transfer-list count-template="{checked} / {total} ausgewählt"></md-transfer-list>
```

Other templated props: `md-autocomplete status-template`, `md-otp-field
cell-label-template`. Default prop values are English (`Search`, `Dismiss`,
`No results`, `Move selected to target`, …) — every one of them needs
translating in a localized app.

### 4.7 Forms and validation

Fourteen components are form-associated via `ElementInternals`, so they
participate in `FormData` and constraint validation like native controls:

`md-text-field` · `md-number-field` · `md-otp-field` · `md-select` ·
`md-multi-select` · `md-autocomplete` · `md-checkbox` · `md-radio` ·
`md-switch` · `md-slider` · `md-rating` · `md-date-picker` · `md-time-picker` ·
`md-button`

Rules:

- Use a real `<form>`. `md-button type="submit"` calls `form.requestSubmit()`
  (not `submit()`), so the `submit` event fires **and** built-in constraint
  validation runs. `required` genuinely blocks submit.
  `md-button type="reset"` calls `form.reset()`.
- Give every control a `name`, or it will not appear in `FormData`.
- Do **not** add hidden `<input>`s to mirror values — that's the old pattern and
  it double-submits.
- Validity changes are announced on a `mdValidityChange` event on the control.
  Error presentation is `error` + `error-text` on the field.
- Boolean state props differ by control — `md-checkbox` uses `checked`,
  `md-switch` uses **`selected`**, `md-select-option` uses `selected`. Check the
  manual; guessing `checked` on a switch silently does nothing.

---

## §5 — Component decision matrix

Route by **need**, not by name. If the need isn't listed, find the closest row
and read that component's `When NOT to use`.

### 5.1 Actions

| Need | Use | Don't use |
|---|---|---|
| Discrete labelled action | `md-button` | `md-chip`, raw `<button>` |
| Icon-only action | `md-icon-button` | `md-button` with no label |
| A destructive action | `md-button` + `md-dialog` to confirm | an unconfirmed `filled` button |
| The single most prominent screen action (mobile) | `md-fab` | a second `filled` `md-button` |
| One prominent action that expands to several | `md-fab-menu` + `md-fab-menu-item` | a stack of FABs |
| Primary action + variants of it | `md-split-button` | button + separate menu |
| 2–5 related actions as one unit | `md-button-group` | loose adjacent buttons |
| Mutually exclusive view/mode switch | `md-segmented-button-set` + `md-segmented-button` | radio buttons, tabs |
| Overflow / contextual actions | `md-menu` + `md-menu-item` | a row of text buttons |

### 5.2 Text input

| Need | Use | Don't use |
|---|---|---|
| Any single-line or multi-line text entry | `md-text-field` | raw `<input>` |
| A number with steppers and locale formatting | `md-number-field` | `md-text-field type="number"` |
| A one-time code / PIN | `md-otp-field` | a row of text fields |
| Text entry with suggestions | `md-autocomplete` | `md-select` |
| Site/app-wide search with a results surface | `md-search` | `md-text-field` with an icon |

### 5.3 Selection

| Need | Use | Don't use |
|---|---|---|
| One of many, from a list | `md-select` + `md-select-option` | radio group over ~7 options |
| One of few (2–5), all visible | `md-radio` | `md-select` |
| Several of many | `md-multi-select` | many `md-checkbox`es |
| Several of few, all visible | `md-checkbox` | `md-multi-select` |
| Instant on/off setting | `md-switch` | `md-checkbox` |
| A value in a numeric range | `md-slider` | `md-text-field type=number` |
| Subjective score | `md-rating` | slider |
| A color | `md-color-picker` | `<input type=color>` |
| Assign a subset from a bounded pool, side by side | `md-transfer-list` | two lists + buttons |
| Filter / attribute / removable entry | `md-chip` | small buttons |
| A date | `md-date-picker` | three selects |
| A time | `md-time-picker` | text field |

### 5.4 Navigation

| Need | Use | Don't use |
|---|---|---|
| Top-level destinations, mobile | `md-navigation-bar` + `md-navigation-tab` | tabs |
| Top-level destinations, desktop | `md-navigation-rail` + `md-navigation-rail-tab` | bottom bar |
| App header: title, actions, search | `md-app-bar` | a custom `<header>` |
| A dense action strip | `md-toolbar` | app bar |
| Sibling views **within** one screen | `md-tabs` + `md-tab` + `md-tab-panels` + `md-tab-panel` | navigation bar |
| Hierarchy / where-am-I | `md-breadcrumbs` + `md-breadcrumb-item` | text links |
| A linear multi-step flow | `md-stepper` + `md-step` | tabs |
| Contextual popup actions | `md-menu` + `md-menu-item`, `md-menu-item-group`, `md-sub-menu-item` | dialog |
| Hierarchical command menu (File → Export → PDF) | `md-menu` + `md-sub-menu-item` | nested dialogs |

### 5.5 Containment and feedback

| Need | Use | Don't use |
|---|---|---|
| Group related content | `md-card` | a bare `<div>` with a border |
| Blocking decision or focused task | `md-dialog` | a new page |
| Critical error the user must acknowledge | `md-dialog` | `md-snackbar` |
| Supplementary content from the bottom (mobile) | `md-bottom-sheet` | dialog |
| Supplementary content from the side (desktop) | `md-side-sheet` | dialog |
| Brief confirmation of an action, optionally undoable | `md-snackbar` | dialog, alert |
| Explain a control on hover/focus | `md-tooltip` | a dialog or inline hint |
| Progressive disclosure of sections | `md-accordion` + `md-accordion-item` | tabs |
| Visual separation | `md-divider` | a styled `<hr>` |
| A vertical set of records | `md-list` + `md-list-item` | a table |
| Determinate/indeterminate progress | `md-progress-indicator` | spinner GIF |
| Brand-consistent page/content loading | `md-loading-indicator` | custom spinner |
| Content-shaped loading placeholder | `md-skeleton` | a spinner over the whole page |
| Count or status on an element | `md-badge` | superscript text |
| Compact status dot | `md-status-dot` | a colored emoji |
| Read-only value within a known range (quota, battery) | `md-meter` | `md-progress-indicator` |
| A person or entity image/initials | `md-avatar` | a raw `<img>` |
| Touch feedback inside a custom control | `md-ripple` | custom CSS animation |

### 5.6 Data

| Need | Use | Don't use |
|---|---|---|
| Any table | `md-table-container` wrapping `md-table`, with `-head`/`-body`/`-row`/`-cell`/`-foot` inside the table and `-toolbar`/`-pagination` beside it in the container (§7.1) | a native `<table>` |
| Sorting, selection, paging on that table | the same parts — `md-table` carries the STATE (`sort-by`, `sort-order`, `selection`, `row-offset`, `row-count`, `loading`) and emits events; you own the data and do the actual sorting/paging | expecting it to sort an array for you |
| Hierarchy / reporting lines | `md-organization-chart` | nested lists |
| Compare categories | `md-bar-chart` | pie chart |
| Trend over time | `md-line-chart` | bar chart |
| Trend with cumulative volume | `md-area-chart` | line chart |
| Parts of a whole (≤ ~6 slices) | `md-pie-chart` | bar chart |
| Inline micro-trend in a cell or card | `md-sparkline` | a full chart |

> **There is no data-driven table component.** `md-table` is composable: you
> render the rows. It tracks and announces sort, selection and pagination state
> and emits events when the user changes them, but the sorting, filtering and
> slicing of your data is yours to perform. Render rows from your own array in
> response to those events.

### 5.7 Choosing the variant

The matrix picks the component; this picks its shape. Every value below is a
real enum member — anything not listed here is not a valid value.

| Component | Prop | Values, and when |
|---|---|---|
| `md-button` | `variant` | `filled` the one primary action · `tonal` a strong secondary · `outlined` secondary, and the safe choice for a destructive action behind a confirm · `text` low emphasis, dialog Cancel · `elevated` when it sits on a busy or coloured background (default `filled`) |
| `md-button` / `md-icon-button` / `md-button-group` | `size` | `xs` `sm` `md` `lg` `xl` — default `sm`; go `md`/`lg` for consumer CTAs, `xs`/`sm` for dense admin UI |
| `md-icon-button` | `variant` | `standard` (default) · `filled` · `tonal` · `outlined` |
| `md-button-group` | `variant` | `standard` spaced · `connected` fused into one bar |
| `md-fab` | `size` | `standard` (default) · `medium` · `large` |
| `md-fab` | `variant` | `primary-container` (default) · `secondary-container` · `tertiary-container` · `surface` · `primary` · `secondary` · `tertiary` |
| `md-card` | `variant` | `filled` for a group of comparable items · `elevated` (default) for a hero or featured item · `outlined` for a settings or form section |
| `md-text-field` / `md-select` | `variant` | `outlined` for forms on a surface · `filled` for dense or tinted layouts (`md-text-field` defaults to `filled`, `md-select` to `outlined`) — pick one and use it for every field on the screen |
| `md-text-field` | `type` | any native input type: `password`, `email`, `tel`, `url`, `search`, … (default `text`) |
| `md-text-field` | `multiline` | `"auto-grow"` grows with content · `"fixed"` with `rows` for a fixed comment box · `false` (default) single line |
| `md-search` | `variant` | `contained` (default) · `divided` |
| `md-app-bar` | `variant` | `small` (default) · `medium` · `large` for a prominent headline · `search` for a bar that hosts a field |
| `md-chip` | `variant` | `assist` (default) · `filter` for toggleable facets · `input` for user-entered removable values · `suggestion` |
| `md-chip` | `appearance` | `outlined` (default) · `filled` · `elevated` |
| `md-badge` | `variant` | `small` a bare dot · `large` (default) a count |
| `md-tooltip` | `variant` | `plain` (default) a short label on an icon control · `rich` an explanatory popover that may hold a link or action |
| `md-divider` | — | **no `variant`** — use the booleans `inset`, `inset-start`, `inset-end` |
| `md-side-sheet` | `variant` | `standard` coexists with page content · `modal` overlays with a scrim |
| `md-bottom-sheet` | `variant` | `standard` (default) · `detached` floating above the edge |
| `md-dialog` | `fullscreen` | boolean — a full-screen dialog for a long mobile task |
| `md-date-picker` | `variant` | `modal-input` (default) calendar plus a typed field · `modal` calendar only · `docked` inline, anchored to the field |
| `md-time-picker` | `variant` | `dial` · `input` (default) |
| `md-progress-indicator` | `variant` | `linear` (default) · `circular`; add `indeterminate` when the total is unknown |
| `md-list-item` | `lines` | `1` · `2` · `3` — must match how much supporting text you pass |
| `md-navigation-bar` | — | 3–5 destinations. Fewer than three: use `md-tabs`. More than five: a rail or a menu |
| `md-navigation-rail` | — | 3–7 destinations; cap the overflow with `max-visible` |

### 5.8 Not in the library

Rich text editor · file upload/dropzone · calendar/scheduler view · map ·
toast stack manager (use `md-snackbar` and manage the queue yourself) ·
data grid with virtualized columns. If the user needs one, say so plainly and
integrate a third-party component styled with the MD3 tokens.

**There is no `md-grid`, no `md-data-table`, no `md-layout`, no `md-icon`.**
If a tag is not listed in §6, it does not exist — do not emit it.

---

## §6 — Component inventory

**Every component has exactly one manual, and it is the readme.md in its own
source folder:**

```
./packages/core/src/components/<tag>/readme.md
```

e.g. [`md-select`](./packages/core/src/components/md-select/readme.md),
[`md-button`](./packages/core/src/components/md-button/readme.md).

**Load that file before you use the component.** There is no second, shorter
summary to rely on — this readme is the single source, so anything you do not
read there, you do not know. Each one carries When-to-use, a Do/Don't table
from M3, copy-paste patterns, an anti-patterns table, and the theming surface.

Work through them one at a time: pick the component from the decision matrix
(§5), load its readme, write that component's markup, then move to the next.

There are 81 manuals for 57 components: 24 of them document sub-components that
are only valid inside a parent (a table cell, a tab panel, a select option).
Every sub-component manual names its parent in the first line, and §7 below
summarises the nesting.

`status` in each manual's `llm:meta` block is one of:

- **`md3-mapped`** — has a Material Design 3 guidelines page; the Do/Don't is
  sourced from it.
- **`custom`** — an addition to MD3; guidance is derived house rules.
- **`sub-component`** — only valid inside a specific parent.

| Category | Components |
|---|---|
| Actions | `md-button` `md-icon-button` `md-fab` `md-fab-menu` `md-fab-menu-item` `md-split-button` `md-button-group` `md-segmented-button` `md-segmented-button-set` |
| Text input | `md-text-field` `md-number-field` `md-otp-field` `md-autocomplete` `md-search` |
| Selection | `md-select` `md-select-option` `md-multi-select` `md-checkbox` `md-radio` `md-switch` `md-slider` `md-rating` `md-color-picker` `md-transfer-list` `md-chip` |
| Pickers | `md-date-picker` `md-time-picker` |
| Navigation | `md-app-bar` `md-toolbar` `md-navigation-bar` `md-navigation-tab` `md-navigation-rail` `md-navigation-rail-tab` `md-tabs` `md-tab` `md-tab-panels` `md-tab-panel` `md-breadcrumbs` `md-breadcrumb-item` `md-menu` `md-menu-item` `md-menu-item-group` `md-sub-menu-item` `md-stepper` `md-step` |
| Containment | `md-card` `md-dialog` `md-bottom-sheet` `md-side-sheet` `md-snackbar` `md-tooltip` `md-accordion` `md-accordion-item` `md-divider` `md-list` `md-list-item` |
| Data | `md-table` `md-table-container` `md-table-head` `md-table-body` `md-table-row` `md-table-cell` `md-table-foot` `md-table-toolbar` `md-table-pagination` `md-table-sort-label` `md-table-expand-toggle` `md-organization-chart` |
| Charts | `md-bar-chart` `md-line-chart` `md-area-chart` `md-pie-chart` `md-sparkline` |
| Status & feedback | `md-progress-indicator` `md-loading-indicator` `md-skeleton` `md-badge` `md-status-dot` `md-meter` `md-avatar` `md-ripple` |

---

## §7 — Composition rules

### 7.1 What nests inside what

A sub-component is only valid inside its parent. Putting one anywhere else
produces an unstyled, unregistered-looking element with no keyboard behaviour,
because the parent is what wires roving tabindex, ARIA ids and selection.

| Parent | Children it manages |
|---|---|
| `md-button-group` | `md-button`, `md-icon-button` |
| `md-segmented-button-set` | `md-segmented-button` |
| `md-fab-menu` | `md-fab-menu-item` (anchored to an `md-fab` via `anchor="<id>"`) |
| `md-menu` | `md-menu-item`, `md-sub-menu-item`, `md-menu-item-group` — **not** `md-divider`; separate rows with `md-menu-item`'s own `divider` (or `gap`) prop |
| `md-menu-item-group` | `md-menu-item` |
| `md-sub-menu-item` | a nested `md-menu` in `slot="submenu"` — the items go in *that* menu. There is no default slot, so anything else you nest renders nothing |
| `md-select`, `md-multi-select`, `md-autocomplete` | `md-select-option` |
| `md-list` | `md-list-item`, `md-divider` |
| `md-tabs` | `md-tab` |
| `md-tab-panels` | `md-tab-panel` (one per tab, in tab order) |
| `md-navigation-bar` | `md-navigation-tab` |
| `md-navigation-rail` | `md-navigation-rail-tab`, plus an `md-fab` in `slot="fab"` |
| `md-accordion` | `md-accordion-item` |
| `md-stepper` | `md-step` (horizontal steppers also take `slot="content"`) |
| `md-breadcrumbs` | `md-breadcrumb-item` |
| `md-table-container` | `md-table` — **it wraps the table, not the other way round** — plus `md-table-toolbar` in `slot="top"` and `md-table-pagination` in `slot="bottom"`, which sit outside the scroll region |
| `md-table` | `md-table-head`, `md-table-body`, `md-table-foot` (and bare `md-table-row`). It does **not** accept the container, toolbar or pagination |
| `md-table-head` / `-body` / `-foot` | `md-table-row` |
| `md-table-row` | `md-table-cell`, plus `md-table-expand-toggle` for an expandable row |
| `md-table-cell` | `md-table-sort-label` in a header cell |
| `md-tooltip` | **its trigger** — the tooltip wraps the element it describes in its default slot |
| `md-dialog` | body content in the default slot; `md-button` in `slot="actions"` |
| `md-bottom-sheet` / `md-side-sheet` | content in the default slot; `md-button` in `slot="actions"`; headline in `slot="headline"` |
| `md-app-bar` | `md-icon-button` in `slot="leading"` and `slot="trailing"`; `md-menu` for overflow; a field in `slot="search"` on `variant="search"` |
| `md-toolbar` | `md-icon-button`, `md-button`, `md-button-group`; an `md-fab` in `slot="fab"`; `slot="leading"` / `slot="trailing"` for the end clusters |

### 7.2 Pairs that belong together

These don't nest — they sit next to each other in a working flow. Reaching for
one usually means you want the other.

| This | Goes with | Why |
|---|---|---|
| `md-icon-button` | `md-tooltip` | The tooltip supplies the visible meaning the icon lacks |
| `md-button` (`soft-disabled`) | `md-tooltip` | Explains *why* the action is unavailable |
| `md-fab` | `md-fab-menu` | The FAB is the menu's anchor |
| `md-split-button` | `md-menu` | The trailing half opens it |
| `md-card` | `md-button`, `md-icon-button`, `md-divider` | Footer actions, corner action, internal sections |
| `md-list-item` | `md-checkbox`, `md-switch`, `md-icon-button` | Trailing controls in a selectable or settings row |
| `md-bottom-sheet` / `md-side-sheet` | `md-list` | Action menus and filter panels inside the sheet |
| `md-search` | `md-list`, `md-avatar`, `md-icon-button` | Results in the panel; account and voice/filter affordances in the trailing slot |
| `md-date-picker` | `md-time-picker` | Date + time row for booking and scheduling forms |
| `md-time-picker` | `md-button` | The trigger, when `hide-trigger` is set. The picker **is** its own dialog — don't nest it in another one |
| `md-text-field` | `md-button` | Submit / cancel in the form footer |
| `md-multi-select` / `md-autocomplete` | `md-text-field`, `md-menu`, `md-chip` | The field is the trigger (and inherits its variant, density and error state), the menu is the option surface, chips are the selected values |
| `md-autocomplete` | `md-progress-indicator` | The loading row while suggestions are fetched |
| `md-transfer-list` | `md-checkbox`, `md-text-field`, `md-icon-button` | Per-row select, per-side search, mover controls |
| `md-number-field` | `md-text-field` hooks, `md-icon-button` | It *is* an `md-text-field` internally — every `--md-text-field-*` custom property passes through — and its steppers are `md-icon-button`s |
| `md-otp-field` | `md-button` | Verify action (`auto-submit` covers the no-button flow) |
| Any chart | `md-card` | Charts belong on a dashboard tile |
| `md-line-chart` | `md-segmented-button-set` | Period picker (1W / 1M / 1Y) driving the range |
| `md-sparkline` | `md-list-item`, `md-table-cell` | Trend column beside a value |
| `md-skeleton` | `md-card`, `md-list` | Render N placeholders in the real layout while fetching |
| `md-meter` | `md-chip`, `md-card` | Same semantic status colour on both; quota and usage summaries live on a card |
| `md-color-picker` | `md-text-field`, `md-button` | Label and helper text beside it in a form; save / cancel in the surrounding popover or dialog |
| `md-rating` | `md-text-field`, `md-card` | A rating row in a review form; aggregate scores on a review card |
| `md-accordion` | `md-divider` | Optional inner dividers inside long item content |
| `md-stepper` | `md-button` | Next / back / submit adjacent to the stepper |

### 7.3 Nesting that is always wrong

- A dialog opened from inside a dialog. Use `md-stepper` inside **one**
  `md-dialog`.
- A component inside a native interactive element (`<button>`, `<a>`) — it
  nests interactive controls and destroys the accessibility tree. Use the
  component's own `href` / `type` props.
- `md-tabs` used for top-level app navigation. Tabs switch sibling views of the
  same data; destinations are `md-navigation-bar` / `md-navigation-rail`.

---

## §8 — Page recipes

Complete, runnable screens. Each renders as-is once the components are
registered and the token sheet and font links from §3 are loaded — no
placeholder identifiers, no helper functions to write.

### 8.1 Login screen

`<form>` is load-bearing: it is what makes `required` block submit and what
`type="submit"` calls `requestSubmit()` on.

```html
<main style="display: grid; place-items: center; min-block-size: 100dvh; padding: 24px;">
  <form id="login-form" style="inline-size: min(420px, 100%);">
    <md-card variant="elevated" style="padding: 32px; display: flex; flex-direction: column; gap: 20px;">
      <h1 style="margin: 0; font: var(--md-sys-typescale-headline-medium-font);">Sign in</h1>

      <md-text-field
        variant="outlined"
        label="Email"
        type="email"
        name="email"
        autocomplete="username"
        required
      ></md-text-field>

      <md-text-field
        variant="outlined"
        label="Password"
        type="password"
        name="password"
        autocomplete="current-password"
        password-toggle="internal"
        required
      ></md-text-field>

      <md-button variant="filled" type="submit" full-width>Sign in</md-button>
      <md-button variant="text" href="/forgot-password">Forgot password?</md-button>
    </md-card>
  </form>
</main>

<script type="module">
  document.getElementById('login-form').addEventListener('submit', (e) => {
    e.preventDefault();
    const data = new FormData(e.currentTarget);
    console.log(data.get('email'), data.get('password'));
  });
</script>
```

### 8.2 Settings page (mobile)

Top app bar + grouped rows of instant-apply switches. `md-switch` uses
**`selected`**, not `checked`. The rows are `type="text"` (non-interactive), so
the switch is the only control — one tab stop per setting.

```html
<md-app-bar variant="small" headline="Settings">
  <md-icon-button slot="leading" icon="arrow_back" aria-label="Back"></md-icon-button>
</md-app-bar>

<main style="padding: 16px; display: flex; flex-direction: column; gap: 16px;">
  <md-card variant="outlined">
    <md-list>
      <md-list-item headline="Notifications" supporting-text="Push, email, in-app" lines="2">
        <md-switch slot="trailing" selected aria-label="Enable notifications" data-setting="notifications"></md-switch>
      </md-list-item>
      <md-divider></md-divider>
      <md-list-item headline="Dark mode" supporting-text="Match system" lines="2">
        <md-switch slot="trailing" aria-label="Enable dark mode" data-setting="dark"></md-switch>
      </md-list-item>
      <md-divider></md-divider>
      <md-list-item headline="Sync over cellular">
        <md-switch slot="trailing" selected aria-label="Sync over cellular" data-setting="cellular"></md-switch>
      </md-list-item>
    </md-list>
  </md-card>
</main>

<md-snackbar id="settings-toast" message="Setting saved"></md-snackbar>

<script type="module">
  const toast = document.getElementById('settings-toast');
  document.querySelectorAll('md-switch[data-setting]').forEach((sw) => {
    sw.addEventListener('mdChange', (e) => {
      if (sw.dataset.setting === 'dark') {
        document.documentElement.setAttribute('data-theme', e.detail.selected ? 'dark' : 'light');
      }
      toast.show();
    });
  });
</script>
```

### 8.3 Settings form (deferred save, with validation)

When settings are saved on submit rather than applied instantly, use a real
form. `required` blocks the submit; every control needs a `name` to reach
`FormData`.

```html
<form id="profile-form" style="max-inline-size: 560px; margin: 24px auto; padding: 0 16px;">
  <md-card variant="outlined" style="padding: 24px; display: flex; flex-direction: column; gap: 20px;">
    <h2 style="margin: 0; font: var(--md-sys-typescale-title-large-font);">Profile</h2>

    <md-text-field
      variant="outlined"
      label="Display name"
      name="displayName"
      required
      supporting-text="Shown on your public profile"
    ></md-text-field>

    <md-select variant="outlined" label="Language" name="language" value="en" required>
      <md-select-option value="en" label="English"></md-select-option>
      <md-select-option value="de" label="Deutsch"></md-select-option>
      <md-select-option value="ar" label="العربية"></md-select-option>
    </md-select>

    <!-- md-checkbox has NO label slot. It is a labelable, form-associated
         element: wrap it in a native <label> (which names it AND forwards
         clicks), or give the host an aria-label. Text between the tags is
         NOT rendered. -->
    <label style="display: inline-flex; align-items: center; gap: 12px; cursor: pointer;">
      <md-checkbox name="newsletter" value="yes" supporting-text="Monthly, no more"></md-checkbox>
      <span>Send me product news</span>
    </label>

    <div style="display: flex; gap: 8px; justify-content: flex-end;">
      <md-button variant="text" type="reset">Reset</md-button>
      <md-button variant="filled" type="submit">Save changes</md-button>
    </div>
  </md-card>
</form>

<md-snackbar id="saved-toast" message="Changes saved" action="Undo"></md-snackbar>

<script type="module">
  const form = document.getElementById('profile-form');
  const toast = document.getElementById('saved-toast');

  form.addEventListener('submit', (e) => {
    e.preventDefault();
    const data = Object.fromEntries(new FormData(form));
    console.log(data); // { displayName, language, newsletter? }
    toast.show();
  });

  toast.addEventListener('mdAction', () => form.reset());
</script>
```

### 8.4 Dashboard with a FAB

```html
<md-app-bar variant="medium" headline="Inbox">
  <md-icon-button slot="trailing" icon="search" aria-label="Search"></md-icon-button>
  <md-icon-button slot="trailing" icon="filter_list" aria-label="Filter"></md-icon-button>
</md-app-bar>

<main style="padding: 16px; display: grid; gap: 12px; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));">
  <md-card variant="filled" interactive style="padding: 16px;">
    <strong>Acme contract</strong>
    <p style="margin: 4px 0 0; color: var(--md-sys-color-on-surface-variant);">Renewal due in 5 days</p>
  </md-card>
  <md-card variant="filled" interactive style="padding: 16px;">
    <strong>Q4 report draft</strong>
    <p style="margin: 4px 0 0; color: var(--md-sys-color-on-surface-variant);">Shared by Alex</p>
  </md-card>
</main>

<md-fab
  icon="add"
  aria-label="New item"
  style="position: fixed; inset-block-end: 16px; inset-inline-end: 16px; z-index: var(--md-sys-z-index-navigation);"
></md-fab>
```

`inset-inline-end` (not `right`) is what keeps the FAB in the correct corner
under `dir="rtl"`.

### 8.5 Destructive confirmation dialog

`md-dialog` traps focus and returns it to the trigger on close — do not add your
own focus management. The error colouring goes through the button's own custom
properties, never a hex.

```html
<md-button id="open-delete" variant="outlined">Delete account</md-button>

<md-dialog id="confirm-delete" headline="Delete account?" icon="warning">
  <p style="margin: 0;">
    This will permanently delete your account and all associated data.
    This action cannot be undone.
  </p>
  <md-button id="cancel-delete" slot="actions" variant="text">Cancel</md-button>
  <md-button
    id="do-delete"
    slot="actions"
    variant="filled"
    style="--md-button-container-color: var(--md-sys-color-error);
           --md-button-label-color: var(--md-sys-color-on-error);"
  >Delete</md-button>
</md-dialog>

<script type="module">
  const dialog = document.getElementById('confirm-delete');
  document.getElementById('open-delete').addEventListener('mdClick', () => dialog.show());
  document.getElementById('cancel-delete').addEventListener('mdClick', () => dialog.close());
  document.getElementById('do-delete').addEventListener('mdClick', () => {
    dialog.close();
    // perform the deletion
  });
</script>
```

If you omit `slot="actions"` entirely, `md-dialog` renders its own Cancel / OK
pair (labels via `cancel-label` / `ok-label`) and closes itself.

### 8.6 Tabbed content page

`md-tab-panels` finds the nearest preceding `md-tabs` (or the one named by
`for`), follows its `mdTabChange`, and wires `aria-controls` /
`aria-labelledby` both ways. **No JavaScript is required**, and `md-tab` has no
`value` or `selected` prop — selection lives on `md-tabs` as `active-tab-index`.

```html
<md-tabs id="profile-tabs" aria-label="Profile sections" active-tab-index="0">
  <md-tab label="Posts"></md-tab>
  <md-tab label="Replies"></md-tab>
  <md-tab label="Likes" badge="3"></md-tab>
</md-tabs>

<md-tab-panels for="profile-tabs">
  <md-tab-panel style="padding: 16px;">
    <p style="margin: 0;">Your posts appear here.</p>
  </md-tab-panel>
  <md-tab-panel style="padding: 16px;">
    <p style="margin: 0;">Your replies appear here.</p>
  </md-tab-panel>
  <md-tab-panel style="padding: 16px;">
    <p style="margin: 0;">Posts you liked appear here.</p>
  </md-tab-panel>
</md-tab-panels>
```

To react to the switch (lazy-loading a panel, for example), listen on the tabs:

```js
document.getElementById('profile-tabs')
  .addEventListener('mdTabChange', (e) => console.log(e.detail.index, e.detail.previousIndex));
```

### 8.7 The full recipe library

Twenty-two more complete screens live in the documentation, each with a live
demo, the full markup, framework tabs, and production notes. When the user's
request matches one of these, read that page (append the slug to
`https://awc-ui.dev/recipes/`) instead of composing from scratch:

| Recipe slug | Screen |
|---|---|
| `two-factor-verification` | OTP entry, resend countdown, backup-codes dialog |
| `kpi-overview` | Stat tiles with sparklines + charts under a range switcher |
| `data-grid-console` | Bulk-action data table: filters, selection, undo |
| `server-fleet-status` | Table of hosts with meters, sparklines, status dots |
| `release-health-drilldown` | Table row → side-sheet master-detail with charts |
| `csv-import-wizard` | Stepper: upload, map columns, validate, import |
| `role-permission-assignment` | Transfer-list permissions with confirm dialog |
| `org-chart-explorer` | Searchable org chart with side-sheet profiles |
| `moderation-queue` | Verdict controls, confidence meter, card queue |
| `checkout-wizard` | Three-step commerce checkout with validation |
| `appointment-booking` | Date + time pickers inside a stepper flow |
| `survey-nps` | Paged survey using every input control |
| `notification-preferences` | Accordion × switch matrix, quiet hours |
| `app-shell` | Responsive rail/bar chrome, SSR-ready, zero CLS |
| `inbox-shell` | Three-zone list + reading-pane layout |
| `mobile-filter-sheet` | Bottom-sheet filters with applied-chip row |
| `product-reviews` | Rating input + per-star meter breakdown |
| `order-tracking` | Shipment timeline stepper with progress meter |
| `portfolio-markets` | Finance charts + holdings table + trade ticket |
| `pricing-page` | Plan cards, billing toggle, comparison table |
| `async-feedback-patterns` | Skeleton/progress/snackbar choreography rules |
| `charts-gallery` | Every chart component, live-retheming palette |

---

## §9 — Universal do's and don'ts

Apply to every component. Component-specific rules live in each manual.

### 9.1 API and styling

| ✅ Do | ❌ Don't |
|---|---|
| Use the custom element directly — it *is* the control, with its own `href` / `type` props | Wrap it in a native `<button>` / `<a>` (§7.3) |
| Set arrays and objects as **JS properties** (`el.items = [...]`) | Pass them as HTML attributes — they won't parse |
| Theme via `--md-<component>-*` properties, then `::part()` | Reach into shadow internals or override `.md-*` classes |
| Change appearance through design tokens (§4.1) | Hardcode hex colors, px spacing, shadows, or font stacks |
| Use `--md-sys-z-index-*` for your own overlays | Invent z-indexes that land under a menu |
| Use logical CSS (`margin-inline-start`, `inset-inline-end`) | Use `margin-left`, `right`, `padding-right` |
| Set `data-density` / `data-theme` / `dir` once, globally | Set them per component unless you mean a local exception |
| Listen to the component's `md*` events | Rely on native `click` — it fires even when the component's `disabled` / `loading` guard suppressed the action |
| Check the manual for the state prop name | Assume `checked`; `md-switch` uses `selected` |
| Render the element, then call its `@Method` | Call `.show()` on an element not yet in the DOM |

Toggling components flip their own state on activation and *then* emit. On
`md-button`, `mdClick` is cancelable — `preventDefault()` on it vetoes the
toggle and any navigation. `mdChange` fires after the flip and is not
cancelable. If a controlled parent rejects a change it must revert the child
explicitly.

`md-button` has a **toggle mode**: set `toggle` and the button flips its own
`selected` on each activation and exposes `aria-pressed`. `selected` is the
state, not the switch — set it for the initial pressed state and read it back
from `mdClick`'s `detail.selected`. Setting `toggle` and then styling
"pressed" yourself, or setting `selected` without `toggle` (which emits no
`aria-pressed` at all), both produce a control that lies to assistive tech.

### 9.2 Content and hierarchy

| ✅ Do | ❌ Don't |
|---|---|
| Use sentence case for all labels | Uppercase or title-case UI text |
| Keep one high-emphasis action per screen region | Compete `filled` buttons against each other |
| Use `soft-disabled` + `md-tooltip` for contextually-unavailable actions | Use `disabled` and remove it from tab order with no explanation |
| Localize every text prop and `aria-label` | Leave default English prop values in a translated app |

**`disabled` vs `soft-disabled`.** Both render the disabled appearance, but
`disabled` also removes the control from the tab order, so a keyboard or screen
reader user can never find out *why* it is off. `soft-disabled` keeps the
control focusable and announced while still blocking activation — which is what
lets an `md-tooltip` on it explain the gate. Use it whenever the reason is
informative rather than obvious.

Nesting rules — dialog inside a dialog, a component inside a native
`<button>` / `<a>`, tabs used as app navigation — live in §7.3.

### 9.3 Accessibility contract

The library ships WCAG 2.1 AA keyboard and ARIA wiring by default. These are the
rules you must not break:

1. **Every icon-only control gets an accessible name.** `md-icon-button`,
   `md-fab`, and icon-only `md-tab` are nameless without `aria-label` (or
   `aria-labelledby`). `md-fab` will also accept `label`, and warns in the
   console when it has neither.
2. **Every form field gets a `label` prop.** `placeholder` is not a label — it
   disappears on type.
3. **Don't break the tab order.** Every interactive control must be reachable by
   Tab and operable by Enter/Space. If you add `tabindex="-1"` to anything,
   have a reason.
4. **Don't write your own focus trap.** `md-dialog`, `md-bottom-sheet` and
   `md-side-sheet` trap focus while open and restore it to the trigger on
   close — including across shadow boundaries. Adding your own fights theirs.
5. **Don't wrap components in your own live regions.** `md-snackbar` announces
   itself (`politeness="polite"` by default, `"assertive"` when the message must
   interrupt). For an error that blocks the task, use `md-dialog`.
6. **Don't disable motion yourself.** Components honour
   `prefers-reduced-motion: reduce` internally.
7. **Directional icons do not auto-flip in RTL** — see §4.5.
8. **Re-verify contrast after overriding any colour role** — the library's AA
   testing covers the shipped palette only. The Theme Generator at
   <https://awc-ui.dev/theme-generator> runs the WCAG checks live (§4.2).

---

## §10 — Before you ship

1. **Every icon-only control has an accessible name.**
2. **Keyboard-only pass**: reach and operate every control; focus is always
   visible; no traps in dialogs/menus/sheets; focus returns to the trigger.
3. **Theme pass**: light *and* dark, if both are supported — and the attribute
   is set before first paint.
4. **RTL pass**, if an RTL locale ships — check directional icons specifically,
   and grep your own CSS for physical properties.
5. **Density pass** at the configured rung — no clipped labels, touch targets
   still adequate. Remember `density="0"` is inert; use
   `--md-sys-density-scale: 0` to opt a subtree out.
6. **Forms**: every control has a `name`; `required` blocks submit; `FormData`
   contains every field; reset works.
7. **No hardcoded strings** left in markup if the app is localized — including
   default prop values like `Search`, `Dismiss`, `No results`.
8. **No hardcoded design values** — grep the diff for hex colours, `px` radii,
   `box-shadow`, and `z-index` literals.
9. **Contrast** re-verified against AA if colour roles were overridden.
10. **SSR**: if server-rendered, confirm no hydration mismatch and that content
    is present with JS disabled.
11. **No shadow-internal CSS** — only tokens, custom properties, and `::part()`.
12. **Every `md-*` tag you emitted appears in §6.** If it doesn't, it doesn't
    exist.