Segmented Button

A choice between 2–5 exclusive options, all visible at once. Two elements work as one control: <md-segmented-button-set> owns the selection and stamps each child with its position, and <md-segmented-button> renders one segment — value, optional icon, label, and the selected checkmark.

Live preview Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

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

<md-segmented-button-set aria-label="Calendar view">
  <md-segmented-button value="day" label="Day" selected></md-segmented-button>
  <md-segmented-button value="week" label="Week"></md-segmented-button>
  <md-segmented-button value="month" label="Month"></md-segmented-button>
</md-segmented-button-set>

Copy

import { MdSegmentedButton, MdSegmentedButtonSet } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdSegmentedButtonSet aria-label="Calendar view">
        <MdSegmentedButton value="day" label="Day" selected></MdSegmentedButton>
        <MdSegmentedButton value="week" label="Week"></MdSegmentedButton>
        <MdSegmentedButton value="month" label="Month"></MdSegmentedButton>
      </MdSegmentedButtonSet>
    </>
  );
}

Copy

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

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

<!-- app.component.html -->
<md-segmented-button-set aria-label="Calendar view">
  <md-segmented-button value="day" label="Day" selected></md-segmented-button>
  <md-segmented-button value="week" label="Week"></md-segmented-button>
  <md-segmented-button value="month" label="Month"></md-segmented-button>
</md-segmented-button-set>

Copy

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

<template>
  <md-segmented-button-set aria-label="Calendar view">
    <md-segmented-button value="day" label="Day" selected></md-segmented-button>
    <md-segmented-button value="week" label="Week"></md-segmented-button>
    <md-segmented-button value="month" label="Month"></md-segmented-button>
  </md-segmented-button-set>
</template>

Copy

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

<md-segmented-button-set aria-label="Calendar view">
  <md-segmented-button value="day" label="Day" selected></md-segmented-button>
  <md-segmented-button value="week" label="Week"></md-segmented-button>
  <md-segmented-button value="month" label="Month"></md-segmented-button>
</md-segmented-button-set>

Install

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

HTML React Angular Vue Svelte

Copy

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


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


<md-segmented-button-set></md-segmented-button-set>

Copy

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

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


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

export function ExampleTreeShaken() {
  return <md-segmented-button-set></md-segmented-button-set>;
}

Copy

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

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


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

@Component({
  standalone: true,
  imports: [MdSegmentedButtonSet],
  template: `<md-segmented-button-set></md-segmented-button-set>`,
})
export class ExampleTreeShakenComponent {}

Copy

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

<template>
  <MdSegmentedButtonSet></MdSegmentedButtonSet>
</template>


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

<template>
  <md-segmented-button-set></md-segmented-button-set>
</template>

Copy

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

<md-segmented-button-set></md-segmented-button-set>


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

<md-segmented-button-set></md-segmented-button-set>

One component, two tags

The two tags register separately, so the single-component import above only covers the set. With per-component imports you need both:

import '@awc-ui/core/components/md-segmented-button-set';
import '@awc-ui/core/components/md-segmented-button';

A lone md-segmented-button outside a set still renders — it keeps the default segmentIndex = 0 / segmentTotal = 1, so it is both first and last and draws as a correctly rounded pill. What it does not get is behaviour: nothing listens for its mdSegmentClick, so clicking it changes nothing. Always author the pair; that is why both tags are documented on this one page.

When to use

• 2–5 mutually exclusive options the user should see side by side: Day / Week / Month, List / Grid, All / Unread.
• Switching a view or mode, where the current state should stay visible.
• Multi-select over a small, closed set of filters (multiselect).

When not to use

Situation	Use instead
More than five choices	md-chip set, md-select, or md-menu
Navigating between destinations or panels	md-tabs / md-navigation-bar
Running actions rather than choosing a state	md-button-group
A form field that must submit	md-radio / md-checkbox
One default action plus variants	md-split-button
Choosing from a long or dynamic list	md-select
Free-form multi-select of many tags	md-multi-select, md-chip

Composition

The set is an inline-grid with grid-auto-flow: column and grid-auto-columns: 1fr, so segments must be direct, real children: they are the grid items, and that is what gives every segment the same width no matter how long its label is. A <div> wrapper for layout still gets discovered — the set stamps its children with querySelectorAll('md-segmented-button'), a descendant query — but the wrapper becomes the single grid item and the equal columns are lost.

Need	Where it goes
The initial selection	selected on a child. The set has no value prop
Single vs multi	multiselect on the set
Density	density on the set (cascades) or on a child (overrides)
The accessible group name	aria-label on the set
Per-segment identity	value on each child

Same three labels, same set, one wrapped in a <div>. The top row’s columns are equal; the bottom row’s collapse to each label’s intrinsic width:

Direct children vs a div wrapper — the wrapper loses the equal columns

correct wrong

Show code for each technology

HTML React Angular Vue Svelte

Copy

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <md-segmented-button-set aria-label="Direct children">
    <md-segmented-button value="d" label="Day" selected></md-segmented-button>
    <md-segmented-button value="w" label="Week"></md-segmented-button>
    <md-segmented-button value="y" label="Last 12 months"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <md-segmented-button-set aria-label="Wrapped children">
    <div style="display:flex;">
      <md-segmented-button value="d" label="Day" selected></md-segmented-button>
      <md-segmented-button value="w" label="Week"></md-segmented-button>
      <md-segmented-button value="y" label="Last 12 months"></md-segmented-button>
    </div>
  </md-segmented-button-set>
</div>

Copy

import { MdSegmentedButton, MdSegmentedButtonSet } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: "grid", gridTemplateColumns: "auto 1fr", gap: "14px 16px", alignItems: "center" }}>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>correct</span>
        <MdSegmentedButtonSet aria-label="Direct children">
          <MdSegmentedButton value="d" label="Day" selected></MdSegmentedButton>
          <MdSegmentedButton value="w" label="Week"></MdSegmentedButton>
          <MdSegmentedButton value="y" label="Last 12 months"></MdSegmentedButton>
        </MdSegmentedButtonSet>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>wrong</span>
        <MdSegmentedButtonSet aria-label="Wrapped children">
          <div style={{ display: "flex" }}>
            <MdSegmentedButton value="d" label="Day" selected></MdSegmentedButton>
            <MdSegmentedButton value="w" label="Week"></MdSegmentedButton>
            <MdSegmentedButton value="y" label="Last 12 months"></MdSegmentedButton>
          </div>
        </MdSegmentedButtonSet>
      </div>
    </>
  );
}

Copy

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

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

<!-- app.component.html -->
<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <md-segmented-button-set aria-label="Direct children">
    <md-segmented-button value="d" label="Day" selected></md-segmented-button>
    <md-segmented-button value="w" label="Week"></md-segmented-button>
    <md-segmented-button value="y" label="Last 12 months"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <md-segmented-button-set aria-label="Wrapped children">
    <div style="display:flex;">
      <md-segmented-button value="d" label="Day" selected></md-segmented-button>
      <md-segmented-button value="w" label="Week"></md-segmented-button>
      <md-segmented-button value="y" label="Last 12 months"></md-segmented-button>
    </div>
  </md-segmented-button-set>
</div>

Copy

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

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
    <md-segmented-button-set aria-label="Direct children">
      <md-segmented-button value="d" label="Day" selected></md-segmented-button>
      <md-segmented-button value="w" label="Week"></md-segmented-button>
      <md-segmented-button value="y" label="Last 12 months"></md-segmented-button>
    </md-segmented-button-set>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
    <md-segmented-button-set aria-label="Wrapped children">
      <div style="display:flex;">
        <md-segmented-button value="d" label="Day" selected></md-segmented-button>
        <md-segmented-button value="w" label="Week"></md-segmented-button>
        <md-segmented-button value="y" label="Last 12 months"></md-segmented-button>
      </div>
    </md-segmented-button-set>
  </div>
</template>

Copy

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <md-segmented-button-set aria-label="Direct children">
    <md-segmented-button value="d" label="Day" selected></md-segmented-button>
    <md-segmented-button value="w" label="Week"></md-segmented-button>
    <md-segmented-button value="y" label="Last 12 months"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <md-segmented-button-set aria-label="Wrapped children">
    <div style="display:flex;">
      <md-segmented-button value="d" label="Day" selected></md-segmented-button>
      <md-segmented-button value="w" label="Week"></md-segmented-button>
      <md-segmented-button value="y" label="Last 12 months"></md-segmented-button>
    </div>
  </md-segmented-button-set>
</div>

Never set the stamped props

The set writes segmentIndex, segmentTotal, segmentDensity and segmentMultiselect onto each child so they can render the correct end caps and checkmark behaviour. Setting those by hand produces a broken container.

Single-select

Default mode. role="radiogroup", one selection at a time.

Two, three and five segments — M3's full range

Show code for each technology

HTML React Angular Vue Svelte

Copy

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

<md-segmented-button-set aria-label="Time range">
  <md-segmented-button value="d" label="Day" selected></md-segmented-button>
  <md-segmented-button value="w" label="Week"></md-segmented-button>
  <md-segmented-button value="m" label="Month"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Answer">
  <md-segmented-button value="yes" label="Yes" selected></md-segmented-button>
  <md-segmented-button value="no" label="No"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Rating filter">
  <md-segmented-button value="1" label="All" selected></md-segmented-button>
  <md-segmented-button value="2" label="Recent"></md-segmented-button>
  <md-segmented-button value="3" label="Top"></md-segmented-button>
  <md-segmented-button value="4" label="Mine"></md-segmented-button>
  <md-segmented-button value="5" label="Draft"></md-segmented-button>
</md-segmented-button-set>

Copy

import { MdSegmentedButton, MdSegmentedButtonSet } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdSegmentedButtonSet aria-label="Time range">
        <MdSegmentedButton value="d" label="Day" selected></MdSegmentedButton>
        <MdSegmentedButton value="w" label="Week"></MdSegmentedButton>
        <MdSegmentedButton value="m" label="Month"></MdSegmentedButton>
      </MdSegmentedButtonSet>

      <MdSegmentedButtonSet aria-label="Answer">
        <MdSegmentedButton value="yes" label="Yes" selected></MdSegmentedButton>
        <MdSegmentedButton value="no" label="No"></MdSegmentedButton>
      </MdSegmentedButtonSet>

      <MdSegmentedButtonSet aria-label="Rating filter">
        <MdSegmentedButton value="1" label="All" selected></MdSegmentedButton>
        <MdSegmentedButton value="2" label="Recent"></MdSegmentedButton>
        <MdSegmentedButton value="3" label="Top"></MdSegmentedButton>
        <MdSegmentedButton value="4" label="Mine"></MdSegmentedButton>
        <MdSegmentedButton value="5" label="Draft"></MdSegmentedButton>
      </MdSegmentedButtonSet>
    </>
  );
}

Copy

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

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

<!-- app.component.html -->
<md-segmented-button-set aria-label="Time range">
  <md-segmented-button value="d" label="Day" selected></md-segmented-button>
  <md-segmented-button value="w" label="Week"></md-segmented-button>
  <md-segmented-button value="m" label="Month"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Answer">
  <md-segmented-button value="yes" label="Yes" selected></md-segmented-button>
  <md-segmented-button value="no" label="No"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Rating filter">
  <md-segmented-button value="1" label="All" selected></md-segmented-button>
  <md-segmented-button value="2" label="Recent"></md-segmented-button>
  <md-segmented-button value="3" label="Top"></md-segmented-button>
  <md-segmented-button value="4" label="Mine"></md-segmented-button>
  <md-segmented-button value="5" label="Draft"></md-segmented-button>
</md-segmented-button-set>

Copy

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

<template>
  <md-segmented-button-set aria-label="Time range">
    <md-segmented-button value="d" label="Day" selected></md-segmented-button>
    <md-segmented-button value="w" label="Week"></md-segmented-button>
    <md-segmented-button value="m" label="Month"></md-segmented-button>
  </md-segmented-button-set>

  <md-segmented-button-set aria-label="Answer">
    <md-segmented-button value="yes" label="Yes" selected></md-segmented-button>
    <md-segmented-button value="no" label="No"></md-segmented-button>
  </md-segmented-button-set>

  <md-segmented-button-set aria-label="Rating filter">
    <md-segmented-button value="1" label="All" selected></md-segmented-button>
    <md-segmented-button value="2" label="Recent"></md-segmented-button>
    <md-segmented-button value="3" label="Top"></md-segmented-button>
    <md-segmented-button value="4" label="Mine"></md-segmented-button>
    <md-segmented-button value="5" label="Draft"></md-segmented-button>
  </md-segmented-button-set>
</template>

Copy

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

<md-segmented-button-set aria-label="Time range">
  <md-segmented-button value="d" label="Day" selected></md-segmented-button>
  <md-segmented-button value="w" label="Week"></md-segmented-button>
  <md-segmented-button value="m" label="Month"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Answer">
  <md-segmented-button value="yes" label="Yes" selected></md-segmented-button>
  <md-segmented-button value="no" label="No"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Rating filter">
  <md-segmented-button value="1" label="All" selected></md-segmented-button>
  <md-segmented-button value="2" label="Recent"></md-segmented-button>
  <md-segmented-button value="3" label="Top"></md-segmented-button>
  <md-segmented-button value="4" label="Mine"></md-segmented-button>
  <md-segmented-button value="5" label="Draft"></md-segmented-button>
</md-segmented-button-set>

Single-select is sticky

A click always selects: the segment emits selected: true and the set then sets selected = (seg === clicked) across the row. So re-clicking the chosen segment does not clear it, and in single-select mdChange never emits an empty array once something is selected. Only multiselect can reach an empty selection — read detail[0] defensively there.

Multi-select

multiselect on the set switches role to group and allows several selections at once.

Multi-select filters

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- 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-segmented-button-set multiselect aria-label="Filters">
  <md-segmented-button value="unread" label="Unread" icon="mark_email_unread" selected></md-segmented-button>
  <md-segmented-button value="starred" label="Starred" icon="star"></md-segmented-button>
  <md-segmented-button value="mine" label="Mine" icon="person" selected></md-segmented-button>
</md-segmented-button-set>

Copy

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

export function Demo() {
  return (
    <>
      <MdSegmentedButtonSet multiselect aria-label="Filters">
        <MdSegmentedButton value="unread" label="Unread" icon="mark_email_unread" selected></MdSegmentedButton>
        <MdSegmentedButton value="starred" label="Starred" icon="star"></MdSegmentedButton>
        <MdSegmentedButton value="mine" label="Mine" icon="person" selected></MdSegmentedButton>
      </MdSegmentedButtonSet>
    </>
  );
}

Copy

// 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-segmented-button-set multiselect aria-label="Filters">
  <md-segmented-button value="unread" label="Unread" icon="mark_email_unread" selected></md-segmented-button>
  <md-segmented-button value="starred" label="Starred" icon="star"></md-segmented-button>
  <md-segmented-button value="mine" label="Mine" icon="person" selected></md-segmented-button>
</md-segmented-button-set>

Copy

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

<template>
  <md-segmented-button-set multiselect aria-label="Filters">
    <md-segmented-button value="unread" label="Unread" icon="mark_email_unread" selected></md-segmented-button>
    <md-segmented-button value="starred" label="Starred" icon="star"></md-segmented-button>
    <md-segmented-button value="mine" label="Mine" icon="person" selected></md-segmented-button>
  </md-segmented-button-set>
</template>

Copy

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

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

<md-segmented-button-set multiselect aria-label="Filters">
  <md-segmented-button value="unread" label="Unread" icon="mark_email_unread" selected></md-segmented-button>
  <md-segmented-button value="starred" label="Starred" icon="star"></md-segmented-button>
  <md-segmented-button value="mine" label="Mine" icon="person" selected></md-segmented-button>
</md-segmented-button-set>

Icons & label types

Use one label type across the whole set — M3 explicitly warns against mixing an icon-only segment with text segments. An icon-only segment carries no accessible name of its own, so give it an aria-label.

Icon + label, icon-only, and a custom glyph via the icon slot

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- 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-segmented-button-set aria-label="Layout">
  <md-segmented-button value="list" icon="view_list" label="List" selected></md-segmented-button>
  <md-segmented-button value="grid" icon="grid_view" label="Grid"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Alignment">
  <md-segmented-button value="l" icon="format_align_left" aria-label="Align left" selected></md-segmented-button>
  <md-segmented-button value="c" icon="format_align_center" aria-label="Align center"></md-segmented-button>
  <md-segmented-button value="r" icon="format_align_right" aria-label="Align right"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Favourites">
  <md-segmented-button value="all" label="All" selected></md-segmented-button>
  <md-segmented-button value="star" label="Starred">
    <svg slot="icon" viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>
  </md-segmented-button>
</md-segmented-button-set>

Copy

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

export function Demo() {
  return (
    <>
      <MdSegmentedButtonSet aria-label="Layout">
        <MdSegmentedButton value="list" icon="view_list" label="List" selected></MdSegmentedButton>
        <MdSegmentedButton value="grid" icon="grid_view" label="Grid"></MdSegmentedButton>
      </MdSegmentedButtonSet>

      <MdSegmentedButtonSet aria-label="Alignment">
        <MdSegmentedButton value="l" icon="format_align_left" aria-label="Align left" selected></MdSegmentedButton>
        <MdSegmentedButton value="c" icon="format_align_center" aria-label="Align center"></MdSegmentedButton>
        <MdSegmentedButton value="r" icon="format_align_right" aria-label="Align right"></MdSegmentedButton>
      </MdSegmentedButtonSet>

      <MdSegmentedButtonSet aria-label="Favourites">
        <MdSegmentedButton value="all" label="All" selected></MdSegmentedButton>
        <MdSegmentedButton value="star" label="Starred">
          <svg slot="icon" viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>
        </MdSegmentedButton>
      </MdSegmentedButtonSet>
    </>
  );
}

Copy

// 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-segmented-button-set aria-label="Layout">
  <md-segmented-button value="list" icon="view_list" label="List" selected></md-segmented-button>
  <md-segmented-button value="grid" icon="grid_view" label="Grid"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Alignment">
  <md-segmented-button value="l" icon="format_align_left" aria-label="Align left" selected></md-segmented-button>
  <md-segmented-button value="c" icon="format_align_center" aria-label="Align center"></md-segmented-button>
  <md-segmented-button value="r" icon="format_align_right" aria-label="Align right"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Favourites">
  <md-segmented-button value="all" label="All" selected></md-segmented-button>
  <md-segmented-button value="star" label="Starred">
    <svg slot="icon" viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>
  </md-segmented-button>
</md-segmented-button-set>

Copy

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

<template>
  <md-segmented-button-set aria-label="Layout">
    <md-segmented-button value="list" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="grid" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>

  <md-segmented-button-set aria-label="Alignment">
    <md-segmented-button value="l" icon="format_align_left" aria-label="Align left" selected></md-segmented-button>
    <md-segmented-button value="c" icon="format_align_center" aria-label="Align center"></md-segmented-button>
    <md-segmented-button value="r" icon="format_align_right" aria-label="Align right"></md-segmented-button>
  </md-segmented-button-set>

  <md-segmented-button-set aria-label="Favourites">
    <md-segmented-button value="all" label="All" selected></md-segmented-button>
    <md-segmented-button value="star" label="Starred">
      <svg slot="icon" viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>
    </md-segmented-button>
  </md-segmented-button-set>
</template>

Copy

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

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

<md-segmented-button-set aria-label="Layout">
  <md-segmented-button value="list" icon="view_list" label="List" selected></md-segmented-button>
  <md-segmented-button value="grid" icon="grid_view" label="Grid"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Alignment">
  <md-segmented-button value="l" icon="format_align_left" aria-label="Align left" selected></md-segmented-button>
  <md-segmented-button value="c" icon="format_align_center" aria-label="Align center"></md-segmented-button>
  <md-segmented-button value="r" icon="format_align_right" aria-label="Align right"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Favourites">
  <md-segmented-button value="all" label="All" selected></md-segmented-button>
  <md-segmented-button value="star" label="Starred">
    <svg slot="icon" viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>
  </md-segmented-button>
</md-segmented-button-set>

The icon prop and the checkmark share one element — selecting an icon+label segment swaps the glyph for the check. The icon slot does not: it renders alongside, so a selected slotted segment shows the checkmark and your glyph. Add no-checkmark to that segment if you want the glyph to stand alone — and read The checkmark first, because that trade is an accessibility one.

The checkmark

The selected segment shows a checkmark by default. That is what conveys selection non-visually — no-checkmark removes the cue and leaves colour alone, which is a real accessibility regression in multiselect.

Checkmark vs no-checkmark

Show code for each technology

HTML React Angular Vue Svelte

Copy

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

<md-segmented-button-set aria-label="With checkmark">
  <md-segmented-button value="a" label="Selected" selected></md-segmented-button>
  <md-segmented-button value="b" label="Unselected"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Without checkmark">
  <md-segmented-button value="a" label="Selected" selected no-checkmark></md-segmented-button>
  <md-segmented-button value="b" label="Unselected" no-checkmark></md-segmented-button>
</md-segmented-button-set>

Copy

import { MdSegmentedButton, MdSegmentedButtonSet } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdSegmentedButtonSet aria-label="With checkmark">
        <MdSegmentedButton value="a" label="Selected" selected></MdSegmentedButton>
        <MdSegmentedButton value="b" label="Unselected"></MdSegmentedButton>
      </MdSegmentedButtonSet>

      <MdSegmentedButtonSet aria-label="Without checkmark">
        <MdSegmentedButton value="a" label="Selected" selected no-checkmark></MdSegmentedButton>
        <MdSegmentedButton value="b" label="Unselected" no-checkmark></MdSegmentedButton>
      </MdSegmentedButtonSet>
    </>
  );
}

Copy

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

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

<!-- app.component.html -->
<md-segmented-button-set aria-label="With checkmark">
  <md-segmented-button value="a" label="Selected" selected></md-segmented-button>
  <md-segmented-button value="b" label="Unselected"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Without checkmark">
  <md-segmented-button value="a" label="Selected" selected no-checkmark></md-segmented-button>
  <md-segmented-button value="b" label="Unselected" no-checkmark></md-segmented-button>
</md-segmented-button-set>

Copy

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

<template>
  <md-segmented-button-set aria-label="With checkmark">
    <md-segmented-button value="a" label="Selected" selected></md-segmented-button>
    <md-segmented-button value="b" label="Unselected"></md-segmented-button>
  </md-segmented-button-set>

  <md-segmented-button-set aria-label="Without checkmark">
    <md-segmented-button value="a" label="Selected" selected no-checkmark></md-segmented-button>
    <md-segmented-button value="b" label="Unselected" no-checkmark></md-segmented-button>
  </md-segmented-button-set>
</template>

Copy

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

<md-segmented-button-set aria-label="With checkmark">
  <md-segmented-button value="a" label="Selected" selected></md-segmented-button>
  <md-segmented-button value="b" label="Unselected"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Without checkmark">
  <md-segmented-button value="a" label="Selected" selected no-checkmark></md-segmented-button>
  <md-segmented-button value="b" label="Unselected" no-checkmark></md-segmented-button>
</md-segmented-button-set>

States

disabled leaves the tab order; soft-disabled stays focusable so an unavailable choice is still discoverable.

States — try tabbing through them

Show code for each technology

HTML React Angular Vue Svelte

Copy

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

<md-segmented-button-set aria-label="States">
  <md-segmented-button value="a" label="Enabled" selected></md-segmented-button>
  <md-segmented-button value="b" label="Disabled" disabled></md-segmented-button>
  <md-segmented-button value="c" label="Soft-disabled" soft-disabled></md-segmented-button>
</md-segmented-button-set>

Copy

import { MdSegmentedButton, MdSegmentedButtonSet } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdSegmentedButtonSet aria-label="States">
        <MdSegmentedButton value="a" label="Enabled" selected></MdSegmentedButton>
        <MdSegmentedButton value="b" label="Disabled" disabled></MdSegmentedButton>
        <MdSegmentedButton value="c" label="Soft-disabled" soft-disabled></MdSegmentedButton>
      </MdSegmentedButtonSet>
    </>
  );
}

Copy

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

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

<!-- app.component.html -->
<md-segmented-button-set aria-label="States">
  <md-segmented-button value="a" label="Enabled" selected></md-segmented-button>
  <md-segmented-button value="b" label="Disabled" disabled></md-segmented-button>
  <md-segmented-button value="c" label="Soft-disabled" soft-disabled></md-segmented-button>
</md-segmented-button-set>

Copy

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

<template>
  <md-segmented-button-set aria-label="States">
    <md-segmented-button value="a" label="Enabled" selected></md-segmented-button>
    <md-segmented-button value="b" label="Disabled" disabled></md-segmented-button>
    <md-segmented-button value="c" label="Soft-disabled" soft-disabled></md-segmented-button>
  </md-segmented-button-set>
</template>

Copy

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

<md-segmented-button-set aria-label="States">
  <md-segmented-button value="a" label="Enabled" selected></md-segmented-button>
  <md-segmented-button value="b" label="Disabled" disabled></md-segmented-button>
  <md-segmented-button value="c" label="Soft-disabled" soft-disabled></md-segmented-button>
</md-segmented-button-set>

Events

Listen on the set, never on the children.

Event	Cancelable	Detail	Fires
mdChange (set)	no	string[] — values of all selected segments	Every activation of a segment (pointer, Enter, Space, arrow keys in single-select)
mdSegmentClick (segment)	no	{ value, selected }	Internal plumbing — the set listens for it and re-emits mdChange

mdChange is an activation signal, not a diff. It fires on every click, even one that changes nothing — re-clicking the already-selected segment in single-select still emits, with the same array as before. And like the platform’s own change, it does not fire on a programmatic change: setting seg.selected = true in code emits nothing, because the set only ever emits from its mdSegmentClick listener. If your own code changes the selection, your own code already knows. De-duplicate in your handler if you need change-only semantics.

mdChange reports, it does not ask

By the time your handler runs, the set has already written selected onto the segments — all of them in single-select, and just the clicked one in multiselect. The event object is cancelable (Stencil’s default), but nothing consumes preventDefault(): the set never reads defaultPrevented, and it mutates before it emits. So a controlled parent that rejects a change must write selected back onto the segments itself.

Both sets below share one delegated mdChange listener. Watch the multi-select row emit a growing array — and shrink to an empty one when you deselect its last segment, which single-select can never do:

One delegated listener on two sets — watch the detail array

single multi

Pick a segment. Deselect every filter in the multi row to see an empty array.

Show code for each technology

HTML React Angular Vue Svelte

Copy

<md-segmented-button-set id="view" aria-label="Calendar view">
<md-segmented-button value="day" label="Day" selected></md-segmented-button>
<md-segmented-button value="week" label="Week"></md-segmented-button>
<md-segmented-button value="month" label="Month"></md-segmented-button>
</md-segmented-button-set>

<script type="module">
document.getElementById('view').addEventListener('mdChange', (e) => {
  const [view] = e.detail;      // string[] of every selected value
  if (!view) return;            // defensive: multiselect can be empty
  setCalendarView(view);
});
</script>

Copy

import { MdSegmentedButtonSet, MdSegmentedButton } from '@awc-ui/react';
import { useState } from 'react';

export function CalendarView() {
const [view, setView] = useState('day');

return (
  <MdSegmentedButtonSet
    aria-label="Calendar view"
    onMdChange={(e) => {
      const [next] = e.detail;
      if (next) setView(next);
    }}
  >
    <MdSegmentedButton value="day" label="Day" selected={view === 'day'} />
    <MdSegmentedButton value="week" label="Week" selected={view === 'week'} />
    <MdSegmentedButton value="month" label="Month" selected={view === 'month'} />
  </MdSegmentedButtonSet>
);
}

Copy

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

@Component({
selector: 'app-calendar-view',
template: `
  <md-segmented-button-set aria-label="Calendar view" (mdChange)="onChange($event)">
    <md-segmented-button value="day" label="Day" selected></md-segmented-button>
    <md-segmented-button value="week" label="Week"></md-segmented-button>
    <md-segmented-button value="month" label="Month"></md-segmented-button>
  </md-segmented-button-set>
`,
})
export class CalendarViewComponent {
view = 'day';

onChange(e: CustomEvent<string[]>) {
  const [next] = e.detail;
  if (next) this.view = next;
}
}

Copy

<script setup lang="ts">
import { ref } from 'vue';
const view = ref('day');

function onChange(e: CustomEvent) {
const [next] = e.detail;
if (next) view.value = next;
}
</script>

<template>
<md-segmented-button-set aria-label="Calendar view" @mdChange="onChange">
  <md-segmented-button value="day" label="Day" selected />
  <md-segmented-button value="week" label="Week" />
  <md-segmented-button value="month" label="Month" />
</md-segmented-button-set>
</template>

Copy

<script lang="ts">
let view = 'day';

function onChange(e: CustomEvent) {
  const [next] = e.detail;
  if (next) view = next;
}
</script>

<md-segmented-button-set aria-label="Calendar view" on:mdChange={onChange}>
<md-segmented-button value="day" label="Day" selected></md-segmented-button>
<md-segmented-button value="week" label="Week"></md-segmented-button>
<md-segmented-button value="month" label="Month"></md-segmented-button>
</md-segmented-button-set>

API Reference

The set element — <md-segmented-button-set>.

tune

Properties

Property	Attribute	Type	Default	Reflects
multiselect	multiselect	boolean	false	—
density	density	0 | -1 | -2 | -3 | -4	0	Yes

view_in_ar

Slots

Slot	Description
(default)	—

Accessibility

• The set is role="radiogroup" in single-select and role="group" in multiselect. Give the set an aria-label naming what it controls — the children name themselves via their label.
• Icon-only segments have no accessible name; add aria-label to each.
• The checkmark is the non-colour selection cue. Think hard before no-checkmark, especially in multiselect.
• disabled leaves the tab order; soft-disabled stays focusable.
• Arrow keys move focus within the set and wrap around, skipping disabled segments. In single-select, arrowing also selects — the WAI-ARIA radiogroup pattern. Enter and Space activate.

Tab in, then arrow — focus wraps and skips the disabled segment

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- 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-segmented-button-set aria-label="Transport">
  <md-segmented-button value="car" icon="directions_car" label="Car" selected></md-segmented-button>
  <md-segmented-button value="bus" icon="directions_bus" label="Bus"></md-segmented-button>
  <md-segmented-button value="rail" icon="train" label="Rail" disabled></md-segmented-button>
  <md-segmented-button value="bike" icon="pedal_bike" label="Bike"></md-segmented-button>
</md-segmented-button-set>

Copy

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

export function Demo() {
  return (
    <>
      <MdSegmentedButtonSet aria-label="Transport">
        <MdSegmentedButton value="car" icon="directions_car" label="Car" selected></MdSegmentedButton>
        <MdSegmentedButton value="bus" icon="directions_bus" label="Bus"></MdSegmentedButton>
        <MdSegmentedButton value="rail" icon="train" label="Rail" disabled></MdSegmentedButton>
        <MdSegmentedButton value="bike" icon="pedal_bike" label="Bike"></MdSegmentedButton>
      </MdSegmentedButtonSet>
    </>
  );
}

Copy

// 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-segmented-button-set aria-label="Transport">
  <md-segmented-button value="car" icon="directions_car" label="Car" selected></md-segmented-button>
  <md-segmented-button value="bus" icon="directions_bus" label="Bus"></md-segmented-button>
  <md-segmented-button value="rail" icon="train" label="Rail" disabled></md-segmented-button>
  <md-segmented-button value="bike" icon="pedal_bike" label="Bike"></md-segmented-button>
</md-segmented-button-set>

Copy

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

<template>
  <md-segmented-button-set aria-label="Transport">
    <md-segmented-button value="car" icon="directions_car" label="Car" selected></md-segmented-button>
    <md-segmented-button value="bus" icon="directions_bus" label="Bus"></md-segmented-button>
    <md-segmented-button value="rail" icon="train" label="Rail" disabled></md-segmented-button>
    <md-segmented-button value="bike" icon="pedal_bike" label="Bike"></md-segmented-button>
  </md-segmented-button-set>
</template>

Copy

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

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

<md-segmented-button-set aria-label="Transport">
  <md-segmented-button value="car" icon="directions_car" label="Car" selected></md-segmented-button>
  <md-segmented-button value="bus" icon="directions_bus" label="Bus"></md-segmented-button>
  <md-segmented-button value="rail" icon="train" label="Rail" disabled></md-segmented-button>
  <md-segmented-button value="bike" icon="pedal_bike" label="Bike"></md-segmented-button>
</md-segmented-button-set>

RTL, density & i18n

RTL — the set lays its segments out with grid-auto-flow: column, and the end caps use logical corner properties (border-start-start-radius and friends), so segment order and the rounding both flip under dir="rtl" with nothing re-authored. There is no mirror-icon prop here: a directional glyph has to be swapped by you. See RTL.

<div dir="rtl">
  <md-segmented-button-set aria-label="العرض">
    <md-segmented-button value="day" label="يوم" selected></md-segmented-button>
    <md-segmented-button value="week" label="أسبوع"></md-segmented-button>
  </md-segmented-button-set>
</div>

The same set in both directions. Only dir changes between these two rows — the selected end cap moves to the other end on its own:

Same markup, dir=ltr vs dir=rtl

ltr

rtl

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- 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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr">
    <md-segmented-button-set aria-label="View">
      <md-segmented-button value="day" icon="today" label="Day" selected></md-segmented-button>
      <md-segmented-button value="week" icon="date_range" label="Week"></md-segmented-button>
      <md-segmented-button value="month" icon="calendar_month" label="Month"></md-segmented-button>
    </md-segmented-button-set>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl">
    <md-segmented-button-set aria-label="العرض">
      <md-segmented-button value="day" icon="today" label="يوم" selected></md-segmented-button>
      <md-segmented-button value="week" icon="date_range" label="أسبوع"></md-segmented-button>
      <md-segmented-button value="month" icon="calendar_month" label="شهر"></md-segmented-button>
    </md-segmented-button-set>
  </div>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: "grid", gridTemplateColumns: "auto 1fr", gap: "14px 16px", alignItems: "center" }}>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>ltr</span>
        <div dir="ltr">
          <MdSegmentedButtonSet aria-label="View">
            <MdSegmentedButton value="day" icon="today" label="Day" selected></MdSegmentedButton>
            <MdSegmentedButton value="week" icon="date_range" label="Week"></MdSegmentedButton>
            <MdSegmentedButton value="month" icon="calendar_month" label="Month"></MdSegmentedButton>
          </MdSegmentedButtonSet>
        </div>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>rtl</span>
        <div dir="rtl">
          <MdSegmentedButtonSet aria-label="العرض">
            <MdSegmentedButton value="day" icon="today" label="يوم" selected></MdSegmentedButton>
            <MdSegmentedButton value="week" icon="date_range" label="أسبوع"></MdSegmentedButton>
            <MdSegmentedButton value="month" icon="calendar_month" label="شهر"></MdSegmentedButton>
          </MdSegmentedButtonSet>
        </div>
      </div>
    </>
  );
}

Copy

// 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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr">
    <md-segmented-button-set aria-label="View">
      <md-segmented-button value="day" icon="today" label="Day" selected></md-segmented-button>
      <md-segmented-button value="week" icon="date_range" label="Week"></md-segmented-button>
      <md-segmented-button value="month" icon="calendar_month" label="Month"></md-segmented-button>
    </md-segmented-button-set>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl">
    <md-segmented-button-set aria-label="العرض">
      <md-segmented-button value="day" icon="today" label="يوم" selected></md-segmented-button>
      <md-segmented-button value="week" icon="date_range" label="أسبوع"></md-segmented-button>
      <md-segmented-button value="month" icon="calendar_month" label="شهر"></md-segmented-button>
    </md-segmented-button-set>
  </div>
</div>

Copy

<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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
    <div dir="ltr">
      <md-segmented-button-set aria-label="View">
        <md-segmented-button value="day" icon="today" label="Day" selected></md-segmented-button>
        <md-segmented-button value="week" icon="date_range" label="Week"></md-segmented-button>
        <md-segmented-button value="month" icon="calendar_month" label="Month"></md-segmented-button>
      </md-segmented-button-set>
    </div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
    <div dir="rtl">
      <md-segmented-button-set aria-label="العرض">
        <md-segmented-button value="day" icon="today" label="يوم" selected></md-segmented-button>
        <md-segmented-button value="week" icon="date_range" label="أسبوع"></md-segmented-button>
        <md-segmented-button value="month" icon="calendar_month" label="شهر"></md-segmented-button>
      </md-segmented-button-set>
    </div>
  </div>
</template>

Copy

<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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr">
    <md-segmented-button-set aria-label="View">
      <md-segmented-button value="day" icon="today" label="Day" selected></md-segmented-button>
      <md-segmented-button value="week" icon="date_range" label="Week"></md-segmented-button>
      <md-segmented-button value="month" icon="calendar_month" label="Month"></md-segmented-button>
    </md-segmented-button-set>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl">
    <md-segmented-button-set aria-label="العرض">
      <md-segmented-button value="day" icon="today" label="يوم" selected></md-segmented-button>
      <md-segmented-button value="week" icon="date_range" label="أسبوع"></md-segmented-button>
      <md-segmented-button value="month" icon="calendar_month" label="شهر"></md-segmented-button>
    </md-segmented-button-set>
  </div>
</div>

Directional glyphs are yours to swap

Layout mirrors itself; a glyph does not. A chevron or an arrow still points the LTR way under dir="rtl", so pick the mirrored Material Symbol yourself (chevron_left for “next”, arrow_back for “forward”). Non-directional glyphs — today, star, person — need nothing:

Directional glyphs under RTL — swapped vs left as-authored

correct

wrong

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- 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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div dir="rtl">
    <md-segmented-button-set aria-label="التنقل الصحيح">
      <md-segmented-button value="prev" icon="chevron_right" label="السابق" selected></md-segmented-button>
      <md-segmented-button value="next" icon="chevron_left" label="التالي"></md-segmented-button>
      <md-segmented-button value="star" icon="star" label="مميز"></md-segmented-button>
    </md-segmented-button-set>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div dir="rtl">
    <md-segmented-button-set aria-label="التنقل الخاطئ">
      <md-segmented-button value="prev" icon="chevron_left" label="السابق" selected></md-segmented-button>
      <md-segmented-button value="next" icon="chevron_right" label="التالي"></md-segmented-button>
      <md-segmented-button value="star" icon="star" label="مميز"></md-segmented-button>
    </md-segmented-button-set>
  </div>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: "grid", gridTemplateColumns: "auto 1fr", gap: "14px 16px", alignItems: "center" }}>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>correct</span>
        <div dir="rtl">
          <MdSegmentedButtonSet aria-label="التنقل الصحيح">
            <MdSegmentedButton value="prev" icon="chevron_right" label="السابق" selected></MdSegmentedButton>
            <MdSegmentedButton value="next" icon="chevron_left" label="التالي"></MdSegmentedButton>
            <MdSegmentedButton value="star" icon="star" label="مميز"></MdSegmentedButton>
          </MdSegmentedButtonSet>
        </div>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>wrong</span>
        <div dir="rtl">
          <MdSegmentedButtonSet aria-label="التنقل الخاطئ">
            <MdSegmentedButton value="prev" icon="chevron_left" label="السابق" selected></MdSegmentedButton>
            <MdSegmentedButton value="next" icon="chevron_right" label="التالي"></MdSegmentedButton>
            <MdSegmentedButton value="star" icon="star" label="مميز"></MdSegmentedButton>
          </MdSegmentedButtonSet>
        </div>
      </div>
    </>
  );
}

Copy

// 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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div dir="rtl">
    <md-segmented-button-set aria-label="التنقل الصحيح">
      <md-segmented-button value="prev" icon="chevron_right" label="السابق" selected></md-segmented-button>
      <md-segmented-button value="next" icon="chevron_left" label="التالي"></md-segmented-button>
      <md-segmented-button value="star" icon="star" label="مميز"></md-segmented-button>
    </md-segmented-button-set>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div dir="rtl">
    <md-segmented-button-set aria-label="التنقل الخاطئ">
      <md-segmented-button value="prev" icon="chevron_left" label="السابق" selected></md-segmented-button>
      <md-segmented-button value="next" icon="chevron_right" label="التالي"></md-segmented-button>
      <md-segmented-button value="star" icon="star" label="مميز"></md-segmented-button>
    </md-segmented-button-set>
  </div>
</div>

Copy

<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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
    <div dir="rtl">
      <md-segmented-button-set aria-label="التنقل الصحيح">
        <md-segmented-button value="prev" icon="chevron_right" label="السابق" selected></md-segmented-button>
        <md-segmented-button value="next" icon="chevron_left" label="التالي"></md-segmented-button>
        <md-segmented-button value="star" icon="star" label="مميز"></md-segmented-button>
      </md-segmented-button-set>
    </div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
    <div dir="rtl">
      <md-segmented-button-set aria-label="التنقل الخاطئ">
        <md-segmented-button value="prev" icon="chevron_left" label="السابق" selected></md-segmented-button>
        <md-segmented-button value="next" icon="chevron_right" label="التالي"></md-segmented-button>
        <md-segmented-button value="star" icon="star" label="مميز"></md-segmented-button>
      </md-segmented-button-set>
    </div>
  </div>
</template>

Copy

<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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div dir="rtl">
    <md-segmented-button-set aria-label="التنقل الصحيح">
      <md-segmented-button value="prev" icon="chevron_right" label="السابق" selected></md-segmented-button>
      <md-segmented-button value="next" icon="chevron_left" label="التالي"></md-segmented-button>
      <md-segmented-button value="star" icon="star" label="مميز"></md-segmented-button>
    </md-segmented-button-set>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div dir="rtl">
    <md-segmented-button-set aria-label="التنقل الخاطئ">
      <md-segmented-button value="prev" icon="chevron_left" label="السابق" selected></md-segmented-button>
      <md-segmented-button value="next" icon="chevron_right" label="التالي"></md-segmented-button>
      <md-segmented-button value="star" icon="star" label="مميز"></md-segmented-button>
    </md-segmented-button-set>
  </div>
</div>

Every density rung

density on the set cascades to every segment, so the row stays uniform. The rungs map to concrete heights:

Rung	Height
0	40px
-1	36px
-2	32px
-3	28px
-4	24px

Density 0 through -4 — height, gap, label and glyph all taper

0 -1 -2 -3 -4

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- 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="inline-size:100%;display:grid;grid-template-columns:auto 1fr;gap:12px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <md-segmented-button-set density="0" aria-label="Density 0">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <md-segmented-button-set density="-1" aria-label="Density -1">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <md-segmented-button-set density="-2" aria-label="Density -2">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <md-segmented-button-set density="-3" aria-label="Density -3">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <md-segmented-button-set density="-4" aria-label="Density -4">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ inlineSize: "100%", display: "grid", gridTemplateColumns: "auto 1fr", gap: "12px 16px", alignItems: "center" }}>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>0</span>
        <MdSegmentedButtonSet density="0" aria-label="Density 0">
          <MdSegmentedButton value="l" icon="view_list" label="List" selected></MdSegmentedButton>
          <MdSegmentedButton value="g" icon="grid_view" label="Grid"></MdSegmentedButton>
        </MdSegmentedButtonSet>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>-1</span>
        <MdSegmentedButtonSet density="-1" aria-label="Density -1">
          <MdSegmentedButton value="l" icon="view_list" label="List" selected></MdSegmentedButton>
          <MdSegmentedButton value="g" icon="grid_view" label="Grid"></MdSegmentedButton>
        </MdSegmentedButtonSet>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>-2</span>
        <MdSegmentedButtonSet density="-2" aria-label="Density -2">
          <MdSegmentedButton value="l" icon="view_list" label="List" selected></MdSegmentedButton>
          <MdSegmentedButton value="g" icon="grid_view" label="Grid"></MdSegmentedButton>
        </MdSegmentedButtonSet>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>-3</span>
        <MdSegmentedButtonSet density="-3" aria-label="Density -3">
          <MdSegmentedButton value="l" icon="view_list" label="List" selected></MdSegmentedButton>
          <MdSegmentedButton value="g" icon="grid_view" label="Grid"></MdSegmentedButton>
        </MdSegmentedButtonSet>
        <span style={{ inlineSize: "3.5rem", opacity: ".65", fontSize: ".75rem", fontFamily: "ui-monospace,monospace" }}>-4</span>
        <MdSegmentedButtonSet density="-4" aria-label="Density -4">
          <MdSegmentedButton value="l" icon="view_list" label="List" selected></MdSegmentedButton>
          <MdSegmentedButton value="g" icon="grid_view" label="Grid"></MdSegmentedButton>
        </MdSegmentedButtonSet>
      </div>
    </>
  );
}

Copy

// 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="inline-size:100%;display:grid;grid-template-columns:auto 1fr;gap:12px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <md-segmented-button-set density="0" aria-label="Density 0">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <md-segmented-button-set density="-1" aria-label="Density -1">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <md-segmented-button-set density="-2" aria-label="Density -2">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <md-segmented-button-set density="-3" aria-label="Density -3">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <md-segmented-button-set density="-4" aria-label="Density -4">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
</div>

Copy

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

<template>
  <div style="inline-size:100%;display:grid;grid-template-columns:auto 1fr;gap:12px 16px;align-items:center;">
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
    <md-segmented-button-set density="0" aria-label="Density 0">
      <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
      <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
    </md-segmented-button-set>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
    <md-segmented-button-set density="-1" aria-label="Density -1">
      <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
      <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
    </md-segmented-button-set>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
    <md-segmented-button-set density="-2" aria-label="Density -2">
      <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
      <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
    </md-segmented-button-set>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
    <md-segmented-button-set density="-3" aria-label="Density -3">
      <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
      <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
    </md-segmented-button-set>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
    <md-segmented-button-set density="-4" aria-label="Density -4">
      <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
      <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
    </md-segmented-button-set>
  </div>
</template>

Copy

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

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

<div style="inline-size:100%;display:grid;grid-template-columns:auto 1fr;gap:12px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <md-segmented-button-set density="0" aria-label="Density 0">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <md-segmented-button-set density="-1" aria-label="Density -1">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <md-segmented-button-set density="-2" aria-label="Density -2">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <md-segmented-button-set density="-3" aria-label="Density -3">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <md-segmented-button-set density="-4" aria-label="Density -4">
    <md-segmented-button value="l" icon="view_list" label="List" selected></md-segmented-button>
    <md-segmented-button value="g" icon="grid_view" label="Grid"></md-segmented-button>
  </md-segmented-button-set>
</div>

Below -2, check your touch targets

The rungs shrink the hit area with the row: 40px at 0 down to 24px at -4. That is well under what pointer-coarse devices want, and the segments have no padding to spare. See Density for the media query that raises the target back on touch.

Density and direction together

They are independent signals and compose without extra wiring — a global data-density ancestor drives the same --md-sys-density-scale the density prop does:

dir=rtl with data-density=-2 on the ancestor

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- 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 dir="rtl" data-density="-2">
  <md-segmented-button-set aria-label="المرشحات" multiselect>
    <md-segmented-button value="unread" icon="mark_email_unread" label="غير مقروء" selected></md-segmented-button>
    <md-segmented-button value="starred" icon="star" label="مميز"></md-segmented-button>
    <md-segmented-button value="mine" icon="person" label="لي" selected></md-segmented-button>
  </md-segmented-button-set>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div dir="rtl" data-density="-2">
        <MdSegmentedButtonSet aria-label="المرشحات" multiselect>
          <MdSegmentedButton value="unread" icon="mark_email_unread" label="غير مقروء" selected></MdSegmentedButton>
          <MdSegmentedButton value="starred" icon="star" label="مميز"></MdSegmentedButton>
          <MdSegmentedButton value="mine" icon="person" label="لي" selected></MdSegmentedButton>
        </MdSegmentedButtonSet>
      </div>
    </>
  );
}

Copy

// 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 dir="rtl" data-density="-2">
  <md-segmented-button-set aria-label="المرشحات" multiselect>
    <md-segmented-button value="unread" icon="mark_email_unread" label="غير مقروء" selected></md-segmented-button>
    <md-segmented-button value="starred" icon="star" label="مميز"></md-segmented-button>
    <md-segmented-button value="mine" icon="person" label="لي" selected></md-segmented-button>
  </md-segmented-button-set>
</div>

Copy

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

<template>
  <div dir="rtl" data-density="-2">
    <md-segmented-button-set aria-label="المرشحات" multiselect>
      <md-segmented-button value="unread" icon="mark_email_unread" label="غير مقروء" selected></md-segmented-button>
      <md-segmented-button value="starred" icon="star" label="مميز"></md-segmented-button>
      <md-segmented-button value="mine" icon="person" label="لي" selected></md-segmented-button>
    </md-segmented-button-set>
  </div>
</template>

Copy

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

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

<div dir="rtl" data-density="-2">
  <md-segmented-button-set aria-label="المرشحات" multiselect>
    <md-segmented-button value="unread" icon="mark_email_unread" label="غير مقروء" selected></md-segmented-button>
    <md-segmented-button value="starred" icon="star" label="مميز"></md-segmented-button>
    <md-segmented-button value="mine" icon="person" label="لي" selected></md-segmented-button>
  </md-segmented-button-set>
</div>

Density — set density on the set so every segment matches; the same rung on a child overrides the cascaded one. See Density.

i18n — translate the child labels; they come straight from your i18n layer, and lang/dir are inherited from any ancestor. Localize each icon-only segment’s aria-label and the set’s aria-label too. Translated labels vary in length and M3 asks for similar-length, non-wrapping labels, so re-check the set per locale.

Theming

The set exposes no custom properties of its own — theme the children. Apply the properties on md-segmented-button, or on md-segmented-button-set to cascade to every segment.

Custom property	Purpose	Default
--md-segmented-button-container-color	Unselected background	transparent
--md-segmented-button-selected-container-color	Selected background	secondary-container
--md-segmented-button-label-color	Unselected label/icon color	on-surface
--md-segmented-button-selected-label-color	Selected label/icon color	on-secondary-container
--md-segmented-button-outline-color	Divider / outline	outline
--md-segmented-button-container-shape	End-cap radius	shape-corner-full
--md-segmented-button-icon-size	Glyph size	18px, tapering with density

Themed sets

Show code for each technology

HTML React Angular Vue Svelte

Copy

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

<md-segmented-button-set aria-label="Themed" style="--md-segmented-button-selected-container-color: var(--md-sys-color-tertiary-container); --md-segmented-button-selected-label-color: var(--md-sys-color-on-tertiary-container); --md-segmented-button-outline-color: var(--md-sys-color-tertiary);">
  <md-segmented-button value="a" label="Tertiary" selected></md-segmented-button>
  <md-segmented-button value="b" label="Tinted"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Squared" style="--md-segmented-button-container-shape: 6px;">
  <md-segmented-button value="a" label="Squared" selected></md-segmented-button>
  <md-segmented-button value="b" label="Off"></md-segmented-button>
</md-segmented-button-set>

Copy

import { MdSegmentedButton, MdSegmentedButtonSet } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdSegmentedButtonSet aria-label="Themed" style={{ "--md-segmented-button-selected-container-color": "var(--md-sys-color-tertiary-container)", "--md-segmented-button-selected-label-color": "var(--md-sys-color-on-tertiary-container)", "--md-segmented-button-outline-color": "var(--md-sys-color-tertiary)" }}>
        <MdSegmentedButton value="a" label="Tertiary" selected></MdSegmentedButton>
        <MdSegmentedButton value="b" label="Tinted"></MdSegmentedButton>
      </MdSegmentedButtonSet>

      <MdSegmentedButtonSet aria-label="Squared" style={{ "--md-segmented-button-container-shape": "6px" }}>
        <MdSegmentedButton value="a" label="Squared" selected></MdSegmentedButton>
        <MdSegmentedButton value="b" label="Off"></MdSegmentedButton>
      </MdSegmentedButtonSet>
    </>
  );
}

Copy

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

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

<!-- app.component.html -->
<md-segmented-button-set aria-label="Themed" style="--md-segmented-button-selected-container-color: var(--md-sys-color-tertiary-container); --md-segmented-button-selected-label-color: var(--md-sys-color-on-tertiary-container); --md-segmented-button-outline-color: var(--md-sys-color-tertiary);">
  <md-segmented-button value="a" label="Tertiary" selected></md-segmented-button>
  <md-segmented-button value="b" label="Tinted"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Squared" style="--md-segmented-button-container-shape: 6px;">
  <md-segmented-button value="a" label="Squared" selected></md-segmented-button>
  <md-segmented-button value="b" label="Off"></md-segmented-button>
</md-segmented-button-set>

Copy

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

<template>
  <md-segmented-button-set aria-label="Themed" style="--md-segmented-button-selected-container-color: var(--md-sys-color-tertiary-container); --md-segmented-button-selected-label-color: var(--md-sys-color-on-tertiary-container); --md-segmented-button-outline-color: var(--md-sys-color-tertiary);">
    <md-segmented-button value="a" label="Tertiary" selected></md-segmented-button>
    <md-segmented-button value="b" label="Tinted"></md-segmented-button>
  </md-segmented-button-set>

  <md-segmented-button-set aria-label="Squared" style="--md-segmented-button-container-shape: 6px;">
    <md-segmented-button value="a" label="Squared" selected></md-segmented-button>
    <md-segmented-button value="b" label="Off"></md-segmented-button>
  </md-segmented-button-set>
</template>

Copy

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

<md-segmented-button-set aria-label="Themed" style="--md-segmented-button-selected-container-color: var(--md-sys-color-tertiary-container); --md-segmented-button-selected-label-color: var(--md-sys-color-on-tertiary-container); --md-segmented-button-outline-color: var(--md-sys-color-tertiary);">
  <md-segmented-button value="a" label="Tertiary" selected></md-segmented-button>
  <md-segmented-button value="b" label="Tinted"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set aria-label="Squared" style="--md-segmented-button-container-shape: 6px;">
  <md-segmented-button value="a" label="Squared" selected></md-segmented-button>
  <md-segmented-button value="b" label="Off"></md-segmented-button>
</md-segmented-button-set>

CSS parts reach inside the segment’s shadow root for what custom properties do not cover. Every part lives on md-segmented-button, never on the set:

::part(label) overrides and a custom-property brand set

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- 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>
  .caps-seg::part(label) { text-transform: uppercase; letter-spacing: .08em; font-weight: 600; }
  .brand-set {
  --md-segmented-button-selected-container-color: #1B5E20;
  --md-segmented-button-selected-label-color: #FFFFFF;
  --md-segmented-button-outline-color: #1B5E20;
  --md-segmented-button-container-shape: 8px;
  }
</style>
<md-segmented-button-set aria-label="Uppercase labels">
  <md-segmented-button class="caps-seg" value="l" label="List" selected></md-segmented-button>
  <md-segmented-button class="caps-seg" value="g" label="Grid"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set class="brand-set" aria-label="Brand colours">
  <md-segmented-button value="a" icon="check_circle" label="Live" selected></md-segmented-button>
  <md-segmented-button value="b" icon="pending" label="Draft"></md-segmented-button>
</md-segmented-button-set>

Copy

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

export function Demo() {
  return (
    <>
      <style>
        .caps-seg::part(label) { text-transform: uppercase; letter-spacing: .08em; font-weight: 600; }
        .brand-set {
        --md-segmented-button-selected-container-color: #1B5E20;
        --md-segmented-button-selected-label-color: #FFFFFF;
        --md-segmented-button-outline-color: #1B5E20;
        --md-segmented-button-container-shape: 8px;
        }
      </style>
      <MdSegmentedButtonSet aria-label="Uppercase labels">
        <MdSegmentedButton className="caps-seg" value="l" label="List" selected></MdSegmentedButton>
        <MdSegmentedButton className="caps-seg" value="g" label="Grid"></MdSegmentedButton>
      </MdSegmentedButtonSet>

      <MdSegmentedButtonSet className="brand-set" aria-label="Brand colours">
        <MdSegmentedButton value="a" icon="check_circle" label="Live" selected></MdSegmentedButton>
        <MdSegmentedButton value="b" icon="pending" label="Draft"></MdSegmentedButton>
      </MdSegmentedButtonSet>
    </>
  );
}

Copy

// 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>
  .caps-seg::part(label) { text-transform: uppercase; letter-spacing: .08em; font-weight: 600; }
  .brand-set {
  --md-segmented-button-selected-container-color: #1B5E20;
  --md-segmented-button-selected-label-color: #FFFFFF;
  --md-segmented-button-outline-color: #1B5E20;
  --md-segmented-button-container-shape: 8px;
  }
</style>
<md-segmented-button-set aria-label="Uppercase labels">
  <md-segmented-button class="caps-seg" value="l" label="List" selected></md-segmented-button>
  <md-segmented-button class="caps-seg" value="g" label="Grid"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set class="brand-set" aria-label="Brand colours">
  <md-segmented-button value="a" icon="check_circle" label="Live" selected></md-segmented-button>
  <md-segmented-button value="b" icon="pending" label="Draft"></md-segmented-button>
</md-segmented-button-set>

Copy

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

<template>
  <style>
    .caps-seg::part(label) { text-transform: uppercase; letter-spacing: .08em; font-weight: 600; }
    .brand-set {
    --md-segmented-button-selected-container-color: #1B5E20;
    --md-segmented-button-selected-label-color: #FFFFFF;
    --md-segmented-button-outline-color: #1B5E20;
    --md-segmented-button-container-shape: 8px;
    }
  </style>
  <md-segmented-button-set aria-label="Uppercase labels">
    <md-segmented-button class="caps-seg" value="l" label="List" selected></md-segmented-button>
    <md-segmented-button class="caps-seg" value="g" label="Grid"></md-segmented-button>
  </md-segmented-button-set>

  <md-segmented-button-set class="brand-set" aria-label="Brand colours">
    <md-segmented-button value="a" icon="check_circle" label="Live" selected></md-segmented-button>
    <md-segmented-button value="b" icon="pending" label="Draft"></md-segmented-button>
  </md-segmented-button-set>
</template>

Copy

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

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

<style>
  .caps-seg::part(label) { text-transform: uppercase; letter-spacing: .08em; font-weight: 600; }
  .brand-set {
  --md-segmented-button-selected-container-color: #1B5E20;
  --md-segmented-button-selected-label-color: #FFFFFF;
  --md-segmented-button-outline-color: #1B5E20;
  --md-segmented-button-container-shape: 8px;
  }
</style>
<md-segmented-button-set aria-label="Uppercase labels">
  <md-segmented-button class="caps-seg" value="l" label="List" selected></md-segmented-button>
  <md-segmented-button class="caps-seg" value="g" label="Grid"></md-segmented-button>
</md-segmented-button-set>

<md-segmented-button-set class="brand-set" aria-label="Brand colours">
  <md-segmented-button value="a" icon="check_circle" label="Live" selected></md-segmented-button>
  <md-segmented-button value="b" icon="pending" label="Draft"></md-segmented-button>
</md-segmented-button-set>

Part	What it is
state-layer	The hover / press overlay
label	The label text
icon	The leading glyph, while the segment is unselected
checkmark	The same slot in the layout once the segment is selected

icon and checkmark are the same element under two names: one span swaps between your glyph and the check, and its part swaps with it. That is why a rule on ::part(icon) stops applying the moment the segment is selected — style both if you want the treatment to survive selection.

md-segmented-button::part(label) {
  letter-spacing: 0.4px;
}

md-segmented-button::part(icon),
md-segmented-button::part(checkmark) {
  font-size: 20px;
}

Not in the generated API table

icon and checkmark are missing from the parts list in the API Reference below. Stencil’s docs generator only sees literal part="…" strings, and these two come from an expression. They are documented in the component’s own CSS header and are as public as the other two.

The segment — md-segmented-button

Each segment is an md-segmented-button. It has its own props and parts, documented here rather than on a separate page: outside a set it is only half a component, and inside one the parent writes four of its props itself.

Segment API Reference

tune

Properties

Property	Attribute	Type	Default	Reflects
value	value	string	''	—
selected	selected	boolean	false	Yes
disabled	disabled	boolean	false	Yes
softDisabled	soft-disabled	boolean	false	Yes
icon	icon	string	''	—
label	label	string	''	—
noCheckmark	no-checkmark	boolean	false	—
ripple	ripple	boolean	true	—
segmentIndex	segment-index	number	0	—
segmentTotal	segment-total	number	1	—
segmentDensity	segment-density	number	0	—
segmentMultiselect	segment-multiselect	boolean	false	—
density	density	0 | -1 | -2 | -3 | -4	0	Yes

view_in_ar

Slots

Slot	Description
(default)	—
icon	Custom icon (replaces icon prop)

palette

CSS Custom Properties

Override on the host element for per-instance theming:

Property	Description
--md-segmented-button-container-color	Unselected bg
--md-segmented-button-selected-container-color	Selected bg
--md-segmented-button-label-color	Unselected text
--md-segmented-button-selected-label-color	Selected text
--md-segmented-button-outline-color	Outline color
--md-segmented-button-container-shape	Border-radius
--md-segmented-button-icon-size	Icon dimensions

layers

CSS Shadow Parts

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

Part	Description
state-layer	Hover/press overlay
label	Label text

Parent-managed props

segmentIndex, segmentTotal, segmentDensity and segmentMultiselect appear in the table above because they are real props, but they are owned by the set — it writes them on load and whenever multiselect or density changes. Never set them yourself.

Related

md-button-group · md-tabs · md-chip · md-radio · md-select · md-split-button · md-ripple

AI / LLM Context

For AI Agents — md-segmented-button-set

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-segmented-button-set spec card

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

Copy spec Expand view

Main-LLM spec

AWC UI Operator's Manual

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

Open spec Expand view

md-segmented-button-set readme.md

Copy readme

# md-segmented-button-set

<!-- llm:meta
tag: md-segmented-button-set
category: actions
status: md3-mapped
m3-guidelines: https://m3.material.io/components/segmented-buttons/guidelines
form-associated: false
depends-on: none
used-by: none
accepts-children: md-segmented-button
-->

**A choice between 2–5 exclusive options, all visible at once.** Wraps
`md-segmented-button` children, owns the selection, and stamps each child with
its position so the fused container renders correct end caps.

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

---

## When to use

- **2–5** mutually exclusive options that the user should see side by side:
  Day / Week / Month, List / Grid, All / Unread.
- Switching a **view or mode**, where the current state should stay visible.
- Multi-select over a small, closed set of filters (`multiselect`).

## When NOT to use

| Situation | Use instead |
|---|---|
| More than five choices | `md-chip` set, `md-select`, or `md-menu` |
| Navigating between destinations or panels | `md-tabs` / `md-navigation-bar` |
| Running actions rather than choosing a state | `md-button-group` |
| A form field that must submit | `md-radio` / `md-checkbox` |
| One default action plus variants | `md-split-button` |
| Choosing from a long or dynamic list | `md-select` |
| Free-form multi-select of many tags | `md-multi-select`, `md-chip` |

## Decision cues

| Need | Setting |
|---|---|
| One choice at a time | default (`multiselect` off) → `role="radiogroup"` |
| Several at once, and clicking again clears a choice | `multiselect` → `role="group"` |
| Compact rows | `density="-1"`…`"-4"` (0 = 40px, −4 = 24px) |
| Hide the selected checkmark | `no-checkmark` on the children |
| Pre-select an option | `selected` on that child |

## API contract

```html
<md-segmented-button-set multiselect aria-label="View mode">
  <md-segmented-button value="day"   label="Day" selected></md-segmented-button>
  <md-segmented-button value="week"  label="Week"></md-segmented-button>
  <md-segmented-button value="month" label="Month"></md-segmented-button>
</md-segmented-button-set>
```

| Prop | Attribute | Type | Default | Purpose |
|---|---|---|---|---|
| `multiselect` | `multiselect` | `boolean` | `false` | Allow several selections, and allow clearing one |
| `density` | `density` | `-1` … `-4` | `0` | 0 = 40px, −1 = 36px, −2 = 32px, −3 = 28px, −4 = 24px |

Rung `0` is the uncompacted default and has no CSS rule, so `density="0"` does
nothing — it does **not** opt the set out of an inherited `data-density`
ancestor. Use `style="--md-sys-density-scale: 0"` for that.

**Slots** — `(default)`: `md-segmented-button` children. No named slots.

**Methods** — none.

**Parts** — none; the set renders only a `<slot>`.

**Events**

| Event | Detail | Bubbles / composed | Fires |
|---|---|---|---|
| `mdChange` | `string[]` — the `value` of every selected segment, in DOM order | yes / yes | On every segment activation |

### Behavioral contract worth knowing

- The set **owns selection.** A segment never toggles itself: it emits an
  internal `mdSegmentClick`, and the set writes `selected` — on the clicked
  segment in `multiselect`, or on the clicked one and off every sibling in
  single-select — then emits `mdChange` with the full snapshot.
- **Single-select cannot be emptied by clicking.** Clicking the already-selected
  segment re-selects it and re-emits the same array. Only `multiselect` lets a
  click clear a choice, so only there can `mdChange` carry `[]`.
- `mdChange` fires on **every** activation, including one that leaves the
  selection unchanged. It never fires on mount.
- The set consumes the children's `mdSegmentClick` and calls
  `stopPropagation()`, so that event never reaches your listeners.
- It writes `segmentIndex`, `segmentTotal`, `segmentDensity`, and
  `segmentMultiselect` onto each child so they can render the correct end caps
  and checkbox/radio role. **Never set those yourself.**
- Those stamps are applied on load and whenever `multiselect` or `density`
  changes — there is no mutation observer. Segments appended later are clickable
  but keep a stale `segmentIndex` / `segmentTotal`, so render the full set of
  segments up front (M3 caps it at five anyway).
- `role` is `radiogroup` in single-select, `group` in `multiselect`. Give the
  set an `aria-label`; it has no naming prop, so the plain attribute is used.
- There is **no roving tabindex**: every enabled segment is its own Tab stop.
  Arrow keys move between segments (and select in single-select) — see
  [`md-segmented-button`](../md-segmented-button).
- Set the initial selection with `selected` on a child, not on the set — the set
  has no `value` prop, and nothing is selected by default.
- Layout is an inline grid of equal-width columns, so every segment is as wide
  as the widest one and the set shrink-wraps its content rather than stretching.

---

## Do / Don't

Sourced from [M3 · Segmented buttons · Guidelines](https://m3.material.io/components/segmented-buttons/guidelines).

| ✅ Do | ❌ Don't |
|---|---|
| Use for **2–5** choices | Don't exceed five segments — scope the choices or switch to chips |
| Keep labels short and similar in length | Don't let segments wrap onto a new line |
| Use a consistent label type across all segments | Don't mix icon-only and text segments in one set |
| Use icons instead of labels only when the meaning is unmistakable | Don't use ambiguous icon-only segments |
| Leave adequate margin around the set | Don't let the container reach the viewport edge |
| Cap the padding inside segments on large screens | Don't let the set span the full width of a wide pane — it becomes hard to use |
| Give the set an `aria-label` for what it controls | Don't leave a radiogroup unnamed |

---

## Patterns

```html
<!-- Single-select view switch -->
<md-segmented-button-set aria-label="Calendar view">
  <md-segmented-button value="day"   label="Day" selected></md-segmented-button>
  <md-segmented-button value="week"  label="Week"></md-segmented-button>
  <md-segmented-button value="month" label="Month"></md-segmented-button>
</md-segmented-button-set>

<script type="module">
  document.querySelector('md-segmented-button-set')
    .addEventListener('mdChange', (e) => {
      const [view] = e.detail;   // single-select always reports exactly one
      console.log('view is now', view);
    });
</script>
```

```html
<!-- Multi-select filters: e.detail can be [] here -->
<md-segmented-button-set multiselect aria-label="Filters" id="filters">
  <md-segmented-button value="unread"  label="Unread"  icon="mark_email_unread"></md-segmented-button>
  <md-segmented-button value="starred" label="Starred" icon="star"></md-segmented-button>
  <md-segmented-button value="mine"    label="Mine"    icon="person"></md-segmented-button>
</md-segmented-button-set>

<script type="module">
  document.getElementById('filters').addEventListener('mdChange', (e) => {
    console.log('active filters:', e.detail);   // [] when nothing is on
  });
</script>
```

```html
<!-- Compact, in a dense region -->
<md-segmented-button-set density="-2" aria-label="Layout">
  <md-segmented-button value="list" icon="view_list" label="List" selected></md-segmented-button>
  <md-segmented-button value="grid" icon="grid_view" label="Grid"></md-segmented-button>
</md-segmented-button-set>
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| Six or more segments | Cap at five, or use `md-chip` / `md-select` | M3's hard limit for this component. |
| `<md-segmented-button-set value="week">` | Put `selected` on the child | The set has no `value` prop. |
| Setting `segment-index` / `segment-total` by hand | Let the set stamp them | Set-owned; wrong values break the end caps. |
| Wrapping children in a `<div>` for layout | Keep them direct children | The set is an `inline-grid` with `grid-auto-columns: 1fr`, so only direct children become equal-width columns — a wrapper collapses everything inside it into one column. (Seam collapsing still works, since the set finds segments with a deep `querySelectorAll`.) |
| Appending segments after first render | Render them all up front | The stamps are not re-applied automatically, so end caps go stale. |
| Expecting single-select to become empty | Guard only in `multiselect` | A single-select click always ends with exactly one selection. |
| Assuming `mdChange` means the selection differed | Compare against your own state | It fires on every activation, including a no-op re-click. |
| Using it for tabs | `md-tabs` | Segmented buttons choose a state, not a panel. |
| Mixing an icon-only segment with text segments | Pick one label type | M3 explicitly warns against this. |
| Full-width set on a wide screen | Constrain the width | M3: too much padding makes it less usable. |
| Listening to children's `mdSegmentClick` | Listen to the set's `mdChange` | The set stops that event before it can bubble to you. |
| Toggling a child's `selected` in the `mdChange` handler | Let the set own it | You would fight the write the set just made. |

## Accessibility, RTL, density, i18n

**Accessibility**
- `radiogroup` (single) / `group` (multi). Give the **set** an `aria-label`
  naming what it controls — the children name themselves via their labels.
- Icon-only segments need their own `aria-label`.
- Every enabled segment is a Tab stop (there is no roving tabindex), and arrow
  keys also move between segments, selecting as they go in single-select.
- The selected segment shows a checkmark by default, so selection isn't
  conveyed by color alone. Think twice before `no-checkmark`, especially in
  multiselect.

**RTL** — segment order and end-cap rounding flip with `dir="rtl"`.
Directional icons need swapping yourself.

**Density** — `density` maps to concrete heights: 0 = 40px, −1 = 36px,
−2 = 32px, −3 = 28px, −4 = 24px, and tapers icon size, gap and label type with
them. Below −2, verify touch targets. A child's own `density` attribute
overrides the rung the set stamps.

**i18n** — translate child `label`s. Translated labels vary in length and M3
requires similar-length, non-wrapping labels: re-check the set per locale.
Because the columns are equal-width, the widest translation sets the width of
every segment.

## Related components

`md-segmented-button` · `md-button-group` · `md-tabs` · `md-chip` ·
`md-radio` · `md-select`

## Theming

The set itself reads no custom properties and exposes no CSS parts. Theme the
children with the `--md-segmented-button-*` properties documented in
[`md-segmented-button`](../md-segmented-button); they inherit, so setting them
on the set applies to every segment.

```css
md-segmented-button-set.brand {
  --md-segmented-button-selected-container-color: var(--md-sys-color-tertiary-container);
  --md-segmented-button-selected-label-color: var(--md-sys-color-on-tertiary-container);
}
```

<!-- Auto Generated Below -->


## Properties

| Property      | Attribute     | Description                                                   | Type                        | Default |
| ------------- | ------------- | ------------------------------------------------------------- | --------------------------- | ------- |
| `density`     | `density`     | Density: 0 = 40px, -1 = 36px, -2 = 32px, -3 = 28px, -4 = 24px | `-1 \| -2 \| -3 \| -4 \| 0` | `0`     |
| `multiselect` | `multiselect` | Single-select or multi-select mode                            | `boolean`                   | `false` |


## Events

| Event      | Description                                           | Type                    |
| ---------- | ----------------------------------------------------- | ----------------------- |
| `mdChange` | Fires when the set of selected segment values changes | `CustomEvent<string[]>` |


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

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

AWC UI Operator’s Manual

Copy spec

# main-llm.md — AWC UI build director

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

**Use this reference when building, updating, or reviewing an interface with
AWC UI, a Material Design 3 web-component library.** Start with the user's
request and the existing project. The sections below cover setup, component
selection, composition, and verification; read the sections relevant to the
task. Per-component detail lives in
`./packages/core/src/components/<tag>/readme.md` — e.g.
[`md-button`](./packages/core/src/components/md-button/readme.md).

1. **Match the task's scope** (§1). Reuse decisions from the project and
   conversation. A focused edit does not need a product interview or scaffold.
2. **Choose documented components** using the decision matrix (§5), and read
   each affected component's manual before changing its markup (§6). Check its
   API, `When NOT to use`, accessibility, and `Anti-patterns` sections; do not
   infer behavior from a similar library or sibling component.
3. **Use the existing integration.** For a new app or a requested setup change,
   use §2–§4. For composition, consult §7 and the relevant recipes in §8.
4. **Follow the API and accessibility rules** (§9). Do not invent an `md-*`
   tag, prop, event, slot, CSS part, or token. If the documented API cannot
   satisfy the request, explain the gap and resolve the consequential choice.
5. **Verify the affected behavior** using the applicable checks in §10.
   Report what changed and what was checked. A review reports findings without
   changing files unless a fix was requested.

---

## §1 — Match the task

| Task | How to proceed |
|---|---|
| New app | Establish the app's purpose and use known project or user decisions. Ask only about missing choices that materially affect the result; use reasonable defaults for minor details and state consequential assumptions. Then apply the relevant setup in §2–§4. |
| Existing app or focused fix | Preserve the framework, configuration, design, and product scope unless the request changes them. Inspect the affected code and manuals, then make the requested change. Do not restart discovery or scaffold another app. |
| Review or explanation | Inspect and explain the requested surface. Keep the work read-only unless the user asks for a fix. |

### Optional discovery checklist

Use the questions below as a reference when a new app or requested feature
leaves an important decision open. They are not a required interview, an
ordered sequence, or a reason to stop a focused task. Project configuration
and answers already given in the conversation take precedence; do not ask for
them again. Ask only what matters to the current task, and group related
questions when that helps. The **bold** options are starting defaults for a
new app, not instructions to override an existing project.

### 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,
    the feature needs a third-party editor (TipTap, Lexical, Quill) styled with
    MD3 tokens. Resolve that choice if the project or request does not cover it.

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

Apply this reference to new setup or requested configuration changes. Preserve
an existing project's choices for unrelated work.

| 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 20.3.31+ |
| Vue / Nuxt | `@awc-ui/vue` | Vue 3 |
| Svelte / SvelteKit | `@awc-ui/svelte` | Svelte 5.57+ |
| 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.
  Invalid submissions show the platform's message in the control's own inline
  error styling, with no browser validation popover. Correcting or resetting a
  field clears its generated message. `error` + `error-text` remain available
  for app-provided messages and take precedence over generated messages.
  `checkValidity()` checks silently; `reportValidity()` shows inline errors and
  focuses the first invalid control. Core submit buttons and Enter do the same.
- 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.

The library has 56 components and 25 sub-components, with 81 manuals in total.
Sub-components 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 Reusable interaction patterns

- **One footer for a dialog wizard.** Set `md-stepper.nav = false` and put
  Back / Continue in the dialog's `actions` slot. Keep the steps in the body;
  the dialog owns scrolling and keeps its header/footer visible. In fullscreen
  mode use the header close button for dismissal. Use a real form and submit
  button so Enter and inline validation follow the same path as a click.
- **Overlay handoffs wait for completion.** Use `await search.close(); await
  search.whenClosed();` before opening a result dialog or unmounting search.
  `mdClose` signals the state change; `whenClosed()` includes motion and cleanup.
  Do not replace that contract with a guessed timeout or a second focus trap.
- **Appearance controls fill their allocated space.** For an inline color picker
  in settings, set `--md-color-picker-width: 100%`. Its compact default remains
  appropriate for a popover. No shadow-DOM width overrides or extra tabindex.
- **Loading belongs to the operation.** Use `md-button.loading` for the initiating
  action and `md-skeleton` with `announce=false` for the content being replaced.
  Preserve the content layout, expose one live status, and guard repeated submits.
  Abort or ignore stale responses when the owner closes or a newer request wins.
  Provide inline error/retry and preserve entered values; do not add artificial waits.
- **Separate routing intent from selection synchronization.** `md-navigation-bar`
  emits `mdChange` for both user and programmatic changes. For a controlled router,
  use each `md-navigation-tab`'s `mdTabClick` for user intent, `manual-activation`
  on the bar, and synchronize `activeIndex` from the confirmed route. Avoid routing
  again merely because browser Back/Forward updated the selected index.
- **Keep table chrome outside the column scroller.** Use `slot="top"` and
  `slot="bottom"` on the toolbar and pagination. Set `min-inline-size: 0` on the
  containing grid/flex child and a readable minimum width on the table. Nested
  controls own their keys; do not add row-level Enter/Space interception in apps.

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

Use the checks relevant to the affected components and behavior. For a small
fix, verify the changed interaction and nearby regressions; a new app or broad
change needs wider coverage. Do not turn a focused edit into an unrelated
full-app audit.

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.


## MCP server and reusable skills

Core provides a read-only MCP server (`@awc-ui/mcp`) and `awc-ui-build` / `awc-ui-review` skills. MCP tools `search_components`, `get_component`, `list_guides`, and `get_guide` expose versioned Core documentation. Match the reported Core version to the consumer installation; use local manuals when versions differ. The server is optional and grants no permission for project mutations.

The Core package ships skills in `skills/`; `awc-ui ai-setup --skills` installs them under the consumer project’s `.agents/skills/` without overwriting customized copies. For configuration and skill-installer availability, see [AI integration](https://awc-ui.dev/guides/building-with-ai/#optional-mcp-and-skills). Use existing project and user decisions rather than restarting discovery for a focused edit.

For AI Agents — md-segmented-button

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-segmented-button spec card

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

Copy spec Expand view

Main-LLM spec

AWC UI Operator's Manual

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

Open spec Expand view

md-segmented-button readme.md

Copy readme

# md-segmented-button

<!-- llm:meta
tag: md-segmented-button
category: actions
status: sub-component
parent: md-segmented-button-set
standalone: false
m3-guidelines: https://m3.material.io/components/segmented-buttons/guidelines
form-associated: false
depends-on: md-ripple
used-by: none
-->

**One segment inside a `md-segmented-button-set`.** Carries a value, an
optional icon, a label, and the selected checkmark. The parent set owns
selection and stamps each segment with its position.

> 🧩 **Sub-component.** Only valid as a direct child of
> `md-segmented-button-set`. Standalone it still *renders* — with
> `segment-index="0"` / `segment-total="1"` it counts as both first and last, so
> it draws as a fully rounded pill — but nothing reconciles its selection, so
> clicking it changes nothing.

---

## When to use

- As a child of [`md-segmented-button-set`](../md-segmented-button-set), one per
  choice (M3 allows **2–5**). The set owns selection, keyboard reconciliation
  and the `mdChange` event; this element is the individual option.

## When NOT to use

| Situation | Use instead |
|---|---|
| A standalone toggle | `md-button toggle` |
| An action rather than a state | `md-button` / `md-icon-button` |
| A removable or filterable tag | `md-chip` |
| A panel switch | `md-tab` inside `md-tabs` |
| A form radio option | `md-radio` |
| Anywhere outside the set | Nothing — it won't be managed |

## API contract

```html
<md-segmented-button-set aria-label="Layout">
  <md-segmented-button value="grid" label="Grid" icon="grid_view" selected></md-segmented-button>
  <md-segmented-button value="list" label="List"></md-segmented-button>
</md-segmented-button-set>
```

| Prop | Attribute | Type | Default | Purpose |
|---|---|---|---|---|
| `value` | `value` | `string` | `''` | Identity reported in the set's `mdChange` |
| `label` | `label` | `string` | `''` | Segment text; wins over slotted text |
| `icon` | `icon` | `string` | `''` | Optional Material Symbols glyph |
| `selected` | `selected` | `boolean` | `false` | Selected state, and the way to express the initial selection |
| `disabled` | `disabled` | `boolean` | `false` | Inert, `tabindex="-1"`, skipped by arrow keys |
| `softDisabled` | `soft-disabled` | `boolean` | `false` | Looks disabled and ignores clicks, but stays focusable |
| `noCheckmark` | `no-checkmark` | `boolean` | `false` | **Suppresses** the selected checkmark |
| `ripple` | `ripple` | `boolean` | `true` | Render the `md-ripple` child |
| `density` | `density` | `-1` … `-4` | `0` | Local density rung; overrides the rung the set stamps |

`no-checkmark` **hides** the checkmark. (The one-line description in the
generated Properties table below reads the other way round; the behaviour above
is what the component does.)

**Parent-managed — never set these:** `segmentIndex`, `segmentTotal`,
`segmentDensity`, `segmentMultiselect`.

**Slots** — `(default)` for label content (used only when `label` is empty),
`icon` for a custom glyph in place of the `icon` prop.

**Events** — `mdSegmentClick` with `{ value, selected }`. **Internal**: the set
listens for it and calls `stopPropagation()`, so it never reaches an ancestor.
Listen to the set's `mdChange` instead.

**Methods** — none.

**Parts** — `state-layer`, `label`, plus the leading graphic, which carries
`part="icon"` while it shows the `icon` glyph and `part="checkmark"` while it
shows the selected check.

### Behavioral contract worth knowing

- The segment **does not toggle itself.** A click (or `Enter` / `Space`) only
  emits `mdSegmentClick`; the parent set is what writes `selected` — on this
  segment and, in single-select, on all of its siblings. Outside a set nothing
  ever changes.
- In single-select the emitted `selected` is always `true`: clicking the already
  selected segment cannot clear it. Only `multiselect` on the set produces a
  toggle.
- `selected` on a child is how you express the **initial** selection — the set
  has no `value` prop.
- **Every enabled segment is its own tab stop** (`tabindex="0"`); the set does
  not implement a roving tabindex. `disabled` sets `tabindex="-1"`;
  `soft-disabled` stays focusable and stays in the tab order.
- Arrow keys move focus to the previous/next non-disabled sibling and wrap
  around; `ArrowRight`/`ArrowDown` go forward, `ArrowLeft`/`ArrowUp` back. In
  single-select the arrow also activates the segment it lands on (the WAI-ARIA
  radiogroup pattern). `Home` / `End` are not handled.
- The accessible name comes from `label`, slotted text, or `aria-label`. With
  none of the three, a development-build console warning is logged.
- Slotted label text is read **once**, before the first render — text injected
  into the default slot later will not create the label box. Use the `label`
  prop for dynamic text.
- The checkmark is what conveys selection non-visually; `no-checkmark` removes
  that cue and leaves color alone.
- `segmentIndex` / `segmentTotal` drive the end-cap rounding. Wrong values (set
  by hand, or segments that the set never re-stamped) produce a broken
  container.

---

## Do / Don't

Sourced from [M3 · Segmented buttons · Guidelines](https://m3.material.io/components/segmented-buttons/guidelines).

| ✅ Do | ❌ Don't |
|---|---|
| Keep labels short and similar in length across segments | Don't let a label wrap to a second line |
| Use the same label type for every segment in the set | Don't mix icon-only segments with text segments |
| Use an icon only when its meaning is unmistakable | Don't use ambiguous icon-only segments |
| Give every segment a unique `value` | Don't omit `value` — the set reports values |
| Keep the checkmark unless you have a strong reason | Don't rely on color alone to show selection |
| Give icon-only segments an `aria-label` | Don't ship an unnamed icon-only segment |
| Use `disabled` for a genuinely unavailable choice | Don't add and remove segments as state changes |

---

## Patterns

```html
<!-- Text segments -->
<md-segmented-button-set aria-label="Time range">
  <md-segmented-button value="d" label="Day" selected></md-segmented-button>
  <md-segmented-button value="w" label="Week"></md-segmented-button>
  <md-segmented-button value="m" label="Month"></md-segmented-button>
</md-segmented-button-set>

<!-- Icon + label, consistent across the set -->
<md-segmented-button-set aria-label="Layout">
  <md-segmented-button value="list" icon="view_list" label="List" selected></md-segmented-button>
  <md-segmented-button value="grid" icon="grid_view" label="Grid"></md-segmented-button>
</md-segmented-button-set>

<!-- Icon-only, every segment labelled for AT -->
<md-segmented-button-set aria-label="Alignment">
  <md-segmented-button value="l" icon="format_align_left"   aria-label="Left" selected></md-segmented-button>
  <md-segmented-button value="c" icon="format_align_center" aria-label="Center"></md-segmented-button>
</md-segmented-button-set>

<!-- Custom glyph through the icon slot -->
<md-segmented-button-set aria-label="Filter">
  <md-segmented-button value="star" label="Starred">
    <svg slot="icon" viewBox="0 0 24 24" width="18" height="18" fill="currentColor" aria-hidden="true">
      <path d="M12 17.3 6.2 21l1.6-6.6L2.5 9.9l6.8-.6L12 3l2.7 6.3 6.8.6-5.3 4.5L17.8 21z"/>
    </svg>
  </md-segmented-button>
  <md-segmented-button value="all" label="All" selected></md-segmented-button>
</md-segmented-button-set>
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| Standalone `md-segmented-button` | Nest it in `md-segmented-button-set` | The segment only *emits* `mdSegmentClick`; it never writes its own `selected`. With no set to listen, clicking does nothing. |
| Setting `segment-index` / `segment-total` | Let the set stamp them | Parent-owned; wrong values break the container shape. |
| Listening for `mdSegmentClick` | Listen to the set's `mdChange` | The set calls `stopPropagation()`, so the event never reaches your listener. |
| Toggling `selected` yourself in a click handler | Read the set's `mdChange` | The set already wrote it; a second write fights the set. |
| Segments wrapped in a `<div>` | Direct children only | The set's equal-width grid columns apply to direct children only, so a wrapper squeezes every segment inside it into a single column. (The shared seams still collapse — those come from this component's own CSS, driven by `segment-index` / `segment-total`, which the set stamps via a deep query.) |
| No `value` | Always set one | It is the identity in the set's change payload. |
| Icon-only segment with no `aria-label` | Add one | The glyph is `aria-hidden`, so it is not an accessible name. |
| `no-checkmark` in a multiselect set | Keep the checkmark | Without it, selection is color-only. |
| Expecting a `value` prop on the set to select this | Put `selected` here | The set has no `value` prop. |
| Expecting a click to deselect in single-select | Use `multiselect` on the set | Single-select always emits `selected: true`. |
| A long label that wraps | Shorten it | Labels are `white-space: nowrap`; M3 forbids wrapping segments. |
| `density="0"` to escape an inherited rung | `style="--md-sys-density-scale: 0"` | There is no `density="0"` rule; rung 0 is the inert default. |

## Accessibility, RTL, density, i18n

**Accessibility** — the host is `role="radio"` (or `role="checkbox"` when the
set is `multiselect`) with `aria-checked` mirroring `selected` and
`aria-disabled` when disabled or soft-disabled. `label`, slotted text or
`aria-label` supplies the name — icon-only segments need `aria-label`, since the
glyph is `aria-hidden`. The checkmark is the non-color selection cue; keep it
where you can. Focus shows a 3px inset `secondary` ring.

**RTL** — order and end-cap rounding flip automatically (the corner radii use
logical properties). Swap directional glyphs yourself.

**Density** — the set pushes its rung down to every segment; a local
`density="-1"`…`"-4"` on the segment overrides it. Each rung removes 4px from
the 40px height (`-4` = 24px) and tapers the icon, gap and label type with it.

**i18n** — translate `label`. Keep translated labels short and similar in
length so the set neither wraps nor jumps in width.

## Related components

`md-segmented-button-set` · `md-button-group` · `md-chip` · `md-tab` ·
`md-radio` · `md-ripple`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-segmented-button-container-color` | Unselected background | `transparent` |
| `--md-segmented-button-selected-container-color` | Selected background | `--md-sys-color-secondary-container` |
| `--md-segmented-button-label-color` | Unselected label/icon color | `--md-sys-color-on-surface` |
| `--md-segmented-button-selected-label-color` | Selected label/icon color | `--md-sys-color-on-secondary-container` |
| `--md-segmented-button-outline-color` | Divider / outline | `--md-sys-color-outline` |
| `--md-segmented-button-container-shape` | End-cap radius | `--md-sys-shape-corner-full` (`9999px`) |
| `--md-segmented-button-icon-size` | Glyph and checkmark box | `18px` at density 0 |

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

```css
/* Square-ended segments, tinted selection */
md-segmented-button {
  --md-segmented-button-container-shape: 8px;
  --md-segmented-button-selected-container-color: var(--md-sys-color-tertiary-container);
  --md-segmented-button-selected-label-color: var(--md-sys-color-on-tertiary-container);
}
```

<!-- 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`            | Disable this segment                                                                                                                                                                                  | `boolean`                   | `false` |
| `icon`               | `icon`                | Material Symbols icon name (optional)                                                                                                                                                                 | `string`                    | `''`    |
| `label`              | `label`               | Label text                                                                                                                                                                                            | `string`                    | `''`    |
| `noCheckmark`        | `no-checkmark`        | Show checkmark icon when selected                                                                                                                                                                     | `boolean`                   | `false` |
| `ripple`             | `ripple`              | Enable/disable ripple                                                                                                                                                                                 | `boolean`                   | `true`  |
| `segmentDensity`     | `segment-density`     | Density value from parent set (managed by md-segmented-button-set)                                                                                                                                    | `number`                    | `0`     |
| `segmentIndex`       | `segment-index`       | Position index within the set (managed by md-segmented-button-set)                                                                                                                                    | `number`                    | `0`     |
| `segmentMultiselect` | `segment-multiselect` | Whether the parent set is in multiselect mode (managed by md-segmented-button-set)                                                                                                                    | `boolean`                   | `false` |
| `segmentTotal`       | `segment-total`       | Total number of segments in the set (managed by md-segmented-button-set)                                                                                                                              | `number`                    | `1`     |
| `selected`           | `selected`            | Whether this segment is selected                                                                                                                                                                      | `boolean`                   | `false` |
| `softDisabled`       | `soft-disabled`       | Visually disabled but remains focusable for screen readers                                                                                                                                            | `boolean`                   | `false` |
| `value`              | `value`               | Unique value identifying this segment                                                                                                                                                                 | `string`                    | `''`    |


## Events

| Event            | Description                        | Type                                                 |
| ---------------- | ---------------------------------- | ---------------------------------------------------- |
| `mdSegmentClick` | Internal event — caught by the set | `CustomEvent<{ value: string; selected: boolean; }>` |


## Shadow Parts

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


## Dependencies

### Depends on

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

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

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

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

AWC UI Operator’s Manual

Copy spec

# main-llm.md — AWC UI build director

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

**Use this reference when building, updating, or reviewing an interface with
AWC UI, a Material Design 3 web-component library.** Start with the user's
request and the existing project. The sections below cover setup, component
selection, composition, and verification; read the sections relevant to the
task. Per-component detail lives in
`./packages/core/src/components/<tag>/readme.md` — e.g.
[`md-button`](./packages/core/src/components/md-button/readme.md).

1. **Match the task's scope** (§1). Reuse decisions from the project and
   conversation. A focused edit does not need a product interview or scaffold.
2. **Choose documented components** using the decision matrix (§5), and read
   each affected component's manual before changing its markup (§6). Check its
   API, `When NOT to use`, accessibility, and `Anti-patterns` sections; do not
   infer behavior from a similar library or sibling component.
3. **Use the existing integration.** For a new app or a requested setup change,
   use §2–§4. For composition, consult §7 and the relevant recipes in §8.
4. **Follow the API and accessibility rules** (§9). Do not invent an `md-*`
   tag, prop, event, slot, CSS part, or token. If the documented API cannot
   satisfy the request, explain the gap and resolve the consequential choice.
5. **Verify the affected behavior** using the applicable checks in §10.
   Report what changed and what was checked. A review reports findings without
   changing files unless a fix was requested.

---

## §1 — Match the task

| Task | How to proceed |
|---|---|
| New app | Establish the app's purpose and use known project or user decisions. Ask only about missing choices that materially affect the result; use reasonable defaults for minor details and state consequential assumptions. Then apply the relevant setup in §2–§4. |
| Existing app or focused fix | Preserve the framework, configuration, design, and product scope unless the request changes them. Inspect the affected code and manuals, then make the requested change. Do not restart discovery or scaffold another app. |
| Review or explanation | Inspect and explain the requested surface. Keep the work read-only unless the user asks for a fix. |

### Optional discovery checklist

Use the questions below as a reference when a new app or requested feature
leaves an important decision open. They are not a required interview, an
ordered sequence, or a reason to stop a focused task. Project configuration
and answers already given in the conversation take precedence; do not ask for
them again. Ask only what matters to the current task, and group related
questions when that helps. The **bold** options are starting defaults for a
new app, not instructions to override an existing project.

### 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,
    the feature needs a third-party editor (TipTap, Lexical, Quill) styled with
    MD3 tokens. Resolve that choice if the project or request does not cover it.

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

Apply this reference to new setup or requested configuration changes. Preserve
an existing project's choices for unrelated work.

| 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 20.3.31+ |
| Vue / Nuxt | `@awc-ui/vue` | Vue 3 |
| Svelte / SvelteKit | `@awc-ui/svelte` | Svelte 5.57+ |
| 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.
  Invalid submissions show the platform's message in the control's own inline
  error styling, with no browser validation popover. Correcting or resetting a
  field clears its generated message. `error` + `error-text` remain available
  for app-provided messages and take precedence over generated messages.
  `checkValidity()` checks silently; `reportValidity()` shows inline errors and
  focuses the first invalid control. Core submit buttons and Enter do the same.
- 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.

The library has 56 components and 25 sub-components, with 81 manuals in total.
Sub-components 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 Reusable interaction patterns

- **One footer for a dialog wizard.** Set `md-stepper.nav = false` and put
  Back / Continue in the dialog's `actions` slot. Keep the steps in the body;
  the dialog owns scrolling and keeps its header/footer visible. In fullscreen
  mode use the header close button for dismissal. Use a real form and submit
  button so Enter and inline validation follow the same path as a click.
- **Overlay handoffs wait for completion.** Use `await search.close(); await
  search.whenClosed();` before opening a result dialog or unmounting search.
  `mdClose` signals the state change; `whenClosed()` includes motion and cleanup.
  Do not replace that contract with a guessed timeout or a second focus trap.
- **Appearance controls fill their allocated space.** For an inline color picker
  in settings, set `--md-color-picker-width: 100%`. Its compact default remains
  appropriate for a popover. No shadow-DOM width overrides or extra tabindex.
- **Loading belongs to the operation.** Use `md-button.loading` for the initiating
  action and `md-skeleton` with `announce=false` for the content being replaced.
  Preserve the content layout, expose one live status, and guard repeated submits.
  Abort or ignore stale responses when the owner closes or a newer request wins.
  Provide inline error/retry and preserve entered values; do not add artificial waits.
- **Separate routing intent from selection synchronization.** `md-navigation-bar`
  emits `mdChange` for both user and programmatic changes. For a controlled router,
  use each `md-navigation-tab`'s `mdTabClick` for user intent, `manual-activation`
  on the bar, and synchronize `activeIndex` from the confirmed route. Avoid routing
  again merely because browser Back/Forward updated the selected index.
- **Keep table chrome outside the column scroller.** Use `slot="top"` and
  `slot="bottom"` on the toolbar and pagination. Set `min-inline-size: 0` on the
  containing grid/flex child and a readable minimum width on the table. Nested
  controls own their keys; do not add row-level Enter/Space interception in apps.

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

Use the checks relevant to the affected components and behavior. For a small
fix, verify the changed interaction and nearby regressions; a new app or broad
change needs wider coverage. Do not turn a focused edit into an unrelated
full-app audit.

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.


## MCP server and reusable skills

Core provides a read-only MCP server (`@awc-ui/mcp`) and `awc-ui-build` / `awc-ui-review` skills. MCP tools `search_components`, `get_component`, `list_guides`, and `get_guide` expose versioned Core documentation. Match the reported Core version to the consumer installation; use local manuals when versions differ. The server is optional and grants no permission for project mutations.

The Core package ships skills in `skills/`; `awc-ui ai-setup --skills` installs them under the consumer project’s `.agents/skills/` without overwriting customized copies. For configuration and skill-installer availability, see [AI integration](https://awc-ui.dev/guides/building-with-ai/#optional-mcp-and-skills). Use existing project and user decisions rather than restarting discovery for a focused edit.