FAB

The single most prominent action on a screen. Floats above the UI in six colour mappings and three sizes, and morphs between an icon-only circle and an extended pill that carries a label.

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-fab icon="add" aria-label="Create"></md-fab>
<md-fab icon="edit" label="Compose"></md-fab>
<md-fab variant="primary" size="large" icon="add" aria-label="Create"></md-fab>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdFab icon="add" aria-label="Create"></MdFab>
      <MdFab icon="edit" label="Compose"></MdFab>
      <MdFab variant="primary" size="large" icon="add" aria-label="Create"></MdFab>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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-fab icon="add" aria-label="Create"></md-fab>
<md-fab icon="edit" label="Compose"></md-fab>
<md-fab variant="primary" size="large" icon="add" aria-label="Create"></md-fab>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <md-fab icon="add" aria-label="Create"></md-fab>
  <md-fab icon="edit" label="Compose"></md-fab>
  <md-fab variant="primary" size="large" icon="add" aria-label="Create"></md-fab>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<md-fab icon="add" aria-label="Create"></md-fab>
<md-fab icon="edit" label="Compose"></md-fab>
<md-fab variant="primary" size="large" icon="add" aria-label="Create"></md-fab>

Install

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

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


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


<md-fab></md-fab>

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

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


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

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

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


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

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

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

<template>
  <MdFab></MdFab>
</template>


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

<template>
  <md-fab></md-fab>
</template>

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

<md-fab></md-fab>


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

<md-fab></md-fab>

When to use

One primary, constructive action per screen: compose, add, create, edit.
The action is the reason the screen exists — not one option among several.
Inside a md-navigation-rail, where it collapses to icon-only as the rail collapses.

When not to use

Situation	Use instead
A second prominent action on the same screen	`md-button variant="filled"`
Minor, overflow, unclear or destructive actions	`md-button` / `md-menu`
An action scoped to a card or other container	A button inside it
2–6 related creation actions behind one trigger	`md-fab-menu`
Screens where imagery already represents the primary action	Nothing — M3 says a FAB isn’t always needed

Variants

primary, secondary, tertiary and their -container forms. The -container variants are the softer, standard look; the bare roles are higher-contrast.

surface is M3’s own default FAB — a neutral container with a primary-role icon, for when the FAB should not compete with the content behind it. This component defaults to primary-container instead, so pass variant="surface" explicitly when you want the spec’s baseline.

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-fab variant="surface" icon="add" aria-label="Surface"></md-fab>
<md-fab variant="primary-container" icon="add" aria-label="Add"></md-fab>
<md-fab variant="secondary-container" icon="add" aria-label="Add"></md-fab>
<md-fab variant="tertiary-container" icon="add" aria-label="Add"></md-fab>
<md-fab variant="primary" icon="add" aria-label="Add"></md-fab>
<md-fab variant="secondary" icon="add" aria-label="Add"></md-fab>
<md-fab variant="tertiary" icon="add" aria-label="Add"></md-fab>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdFab variant="surface" icon="add" aria-label="Surface"></MdFab>
      <MdFab variant="primary-container" icon="add" aria-label="Add"></MdFab>
      <MdFab variant="secondary-container" icon="add" aria-label="Add"></MdFab>
      <MdFab variant="tertiary-container" icon="add" aria-label="Add"></MdFab>
      <MdFab variant="primary" icon="add" aria-label="Add"></MdFab>
      <MdFab variant="secondary" icon="add" aria-label="Add"></MdFab>
      <MdFab variant="tertiary" icon="add" aria-label="Add"></MdFab>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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-fab variant="surface" icon="add" aria-label="Surface"></md-fab>
<md-fab variant="primary-container" icon="add" aria-label="Add"></md-fab>
<md-fab variant="secondary-container" icon="add" aria-label="Add"></md-fab>
<md-fab variant="tertiary-container" icon="add" aria-label="Add"></md-fab>
<md-fab variant="primary" icon="add" aria-label="Add"></md-fab>
<md-fab variant="secondary" icon="add" aria-label="Add"></md-fab>
<md-fab variant="tertiary" icon="add" aria-label="Add"></md-fab>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <md-fab variant="surface" icon="add" aria-label="Surface"></md-fab>
  <md-fab variant="primary-container" icon="add" aria-label="Add"></md-fab>
  <md-fab variant="secondary-container" icon="add" aria-label="Add"></md-fab>
  <md-fab variant="tertiary-container" icon="add" aria-label="Add"></md-fab>
  <md-fab variant="primary" icon="add" aria-label="Add"></md-fab>
  <md-fab variant="secondary" icon="add" aria-label="Add"></md-fab>
  <md-fab variant="tertiary" icon="add" aria-label="Add"></md-fab>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<md-fab variant="surface" icon="add" aria-label="Surface"></md-fab>
<md-fab variant="primary-container" icon="add" aria-label="Add"></md-fab>
<md-fab variant="secondary-container" icon="add" aria-label="Add"></md-fab>
<md-fab variant="tertiary-container" icon="add" aria-label="Add"></md-fab>
<md-fab variant="primary" icon="add" aria-label="Add"></md-fab>
<md-fab variant="secondary" icon="add" aria-label="Add"></md-fab>
<md-fab variant="tertiary" icon="add" aria-label="Add"></md-fab>

Sizes

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-fab size="standard" icon="add" aria-label="Add"></md-fab>
<md-fab size="medium" icon="add" aria-label="Add"></md-fab>
<md-fab size="large" icon="add" aria-label="Add"></md-fab>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdFab size="standard" icon="add" aria-label="Add"></MdFab>
      <MdFab size="medium" icon="add" aria-label="Add"></MdFab>
      <MdFab size="large" icon="add" aria-label="Add"></MdFab>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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-fab size="standard" icon="add" aria-label="Add"></md-fab>
<md-fab size="medium" icon="add" aria-label="Add"></md-fab>
<md-fab size="large" icon="add" aria-label="Add"></md-fab>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <md-fab size="standard" icon="add" aria-label="Add"></md-fab>
  <md-fab size="medium" icon="add" aria-label="Add"></md-fab>
  <md-fab size="large" icon="add" aria-label="Add"></md-fab>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<md-fab size="standard" icon="add" aria-label="Add"></md-fab>
<md-fab size="medium" icon="add" aria-label="Add"></md-fab>
<md-fab size="large" icon="add" aria-label="Add"></md-fab>

States

lowered drops the resting elevation for FABs that sit on an already-elevated surface. disabled and soft-disabled behave as they do on md-button — the soft one stays focusable.

default

lowered

disabled

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

<!-- 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:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">default</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="Create"></md-fab>
    <md-fab variant="secondary" icon="edit" aria-label="Edit"></md-fab>
    <md-fab variant="tertiary" icon="share" aria-label="Share"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">lowered</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab lowered icon="add" aria-label="Create, lowered"></md-fab>
    <md-fab lowered variant="secondary" icon="edit" aria-label="Edit, lowered"></md-fab>
    <md-fab lowered variant="tertiary" icon="share" aria-label="Share, lowered"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">disabled</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab disabled icon="add" aria-label="Create, disabled"></md-fab>
    <md-fab soft-disabled icon="edit" aria-label="Edit, soft-disabled"></md-fab>
  </div>
</div>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>default</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdFab icon="add" aria-label="Create"></MdFab>
          <MdFab variant="secondary" icon="edit" aria-label="Edit"></MdFab>
          <MdFab variant="tertiary" icon="share" aria-label="Share"></MdFab>
        </div>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>lowered</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdFab lowered icon="add" aria-label="Create, lowered"></MdFab>
          <MdFab lowered variant="secondary" icon="edit" aria-label="Edit, lowered"></MdFab>
          <MdFab lowered variant="tertiary" icon="share" aria-label="Share, lowered"></MdFab>
        </div>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>disabled</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdFab disabled icon="add" aria-label="Create, disabled"></MdFab>
          <MdFab softDisabled icon="edit" aria-label="Edit, soft-disabled"></MdFab>
        </div>
      </div>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">default</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="Create"></md-fab>
    <md-fab variant="secondary" icon="edit" aria-label="Edit"></md-fab>
    <md-fab variant="tertiary" icon="share" aria-label="Share"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">lowered</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab lowered icon="add" aria-label="Create, lowered"></md-fab>
    <md-fab lowered variant="secondary" icon="edit" aria-label="Edit, lowered"></md-fab>
    <md-fab lowered variant="tertiary" icon="share" aria-label="Share, lowered"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">disabled</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab disabled icon="add" aria-label="Create, disabled"></md-fab>
    <md-fab soft-disabled icon="edit" aria-label="Edit, soft-disabled"></md-fab>
  </div>
</div>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">default</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <md-fab icon="add" aria-label="Create"></md-fab>
      <md-fab variant="secondary" icon="edit" aria-label="Edit"></md-fab>
      <md-fab variant="tertiary" icon="share" aria-label="Share"></md-fab>
    </div>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">lowered</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <md-fab lowered icon="add" aria-label="Create, lowered"></md-fab>
      <md-fab lowered variant="secondary" icon="edit" aria-label="Edit, lowered"></md-fab>
      <md-fab lowered variant="tertiary" icon="share" aria-label="Share, lowered"></md-fab>
    </div>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">disabled</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <md-fab disabled icon="add" aria-label="Create, disabled"></md-fab>
      <md-fab soft-disabled icon="edit" aria-label="Edit, soft-disabled"></md-fab>
    </div>
  </div>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">default</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="Create"></md-fab>
    <md-fab variant="secondary" icon="edit" aria-label="Edit"></md-fab>
    <md-fab variant="tertiary" icon="share" aria-label="Share"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">lowered</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab lowered icon="add" aria-label="Create, lowered"></md-fab>
    <md-fab lowered variant="secondary" icon="edit" aria-label="Edit, lowered"></md-fab>
    <md-fab lowered variant="tertiary" icon="share" aria-label="Share, lowered"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">disabled</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab disabled icon="add" aria-label="Create, disabled"></md-fab>
    <md-fab soft-disabled icon="edit" aria-label="Edit, soft-disabled"></md-fab>
  </div>
</div>

Every variant at every size

primary

secondary

tertiary

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

<!-- 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:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">primary</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab size="standard" icon="add" aria-label="Create standard"></md-fab>
    <md-fab size="medium" icon="add" aria-label="Create medium"></md-fab>
    <md-fab size="large" icon="add" aria-label="Create large"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">secondary</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab variant="secondary" size="standard" icon="edit" aria-label="Edit standard"></md-fab>
    <md-fab variant="secondary" size="medium" icon="edit" aria-label="Edit medium"></md-fab>
    <md-fab variant="secondary" size="large" icon="edit" aria-label="Edit large"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">tertiary</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab variant="tertiary" size="standard" icon="share" aria-label="Share standard"></md-fab>
    <md-fab variant="tertiary" size="medium" icon="share" aria-label="Share medium"></md-fab>
    <md-fab variant="tertiary" size="large" icon="share" aria-label="Share large"></md-fab>
  </div>
</div>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>primary</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdFab size="standard" icon="add" aria-label="Create standard"></MdFab>
          <MdFab size="medium" icon="add" aria-label="Create medium"></MdFab>
          <MdFab size="large" icon="add" aria-label="Create large"></MdFab>
        </div>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>secondary</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdFab variant="secondary" size="standard" icon="edit" aria-label="Edit standard"></MdFab>
          <MdFab variant="secondary" size="medium" icon="edit" aria-label="Edit medium"></MdFab>
          <MdFab variant="secondary" size="large" icon="edit" aria-label="Edit large"></MdFab>
        </div>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>tertiary</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdFab variant="tertiary" size="standard" icon="share" aria-label="Share standard"></MdFab>
          <MdFab variant="tertiary" size="medium" icon="share" aria-label="Share medium"></MdFab>
          <MdFab variant="tertiary" size="large" icon="share" aria-label="Share large"></MdFab>
        </div>
      </div>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">primary</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab size="standard" icon="add" aria-label="Create standard"></md-fab>
    <md-fab size="medium" icon="add" aria-label="Create medium"></md-fab>
    <md-fab size="large" icon="add" aria-label="Create large"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">secondary</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab variant="secondary" size="standard" icon="edit" aria-label="Edit standard"></md-fab>
    <md-fab variant="secondary" size="medium" icon="edit" aria-label="Edit medium"></md-fab>
    <md-fab variant="secondary" size="large" icon="edit" aria-label="Edit large"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">tertiary</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab variant="tertiary" size="standard" icon="share" aria-label="Share standard"></md-fab>
    <md-fab variant="tertiary" size="medium" icon="share" aria-label="Share medium"></md-fab>
    <md-fab variant="tertiary" size="large" icon="share" aria-label="Share large"></md-fab>
  </div>
</div>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">primary</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <md-fab size="standard" icon="add" aria-label="Create standard"></md-fab>
      <md-fab size="medium" icon="add" aria-label="Create medium"></md-fab>
      <md-fab size="large" icon="add" aria-label="Create large"></md-fab>
    </div>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">secondary</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <md-fab variant="secondary" size="standard" icon="edit" aria-label="Edit standard"></md-fab>
      <md-fab variant="secondary" size="medium" icon="edit" aria-label="Edit medium"></md-fab>
      <md-fab variant="secondary" size="large" icon="edit" aria-label="Edit large"></md-fab>
    </div>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">tertiary</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <md-fab variant="tertiary" size="standard" icon="share" aria-label="Share standard"></md-fab>
      <md-fab variant="tertiary" size="medium" icon="share" aria-label="Share medium"></md-fab>
      <md-fab variant="tertiary" size="large" icon="share" aria-label="Share large"></md-fab>
    </div>
  </div>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">primary</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab size="standard" icon="add" aria-label="Create standard"></md-fab>
    <md-fab size="medium" icon="add" aria-label="Create medium"></md-fab>
    <md-fab size="large" icon="add" aria-label="Create large"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">secondary</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab variant="secondary" size="standard" icon="edit" aria-label="Edit standard"></md-fab>
    <md-fab variant="secondary" size="medium" icon="edit" aria-label="Edit medium"></md-fab>
    <md-fab variant="secondary" size="large" icon="edit" aria-label="Edit large"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">tertiary</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab variant="tertiary" size="standard" icon="share" aria-label="Share standard"></md-fab>
    <md-fab variant="tertiary" size="medium" icon="share" aria-label="Share medium"></md-fab>
    <md-fab variant="tertiary" size="large" icon="share" aria-label="Share large"></md-fab>
  </div>
</div>

Extended

Setting a label makes the FAB extended automatically.

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-fab icon="edit" label="Compose"></md-fab>
<md-fab label="Start a chat"></md-fab>
<md-fab lowered icon="add" label="Add item"></md-fab>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdFab icon="edit" label="Compose"></MdFab>
      <MdFab label="Start a chat"></MdFab>
      <MdFab lowered icon="add" label="Add item"></MdFab>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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-fab icon="edit" label="Compose"></md-fab>
<md-fab label="Start a chat"></md-fab>
<md-fab lowered icon="add" label="Add item"></md-fab>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <md-fab icon="edit" label="Compose"></md-fab>
  <md-fab label="Start a chat"></md-fab>
  <md-fab lowered icon="add" label="Add item"></md-fab>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<md-fab icon="edit" label="Compose"></md-fab>
<md-fab label="Start a chat"></md-fab>
<md-fab lowered icon="add" label="Add item"></md-fab>

unset + label

extended="false"

no label

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

<!-- 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;">unset + label</span>
  <div><md-fab icon="add" label="Compose"></md-fab></div>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">extended="false"</span>
  <div><md-fab icon="add" label="Compose" extended="false"></md-fab></div>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">no label</span>
  <div><md-fab icon="add" aria-label="Compose"></md-fab></div>
</div>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } 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' }}>unset + label</span>
        <div><MdFab icon="add" label="Compose"></MdFab></div>
        <span style={{ inlineSize: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>extended="false"</span>
        <div><MdFab icon="add" label="Compose" extended="false"></MdFab></div>
        <span style={{ inlineSize: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>no label</span>
        <div><MdFab icon="add" aria-label="Compose"></MdFab></div>
      </div>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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;">unset + label</span>
  <div><md-fab icon="add" label="Compose"></md-fab></div>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">extended="false"</span>
  <div><md-fab icon="add" label="Compose" extended="false"></md-fab></div>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">no label</span>
  <div><md-fab icon="add" aria-label="Compose"></md-fab></div>
</div>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
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;">unset + label</span>
    <div><md-fab icon="add" label="Compose"></md-fab></div>
    <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">extended="false"</span>
    <div><md-fab icon="add" label="Compose" extended="false"></md-fab></div>
    <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">no label</span>
    <div><md-fab icon="add" aria-label="Compose"></md-fab></div>
  </div>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

  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;">unset + label</span>
  <div><md-fab icon="add" label="Compose"></md-fab></div>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">extended="false"</span>
  <div><md-fab icon="add" label="Compose" extended="false"></md-fab></div>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">no label</span>
  <div><md-fab icon="add" aria-label="Compose"></md-fab></div>
</div>

Pinning the value is what makes the FAB morph rather than swap. Press the button below: the label’s width and opacity animate over a spring, because the label stays in the DOM the whole time.

Collapse

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<div style="display:flex;gap:16px;align-items:center;">
  <md-button id="fab-morph-btn" variant="outlined">Collapse</md-button>
  <md-fab id="fab-morph" icon="add" label="Compose"></md-fab>
</div>

<script type="module">
  const fab = document.getElementById('fab-morph');
  const btn = document.getElementById('fab-morph-btn');
  fab.extended = true;                     // pin it, so the change can animate
  btn.addEventListener('mdClick', () => {
    fab.extended = !fab.extended;
    btn.textContent = fab.extended ? 'Collapse' : 'Extend';
  });
</script>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { useEffect, useRef } from 'react';
import { MdButton, MdFab } from '@awc-ui/react';

export function Demo() {
  const fabRef = useRef(null);
  const btnRef = useRef(null);

  useEffect(() => {
    const fab = fabRef.current;
    const btn = btnRef.current;
    fab.extended = true;                     // pin it, so the change can animate
    btn.addEventListener('mdClick', () => {
      fab.extended = !fab.extended;
      btn.textContent = fab.extended ? 'Collapse' : 'Extend';
    });
  }, []);

  return (
    <>
      <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
        <MdButton id="fab-morph-btn" ref={btnRef} variant="outlined">Collapse</MdButton>
        <MdFab id="fab-morph" ref={fabRef} icon="add" label="Compose"></MdFab>
      </div>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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.ts
import { AfterViewInit, Component, ElementRef, ViewChild } from '@angular/core';

@Component({
  selector: 'app-demo',
  templateUrl: './app.component.html',
})
export class DemoComponent implements AfterViewInit {
  @ViewChild('fab') fabRef!: ElementRef;
  @ViewChild('btn') btnRef!: ElementRef;

  ngAfterViewInit() {
    const fab = this.fabRef.nativeElement;
    const btn = this.btnRef.nativeElement;
    fab.extended = true;                     // pin it, so the change can animate
    btn.addEventListener('mdClick', () => {
      fab.extended = !fab.extended;
      btn.textContent = fab.extended ? 'Collapse' : 'Extend';
    });
  }
}

<!-- app.component.html -->
<div style="display:flex;gap:16px;align-items:center;">
  <md-button id="fab-morph-btn" #btn variant="outlined">Collapse</md-button>
  <md-fab id="fab-morph" #fab icon="add" label="Compose"></md-fab>
</div>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { onMounted, ref } from 'vue';
import '@awc-ui/core/define';

const fabRef = ref(null);
const btnRef = ref(null);

onMounted(() => {
  const fab = fabRef.value;
  const btn = btnRef.value;
  fab.extended = true;                     // pin it, so the change can animate
  btn.addEventListener('mdClick', () => {
    fab.extended = !fab.extended;
    btn.textContent = fab.extended ? 'Collapse' : 'Extend';
  });
});
</script>

<template>
  <div style="display:flex;gap:16px;align-items:center;">
    <md-button id="fab-morph-btn" ref="btnRef" variant="outlined">Collapse</md-button>
    <md-fab id="fab-morph" ref="fabRef" icon="add" label="Compose"></md-fab>
  </div>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

  import { onMount } from 'svelte';
  import '@awc-ui/core/define';

  let fabRef;
  let btnRef;

  onMount(() => {
    const fab = fabRef;
    const btn = btnRef;
    fab.extended = true;                     // pin it, so the change can animate
    btn.addEventListener('mdClick', () => {
      fab.extended = !fab.extended;
      btn.textContent = fab.extended ? 'Collapse' : 'Extend';
    });
  });
</script>

<div style="display:flex;gap:16px;align-items:center;">
  <md-button id="fab-morph-btn" bind:this={btnRef} variant="outlined">Collapse</md-button>
  <md-fab id="fab-morph" bind:this={fabRef} icon="add" label="Compose"></md-fab>
</div>

Placement

The FAB does not position itself. Placement is yours:

<md-fab icon="add" aria-label="New item"
        style="position: fixed; inset-block-end: 24px; inset-inline-end: 24px;"></md-fab>

Use logical properties (inset-inline-end) so it moves to the correct corner under dir="rtl".

Events

Event	Cancelable	Detail	Fires
`mdClick`	no	`MouseEvent`	On activation

not pressed yet

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-fab id="like" icon="favorite" aria-label="Like"></md-fab>

<script type="module">
  document.getElementById('like').addEventListener('mdClick', (e) => {
    // e.detail IS the original MouseEvent — not a wrapper object
    like(e.detail.shiftKey);
  });
</script>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { useEffect } from 'react';
import { MdFab } from '@awc-ui/react';

export function Demo() {
  useEffect(() => {
    document.getElementById('like').addEventListener('mdClick', (e) => {
      // e.detail IS the original MouseEvent — not a wrapper object
      like(e.detail.shiftKey);
    });
  }, []);

  return (
    <>
      <MdFab id="like" icon="favorite" aria-label="Like"></MdFab>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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.ts
import { AfterViewInit, Component, ElementRef, ViewChild } from '@angular/core';

@Component({
  selector: 'app-demo',
  templateUrl: './app.component.html',
})
export class DemoComponent implements AfterViewInit {

  ngAfterViewInit() {
    document.getElementById('like').addEventListener('mdClick', (e) => {
      // e.detail IS the original MouseEvent — not a wrapper object
      like(e.detail.shiftKey);
    });
  }
}

<!-- app.component.html -->
<md-fab id="like" icon="favorite" aria-label="Like"></md-fab>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { onMounted } from 'vue';
import '@awc-ui/core/define';

onMounted(() => {
  document.getElementById('like').addEventListener('mdClick', (e) => {
    // e.detail IS the original MouseEvent — not a wrapper object
    like(e.detail.shiftKey);
  });
});
</script>

<template>
  <md-fab id="like" icon="favorite" aria-label="Like"></md-fab>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

  import { onMount } from 'svelte';
  import '@awc-ui/core/define';

  onMount(() => {
    document.getElementById('like').addEventListener('mdClick', (e) => {
      // e.detail IS the original MouseEvent — not a wrapper object
      like(e.detail.shiftKey);
    });
  });
</script>

<md-fab id="like" icon="favorite" aria-label="Like"></md-fab>

<md-fab id="create" icon="add" label="Create"></md-fab>

<script type="module">
document.getElementById('create')
  .addEventListener('mdClick', () => openComposer());
</script>

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

export function CreateFab() {
return <MdFab icon="add" label="Create" onMdClick={() => openComposer()} />;
}

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

@Component({
selector: 'app-create-fab',
template: `<md-fab icon="add" label="Create" (mdClick)="openComposer()"></md-fab>`,
})
export class CreateFabComponent {
openComposer() { /* … */ }
}

<script setup lang="ts">
function openComposer() { /* … */ }
</script>

<template>
<md-fab icon="add" label="Create" @mdClick="openComposer" />
</template>

<script lang="ts">
function openComposer() { /* … */ }
</script>

<md-fab icon="add" label="Create" on:mdClick={openComposer} />

The rail owns the FAB’s extended state across its collapse transition — slot it and leave extended alone.

<md-navigation-rail expandable>
  <md-fab slot="fab" icon="add" label="Create"></md-fab>
  <md-navigation-rail-tab icon="home" label="Home" value="home"></md-navigation-rail-tab>
</md-navigation-rail>

API Reference

Property	Attribute	Type	Default	Reflects
`variant`	`variant`	`'surface' \| 'primary-container' \| 'secondary-container' \| 'tertiary-container' \| 'primary' \| 'secondary' \| 'tertiary'`	`'primary-container'`	—
`size`	`size`	`'standard' \| 'medium' \| 'large'`	`'standard'`	—
`disabled`	`disabled`	`boolean`	`false`	Yes
`softDisabled`	`soft-disabled`	`boolean`	`false`	Yes
`lowered`	`lowered`	`boolean`	`false`	Yes
`ripple`	`ripple`	`boolean`	`true`	—
`icon`	`icon`	`string`	`''`	—
`label`	`label`	`string`	`''`	—
`extended`	`extended`	`boolean`	`—`	Yes
`density`	`density`	`0 \| -1 \| -2 \| -3 \| -4`	`0`	Yes

Slot	Description
`icon`	Custom icon (replaces icon prop)

Override on the host element for per-instance theming:

Property	Description
`--md-fab-container-color`	Container background
`--md-fab-icon-color`	Icon color
`--md-fab-icon-size`	Icon dimensions
`--md-fab-container-shape`	Border-radius override
`--md-fab-label-color`	Label text color (extended)

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

Part	Description
`state-layer`	Hover/press overlay
`icon`	Icon element
`label`	Label text (extended only)

Accessibility

Icon-only FABs must have aria-label. Extended FABs take their name from label, so an extra aria-label is redundant unless it adds detail.
A fixed FAB can cover other controls. M3 requires the actionable element and its focus indicator to stay visible — check at your smallest supported viewport.
Its DOM position should match its importance in the reading order; don’t append it last purely for CSS convenience.
disabled leaves the tab order; soft-disabled stays focusable.

Three ways to name a FAB

An icon has no text, so a FAB is only accessible if something supplies its name. There are exactly three sources, and the component checks for them before its first render:

aria-label

aria-labelledby

Create document

label (extended)

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

<!-- 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:16px;align-items:center;">
  <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-label</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="Create document"></md-fab>
  </div>
  <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-labelledby</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <span id="fab-name-src" style="opacity:.7;font-size:.85rem;">Create document</span>
    <md-fab icon="add" aria-labelledby="fab-name-src"></md-fab>
  </div>
  <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">label (extended)</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab extended icon="add" label="Create document"></md-fab>
  </div>
</div>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '8rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>aria-label</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdFab icon="add" aria-label="Create document"></MdFab>
        </div>
        <span style={{ inlineSize: '8rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>aria-labelledby</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <span id="fab-name-src" style={{ opacity: '.7', fontSize: '.85rem' }}>Create document</span>
          <MdFab icon="add" aria-labelledby="fab-name-src"></MdFab>
        </div>
        <span style={{ inlineSize: '8rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>label (extended)</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdFab extended icon="add" label="Create document"></MdFab>
        </div>
      </div>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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:16px;align-items:center;">
  <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-label</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="Create document"></md-fab>
  </div>
  <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-labelledby</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <span id="fab-name-src" style="opacity:.7;font-size:.85rem;">Create document</span>
    <md-fab icon="add" aria-labelledby="fab-name-src"></md-fab>
  </div>
  <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">label (extended)</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab extended icon="add" label="Create document"></md-fab>
  </div>
</div>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
    <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-label</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <md-fab icon="add" aria-label="Create document"></md-fab>
    </div>
    <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-labelledby</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <span id="fab-name-src" style="opacity:.7;font-size:.85rem;">Create document</span>
      <md-fab icon="add" aria-labelledby="fab-name-src"></md-fab>
    </div>
    <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">label (extended)</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <md-fab extended icon="add" label="Create document"></md-fab>
    </div>
  </div>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
  <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-label</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="Create document"></md-fab>
  </div>
  <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-labelledby</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <span id="fab-name-src" style="opacity:.7;font-size:.85rem;">Create document</span>
    <md-fab icon="add" aria-labelledby="fab-name-src"></md-fab>
  </div>
  <span style="inline-size:8rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">label (extended)</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab extended icon="add" label="Create document"></md-fab>
  </div>
</div>

Source	Use when
`aria-label`	Icon-only. The usual case.
`aria-labelledby`	Visible text elsewhere already names it — no duplicated string to translate
`label`	`extended` FABs. The visible label is the accessible name

RTL, density & i18n

RTL — position with logical properties so it lands in the correct corner. add/edit need no mirroring; a directional glyph does. See RTL.

Density — density="-1…-4" tightens the container; keep it ≥48px on touch.

i18n — translate label and aria-label. Translated labels run longer, so re-check M3’s no-wrap/no-truncate rule per locale.

ltr

rtl

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

<!-- 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:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="Create"></md-fab>
    <md-fab extended icon="add" label="Create document"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="إنشاء"></md-fab>
    <md-fab extended icon="add" label="إنشاء مستند"></md-fab>
  </div>
</div>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>ltr</span>
        <div dir="ltr" style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdFab icon="add" aria-label="Create"></MdFab>
          <MdFab extended icon="add" label="Create document"></MdFab>
        </div>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>rtl</span>
        <div dir="rtl" style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdFab icon="add" aria-label="إنشاء"></MdFab>
          <MdFab extended icon="add" label="إنشاء مستند"></MdFab>
        </div>
      </div>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="Create"></md-fab>
    <md-fab extended icon="add" label="Create document"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="إنشاء"></md-fab>
    <md-fab extended icon="add" label="إنشاء مستند"></md-fab>
  </div>
</div>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
    <div dir="ltr" style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <md-fab icon="add" aria-label="Create"></md-fab>
      <md-fab extended icon="add" label="Create document"></md-fab>
    </div>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
    <div dir="rtl" style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
      <md-fab icon="add" aria-label="إنشاء"></md-fab>
      <md-fab extended icon="add" label="إنشاء مستند"></md-fab>
    </div>
  </div>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="Create"></md-fab>
    <md-fab extended icon="add" label="Create document"></md-fab>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab icon="add" aria-label="إنشاء"></md-fab>
    <md-fab extended icon="add" label="إنشاء مستند"></md-fab>
  </div>
</div>

On an extended FAB the icon leads the label, so under RTL it moves to the right edge on its own — the box metrics are logical. A plain icon-only FAB has nothing to mirror.

Every density rung

-1

-2

-3

-4

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

<!-- 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:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="0" icon="add" aria-label="Create 0"></md-fab><md-fab density="0" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-1" icon="add" aria-label="Create -1"></md-fab><md-fab density="-1" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-2" icon="add" aria-label="Create -2"></md-fab><md-fab density="-2" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-3" icon="add" aria-label="Create -3"></md-fab><md-fab density="-3" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-4" icon="add" aria-label="Create -4"></md-fab><md-fab density="-4" extended icon="add" label="Create"></md-fab></div>
</div>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>0</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}><MdFab density="0" icon="add" aria-label="Create 0"></MdFab><MdFab density="0" extended icon="add" label="Create"></MdFab></div>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-1</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}><MdFab density="-1" icon="add" aria-label="Create -1"></MdFab><MdFab density="-1" extended icon="add" label="Create"></MdFab></div>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-2</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}><MdFab density="-2" icon="add" aria-label="Create -2"></MdFab><MdFab density="-2" extended icon="add" label="Create"></MdFab></div>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-3</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}><MdFab density="-3" icon="add" aria-label="Create -3"></MdFab><MdFab density="-3" extended icon="add" label="Create"></MdFab></div>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-4</span>
        <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}><MdFab density="-4" icon="add" aria-label="Create -4"></MdFab><MdFab density="-4" extended icon="add" label="Create"></MdFab></div>
      </div>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="0" icon="add" aria-label="Create 0"></md-fab><md-fab density="0" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-1" icon="add" aria-label="Create -1"></md-fab><md-fab density="-1" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-2" icon="add" aria-label="Create -2"></md-fab><md-fab density="-2" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-3" icon="add" aria-label="Create -3"></md-fab><md-fab density="-3" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-4" icon="add" aria-label="Create -4"></md-fab><md-fab density="-4" extended icon="add" label="Create"></md-fab></div>
</div>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="0" icon="add" aria-label="Create 0"></md-fab><md-fab density="0" extended icon="add" label="Create"></md-fab></div>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-1" icon="add" aria-label="Create -1"></md-fab><md-fab density="-1" extended icon="add" label="Create"></md-fab></div>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-2" icon="add" aria-label="Create -2"></md-fab><md-fab density="-2" extended icon="add" label="Create"></md-fab></div>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-3" icon="add" aria-label="Create -3"></md-fab><md-fab density="-3" extended icon="add" label="Create"></md-fab></div>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
    <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-4" icon="add" aria-label="Create -4"></md-fab><md-fab density="-4" extended icon="add" label="Create"></md-fab></div>
  </div>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="0" icon="add" aria-label="Create 0"></md-fab><md-fab density="0" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-1" icon="add" aria-label="Create -1"></md-fab><md-fab density="-1" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-2" icon="add" aria-label="Create -2"></md-fab><md-fab density="-2" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-3" icon="add" aria-label="Create -3"></md-fab><md-fab density="-3" extended icon="add" label="Create"></md-fab></div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;"><md-fab density="-4" icon="add" aria-label="Create -4"></md-fab><md-fab density="-4" extended icon="add" label="Create"></md-fab></div>
</div>

Theming

Custom property	Purpose
`--md-fab-container-color`	Container background
`--md-fab-icon-color` / `--md-fab-icon-size`	Glyph
`--md-fab-container-shape`	Corner radius
`--md-fab-label-color`	Extended-label colour

CSS parts — state-layer, icon, label. Slot — icon for a custom glyph.

Show code for each technology

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<style>
  .fab-brand {
  --md-fab-container-color: #1B5E20;
  --md-fab-icon-color: #FFFFFF;
  --md-fab-label-color: #FFFFFF;
  }
  .fab-square { --md-fab-container-shape: 12px; }
  .fab-big-icon::part(icon) { transform: scale(1.3); }
</style>
<div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
  <md-fab class="fab-brand" icon="add" aria-label="Brand colour"></md-fab>
  <md-fab class="fab-brand" extended icon="add" label="Brand extended"></md-fab>
  <md-fab class="fab-square" icon="edit" aria-label="Square shape"></md-fab>
  <md-fab class="fab-big-icon" variant="secondary" icon="share" aria-label="Larger icon via ::part"></md-fab>
</div>

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdFab } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <style>
        .fab-brand {
        --md-fab-container-color: #1B5E20;
        --md-fab-icon-color: #FFFFFF;
        --md-fab-label-color: #FFFFFF;
        }
        .fab-square { --md-fab-container-shape: 12px; }
        .fab-big-icon::part(icon) { transform: scale(1.3); }
      </style>
      <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap', alignItems: 'center' }}>
        <MdFab className="fab-brand" icon="add" aria-label="Brand colour"></MdFab>
        <MdFab className="fab-brand" extended icon="add" label="Brand extended"></MdFab>
        <MdFab className="fab-square" icon="edit" aria-label="Square shape"></MdFab>
        <MdFab className="fab-big-icon" variant="secondary" icon="share" aria-label="Larger icon via ::part"></MdFab>
      </div>
    </>
  );
}

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

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

<!-- app.component.html -->
<style>
  .fab-brand {
  --md-fab-container-color: #1B5E20;
  --md-fab-icon-color: #FFFFFF;
  --md-fab-label-color: #FFFFFF;
  }
  .fab-square { --md-fab-container-shape: 12px; }
  .fab-big-icon::part(icon) { transform: scale(1.3); }
</style>
<div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
  <md-fab class="fab-brand" icon="add" aria-label="Brand colour"></md-fab>
  <md-fab class="fab-brand" extended icon="add" label="Brand extended"></md-fab>
  <md-fab class="fab-square" icon="edit" aria-label="Square shape"></md-fab>
  <md-fab class="fab-big-icon" variant="secondary" icon="share" aria-label="Larger icon via ::part"></md-fab>
</div>

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <style>
    .fab-brand {
    --md-fab-container-color: #1B5E20;
    --md-fab-icon-color: #FFFFFF;
    --md-fab-label-color: #FFFFFF;
    }
    .fab-square { --md-fab-container-shape: 12px; }
    .fab-big-icon::part(icon) { transform: scale(1.3); }
  </style>
  <div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
    <md-fab class="fab-brand" icon="add" aria-label="Brand colour"></md-fab>
    <md-fab class="fab-brand" extended icon="add" label="Brand extended"></md-fab>
    <md-fab class="fab-square" icon="edit" aria-label="Square shape"></md-fab>
    <md-fab class="fab-big-icon" variant="secondary" icon="share" aria-label="Larger icon via ::part"></md-fab>
  </div>
</template>

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<style>
  .fab-brand {
  --md-fab-container-color: #1B5E20;
  --md-fab-icon-color: #FFFFFF;
  --md-fab-label-color: #FFFFFF;
  }
  .fab-square { --md-fab-container-shape: 12px; }
  .fab-big-icon::part(icon) { transform: scale(1.3); }
</style>
<div style="display:flex;gap:16px;flex-wrap:wrap;align-items:center;">
  <md-fab class="fab-brand" icon="add" aria-label="Brand colour"></md-fab>
  <md-fab class="fab-brand" extended icon="add" label="Brand extended"></md-fab>
  <md-fab class="fab-square" icon="edit" aria-label="Square shape"></md-fab>
  <md-fab class="fab-big-icon" variant="secondary" icon="share" aria-label="Larger icon via ::part"></md-fab>
</div>

The three parts — state-layer, icon, label — cover what the custom properties cannot reach, such as transforming the glyph itself.

md-fab-menu · md-button · md-icon-button · md-navigation-rail · md-toolbar

AI / LLM Context

For AI Agents — `md-fab`

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-fab` 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.

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 spec

`md-fab` readme.md

# md-fab

<!-- llm:meta
tag: md-fab
category: actions
status: md3-mapped
m3-guidelines: https://m3.material.io/components/floating-action-button/guidelines
m3-guidelines-extended: https://m3.material.io/components/extended-fab/guidelines
form-associated: false
depends-on: md-ripple
used-by: none
-->

**The single most prominent action on a screen.** Floats above the UI in seven
color mappings and three sizes, and morphs between an icon-only circle and an
**extended** pill that carries a label.

> Setup, theming, density and i18n are configured once for the whole library —
> see [`main-llm.md`](../../../../../main-llm.md), the library-wide manual that ships
> alongside these files.

---

## When to use

- **One** primary, constructive action per screen: compose, add, create, edit.
- The action is the reason the screen exists — not one option among several.
- Inside a `md-navigation-rail`, where it collapses to icon-only when the rail
  collapses.

## When NOT to use

| Situation | Use instead |
|---|---|
| A second prominent action on the same screen | `md-button variant="filled"` |
| Minor, overflow, unclear, or **destructive** actions | `md-button` / `md-menu` |
| An action scoped to a card or other container | `md-button` / `md-icon-button` inside it |
| One of a set of equal options | `md-button-group` |
| 2–6 related creation actions behind one trigger | `md-fab-menu` |
| Screens where imagery already represents the primary action | Nothing — M3 says a FAB isn't always needed |
| A destination change | `md-navigation-bar` / `md-navigation-rail` |

## Decision cues

| Need | Setting |
|---|---|
| Standard floating action | `size="standard"` (default) |
| More presence on a large screen | `size="medium"` or `"large"` — **icon-only FABs only** |
| Icon + label (extended FAB) | set `label` — `extended` follows automatically |
| Force icon-only despite a label | `extended="false"` |
| Force extended | `extended` |
| Reduced elevation (on a busy surface) | `lowered` |
| Highest color emphasis | `variant="primary"` |
| Softer, container-toned default | `variant="primary-container"` (default) |

`variant` accepts `surface`, `primary`, `secondary`, `tertiary` and the three
`-container` forms. The `-container` variants are the softer, standard look;
the bare roles are higher-contrast. `surface` is M3's own default and is the
only variant that changes container color under `lowered`
(`surface-container-high` → `surface-container-low`); this component keeps
`primary-container` as its default.

| `size` | Container (icon-only) | Icon |
|---|---|---|
| `standard` | 56 × 56px | 24px |
| `medium` | 80 × 80px | 28px |
| `large` | 96 × 96px | 36px |

A labelled FAB ignores `size` entirely — extended and collapsed forms are both
56px tall (`min-width` 80px extended, 56px collapsed).

## API contract

```html
<md-fab
  variant="surface|primary-container|secondary-container|tertiary-container|primary|secondary|tertiary"
  size="standard|medium|large"    <!-- default: standard -->
  icon="add"
  label="Compose"                 <!-- presence implies extended -->
  extended                        <!-- explicit override, tri-state -->
  lowered
  disabled | soft-disabled
  ripple
  density="-1|-2|-3|-4"           <!-- omit for the default rung -->
  aria-label="Compose"            <!-- REQUIRED when icon-only -->
></md-fab>
```

**Slot** — `icon`, for a custom glyph in place of the `icon` prop. Element
content in that slot suppresses the `icon` prop's glyph. There is no default
slot: the extended label comes from the `label` prop, not from slotted text.

**Event**

| Event | Cancelable | Detail | Fires |
|---|---|---|---|
| `mdClick` | yes, but ignored | `MouseEvent` | On activation |

`mdClick` is dispatched with `cancelable: true`, so `preventDefault()` succeeds
— but the component never reads `defaultPrevented`, so it changes nothing.
There is no veto hook on `md-fab`; use `md-button`, whose `mdClick` is honoured.

**Parts** — `state-layer`, `icon`, `label`.

### Behavioral contract worth knowing

- **`extended` is tri-state.** Left unset it is *derived*: extended whenever a
  `label` is present. Setting it explicitly (`true`/`false`) pins the state and
  lets the FAB **morph** between forms — this is how `md-navigation-rail`
  collapses it. Don't set it unless you're driving that transition.
- The detail of `mdClick` is the raw `MouseEvent`, not an object — there is no
  `detail.selected`. This FAB has **no toggle mode**.
- **`size` applies only to a FAB with no `label`.** The moment `label` is set
  the size class is dropped and the container follows the extended/collapsed
  metrics instead. `size="large" label="Compose"` is not a large extended FAB.
- The component writes `aria-label` from `label` **only when you did not author
  `aria-label` or `aria-labelledby` yourself**. Yours always wins.
- In collapsed form the visual label is `aria-hidden`, but the host's
  `aria-label` keeps the accessible name — the name survives the morph.
- In dev builds an icon-only FAB with no `label`, `aria-label` or
  `aria-labelledby` logs a `console.warn` naming the WCAG failure.
- A FAB does not position itself. Placement (fixed bottom-end, inside a rail,
  etc.) is yours to set with CSS.
- **While its menu is open**, `md-fab-menu` sets `data-shape="circle"` on its
  trigger FAB to force a full circle, and removes it again on close (and on
  disconnect). It is not a permanent marker on a FAB that anchors a menu. Don't
  set that attribute yourself.

---

## Do / Don't

Sourced from M3 · [FAB](https://m3.material.io/components/floating-action-button/guidelines)
and [Extended FAB](https://m3.material.io/components/extended-fab/guidelines).

| ✅ Do | ❌ Don't |
|---|---|
| Show **one** FAB per screen | Don't display multiple FABs on a single screen |
| Use it for primary, **positive** actions | Don't use it for minor, overflow, unclear, or destructive actions |
| Use clear, simple icons — `add`, `message`, `edit` | Don't use confusing or open-ended icons for uncommon actions |
| Place it within a navigation component such as a rail when appropriate | Don't give individual components, like cards, their own FAB |
| Let it disappear and reappear when switching pages | Don't keep the FAB on screen across page changes |
| Skip the FAB when imagery already represents the primary action | Don't force one onto every screen |
| Keep it above the rest of the UI, clear of app bars | Don't place it on top of toolbars — it breaks the elevation layering |
| Keep the extended label short; add an icon for context | Don't wrap or truncate the extended label |
| Remember an extended FAB may omit its icon | Don't give an extended FAB an icon **without** a text label |
| Keep it in the lower half of a mobile screen | Don't place an extended FAB in the upper half — it disrupts reading order |
| Show one prominent action at a time | Don't use several extended FABs — it destroys the hierarchy |
| Use a plain FAB alongside a floating toolbar | Don't pair an **extended** FAB with a floating toolbar |

---

## Patterns

```html
<!-- Standard: icon-only, fixed bottom-end -->
<md-fab icon="add" aria-label="New item"
        style="position:fixed; inset-block-end:24px; inset-inline-end:24px;"></md-fab>

<!-- Extended: label implies extended, icon adds context -->
<md-fab icon="edit" label="Compose"></md-fab>

<!-- Extended with no icon (allowed) -->
<md-fab label="Start a chat"></md-fab>

<!-- Large, high-emphasis -->
<md-fab variant="primary" size="large" icon="add" aria-label="Create"></md-fab>

<!-- Lowered, for a visually busy surface -->
<md-fab lowered icon="add" aria-label="Add"></md-fab>

<!-- Morphing: pinned extended state, driven by layout.
     `extended` is a tri-state boolean, so drive it as a JS property —
     removing the attribute would fall back to "derived", not to false. -->
<md-fab id="create-fab" icon="add" label="Create"></md-fab>
<script>
  const fab = document.getElementById('create-fab');
  const narrow = window.matchMedia('(max-width: 600px)');
  const sync = () => { fab.extended = !narrow.matches; };
  sync();
  narrow.addEventListener('change', sync);
</script>

<!-- Hide when the current view has no primary action, per M3 -->
<script>
  document.getElementById('create-fab').hidden = true;
</script>
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| Two FABs on one screen | One FAB; demote the other to `md-button` | M3's clearest FAB rule. |
| A FAB for "Delete" | `md-button` or `md-icon-button` | FABs are for positive actions. |
| A FAB inside each `md-card` | One screen-level FAB, or per-card `md-button` | M3 forbids per-container FABs. |
| `<md-fab icon="add">` with no `aria-label` | Add `aria-label` | Icon-only FABs have no accessible name. |
| `<md-fab icon="add" extended>` with no `label` | Add a `label`, or drop `extended` | An extended FAB can't be icon-only. |
| Setting `extended="false"` to hide a label you didn't set | Just omit `label` | `extended` is derived unless pinned. |
| `e.detail.selected` in the click handler | `mdClick` detail is a `MouseEvent` | There's no toggle mode. |
| Expecting the FAB to position itself | Position it with CSS | The component is layout-agnostic. |
| `<md-fab size="large" label="Compose">` expecting a large pill | Drop `label`, or accept the 56px extended height | `size` is ignored once `label` is set. |
| `fab.setAttribute('extended', '')` / `removeAttribute` to collapse | `fab.extended = false` | Removing the attribute returns it to *derived*, which is extended whenever `label` is set. |
| Extended FAB overlapping a toolbar | Move it clear, or use a plain FAB | M3 calls out both cases. |
| A wrapping/truncating extended label | Shorten the text | M3: never wrap or truncate. |

## Accessibility, RTL, density, i18n

**Accessibility**
- Icon-only FABs **must** have `aria-label`. Extended FABs take their name from
  `label`, so an extra `aria-label` is redundant unless it adds detail.
- `Enter`/`Space` activate. `disabled` leaves the tab order;
  `soft-disabled` stays focusable.
- A fixed FAB can cover other controls — M3 requires the actionable element
  *and its focus indicator* to remain visible behind it. Check this at your
  smallest supported viewport.
- Its position in the DOM should match its importance in the reading order;
  don't append it last purely for CSS convenience.

**RTL** — position with logical properties (`inset-inline-end`) so it moves to
the correct corner. Swap directional glyphs yourself; `add`/`edit` need no
change.

**Density** — `density="-1…-4"` tightens the container; only those four rungs
exist and omitting the attribute is the uncompacted default. `density="0"` does
**not** opt out of an ancestor's `data-density` rung — reset the scale with
`style="--md-sys-density-scale: 0"` instead. The standard FAB floors at 40px,
so check the touch target on deep rungs.

**i18n** — `label` and `aria-label` come from your dictionary. Translated labels
run longer, so re-check M3's no-wrap/no-truncate rule per locale.

## Related components

`md-fab-menu` · `md-fab-menu-item` · `md-button` · `md-icon-button` ·
`md-navigation-rail` · `md-toolbar` · `md-ripple`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-fab-container-color` | Container background | Per variant (`--md-sys-color-primary-container`) |
| `--md-fab-icon-color` | Glyph color | Per variant (`--md-sys-color-on-primary-container`) |
| `--md-fab-icon-size` | Glyph size | 24px `standard` / 28px `medium` / 36px `large` |
| `--md-fab-container-shape` | Corner radius | `--md-sys-shape-corner-large` (`extra-large` on `medium`/`large`) |
| `--md-fab-label-color` | Extended-label color | `inherit` — the host color, i.e. the variant icon color |

**CSS parts** — `state-layer`, `icon`, `label`.

```css
md-fab.brand {
  --md-fab-container-color: var(--md-sys-color-tertiary);
  --md-fab-icon-color: var(--md-sys-color-on-tertiary);
  --md-fab-label-color: var(--md-sys-color-on-tertiary);
}
```

<!-- Auto Generated Below -->


## 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`                   |
| `disabled`     | `disabled`      |                                                                                                                                                                                                                                                                                                                                                                                                                    | `boolean`                                                                                                                     | `false`               |
| `extended`     | `extended`      | Whether the FAB shows its label (extended) or collapses to an icon-only circle. Leave unset for the default behaviour (extended whenever a `label` is provided). Set explicitly — e.g. by `<md-navigation-rail>` on collapse — to morph between extended and icon-only: the label width/opacity springs closed and the container shrinks to a 56px circle, while the label stays available as the accessible name. | `boolean \| undefined`                                                                                                        | `undefined`           |
| `icon`         | `icon`          |                                                                                                                                                                                                                                                                                                                                                                                                                    | `string`                                                                                                                      | `''`                  |
| `label`        | `label`         |                                                                                                                                                                                                                                                                                                                                                                                                                    | `string`                                                                                                                      | `''`                  |
| `lowered`      | `lowered`       |                                                                                                                                                                                                                                                                                                                                                                                                                    | `boolean`                                                                                                                     | `false`               |
| `ripple`       | `ripple`        |                                                                                                                                                                                                                                                                                                                                                                                                                    | `boolean`                                                                                                                     | `true`                |
| `size`         | `size`          |                                                                                                                                                                                                                                                                                                                                                                                                                    | `"large" \| "medium" \| "standard"`                                                                                           | `'standard'`          |
| `softDisabled` | `soft-disabled` |                                                                                                                                                                                                                                                                                                                                                                                                                    | `boolean`                                                                                                                     | `false`               |
| `variant`      | `variant`       |                                                                                                                                                                                                                                                                                                                                                                                                                    | `"primary" \| "primary-container" \| "secondary" \| "secondary-container" \| "surface" \| "tertiary" \| "tertiary-container"` | `'primary-container'` |


## Events

| Event     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                         | Type                      |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `mdClick` | Fires when the user activates the FAB (mouse click, touch, or `Enter`/`Space` while focused). Not emitted when `disabled` or `soft-disabled`. Bubbles and is composed so a delegated listener on a parent element works.  ```ts document.querySelector('md-fab')!.addEventListener('mdClick', (e) => {   const mouseEvent = (e as CustomEvent<MouseEvent>).detail;   console.log('FAB clicked at', mouseEvent.clientX, mouseEvent.clientY); }); ``` | `CustomEvent<MouseEvent>` |


## Shadow Parts

| Part            | Description |
| --------------- | ----------- |
| `"icon"`        |             |
| `"label"`       |             |
| `"state-layer"` |             |


## Dependencies

### Depends on

- [md-ripple](../md-ripple)

### Graph
```mermaid
graph TD;
  md-fab --> md-ripple
  style md-fab fill:#f9f,stroke:#333,stroke-width:4px
```

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

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

AWC UI Operator’s Manual

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

FAB

Install

When to use

When not to use

Variants

Sizes

States

Every variant at every size

Extended

Placement

Events

In a navigation rail

API Reference

Properties

Slots

CSS Custom Properties

CSS Shadow Parts

Accessibility

Three ways to name a FAB

RTL, density & i18n

Every density rung

Theming

AI / LLM Context

For AI Agents — `md-fab`

`md-fab` spec card

AWC UI Operator's Manual

`md-fab` readme.md

AWC UI Operator’s Manual