Status Dot

A presence or health indicator. A small coloured dot with six states, three sizes and an optional pulse — typically anchored to the corner of an avatar, or sitting inline in a dense table row.

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>

<div style="display: flex; gap: 24px; align-items: center;">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot state="busy" label="Busy"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Alan Turing" size="large"></md-avatar>
    <md-status-dot state="away" label="Away"></md-status-dot>
  </span>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', gap: '24px', alignItems: 'center' }}>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Ada Lovelace" size="large"></MdAvatar>
          <MdStatusDot state="online" label="Online"></MdStatusDot>
        </span>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Grace Hopper" size="large"></MdAvatar>
          <MdStatusDot state="busy" label="Busy"></MdStatusDot>
        </span>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Alan Turing" size="large"></MdAvatar>
          <MdStatusDot state="away" label="Away"></MdStatusDot>
        </span>
      </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: 24px; align-items: center;">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot state="busy" label="Busy"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Alan Turing" size="large"></md-avatar>
    <md-status-dot state="away" label="Away"></md-status-dot>
  </span>
</div>

Copy

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

<template>
  <div style="display: flex; gap: 24px; align-items: center;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" size="large"></md-avatar>
      <md-status-dot state="online" label="Online"></md-status-dot>
    </span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Grace Hopper" size="large"></md-avatar>
      <md-status-dot state="busy" label="Busy"></md-status-dot>
    </span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Alan Turing" size="large"></md-avatar>
      <md-status-dot state="away" label="Away"></md-status-dot>
    </span>
  </div>
</template>

Copy

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

<div style="display: flex; gap: 24px; align-items: center;">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot state="busy" label="Busy"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Alan Turing" size="large"></md-avatar>
    <md-status-dot state="away" label="Away"></md-status-dot>
  </span>
</div>

Install

Already installed? See the Installation guide for one-time package setup (core + tokens, fonts). Each tab below shows two patterns for using md-status-dot 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-status-dot) ─── -->
<script type="module">
  import '@awc-ui/core/components/md-status-dot';
</script>


<md-status-dot></md-status-dot>

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 { MdStatusDot } from '@awc-ui/react';

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


// ─── Option B: single import (tree-shake to only md-status-dot) ───
//   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-status-dot';

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

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-status-dot></md-status-dot>`,
})
export class ExampleComponent {}


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

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

Copy

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

<template>
  <MdStatusDot></MdStatusDot>
</template>


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

<template>
  <md-status-dot></md-status-dot>
</template>

Copy

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

<md-status-dot></md-status-dot>


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

<md-status-dot></md-status-dot>

When to use

Not a Material Design 3 component

M3 has badges, not status dots. The guidance on this page is house rules, derived from M3’s badge guidance plus general status-indicator practice — there is no M3 status-dot page to cite.

• Presence: online / away / busy / offline / invisible on an avatar.
• A compact health or state marker in a dense list or table row.

When not to use

Situation	Use instead
A count of unread items	md-badge
An interactive filter or tag	md-chip
A status with a text label the user reads	md-chip
Progress or loading	md-progress-indicator / md-loading-indicator
A large, prominent state banner	md-card with a semantic colour
Something clickable	md-button / md-icon-button

Dot vs badge

A status dot is presence; md-badge is a count. If the answer to “what does it show?” is a number, you want the badge.

Positioning

The dot positions itself absolutely at the bottom inline-end corner of its containing block, using --md-status-dot-inset-end and --md-status-dot-inset-block-end (both 0 at small and medium, -3px at large so the bigger dot still kisses the tile edge).

The parent needs position: relative

Without a positioned ancestor the dot anchors to the nearest one further up the tree — often the page — and lands somewhere unrelated to its subject. Wrap the avatar (or row, or tile) in a position: relative element.

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

A relative parent anchors the dot to the corner — position: static lets it flow instead

relative static

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:5.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">relative</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot state="online" label="Online" size="large"></md-status-dot>
  </span>
  <span style="inline-size:5.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">static</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot state="online" label="Online" size="large" style="position: static;"></md-status-dot>
  </span>
</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: '5.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>relative</span>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Ada Lovelace" size="large"></MdAvatar>
          <MdStatusDot state="online" label="Online" size="large"></MdStatusDot>
        </span>
        <span style={{ inlineSize: '5.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>static</span>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Grace Hopper" size="large"></MdAvatar>
          <MdStatusDot state="online" label="Online" size="large" style={{ position: 'static' }}></MdStatusDot>
        </span>
      </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:5.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">relative</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot state="online" label="Online" size="large"></md-status-dot>
  </span>
  <span style="inline-size:5.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">static</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot state="online" label="Online" size="large" style="position: static;"></md-status-dot>
  </span>
</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:5.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">relative</span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" size="large"></md-avatar>
      <md-status-dot state="online" label="Online" size="large"></md-status-dot>
    </span>
    <span style="inline-size:5.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">static</span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Grace Hopper" size="large"></md-avatar>
      <md-status-dot state="online" label="Online" size="large" style="position: static;"></md-status-dot>
    </span>
  </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:5.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">relative</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot state="online" label="Online" size="large"></md-status-dot>
  </span>
  <span style="inline-size:5.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">static</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot state="online" label="Online" size="large" style="position: static;"></md-status-dot>
  </span>
</div>

The insets are logical, so the dot flips to the correct corner under dir="rtl" with no extra CSS. A surface-coloured outline (2px at medium, 1.5px at small, 3px at large) keeps it visually detached from whatever it sits on.

Match the anchor to the tile shape

The default offset is tuned for a circular avatar, where the corner of the box sits outside the drawn shape. On a rounded or square tile the same offset puts the dot inside the silhouette, overlapping the radius — push it further out so it kisses the corner instead.

Anchor per tile shape

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: 32px; align-items: center;">
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 50%; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="Online" style="--md-status-dot-inset-end: -3px; --md-status-dot-inset-block-end: -3px;"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 4px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="Online" style="--md-status-dot-inset-end: -4px; --md-status-dot-inset-block-end: -4px;"></md-status-dot>
  </span>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', gap: '32px', alignItems: 'center' }}>
        <span style={{ position: 'relative', display: 'inline-flex', inlineSize: '48px', blockSize: '48px', borderRadius: '50%', background: 'var(--md-sys-color-primary-container)' }}>
          <MdStatusDot state="online" label="Online"></MdStatusDot>
        </span>
        <span style={{ position: 'relative', display: 'inline-flex', inlineSize: '48px', blockSize: '48px', borderRadius: '12px', background: 'var(--md-sys-color-primary-container)' }}>
          <MdStatusDot state="online" label="Online" style={{ '--md-status-dot-inset-end': '-3px', '--md-status-dot-inset-block-end': '-3px' }}></MdStatusDot>
        </span>
        <span style={{ position: 'relative', display: 'inline-flex', inlineSize: '48px', blockSize: '48px', borderRadius: '4px', background: 'var(--md-sys-color-primary-container)' }}>
          <MdStatusDot state="online" label="Online" style={{ '--md-status-dot-inset-end': '-4px', '--md-status-dot-inset-block-end': '-4px' }}></MdStatusDot>
        </span>
      </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: 32px; align-items: center;">
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 50%; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="Online" style="--md-status-dot-inset-end: -3px; --md-status-dot-inset-block-end: -3px;"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 4px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="Online" style="--md-status-dot-inset-end: -4px; --md-status-dot-inset-block-end: -4px;"></md-status-dot>
  </span>
</div>

Copy

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

<template>
  <div style="display: flex; gap: 32px; align-items: center;">
    <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 50%; background: var(--md-sys-color-primary-container);">
      <md-status-dot state="online" label="Online"></md-status-dot>
    </span>
    <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
      <md-status-dot state="online" label="Online" style="--md-status-dot-inset-end: -3px; --md-status-dot-inset-block-end: -3px;"></md-status-dot>
    </span>
    <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 4px; background: var(--md-sys-color-primary-container);">
      <md-status-dot state="online" label="Online" style="--md-status-dot-inset-end: -4px; --md-status-dot-inset-block-end: -4px;"></md-status-dot>
    </span>
  </div>
</template>

Copy

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

<div style="display: flex; gap: 32px; align-items: center;">
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 50%; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="Online" style="--md-status-dot-inset-end: -3px; --md-status-dot-inset-block-end: -3px;"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 4px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="Online" style="--md-status-dot-inset-end: -4px; --md-status-dot-inset-block-end: -4px;"></md-status-dot>
  </span>
</div>

Inline, without an anchor

In a legend, a status menu or a dropdown row the dot is not decorating a tile — it is content in its own right. Override position: static and it detaches from corner-anchoring and flows like any inline element.

A status legend

• Available now
• Away from desk
• Do not disturb
• Signed out

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>

<ul style="list-style: none; padding: 0; margin: 0; display: grid; gap: 8px; font: 400 14px/20px system-ui, sans-serif; color: var(--md-sys-color-on-surface);">
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="online" style="position: static;"></md-status-dot>
    Available now
  </li>
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="away" style="position: static;"></md-status-dot>
    Away from desk
  </li>
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="busy" style="position: static;"></md-status-dot>
    Do not disturb
  </li>
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="offline" style="position: static;"></md-status-dot>
    Signed out
  </li>
</ul>

Copy

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

export function Demo() {
  return (
    <>
      <ul style={{ listStyle: 'none', padding: '0', margin: '0', display: 'grid', gap: '8px', font: '400 14px/20px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface)' }}>
        <li style={{ display: 'inline-flex', alignItems: 'center', gap: '10px' }}>
          <MdStatusDot state="online" style={{ position: 'static' }}></MdStatusDot>
          Available now
        </li>
        <li style={{ display: 'inline-flex', alignItems: 'center', gap: '10px' }}>
          <MdStatusDot state="away" style={{ position: 'static' }}></MdStatusDot>
          Away from desk
        </li>
        <li style={{ display: 'inline-flex', alignItems: 'center', gap: '10px' }}>
          <MdStatusDot state="busy" style={{ position: 'static' }}></MdStatusDot>
          Do not disturb
        </li>
        <li style={{ display: 'inline-flex', alignItems: 'center', gap: '10px' }}>
          <MdStatusDot state="offline" style={{ position: 'static' }}></MdStatusDot>
          Signed out
        </li>
      </ul>
    </>
  );
}

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 -->
<ul style="list-style: none; padding: 0; margin: 0; display: grid; gap: 8px; font: 400 14px/20px system-ui, sans-serif; color: var(--md-sys-color-on-surface);">
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="online" style="position: static;"></md-status-dot>
    Available now
  </li>
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="away" style="position: static;"></md-status-dot>
    Away from desk
  </li>
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="busy" style="position: static;"></md-status-dot>
    Do not disturb
  </li>
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="offline" style="position: static;"></md-status-dot>
    Signed out
  </li>
</ul>

Copy

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

<template>
  <ul style="list-style: none; padding: 0; margin: 0; display: grid; gap: 8px; font: 400 14px/20px system-ui, sans-serif; color: var(--md-sys-color-on-surface);">
    <li style="display: inline-flex; align-items: center; gap: 10px;">
      <md-status-dot state="online" style="position: static;"></md-status-dot>
      Available now
    </li>
    <li style="display: inline-flex; align-items: center; gap: 10px;">
      <md-status-dot state="away" style="position: static;"></md-status-dot>
      Away from desk
    </li>
    <li style="display: inline-flex; align-items: center; gap: 10px;">
      <md-status-dot state="busy" style="position: static;"></md-status-dot>
      Do not disturb
    </li>
    <li style="display: inline-flex; align-items: center; gap: 10px;">
      <md-status-dot state="offline" style="position: static;"></md-status-dot>
      Signed out
    </li>
  </ul>
</template>

Copy

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

<ul style="list-style: none; padding: 0; margin: 0; display: grid; gap: 8px; font: 400 14px/20px system-ui, sans-serif; color: var(--md-sys-color-on-surface);">
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="online" style="position: static;"></md-status-dot>
    Available now
  </li>
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="away" style="position: static;"></md-status-dot>
    Away from desk
  </li>
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="busy" style="position: static;"></md-status-dot>
    Do not disturb
  </li>
  <li style="display: inline-flex; align-items: center; gap: 10px;">
    <md-status-dot state="offline" style="position: static;"></md-status-dot>
    Signed out
  </li>
</ul>

Used this way the dot needs no position: relative parent, since it is no longer looking for a corner to sit in.

States

Six presence states, each with its own fill and pulse colour.

state	Meaning
online	Available
away	Idle
busy	Do not disturb / in a call
offline	Not connected
invisible	Connected but appearing offline — a hollow ring on a surface fill
neutral	Default. No presence semantics

online, away, busy, offline, invisible, neutral

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: 28px; align-items: center; padding: 8px;">
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="online" label="Online"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="away" label="Away"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="busy" label="Busy"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="offline" label="Offline"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="invisible" label="Invisible"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="neutral" label="Unknown"></md-status-dot></span>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', gap: '28px', alignItems: 'center', padding: '8px' }}>
        <span style={{ position: 'relative', display: 'inline-flex', width: '24px', height: '24px' }}><MdStatusDot state="online" label="Online"></MdStatusDot></span>
        <span style={{ position: 'relative', display: 'inline-flex', width: '24px', height: '24px' }}><MdStatusDot state="away" label="Away"></MdStatusDot></span>
        <span style={{ position: 'relative', display: 'inline-flex', width: '24px', height: '24px' }}><MdStatusDot state="busy" label="Busy"></MdStatusDot></span>
        <span style={{ position: 'relative', display: 'inline-flex', width: '24px', height: '24px' }}><MdStatusDot state="offline" label="Offline"></MdStatusDot></span>
        <span style={{ position: 'relative', display: 'inline-flex', width: '24px', height: '24px' }}><MdStatusDot state="invisible" label="Invisible"></MdStatusDot></span>
        <span style={{ position: 'relative', display: 'inline-flex', width: '24px', height: '24px' }}><MdStatusDot state="neutral" label="Unknown"></MdStatusDot></span>
      </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: 28px; align-items: center; padding: 8px;">
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="online" label="Online"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="away" label="Away"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="busy" label="Busy"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="offline" label="Offline"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="invisible" label="Invisible"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="neutral" label="Unknown"></md-status-dot></span>
</div>

Copy

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

<template>
  <div style="display: flex; gap: 28px; align-items: center; padding: 8px;">
    <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="online" label="Online"></md-status-dot></span>
    <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="away" label="Away"></md-status-dot></span>
    <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="busy" label="Busy"></md-status-dot></span>
    <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="offline" label="Offline"></md-status-dot></span>
    <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="invisible" label="Invisible"></md-status-dot></span>
    <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="neutral" label="Unknown"></md-status-dot></span>
  </div>
</template>

Copy

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

<div style="display: flex; gap: 28px; align-items: center; padding: 8px;">
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="online" label="Online"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="away" label="Away"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="busy" label="Busy"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="offline" label="Offline"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="invisible" label="Invisible"></md-status-dot></span>
  <span style="position: relative; display: inline-flex; width: 24px; height: 24px;"><md-status-dot state="neutral" label="Unknown"></md-status-dot></span>
</div>

Without label the dot is silent to assistive tech

With an empty label (the default) the dot renders as role="presentation" + aria-hidden="true". Colour then becomes the only signal of state, which fails WCAG 1.4.1 Use of Colour on its own — and in Windows High Contrast every state collapses to one system colour. Treat label as required, unless the parent element’s own text already says the state.

state="invisible" is a semantic, not display: none

It means “the user appears offline” and renders a visible hollow ring. To hide the indicator, remove the element — don’t reach for invisible.

Sizes

size	Diameter	Pairs with
small	8px	md-avatar size="small", dense tables
medium	12px	Default. md-avatar size="medium"
large	16px	md-avatar size="large", standalone use

small, medium, large

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: 24px; align-items: center;">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="small"></md-avatar>
    <md-status-dot size="small" state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="medium"></md-avatar>
    <md-status-dot size="medium" state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot size="large" state="online" label="Online"></md-status-dot>
  </span>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', gap: '24px', alignItems: 'center' }}>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Ada Lovelace" size="small"></MdAvatar>
          <MdStatusDot size="small" state="online" label="Online"></MdStatusDot>
        </span>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Ada Lovelace" size="medium"></MdAvatar>
          <MdStatusDot size="medium" state="online" label="Online"></MdStatusDot>
        </span>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Ada Lovelace" size="large"></MdAvatar>
          <MdStatusDot size="large" state="online" label="Online"></MdStatusDot>
        </span>
      </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: 24px; align-items: center;">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="small"></md-avatar>
    <md-status-dot size="small" state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="medium"></md-avatar>
    <md-status-dot size="medium" state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot size="large" state="online" label="Online"></md-status-dot>
  </span>
</div>

Copy

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

<template>
  <div style="display: flex; gap: 24px; align-items: center;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" size="small"></md-avatar>
      <md-status-dot size="small" state="online" label="Online"></md-status-dot>
    </span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" size="medium"></md-avatar>
      <md-status-dot size="medium" state="online" label="Online"></md-status-dot>
    </span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" size="large"></md-avatar>
      <md-status-dot size="large" state="online" label="Online"></md-status-dot>
    </span>
  </div>
</template>

Copy

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

<div style="display: flex; gap: 24px; align-items: center;">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="small"></md-avatar>
    <md-status-dot size="small" state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="medium"></md-avatar>
    <md-status-dot size="medium" state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot size="large" state="online" label="Online"></md-status-dot>
  </span>
</div>

Set an arbitrary diameter with --md-status-dot-size.

Live pulse

live pulses the dot outward in its own colour — useful for “live now”, “in a call” or “recording”.

Pulsing dots Open in Storybook

States that pulse

online away busy

Each size

small medium large

States with no halo of their own

offline invisible neutral neutral + halo

Tuned pulse

0.8s 1.6s (default) 3s custom halo

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>

<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">States that pulse</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="online" live label="online"></md-status-dot></span>online</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="away" live label="away"></md-status-dot></span>away</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="busy" live label="busy"></md-status-dot></span>busy</span>
</div>
<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Each size</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="small" live label="Live, small"></md-status-dot></span>small</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="medium" live label="Live, medium"></md-status-dot></span>medium</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="large" live label="Live, large"></md-status-dot></span>large</span>
</div>
<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">States with no halo of their own</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="offline" live label="Offline"></md-status-dot></span>offline</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="invisible" live label="Invisible"></md-status-dot></span>invisible</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="neutral" live label="Neutral"></md-status-dot></span>neutral</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="neutral" live label="Neutral, halo set" style="--md-status-dot-pulse-color: rgba(103, 80, 164, 0.55);"></md-status-dot></span>neutral + halo</span>
</div>
<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Tuned pulse</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Fast pulse" style="--md-status-dot-pulse-duration: 0.8s;"></md-status-dot></span>0.8s</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Recording"></md-status-dot></span>1.6s (default)</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Slow pulse" style="--md-status-dot-pulse-duration: 3s;"></md-status-dot></span>3s</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Custom halo" style="--md-status-dot-pulse-color: rgba(103, 80, 164, 0.55);"></md-status-dot></span>custom halo</span>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <p style={{ margin: '0 0 10px', font: '500 12px/1.2 system-ui, sans-serif', letterSpacing: '.04em', textTransform: 'uppercase', color: 'var(--md-sys-color-on-surface-variant)' }}>States that pulse</p>
      <div style={{ display: 'flex', gap: '24px', alignItems: 'flex-start', flexWrap: 'wrap', marginBlockEnd: '24px' }}>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '28px', blockSize: '28px' }}><MdStatusDot state="online" live label="online"></MdStatusDot></span>online</span>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '28px', blockSize: '28px' }}><MdStatusDot state="away" live label="away"></MdStatusDot></span>away</span>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '28px', blockSize: '28px' }}><MdStatusDot state="busy" live label="busy"></MdStatusDot></span>busy</span>
      </div>
      <p style={{ margin: '0 0 10px', font: '500 12px/1.2 system-ui, sans-serif', letterSpacing: '.04em', textTransform: 'uppercase', color: 'var(--md-sys-color-on-surface-variant)' }}>Each size</p>
      <div style={{ display: 'flex', gap: '24px', alignItems: 'flex-start', flexWrap: 'wrap', marginBlockEnd: '24px' }}>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '30px', blockSize: '30px' }}><MdStatusDot state="online" size="small" live label="Live, small"></MdStatusDot></span>small</span>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '30px', blockSize: '30px' }}><MdStatusDot state="online" size="medium" live label="Live, medium"></MdStatusDot></span>medium</span>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '30px', blockSize: '30px' }}><MdStatusDot state="online" size="large" live label="Live, large"></MdStatusDot></span>large</span>
      </div>
      <p style={{ margin: '0 0 10px', font: '500 12px/1.2 system-ui, sans-serif', letterSpacing: '.04em', textTransform: 'uppercase', color: 'var(--md-sys-color-on-surface-variant)' }}>States with no halo of their own</p>
      <div style={{ display: 'flex', gap: '24px', alignItems: 'flex-start', flexWrap: 'wrap', marginBlockEnd: '24px' }}>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '28px', blockSize: '28px' }}><MdStatusDot state="offline" live label="Offline"></MdStatusDot></span>offline</span>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '28px', blockSize: '28px' }}><MdStatusDot state="invisible" live label="Invisible"></MdStatusDot></span>invisible</span>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '28px', blockSize: '28px' }}><MdStatusDot state="neutral" live label="Neutral"></MdStatusDot></span>neutral</span>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '28px', blockSize: '28px' }}><MdStatusDot state="neutral" live label="Neutral, halo set" style={{ '--md-status-dot-pulse-color': 'rgba(103, 80, 164, 0.55)' }}></MdStatusDot></span>neutral + halo</span>
      </div>
      <p style={{ margin: '0 0 10px', font: '500 12px/1.2 system-ui, sans-serif', letterSpacing: '.04em', textTransform: 'uppercase', color: 'var(--md-sys-color-on-surface-variant)' }}>Tuned pulse</p>
      <div style={{ display: 'flex', gap: '24px', alignItems: 'flex-start', flexWrap: 'wrap', marginBlockEnd: '24px' }}>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '30px', blockSize: '30px' }}><MdStatusDot state="busy" live label="Fast pulse" style={{ '--md-status-dot-pulse-duration': '0.8s' }}></MdStatusDot></span>0.8s</span>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '30px', blockSize: '30px' }}><MdStatusDot state="busy" live label="Recording"></MdStatusDot></span>1.6s (default)</span>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '30px', blockSize: '30px' }}><MdStatusDot state="busy" live label="Slow pulse" style={{ '--md-status-dot-pulse-duration': '3s' }}></MdStatusDot></span>3s</span>
        <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: '8px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><span style={{ position: 'relative', display: 'inline-flex', inlineSize: '30px', blockSize: '30px' }}><MdStatusDot state="busy" live label="Custom halo" style={{ '--md-status-dot-pulse-color': 'rgba(103, 80, 164, 0.55)' }}></MdStatusDot></span>custom halo</span>
      </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 -->
<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">States that pulse</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="online" live label="online"></md-status-dot></span>online</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="away" live label="away"></md-status-dot></span>away</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="busy" live label="busy"></md-status-dot></span>busy</span>
</div>
<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Each size</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="small" live label="Live, small"></md-status-dot></span>small</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="medium" live label="Live, medium"></md-status-dot></span>medium</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="large" live label="Live, large"></md-status-dot></span>large</span>
</div>
<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">States with no halo of their own</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="offline" live label="Offline"></md-status-dot></span>offline</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="invisible" live label="Invisible"></md-status-dot></span>invisible</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="neutral" live label="Neutral"></md-status-dot></span>neutral</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="neutral" live label="Neutral, halo set" style="--md-status-dot-pulse-color: rgba(103, 80, 164, 0.55);"></md-status-dot></span>neutral + halo</span>
</div>
<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Tuned pulse</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Fast pulse" style="--md-status-dot-pulse-duration: 0.8s;"></md-status-dot></span>0.8s</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Recording"></md-status-dot></span>1.6s (default)</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Slow pulse" style="--md-status-dot-pulse-duration: 3s;"></md-status-dot></span>3s</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Custom halo" style="--md-status-dot-pulse-color: rgba(103, 80, 164, 0.55);"></md-status-dot></span>custom halo</span>
</div>

Copy

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

<template>
  <p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">States that pulse</p>
  <div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="online" live label="online"></md-status-dot></span>online</span>
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="away" live label="away"></md-status-dot></span>away</span>
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="busy" live label="busy"></md-status-dot></span>busy</span>
  </div>
  <p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Each size</p>
  <div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="small" live label="Live, small"></md-status-dot></span>small</span>
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="medium" live label="Live, medium"></md-status-dot></span>medium</span>
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="large" live label="Live, large"></md-status-dot></span>large</span>
  </div>
  <p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">States with no halo of their own</p>
  <div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="offline" live label="Offline"></md-status-dot></span>offline</span>
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="invisible" live label="Invisible"></md-status-dot></span>invisible</span>
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="neutral" live label="Neutral"></md-status-dot></span>neutral</span>
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="neutral" live label="Neutral, halo set" style="--md-status-dot-pulse-color: rgba(103, 80, 164, 0.55);"></md-status-dot></span>neutral + halo</span>
  </div>
  <p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Tuned pulse</p>
  <div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Fast pulse" style="--md-status-dot-pulse-duration: 0.8s;"></md-status-dot></span>0.8s</span>
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Recording"></md-status-dot></span>1.6s (default)</span>
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Slow pulse" style="--md-status-dot-pulse-duration: 3s;"></md-status-dot></span>3s</span>
    <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Custom halo" style="--md-status-dot-pulse-color: rgba(103, 80, 164, 0.55);"></md-status-dot></span>custom halo</span>
  </div>
</template>

Copy

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

<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">States that pulse</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="online" live label="online"></md-status-dot></span>online</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="away" live label="away"></md-status-dot></span>away</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="busy" live label="busy"></md-status-dot></span>busy</span>
</div>
<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Each size</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="small" live label="Live, small"></md-status-dot></span>small</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="medium" live label="Live, medium"></md-status-dot></span>medium</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="online" size="large" live label="Live, large"></md-status-dot></span>large</span>
</div>
<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">States with no halo of their own</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="offline" live label="Offline"></md-status-dot></span>offline</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="invisible" live label="Invisible"></md-status-dot></span>invisible</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="neutral" live label="Neutral"></md-status-dot></span>neutral</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 28px; block-size: 28px;"><md-status-dot state="neutral" live label="Neutral, halo set" style="--md-status-dot-pulse-color: rgba(103, 80, 164, 0.55);"></md-status-dot></span>neutral + halo</span>
</div>
<p style="margin: 0 0 10px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Tuned pulse</p>
<div style="display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; margin-block-end: 24px;">
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Fast pulse" style="--md-status-dot-pulse-duration: 0.8s;"></md-status-dot></span>0.8s</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Recording"></md-status-dot></span>1.6s (default)</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Slow pulse" style="--md-status-dot-pulse-duration: 3s;"></md-status-dot></span>3s</span>
  <span style="display: inline-flex; flex-direction: column; align-items: center; gap: 8px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><span style="position: relative; display: inline-flex; inline-size: 30px; block-size: 30px;"><md-status-dot state="busy" live label="Custom halo" style="--md-status-dot-pulse-color: rgba(103, 80, 164, 0.55);"></md-status-dot></span>custom halo</span>
</div>

live animates — it does not announce

The prop’s name is about motion, not about ARIA. Nothing you do to state is spoken as a result of setting live: the dot’s accessible name comes from aria-label, and changing an aria-label is not a live-region content change. If a state transition matters to a screen-reader user, publish it yourself through your own aria-live region — see below.

Each state pulses in its own colour — green pulses green, busy pulses red — so the halo never contradicts the dot.

Only online, away and busy ship a halo colour, though. The base --_pulse-color is transparent, so live on offline, invisible or neutral animates nothing you can see — the animation runs, but the halo it interpolates is invisible. That is deliberate (a dot that is offline is not “live”), and if you do want one, set --md-status-dot-pulse-color yourself, as the fourth dot in that row does. invisible is the odd one out even then: its inset ring is drawn over by the pulse keyframe, so the two conflict visually.

--md-status-dot-pulse-duration sets the period (default 1.6s).

The pulse is gated behind prefers-reduced-motion: no-preference, so users with reduced motion enabled at the OS level see a static dot — no opt-out prop needed, and nothing to configure.

Announcing state changes

Since the component will not announce for you, pair it with a live region that you update alongside the dot. Switch presence below: the dot recolours, its label follows, and the region — visible here, visually hidden in production — is what a screen reader actually reads out.

Presence switcher — change the state and watch the live region

Online Away Busy

Ada Lovelace is online

Show code for each technology

HTML React Angular Vue Svelte

Copy

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

<div style="display: flex; gap: 8px;">
<md-button variant="outlined" data-state="online">Online</md-button>
<md-button variant="outlined" data-state="away">Away</md-button>
<md-button variant="outlined" data-state="busy">Busy</md-button>
</div>

<!-- .sr-only = your own visually-hidden utility class -->
<div id="presence" class="sr-only" aria-live="polite">Ada Lovelace is online</div>

<script type="module">
const LABELS = { online: 'Online', away: 'Away', busy: 'Busy' };
const dot = document.getElementById('dot');
const region = document.getElementById('presence');

document.querySelectorAll('md-button[data-state]').forEach((btn) => {
  btn.addEventListener('mdClick', () => {
    const next = btn.dataset.state;
    dot.state = next;                                  // recolours the dot
    dot.label = LABELS[next];                          // keeps the dot labelled
    region.textContent = 'Ada Lovelace is ' + next;    // announces the change
  });
});
</script>

Copy

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

const LABELS = { online: 'Online', away: 'Away', busy: 'Busy' } as const;
type Presence = keyof typeof LABELS;

export function PresenceCard({ name }: { name: string }) {
const [state, setState] = useState<Presence>('online');

return (
  <>
    <span style={{ position: 'relative', display: 'inline-flex' }}>
      <MdAvatar name={name} size="large" />
      <MdStatusDot state={state} label={LABELS[state]} size="large" />
    </span>

    <div style={{ display: 'flex', gap: 8 }}>
      {(Object.keys(LABELS) as Presence[]).map((s) => (
        <MdButton key={s} variant="outlined" onMdClick={() => setState(s)}>
          {LABELS[s]}
        </MdButton>
      ))}
    </div>

    <div className="sr-only" aria-live="polite">
      {name} is {state}
    </div>
  </>
);
}

Copy

@Component({
selector: 'app-presence',
template: `
  <span style="position: relative; display: inline-flex;">
    <md-avatar [name]="name" size="large"></md-avatar>
    <md-status-dot [state]="state" [label]="label" size="large"></md-status-dot>
  </span>

  <div style="display: flex; gap: 8px;">
    <md-button variant="outlined" (mdClick)="setPresence('online')">Online</md-button>
    <md-button variant="outlined" (mdClick)="setPresence('away')">Away</md-button>
    <md-button variant="outlined" (mdClick)="setPresence('busy')">Busy</md-button>
  </div>

  <div class="sr-only" aria-live="polite">{{ name }} is {{ state }}</div>
`,
})
export class PresenceComponent {
readonly labels = { online: 'Online', away: 'Away', busy: 'Busy' };

name = 'Ada Lovelace';
state: 'online' | 'away' | 'busy' = 'online';

get label() {
  return this.labels[this.state];
}

setPresence(next: 'online' | 'away' | 'busy') {
  this.state = next;
}
}

Copy

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

const LABELS = { online: 'Online', away: 'Away', busy: 'Busy' } as const;
type Presence = keyof typeof LABELS;

const name = 'Ada Lovelace';
const state = ref<Presence>('online');
const label = computed(() => LABELS[state.value]);
</script>

<template>
<span style="position: relative; display: inline-flex;">
  <md-avatar :name="name" size="large" />
  <md-status-dot :state="state" :label="label" size="large" />
</span>

<div style="display: flex; gap: 8px;">
  <md-button variant="outlined" @mdClick="state = 'online'">Online</md-button>
  <md-button variant="outlined" @mdClick="state = 'away'">Away</md-button>
  <md-button variant="outlined" @mdClick="state = 'busy'">Busy</md-button>
</div>

<div class="sr-only" aria-live="polite">{{ name }} is {{ state }}</div>
</template>

Copy

<script lang="ts">
const LABELS = { online: 'Online', away: 'Away', busy: 'Busy' } as const;
type Presence = keyof typeof LABELS;

const name = 'Ada Lovelace';
let state: Presence = 'online';
$: label = LABELS[state];
</script>

<span style="position: relative; display: inline-flex;">
<md-avatar {name} size="large" />
<md-status-dot {state} {label} size="large" />
</span>

<div style="display: flex; gap: 8px;">
<md-button variant="outlined" on:mdClick={() => (state = 'online')}>Online</md-button>
<md-button variant="outlined" on:mdClick={() => (state = 'away')}>Away</md-button>
<md-button variant="outlined" on:mdClick={() => (state = 'busy')}>Busy</md-button>
</div>

<div class="sr-only" aria-live="polite">{name} is {state}</div>

Why the region and not the dot

role="status" (what a labelled live dot renders as) announces text content changes, and the dot has no text content — its name comes from aria-label, which screen readers do not re-announce. The separate region is what carries the change.

In a table row

size="small" plus adjacent text is the dense-row pattern. The text carries the meaning; the dot is the scannable cue — never ship the dot alone in a status column, since colour is the only thing distinguishing the states and that fails for colour-blind readers and in a printed table alike.

Inside a cell the dot still anchors absolutely, so give it a small positioned box of its own (position: relative) rather than letting it hunt for the nearest positioned ancestor — the row.

A status column

Service Region Status api-gateway eu-west-1 Healthy billing-worker eu-west-1 Deploying search-indexer us-east-1 Degraded legacy-cron us-east-1 Stopped

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-table-container variant="outlined">
  <md-table column-template="2fr 1fr 1fr" label="Service health">
    <md-table-head>
      <md-table-row rowgroup="head">
        <md-table-cell head scope="col">Service</md-table-cell>
        <md-table-cell head scope="col">Region</md-table-cell>
        <md-table-cell head scope="col">Status</md-table-cell>
      </md-table-row>
    </md-table-head>
    <md-table-body>
      <md-table-row value="api-gateway">
        <md-table-cell head scope="row">api-gateway</md-table-cell>
        <md-table-cell>eu-west-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="online" label="Healthy"></md-status-dot></span>
            Healthy
          </span>
        </md-table-cell>
      </md-table-row>
      <md-table-row value="billing-worker">
        <md-table-cell head scope="row">billing-worker</md-table-cell>
        <md-table-cell>eu-west-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="busy" label="Deploying"></md-status-dot></span>
            Deploying
          </span>
        </md-table-cell>
      </md-table-row>
      <md-table-row value="search-indexer">
        <md-table-cell head scope="row">search-indexer</md-table-cell>
        <md-table-cell>us-east-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="away" label="Degraded"></md-status-dot></span>
            Degraded
          </span>
        </md-table-cell>
      </md-table-row>
      <md-table-row value="legacy-cron">
        <md-table-cell head scope="row">legacy-cron</md-table-cell>
        <md-table-cell>us-east-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="offline" label="Stopped"></md-status-dot></span>
            Stopped
          </span>
        </md-table-cell>
      </md-table-row>
    </md-table-body>
  </md-table>
</md-table-container>

Copy

import { MdStatusDot, MdTable, MdTableBody, MdTableCell, MdTableContainer, MdTableHead, MdTableRow } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdTableContainer variant="outlined">
        <MdTable columnTemplate="2fr 1fr 1fr" label="Service health">
          <MdTableHead>
            <MdTableRow rowgroup="head">
              <MdTableCell head scope="col">Service</MdTableCell>
              <MdTableCell head scope="col">Region</MdTableCell>
              <MdTableCell head scope="col">Status</MdTableCell>
            </MdTableRow>
          </MdTableHead>
          <MdTableBody>
            <MdTableRow value="api-gateway">
              <MdTableCell head scope="row">api-gateway</MdTableCell>
              <MdTableCell>eu-west-1</MdTableCell>
              <MdTableCell>
                <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
                  <span style={{ position: 'relative', display: 'inline-flex', inlineSize: '8px', blockSize: '8px' }}><MdStatusDot size="small" state="online" label="Healthy"></MdStatusDot></span>
                  Healthy
                </span>
              </MdTableCell>
            </MdTableRow>
            <MdTableRow value="billing-worker">
              <MdTableCell head scope="row">billing-worker</MdTableCell>
              <MdTableCell>eu-west-1</MdTableCell>
              <MdTableCell>
                <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
                  <span style={{ position: 'relative', display: 'inline-flex', inlineSize: '8px', blockSize: '8px' }}><MdStatusDot size="small" state="busy" label="Deploying"></MdStatusDot></span>
                  Deploying
                </span>
              </MdTableCell>
            </MdTableRow>
            <MdTableRow value="search-indexer">
              <MdTableCell head scope="row">search-indexer</MdTableCell>
              <MdTableCell>us-east-1</MdTableCell>
              <MdTableCell>
                <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
                  <span style={{ position: 'relative', display: 'inline-flex', inlineSize: '8px', blockSize: '8px' }}><MdStatusDot size="small" state="away" label="Degraded"></MdStatusDot></span>
                  Degraded
                </span>
              </MdTableCell>
            </MdTableRow>
            <MdTableRow value="legacy-cron">
              <MdTableCell head scope="row">legacy-cron</MdTableCell>
              <MdTableCell>us-east-1</MdTableCell>
              <MdTableCell>
                <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
                  <span style={{ position: 'relative', display: 'inline-flex', inlineSize: '8px', blockSize: '8px' }}><MdStatusDot size="small" state="offline" label="Stopped"></MdStatusDot></span>
                  Stopped
                </span>
              </MdTableCell>
            </MdTableRow>
          </MdTableBody>
        </MdTable>
      </MdTableContainer>
    </>
  );
}

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-table-container variant="outlined">
  <md-table column-template="2fr 1fr 1fr" label="Service health">
    <md-table-head>
      <md-table-row rowgroup="head">
        <md-table-cell head scope="col">Service</md-table-cell>
        <md-table-cell head scope="col">Region</md-table-cell>
        <md-table-cell head scope="col">Status</md-table-cell>
      </md-table-row>
    </md-table-head>
    <md-table-body>
      <md-table-row value="api-gateway">
        <md-table-cell head scope="row">api-gateway</md-table-cell>
        <md-table-cell>eu-west-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="online" label="Healthy"></md-status-dot></span>
            Healthy
          </span>
        </md-table-cell>
      </md-table-row>
      <md-table-row value="billing-worker">
        <md-table-cell head scope="row">billing-worker</md-table-cell>
        <md-table-cell>eu-west-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="busy" label="Deploying"></md-status-dot></span>
            Deploying
          </span>
        </md-table-cell>
      </md-table-row>
      <md-table-row value="search-indexer">
        <md-table-cell head scope="row">search-indexer</md-table-cell>
        <md-table-cell>us-east-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="away" label="Degraded"></md-status-dot></span>
            Degraded
          </span>
        </md-table-cell>
      </md-table-row>
      <md-table-row value="legacy-cron">
        <md-table-cell head scope="row">legacy-cron</md-table-cell>
        <md-table-cell>us-east-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="offline" label="Stopped"></md-status-dot></span>
            Stopped
          </span>
        </md-table-cell>
      </md-table-row>
    </md-table-body>
  </md-table>
</md-table-container>

Copy

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

<template>
  <md-table-container variant="outlined">
    <md-table column-template="2fr 1fr 1fr" label="Service health">
      <md-table-head>
        <md-table-row rowgroup="head">
          <md-table-cell head scope="col">Service</md-table-cell>
          <md-table-cell head scope="col">Region</md-table-cell>
          <md-table-cell head scope="col">Status</md-table-cell>
        </md-table-row>
      </md-table-head>
      <md-table-body>
        <md-table-row value="api-gateway">
          <md-table-cell head scope="row">api-gateway</md-table-cell>
          <md-table-cell>eu-west-1</md-table-cell>
          <md-table-cell>
            <span style="display: inline-flex; align-items: center; gap: 8px;">
              <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="online" label="Healthy"></md-status-dot></span>
              Healthy
            </span>
          </md-table-cell>
        </md-table-row>
        <md-table-row value="billing-worker">
          <md-table-cell head scope="row">billing-worker</md-table-cell>
          <md-table-cell>eu-west-1</md-table-cell>
          <md-table-cell>
            <span style="display: inline-flex; align-items: center; gap: 8px;">
              <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="busy" label="Deploying"></md-status-dot></span>
              Deploying
            </span>
          </md-table-cell>
        </md-table-row>
        <md-table-row value="search-indexer">
          <md-table-cell head scope="row">search-indexer</md-table-cell>
          <md-table-cell>us-east-1</md-table-cell>
          <md-table-cell>
            <span style="display: inline-flex; align-items: center; gap: 8px;">
              <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="away" label="Degraded"></md-status-dot></span>
              Degraded
            </span>
          </md-table-cell>
        </md-table-row>
        <md-table-row value="legacy-cron">
          <md-table-cell head scope="row">legacy-cron</md-table-cell>
          <md-table-cell>us-east-1</md-table-cell>
          <md-table-cell>
            <span style="display: inline-flex; align-items: center; gap: 8px;">
              <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="offline" label="Stopped"></md-status-dot></span>
              Stopped
            </span>
          </md-table-cell>
        </md-table-row>
      </md-table-body>
    </md-table>
  </md-table-container>
</template>

Copy

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

<md-table-container variant="outlined">
  <md-table column-template="2fr 1fr 1fr" label="Service health">
    <md-table-head>
      <md-table-row rowgroup="head">
        <md-table-cell head scope="col">Service</md-table-cell>
        <md-table-cell head scope="col">Region</md-table-cell>
        <md-table-cell head scope="col">Status</md-table-cell>
      </md-table-row>
    </md-table-head>
    <md-table-body>
      <md-table-row value="api-gateway">
        <md-table-cell head scope="row">api-gateway</md-table-cell>
        <md-table-cell>eu-west-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="online" label="Healthy"></md-status-dot></span>
            Healthy
          </span>
        </md-table-cell>
      </md-table-row>
      <md-table-row value="billing-worker">
        <md-table-cell head scope="row">billing-worker</md-table-cell>
        <md-table-cell>eu-west-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="busy" label="Deploying"></md-status-dot></span>
            Deploying
          </span>
        </md-table-cell>
      </md-table-row>
      <md-table-row value="search-indexer">
        <md-table-cell head scope="row">search-indexer</md-table-cell>
        <md-table-cell>us-east-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="away" label="Degraded"></md-status-dot></span>
            Degraded
          </span>
        </md-table-cell>
      </md-table-row>
      <md-table-row value="legacy-cron">
        <md-table-cell head scope="row">legacy-cron</md-table-cell>
        <md-table-cell>us-east-1</md-table-cell>
        <md-table-cell>
          <span style="display: inline-flex; align-items: center; gap: 8px;">
            <span style="position: relative; display: inline-flex; inline-size: 8px; block-size: 8px;"><md-status-dot size="small" state="offline" label="Stopped"></md-status-dot></span>
            Stopped
          </span>
        </md-table-cell>
      </md-table-row>
    </md-table-body>
  </md-table>
</md-table-container>

API Reference

tune

Properties

Property	Attribute	Type	Default	Reflects
state	state	MdStatusDotState	'neutral'	Yes
size	size	MdStatusDotSize	'medium'	Yes
inline	inline	boolean	false	Yes
live	live	boolean	false	Yes
label	label	string	''	—
density	density	0 | -1 | -2 | -3 | -4	0	Yes

palette

CSS Custom Properties

Override on the host element for per-instance theming:

Property	Description
--md-status-dot-size	Dot diameter (overrides preset)
--md-status-dot-color	Dot fill color
--md-status-dot-pulse-color	Halo color used by the live pulse
--md-status-dot-outline-color	Halo outline (default surface)
--md-status-dot-outline-width	Halo outline width (default 2px)
--md-status-dot-inset-end	inline-end anchor offset (default -2px)
--md-status-dot-inset-block-end	block-end anchor offset (default -2px)
--md-status-dot-pulse-duration	Pulse animation period (default 1.6s)

No events, methods, slots or CSS parts

The dot is a pure indicator — a single leaf element with no shadow children to address, so the custom properties are the whole surface.

Two defaults quoted in that table are stale: it repeats the CSS file’s header comment, which still says -2px for --md-status-dot-inset-end and --md-status-dot-inset-block-end. The rules themselves say 0 for both (-3px at large). --md-status-dot-outline-width is likewise 2px only at size="medium" and density 0 — it is 1.5px at small, 3px at large, and tapers with the density rung. Theming below quotes the rules, not the comment.

Accessibility

• label is effectively required. Empty (the default) → role="presentation" + aria-hidden="true", i.e. invisible to assistive tech, with colour as the only cue. The one acceptable exception is a dot that decorates an element whose own accessible name already carries the state (<md-avatar label="Ada Lovelace, online">).
• With a label and live off, the dot becomes role="img" with that label — a static, named status image.
• With a label and live on, it becomes role="status". That role does not rescue you: the name comes from aria-label, not from text content, so presence changes still need your own live region.
• The dot is not focusable and has no interactive role. Don’t attach click handlers — use md-icon-button if the indicator must be actionable.
• WCAG 1.4.1 — never let the six state colours be the only signal. Under Windows High Contrast they all collapse to one system colour.
• Honour reduced motion: the pulse is already gated behind prefers-reduced-motion, and you can drop live or override --md-status-dot-pulse-duration.

The three exposure modes side by side — the first is invisible to assistive tech, the other two are named:

No label, label only, and label + live — presentation, img and status

presentation img status

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:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">presentation</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large" label="Ada Lovelace, online"></md-avatar>
    <md-status-dot state="online" size="large"></md-status-dot>
  </span>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">img</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot state="away" size="large" label="Away"></md-status-dot>
  </span>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">status</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Alan Turing" size="large"></md-avatar>
    <md-status-dot state="busy" size="large" label="Busy" live></md-status-dot>
  </span>
</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: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>presentation</span>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Ada Lovelace" size="large" label="Ada Lovelace, online"></MdAvatar>
          <MdStatusDot state="online" size="large"></MdStatusDot>
        </span>
        <span style={{ inlineSize: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>img</span>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Grace Hopper" size="large"></MdAvatar>
          <MdStatusDot state="away" size="large" label="Away"></MdStatusDot>
        </span>
        <span style={{ inlineSize: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>status</span>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Alan Turing" size="large"></MdAvatar>
          <MdStatusDot state="busy" size="large" label="Busy" live></MdStatusDot>
        </span>
      </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:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">presentation</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large" label="Ada Lovelace, online"></md-avatar>
    <md-status-dot state="online" size="large"></md-status-dot>
  </span>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">img</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot state="away" size="large" label="Away"></md-status-dot>
  </span>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">status</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Alan Turing" size="large"></md-avatar>
    <md-status-dot state="busy" size="large" label="Busy" live></md-status-dot>
  </span>
</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:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">presentation</span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" size="large" label="Ada Lovelace, online"></md-avatar>
      <md-status-dot state="online" size="large"></md-status-dot>
    </span>
    <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">img</span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Grace Hopper" size="large"></md-avatar>
      <md-status-dot state="away" size="large" label="Away"></md-status-dot>
    </span>
    <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">status</span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Alan Turing" size="large"></md-avatar>
      <md-status-dot state="busy" size="large" label="Busy" live></md-status-dot>
    </span>
  </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:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">presentation</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large" label="Ada Lovelace, online"></md-avatar>
    <md-status-dot state="online" size="large"></md-status-dot>
  </span>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">img</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot state="away" size="large" label="Away"></md-status-dot>
  </span>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">status</span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Alan Turing" size="large"></md-avatar>
    <md-status-dot state="busy" size="large" label="Busy" live></md-status-dot>
  </span>
</div>

RTL, density & i18n

--md-status-dot-inset-end and --md-status-dot-inset-block-end are logical insets, so the same markup anchors bottom-right in LTR and bottom-left in RTL with no extra CSS. See RTL.

<span dir="rtl" style="position: relative; display: inline-flex;">
  <md-avatar name="آدا لوفلايس"></md-avatar>
  <md-status-dot state="online" label="متصل"></md-status-dot>
</span>

Same markup, dir=ltr vs dir=rtl — the dot swaps corners on its own

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:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="Online"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="busy" size="large" label="Busy"></md-status-dot></span>
  </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:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="متصل"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="busy" size="large" label="مشغول"></md-status-dot></span>
  </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: '20px', alignItems: 'center' }}>
          <span style={{ position: 'relative', display: 'inline-flex' }}><MdAvatar name="Ada Lovelace" size="large"></MdAvatar><MdStatusDot state="online" size="large" label="Online"></MdStatusDot></span>
          <span style={{ position: 'relative', display: 'inline-flex' }}><MdAvatar name="Grace Hopper" size="large"></MdAvatar><MdStatusDot state="busy" size="large" label="Busy"></MdStatusDot></span>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>rtl</span>
        <div dir="rtl" style={{ display: 'flex', gap: '20px', alignItems: 'center' }}>
          <span style={{ position: 'relative', display: 'inline-flex' }}><MdAvatar name="Ada Lovelace" size="large"></MdAvatar><MdStatusDot state="online" size="large" label="متصل"></MdStatusDot></span>
          <span style={{ position: 'relative', display: 'inline-flex' }}><MdAvatar name="Grace Hopper" size="large"></MdAvatar><MdStatusDot state="busy" size="large" label="مشغول"></MdStatusDot></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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="Online"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="busy" size="large" label="Busy"></md-status-dot></span>
  </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:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="متصل"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="busy" size="large" label="مشغول"></md-status-dot></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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
    <div dir="ltr" style="display:flex;gap:20px;align-items:center;">
      <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="Online"></md-status-dot></span>
      <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="busy" size="large" label="Busy"></md-status-dot></span>
    </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:20px;align-items:center;">
      <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="متصل"></md-status-dot></span>
      <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="busy" size="large" label="مشغول"></md-status-dot></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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="Online"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="busy" size="large" label="Busy"></md-status-dot></span>
  </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:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="متصل"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="busy" size="large" label="مشغول"></md-status-dot></span>
  </div>
</div>

Override the insets logically, not physically

Retuning the anchor for a squarer tile is fine — do it through --md-status-dot-inset-end / --md-status-dot-inset-block-end and the flip survives. Reach for the physical right / bottom instead and the dot stays pinned to the right-hand corner in RTL, drifting off the tile it belongs to.

dir=rtl — logical insets flip, hard-coded right/bottom do not

correct wrong

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>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="متصل" style="--md-status-dot-inset-end: -3px; --md-status-dot-inset-block-end: -3px;"></md-status-dot>
  </span>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="متصل" style="right: -3px; bottom: -3px;"></md-status-dot>
  </span>
</div>

Copy

import { 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>
        <span style={{ position: 'relative', display: 'inline-flex', inlineSize: '48px', blockSize: '48px', borderRadius: '12px', background: 'var(--md-sys-color-primary-container)' }}>
          <MdStatusDot state="online" label="متصل" style={{ '--md-status-dot-inset-end': '-3px', '--md-status-dot-inset-block-end': '-3px' }}></MdStatusDot>
        </span>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>wrong</span>
        <span style={{ position: 'relative', display: 'inline-flex', inlineSize: '48px', blockSize: '48px', borderRadius: '12px', background: 'var(--md-sys-color-primary-container)' }}>
          <MdStatusDot state="online" label="متصل" style={{ right: '-3px', bottom: '-3px' }}></MdStatusDot>
        </span>
      </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>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="متصل" style="--md-status-dot-inset-end: -3px; --md-status-dot-inset-block-end: -3px;"></md-status-dot>
  </span>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="متصل" style="right: -3px; bottom: -3px;"></md-status-dot>
  </span>
</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>
    <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
      <md-status-dot state="online" label="متصل" style="--md-status-dot-inset-end: -3px; --md-status-dot-inset-block-end: -3px;"></md-status-dot>
    </span>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
    <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
      <md-status-dot state="online" label="متصل" style="right: -3px; bottom: -3px;"></md-status-dot>
    </span>
  </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>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="متصل" style="--md-status-dot-inset-end: -3px; --md-status-dot-inset-block-end: -3px;"></md-status-dot>
  </span>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <span style="position: relative; display: inline-flex; inline-size: 48px; block-size: 48px; border-radius: 12px; background: var(--md-sys-color-primary-container);">
    <md-status-dot state="online" label="متصل" style="right: -3px; bottom: -3px;"></md-status-dot>
  </span>
</div>

Every density rung

density="-1…-4" is a local override of the inherited data-density, and it compounds with size. All five rungs at all three sizes, so the taper is visible in one place. The 0 row carries no density attribute at all — there is no [density="0"] rule to write, so the undensified default is the absence of the prop:

Density 0 (no attribute) through -4 — small, medium and large in each row

0

-1

-2

-3

-4

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;">0</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" style="position: static;"></md-status-dot><md-status-dot state="online" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-1" style="position: static;"></md-status-dot><md-status-dot state="online" density="-1" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-1" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-2" style="position: static;"></md-status-dot><md-status-dot state="online" density="-2" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-2" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-3" style="position: static;"></md-status-dot><md-status-dot state="online" density="-3" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-3" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-4" style="position: static;"></md-status-dot><md-status-dot state="online" density="-4" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-4" style="position: static;"></md-status-dot></div>
</div>

Copy

import { 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' }}>0</span>
        <div style={{ display: 'flex', gap: '20px', alignItems: 'center' }}><MdStatusDot state="online" size="small" style={{ position: 'static' }}></MdStatusDot><MdStatusDot state="online" style={{ position: 'static' }}></MdStatusDot><MdStatusDot state="online" size="large" style={{ position: 'static' }}></MdStatusDot></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-1</span>
        <div style={{ display: 'flex', gap: '20px', alignItems: 'center' }}><MdStatusDot state="online" size="small" density="-1" style={{ position: 'static' }}></MdStatusDot><MdStatusDot state="online" density="-1" style={{ position: 'static' }}></MdStatusDot><MdStatusDot state="online" size="large" density="-1" style={{ position: 'static' }}></MdStatusDot></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-2</span>
        <div style={{ display: 'flex', gap: '20px', alignItems: 'center' }}><MdStatusDot state="online" size="small" density="-2" style={{ position: 'static' }}></MdStatusDot><MdStatusDot state="online" density="-2" style={{ position: 'static' }}></MdStatusDot><MdStatusDot state="online" size="large" density="-2" style={{ position: 'static' }}></MdStatusDot></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-3</span>
        <div style={{ display: 'flex', gap: '20px', alignItems: 'center' }}><MdStatusDot state="online" size="small" density="-3" style={{ position: 'static' }}></MdStatusDot><MdStatusDot state="online" density="-3" style={{ position: 'static' }}></MdStatusDot><MdStatusDot state="online" size="large" density="-3" style={{ position: 'static' }}></MdStatusDot></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-4</span>
        <div style={{ display: 'flex', gap: '20px', alignItems: 'center' }}><MdStatusDot state="online" size="small" density="-4" style={{ position: 'static' }}></MdStatusDot><MdStatusDot state="online" density="-4" style={{ position: 'static' }}></MdStatusDot><MdStatusDot state="online" size="large" density="-4" style={{ position: 'static' }}></MdStatusDot></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;">0</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" style="position: static;"></md-status-dot><md-status-dot state="online" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-1" style="position: static;"></md-status-dot><md-status-dot state="online" density="-1" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-1" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-2" style="position: static;"></md-status-dot><md-status-dot state="online" density="-2" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-2" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-3" style="position: static;"></md-status-dot><md-status-dot state="online" density="-3" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-3" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-4" style="position: static;"></md-status-dot><md-status-dot state="online" density="-4" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-4" style="position: static;"></md-status-dot></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;">0</span>
    <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" style="position: static;"></md-status-dot><md-status-dot state="online" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" style="position: static;"></md-status-dot></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
    <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-1" style="position: static;"></md-status-dot><md-status-dot state="online" density="-1" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-1" style="position: static;"></md-status-dot></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
    <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-2" style="position: static;"></md-status-dot><md-status-dot state="online" density="-2" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-2" style="position: static;"></md-status-dot></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
    <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-3" style="position: static;"></md-status-dot><md-status-dot state="online" density="-3" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-3" style="position: static;"></md-status-dot></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
    <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-4" style="position: static;"></md-status-dot><md-status-dot state="online" density="-4" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-4" style="position: static;"></md-status-dot></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;">0</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" style="position: static;"></md-status-dot><md-status-dot state="online" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-1" style="position: static;"></md-status-dot><md-status-dot state="online" density="-1" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-1" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-2" style="position: static;"></md-status-dot><md-status-dot state="online" density="-2" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-2" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-3" style="position: static;"></md-status-dot><md-status-dot state="online" density="-3" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-3" style="position: static;"></md-status-dot></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:20px;align-items:center;"><md-status-dot state="online" size="small" density="-4" style="position: static;"></md-status-dot><md-status-dot state="online" density="-4" style="position: static;"></md-status-dot><md-status-dot state="online" size="large" density="-4" style="position: static;"></md-status-dot></div>
</div>

small at -4 is 4px

The medium ladder runs 12 → 10.5 → 9 → 7.5 → 6px, and small runs 8 → 7 → 6 → 5 → 4px — small enough that the outline is doing most of the work of making the dot visible. Check the rung you actually ship, and pair the dot with text rather than shrinking it further. See Density.

Every state stays legible at the rung you pick, since the outline tapers with it:

Every state at density -2

online away busy offline invisible neutral

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; flex-wrap:wrap;">
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="online" density="-2" style="position: static;"></md-status-dot>online</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="away" density="-2" style="position: static;"></md-status-dot>away</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="busy" density="-2" style="position: static;"></md-status-dot>busy</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="offline" density="-2" style="position: static;"></md-status-dot>offline</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="invisible" density="-2" style="position: static;"></md-status-dot>invisible</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="neutral" density="-2" style="position: static;"></md-status-dot>neutral</span>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', gap: '20px', alignItems: 'center', flexWrap: 'wrap' }}>
        <span style={{ display: 'inline-flex', alignItems: 'center', gap: '6px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><MdStatusDot state="online" density="-2" style={{ position: 'static' }}></MdStatusDot>online</span>
        <span style={{ display: 'inline-flex', alignItems: 'center', gap: '6px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><MdStatusDot state="away" density="-2" style={{ position: 'static' }}></MdStatusDot>away</span>
        <span style={{ display: 'inline-flex', alignItems: 'center', gap: '6px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><MdStatusDot state="busy" density="-2" style={{ position: 'static' }}></MdStatusDot>busy</span>
        <span style={{ display: 'inline-flex', alignItems: 'center', gap: '6px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><MdStatusDot state="offline" density="-2" style={{ position: 'static' }}></MdStatusDot>offline</span>
        <span style={{ display: 'inline-flex', alignItems: 'center', gap: '6px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><MdStatusDot state="invisible" density="-2" style={{ position: 'static' }}></MdStatusDot>invisible</span>
        <span style={{ display: 'inline-flex', alignItems: 'center', gap: '6px', font: '400 12px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}><MdStatusDot state="neutral" density="-2" style={{ position: 'static' }}></MdStatusDot>neutral</span>
      </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; flex-wrap:wrap;">
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="online" density="-2" style="position: static;"></md-status-dot>online</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="away" density="-2" style="position: static;"></md-status-dot>away</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="busy" density="-2" style="position: static;"></md-status-dot>busy</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="offline" density="-2" style="position: static;"></md-status-dot>offline</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="invisible" density="-2" style="position: static;"></md-status-dot>invisible</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="neutral" density="-2" style="position: static;"></md-status-dot>neutral</span>
</div>

Copy

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

<template>
  <div style="display:flex; gap:20px; align-items:center; flex-wrap:wrap;">
    <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="online" density="-2" style="position: static;"></md-status-dot>online</span>
    <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="away" density="-2" style="position: static;"></md-status-dot>away</span>
    <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="busy" density="-2" style="position: static;"></md-status-dot>busy</span>
    <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="offline" density="-2" style="position: static;"></md-status-dot>offline</span>
    <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="invisible" density="-2" style="position: static;"></md-status-dot>invisible</span>
    <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="neutral" density="-2" style="position: static;"></md-status-dot>neutral</span>
  </div>
</template>

Copy

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

<div style="display:flex; gap:20px; align-items:center; flex-wrap:wrap;">
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="online" density="-2" style="position: static;"></md-status-dot>online</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="away" density="-2" style="position: static;"></md-status-dot>away</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="busy" density="-2" style="position: static;"></md-status-dot>busy</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="offline" density="-2" style="position: static;"></md-status-dot>offline</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="invisible" density="-2" style="position: static;"></md-status-dot>invisible</span>
  <span style="display: inline-flex; align-items: center; gap: 6px; font: 400 12px system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);"><md-status-dot state="neutral" density="-2" style="position: static;"></md-status-dot>neutral</span>
</div>

Density and direction together

The two are independent signals, so they compose without any extra wiring — a global data-density ancestor sets the rung, dir sets the corner. The second dot in each row takes density="-4", tightening past the inherited -2; the third resets to full size with an inline --md-sys-density-scale: 0, which is the only thing that actually escapes the ambient rung:

data-density=-2 in both directions — second dot pushed to -4, third reset with --md-sys-density-scale: 0

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" data-density="-2" style="display:flex;gap:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="Online"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="away" size="large" label="Away" density="-4"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Alan Turing" size="large"></md-avatar><md-status-dot state="busy" size="large" label="Busy" style="--md-sys-density-scale: 0;"></md-status-dot></span>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" data-density="-2" style="display:flex;gap:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="متصل"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="away" size="large" label="غائب" density="-4"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="آلان تورينج" size="large"></md-avatar><md-status-dot state="busy" size="large" label="مشغول" style="--md-sys-density-scale: 0;"></md-status-dot></span>
  </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" data-density="-2" style={{ display: 'flex', gap: '20px', alignItems: 'center' }}>
          <span style={{ position: 'relative', display: 'inline-flex' }}><MdAvatar name="Ada Lovelace" size="large"></MdAvatar><MdStatusDot state="online" size="large" label="Online"></MdStatusDot></span>
          <span style={{ position: 'relative', display: 'inline-flex' }}><MdAvatar name="Grace Hopper" size="large"></MdAvatar><MdStatusDot state="away" size="large" label="Away" density="-4"></MdStatusDot></span>
          <span style={{ position: 'relative', display: 'inline-flex' }}><MdAvatar name="Alan Turing" size="large"></MdAvatar><MdStatusDot state="busy" size="large" label="Busy" style={{ '--md-sys-density-scale': '0' }}></MdStatusDot></span>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>rtl</span>
        <div dir="rtl" data-density="-2" style={{ display: 'flex', gap: '20px', alignItems: 'center' }}>
          <span style={{ position: 'relative', display: 'inline-flex' }}><MdAvatar name="Ada Lovelace" size="large"></MdAvatar><MdStatusDot state="online" size="large" label="متصل"></MdStatusDot></span>
          <span style={{ position: 'relative', display: 'inline-flex' }}><MdAvatar name="Grace Hopper" size="large"></MdAvatar><MdStatusDot state="away" size="large" label="غائب" density="-4"></MdStatusDot></span>
          <span style={{ position: 'relative', display: 'inline-flex' }}><MdAvatar name="آلان تورينج" size="large"></MdAvatar><MdStatusDot state="busy" size="large" label="مشغول" style={{ '--md-sys-density-scale': '0' }}></MdStatusDot></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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" data-density="-2" style="display:flex;gap:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="Online"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="away" size="large" label="Away" density="-4"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Alan Turing" size="large"></md-avatar><md-status-dot state="busy" size="large" label="Busy" style="--md-sys-density-scale: 0;"></md-status-dot></span>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" data-density="-2" style="display:flex;gap:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="متصل"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="away" size="large" label="غائب" density="-4"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="آلان تورينج" size="large"></md-avatar><md-status-dot state="busy" size="large" label="مشغول" style="--md-sys-density-scale: 0;"></md-status-dot></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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
    <div dir="ltr" data-density="-2" style="display:flex;gap:20px;align-items:center;">
      <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="Online"></md-status-dot></span>
      <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="away" size="large" label="Away" density="-4"></md-status-dot></span>
      <span style="position: relative; display: inline-flex;"><md-avatar name="Alan Turing" size="large"></md-avatar><md-status-dot state="busy" size="large" label="Busy" style="--md-sys-density-scale: 0;"></md-status-dot></span>
    </div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
    <div dir="rtl" data-density="-2" style="display:flex;gap:20px;align-items:center;">
      <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="متصل"></md-status-dot></span>
      <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="away" size="large" label="غائب" density="-4"></md-status-dot></span>
      <span style="position: relative; display: inline-flex;"><md-avatar name="آلان تورينج" size="large"></md-avatar><md-status-dot state="busy" size="large" label="مشغول" style="--md-sys-density-scale: 0;"></md-status-dot></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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" data-density="-2" style="display:flex;gap:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="Online"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="away" size="large" label="Away" density="-4"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Alan Turing" size="large"></md-avatar><md-status-dot state="busy" size="large" label="Busy" style="--md-sys-density-scale: 0;"></md-status-dot></span>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" data-density="-2" style="display:flex;gap:20px;align-items:center;">
    <span style="position: relative; display: inline-flex;"><md-avatar name="Ada Lovelace" size="large"></md-avatar><md-status-dot state="online" size="large" label="متصل"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="Grace Hopper" size="large"></md-avatar><md-status-dot state="away" size="large" label="غائب" density="-4"></md-status-dot></span>
    <span style="position: relative; display: inline-flex;"><md-avatar name="آلان تورينج" size="large"></md-avatar><md-status-dot state="busy" size="large" label="مشغول" style="--md-sys-density-scale: 0;"></md-status-dot></span>
  </div>
</div>

density="0" does not undo an inherited rung

The rungs are declared as :host([density='-1']) … :host([density='-4']), and 0 — the prop’s default — has no rule of its own. Inside a data-density="-2" ancestor, density="0" therefore changes nothing: the dot keeps inheriting -2. density tightens past the ambient rung, it does not reset to base. To get a full-size dot inside a dense region, move it out of the dense subtree or set --md-sys-density-scale: 0 on a wrapper.

Density — density="-1…-4" locally overrides the inherited data-density rung, shrinking the dot and its outline together. See Density.

i18n — label is user-facing text. Translate it, along with the state names (“Away”, “Busy”) in your dictionary, and let dir come from the document rather than hard-coding a corner.

Theming

Custom property	Purpose	Default
--md-status-dot-size	Diameter (overrides the size preset)	12px (8px small, 16px large)
--md-status-dot-color	Fill	Per state — --md-sys-color-on-surface-variant for neutral
--md-status-dot-pulse-color	Halo colour used by the live pulse	Per state — transparent for offline, invisible, neutral
--md-status-dot-pulse-duration	Pulse period	1.6s
--md-status-dot-outline-color	Ring separating the dot from its host	--md-sys-color-surface
--md-status-dot-outline-width	Ring width	2px (1.5px small, 3px large)
--md-status-dot-inset-end	Inline-end anchor offset	0 (-3px at large)
--md-status-dot-inset-block-end	Block-end anchor offset	0 (-3px at large)

Default, resized, and fully themed instances

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:32px;align-items:center;">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot
      state="online"
      label="Online"
      style="--md-status-dot-size: 14px; --md-status-dot-outline-width: 3px; --md-status-dot-inset-end: 0px; --md-status-dot-inset-block-end: 0px;"
      ></md-status-dot>
    </span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Alan Turing" size="large"></md-avatar>
      <md-status-dot
        state="neutral"
        label="On brand"
        live
        style="--md-status-dot-color: var(--md-sys-color-primary); --md-status-dot-pulse-color: rgba(103, 80, 164, 0.55); --md-status-dot-outline-color: var(--md-sys-color-surface-container-high);"
        ></md-status-dot>
      </span>
    </div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', gap: '32px', alignItems: 'center' }}>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Ada Lovelace" size="large"></MdAvatar>
          <MdStatusDot state="online" label="Online"></MdStatusDot>
        </span>
        <span style={{ position: 'relative', display: 'inline-flex' }}>
          <MdAvatar name="Grace Hopper" size="large"></MdAvatar>
          <MdStatusDot
            state="online"
            label="Online"
            style={{ '--md-status-dot-size': '14px', '--md-status-dot-outline-width': '3px', '--md-status-dot-inset-end': '0px', '--md-status-dot-inset-block-end': '0px' }}
            ></MdStatusDot>
          </span>
          <span style={{ position: 'relative', display: 'inline-flex' }}>
            <MdAvatar name="Alan Turing" size="large"></MdAvatar>
            <MdStatusDot
              state="neutral"
              label="On brand"
              live
              style={{ '--md-status-dot-color': 'var(--md-sys-color-primary)', '--md-status-dot-pulse-color': 'rgba(103, 80, 164, 0.55)', '--md-status-dot-outline-color': 'var(--md-sys-color-surface-container-high)' }}
              ></MdStatusDot>
            </span>
          </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:32px;align-items:center;">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot
      state="online"
      label="Online"
      style="--md-status-dot-size: 14px; --md-status-dot-outline-width: 3px; --md-status-dot-inset-end: 0px; --md-status-dot-inset-block-end: 0px;"
      ></md-status-dot>
    </span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Alan Turing" size="large"></md-avatar>
      <md-status-dot
        state="neutral"
        label="On brand"
        live
        style="--md-status-dot-color: var(--md-sys-color-primary); --md-status-dot-pulse-color: rgba(103, 80, 164, 0.55); --md-status-dot-outline-color: var(--md-sys-color-surface-container-high);"
        ></md-status-dot>
      </span>
    </div>

Copy

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

<template>
  <div style="display:flex;gap:32px;align-items:center;">
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Ada Lovelace" size="large"></md-avatar>
      <md-status-dot state="online" label="Online"></md-status-dot>
    </span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Grace Hopper" size="large"></md-avatar>
      <md-status-dot
        state="online"
        label="Online"
        style="--md-status-dot-size: 14px; --md-status-dot-outline-width: 3px; --md-status-dot-inset-end: 0px; --md-status-dot-inset-block-end: 0px;"
        ></md-status-dot>
      </span>
      <span style="position: relative; display: inline-flex;">
        <md-avatar name="Alan Turing" size="large"></md-avatar>
        <md-status-dot
          state="neutral"
          label="On brand"
          live
          style="--md-status-dot-color: var(--md-sys-color-primary); --md-status-dot-pulse-color: rgba(103, 80, 164, 0.55); --md-status-dot-outline-color: var(--md-sys-color-surface-container-high);"
          ></md-status-dot>
        </span>
      </div>
</template>

Copy

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

<div style="display:flex;gap:32px;align-items:center;">
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Ada Lovelace" size="large"></md-avatar>
    <md-status-dot state="online" label="Online"></md-status-dot>
  </span>
  <span style="position: relative; display: inline-flex;">
    <md-avatar name="Grace Hopper" size="large"></md-avatar>
    <md-status-dot
      state="online"
      label="Online"
      style="--md-status-dot-size: 14px; --md-status-dot-outline-width: 3px; --md-status-dot-inset-end: 0px; --md-status-dot-inset-block-end: 0px;"
      ></md-status-dot>
    </span>
    <span style="position: relative; display: inline-flex;">
      <md-avatar name="Alan Turing" size="large"></md-avatar>
      <md-status-dot
        state="neutral"
        label="On brand"
        live
        style="--md-status-dot-color: var(--md-sys-color-primary); --md-status-dot-pulse-color: rgba(103, 80, 164, 0.55); --md-status-dot-outline-color: var(--md-sys-color-surface-container-high);"
        ></md-status-dot>
      </span>
    </div>

Set them per instance, or once for every dot in a region:

md-status-dot {
  --md-status-dot-size: 14px;
  --md-status-dot-outline-width: 3px;
  --md-status-dot-outline-color: var(--md-sys-color-surface-container-high);
}

No CSS parts or slots to target

The dot is a single leaf element, so the custom properties above are the whole styling surface — there is nothing inside the shadow root to reach with ::part(), and nothing to slot content into.

If you override --md-status-dot-color, check the contrast yourself — the six built-in state colours are the verified set, and the outline is what keeps the dot legible on whatever it sits on, so check any override in both the light and the dark theme.

Related

md-badge · md-avatar · md-chip · md-list · md-progress-indicator

AI / LLM Context

For AI Agents — md-status-dot

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-status-dot 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-status-dot readme.md

Copy readme

# md-status-dot

<!-- llm:meta
tag: md-status-dot
category: status
status: custom
m3-guidelines: none — not an M3 component
m3-derived-from: https://m3.material.io/components/badges/guidelines
form-associated: false
depends-on: none
used-by: none
-->

**A presence or health indicator.** A small coloured dot with six states and an
optional pulse, absolutely positioned onto an avatar, a row, or any tile.

> ⚠️ **Not a Material Design 3 component.** M3 has badges, not status dots. The
> Do/Don't below are house rules derived from M3's badge guidance plus general
> status-indicator practice.

> 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

- **Presence**: online / away / busy / offline / invisible on an avatar.
- A compact **health or state** marker in a dense list or table row.
- A "live now" / "recording" pip, with `live` for the pulse.

## When NOT to use

| Situation | Use instead |
|---|---|
| A count of unread items | `md-badge` |
| An interactive filter or tag | `md-chip` |
| A status with a text label the user reads | `md-chip` |
| Progress or loading | `md-progress-indicator` / `md-loading-indicator` |
| A large, prominent state banner | `md-card` with semantic colour |
| Something clickable | `md-button` / `md-icon-button` — the dot is `pointer-events: none` |

## Decision cues

| Need | Setting |
|---|---|
| Presence semantics | `state="online\|away\|busy\|offline\|invisible\|neutral"` |
| No semantic meaning (the parent already says it) | `state="neutral"` (default) |
| Attention-drawing animation | `live` |
| Size in a dense table | `size="small"` |
| Default | `size="medium"` |
| Prominent, standalone | `size="large"` |
| Decorative — the parent carries the words | leave `label` empty (default) |
| Standalone, announced statically | `label="Online"` |
| Standalone, changes announced as they happen | `label="Online"` **and** `live` |

## API contract

The authoritative, generated property table is at the bottom of this file. This
is the short form an implementer needs.

```html
<span style="position: relative; display: inline-flex;">
  <md-avatar name="Ada Lovelace"></md-avatar>
  <md-status-dot
    state="online|away|busy|offline|invisible|neutral"   <!-- default: neutral -->
    size="small|medium|large"                            <!-- default: medium -->
    live                                                 <!-- default: false -->
    label="Online"                                       <!-- default: "" (decorative) -->
    density="-1|-2|-3|-4"                                <!-- default: 0 (uncompacted) -->
  ></md-status-dot>
</span>
```

**Events** — none.

**Methods** — none.

**Slots** — none; the component renders no children at all (the host *is* the
dot).

**Parts** — none. Style it through the custom properties in Theming.

### Behavioral contract worth knowing

- **It positions itself absolutely** at the bottom-inline-end corner, so the
  parent needs `position: relative` (or any other containing block). Nudge it
  with `--md-status-dot-inset-end` / `--md-status-dot-inset-block-end`.
- It is `pointer-events: none` and never focusable — it cannot be clicked and
  will not steal a hit from the avatar underneath.
- **The ARIA role depends on `label` and `live`:**
  - `label` empty (default) → `role="presentation"` + `aria-hidden="true"`.
    The dot is decorative; the parent must carry the words (e.g. an
    `md-avatar label="Ada Lovelace, online"`).
  - `label` set, `live` off → `role="img"` + `aria-label` — a static labelled
    status image.
  - `label` set, `live` on → `role="status"`, i.e. a polite **live region**, so
    presence changes *are* announced as they happen.
- `state="invisible"` is a *semantic* presence state (the user appears
  offline), drawn as a surface fill with an inset ring — it is **not**
  `display: none`. To hide the dot, omit the element.
- `live` + `invisible` is allowed but the pulse covers the inner ring, so the
  combination reads poorly; pick one.
- The pulse is already gated behind `prefers-reduced-motion: no-preference` —
  users with reduced motion see a static dot with no work from you.
- Fill and outline colours animate over ~200 ms when `state` changes, so
  websocket-driven presence updates cross-fade instead of snapping.

---

## Do / Don't

House rules — derived from M3 badge guidance; no M3 status-dot page exists.

| ✅ Do | ❌ Don't |
|---|---|
| Make the state available as words — the dot's `label`, or the parent's | Don't convey the state with colour alone |
| Keep the state→colour mapping consistent across the app | Don't reuse "busy" red for an error elsewhere |
| Attach it to something it describes (avatar, row) | Don't float a dot with no clear subject |
| Use `live` sparingly for genuinely changing state | Don't pulse every dot — motion loses meaning |
| Use `small` in dense tables | Don't shrink it until it's invisible |
| Let the logical insets mirror themselves in RTL | Don't hardcode a physical corner offset |
| Leave `label` empty when the parent already announces the status | Don't double-announce "online" from both the avatar and the dot |
| Use `md-badge` when it's a count | Don't overload the dot with meaning |

---

## Patterns

```html
<!-- Decorative: the avatar carries the words, the dot is silent -->
<span style="position: relative; display: inline-flex;">
  <md-avatar name="Ada Lovelace" size="large" label="Ada Lovelace, online">
  </md-avatar>
  <md-status-dot state="online"></md-status-dot>
</span>

<!-- Standalone: the dot itself is labelled -->
<md-status-dot state="busy" label="Busy"></md-status-dot>

<!-- Live pulse for an active job — role="status" announces the changes -->
<md-status-dot state="online" live label="Running"></md-status-dot>

<!-- Dense table cell -->
<md-table-cell>
  <span style="position: relative; display: inline-flex; padding-inline-end: 12px;">
    <md-status-dot size="small" state="busy" label="Busy"></md-status-dot>
  </span>
  Deploying
</md-table-cell>
```

```html
<!-- Websocket presence updates: set state and label together -->
<span id="cell" style="position: relative; display: inline-flex;">
  <md-avatar name="Ada Lovelace"></md-avatar>
  <md-status-dot id="dot" state="online" live label="Online"></md-status-dot>
</span>

<script type="module">
  const dot = document.getElementById('dot');
  const words = { online: 'Online', away: 'Away', busy: 'Busy', offline: 'Offline' };

  socket.addEventListener('message', (e) => {
    const next = JSON.parse(e.data).presence;   // 'online' | 'away' | …
    dot.state = next;
    dot.label = words[next];                    // label + live => announced
  });
</script>
```

```css
/* Per-instance brand colour, still using the state pipeline */
md-status-dot.brand-online {
  --md-status-dot-color: var(--md-sys-color-tertiary);
  --md-status-dot-pulse-color: color-mix(in srgb, var(--md-sys-color-tertiary) 55%, transparent);
}
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| A dot with no `label` next to an avatar whose label omits the status | Put the status in one of the two labels | Otherwise the state exists only as colour. |
| `live` with an empty `label` expecting announcements | Set `label` too | Without a label the host is `aria-hidden`; only `label` + `live` makes it a live region. |
| Building your own `aria-live` region beside a `label` + `live` dot | Let the dot announce | You get the state twice. |
| `state="invisible"` to hide the dot | Remove the element | It's a presence semantic, not `display: none`. |
| A parent without a containing block | Give it `position: relative` | The dot is `position: absolute`. |
| Wiring a click handler onto the dot | Handle the click on the parent | It is `pointer-events: none`. |
| Gating `live` yourself on `prefers-reduced-motion` | Leave it | The pulse is already gated. |
| Using it for an unread count | `md-badge` | Different purpose. |
| A pulsing dot on every row | Reserve `live` for real activity | Motion stops meaning anything. |
| Custom colours without contrast checks | Keep the state palette | The defaults are the verified set. |

## Accessibility, RTL, density, i18n

**Accessibility**
- The dot always has a role: `presentation` (decorative, the default),
  `img` (labelled + static), or `status` (labelled + `live`). Choose by whether
  something else already speaks the status.
- With `label` set and `live` on you get a polite live region for free — do not
  add a second one.
- State is conveyed by colour, and under forced-colors every state collapses to
  one system colour, so the words matter: WCAG 1.4.1 is only satisfied by the
  `label` or by the surrounding text.
- The pulse honours `prefers-reduced-motion` automatically.
- The dot is not focusable and takes no pointer events, so it never appears in
  the tab order.

**RTL** — the dot anchors with logical insets
(`inset-inline-end` / `inset-block-end`) and mirrors automatically. If you
override the insets, keep using the logical custom properties rather than
physical `left` / `right`.

**Density** — `density="-1…-4"` locally overrides the inherited `data-density`
rung, shrinking the diameter and the separating outline. `size="small"` at a
deep rung reaches the 4 px floor and becomes hard to see. Rung `0` is the
uncompacted default and is inert — it does **not** opt a dot out of an
inherited rung; for that, set `style="--md-sys-density-scale: 0"`.

**i18n** — translate `label`. State names ("Away", "Busy") are user-facing text
and belong in your dictionary; the `state` attribute values themselves are API
keys and never translate.

## Related components

`md-badge` · `md-avatar` · `md-chip` · `md-list-item` · `md-table-cell` ·
`md-progress-indicator`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-status-dot-size` | Diameter (overrides the `size` preset) | `12px` medium · `8px` small · `16px` large, density-scaled |
| `--md-status-dot-color` | Fill | Per state — `#2DC653` online, `#F4B400` away, `#DB4437` busy, `--md-sys-color-outline` offline, `--md-sys-color-surface` invisible, `--md-sys-color-on-surface-variant` neutral |
| `--md-status-dot-pulse-color` | Halo colour used by `live` | The state hue at 55% alpha (`transparent` for offline / invisible / neutral) |
| `--md-status-dot-pulse-duration` | Pulse period | `1.6s` |
| `--md-status-dot-outline-color` | Ring separating the dot from the tile | `--md-sys-color-surface` |
| `--md-status-dot-outline-width` | Ring width | `2px` medium · `1.5px` small · `3px` large, density-scaled |
| `--md-status-dot-inset-end` | Inline-end anchor offset | `0px` (`-3px` at `size="large"`) |
| `--md-status-dot-inset-block-end` | Block-end anchor offset | `0px` (`-3px` at `size="large"`) |

**CSS parts** — none; the host is the whole component.

```css
md-status-dot.tight {
  --md-status-dot-inset-end: -4px;
  --md-status-dot-inset-block-end: -4px;
}
```

<!-- Auto Generated Below -->


## Overview

`md-status-dot` — a small absolutely-positioned indicator that pairs
with an avatar (or any other tile) to surface presence / state.

Designed to drop straight into a `position: relative` parent:

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

Anchors at the bottom-inline-end corner via logical-property insets, so
the pip auto-flips in RTL with no extra CSS. A 2 px outline in the
surface color keeps the dot visually detached from the avatar tile
regardless of the avatar's palette.

**Accessibility.** The dot is **decorative by default** — when used to
decorate an avatar, the avatar's own `label` should already encode the
status (`label="Ada Lovelace, online"`). Setting an explicit `label`
exposes the dot to assistive tech:
- **static** (`live` off) → `role="img"` + `aria-label` — a labelled image
  conveying the current state, announced when focused/encountered.
- **live** (`live` on) → `role="status"` (an `aria-live="polite"` region) so
  presence *changes* (online → busy) are announced as they happen.

**WCAG 1.4.1 (use of colour).** State is conveyed by colour alone, and in
Windows High-Contrast every state collapses to a single system colour. Never
rely on the dot's colour as the *only* signal of state — pair it with a
`label` (or text on the parent) so the status is also available as words.

**Live indicator.** When `live` is `true`, the dot pulses outward in its
own colour (online pulses green, busy pulses red, etc.). The animation
is gated behind `prefers-reduced-motion: no-preference`, so users who
have reduced-motion enabled at the OS level see a static dot.

## Properties

| Property  | Attribute | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Type                                                                    | Default     |
| --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------- |
| `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`         |
| `label`   | `label`   | Optional accessible label.  - When **empty** (default), the dot is exposed to AT as decorative   (`role="presentation"` + `aria-hidden="true"`) so the parent   element (typically an `md-avatar` or a list-item) can carry the   spoken status without doubling. - When **set** and `live` is **off**, the dot becomes `role="img"` with   the value as its `aria-label` — a static, labelled status image. - When **set** and `live` is **on**, the dot becomes a `role="status"`   live region so presence *changes* are announced as they occur. Use this   for standalone dots that aren't paired with another labelled element. | `string`                                                                | `''`        |
| `inline`  | `inline`  | Lay the dot out in normal flow (`inline-block`, vertically centred on the text, halo off) instead of as an absolutely-positioned corner badge. Use it wherever the dot sits BESIDE something — a legend swatch, a "Market open" line, a status label in a table cell. Without it such a dot escapes the line box and lands low and to the trailing side, overlapping its own label. Bring the halo back with `--md-status-dot-outline-width`.                                                                                                                                                                                            | `boolean`                                                               | `false`     |
| `live`    | `live`    | Pulse the dot outward in its own colour. Useful for "live now", "in a call", "recording" affordances. Respects `prefers-reduced-motion: reduce` automatically.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `boolean`                                                               | `false`     |
| `size`    | `size`    | Diameter preset: - `small`  — 8 px (pairs with `md-avatar size="small"`) - `medium` — 12 px (pairs with `md-avatar size="medium"` — default) - `large`  — 16 px (pairs with `md-avatar size="large"`)  Custom diameters are exposed via the `--md-status-dot-size` CSS custom property on the host.                                                                                                                                                                                                                                                                                                                                   | `"large" \| "medium" \| "small"`                                        | `'medium'`  |
| `state`   | `state`   | Presence state. Drives the dot's fill color and its corresponding pulse-halo color (when `live` is `true`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `"away" \| "busy" \| "invisible" \| "neutral" \| "offline" \| "online"` | `'neutral'` |


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

*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.