Skip to content
AWC UI

Chip

A compact, contextual option — always part of a set. Four semantic variants (assist / filter / input / suggestion), three appearances, semantic colour roles, optional selection and optional removal. M3 is explicit that a lone chip is a design error: if there is only one, you wanted a button.

Live preview Open in Storybook
Assist Filter Selected filter Input Suggestion
Show code for each technology 
<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-chip variant="assist" icon="event">Assist</md-chip>
<md-chip variant="filter">Filter</md-chip>
<md-chip variant="filter" selected>Selected filter</md-chip>
<md-chip variant="input">Input</md-chip>
<md-chip variant="suggestion">Suggestion</md-chip>

Install

Section titled “Install”

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

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


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


<md-chip>Chip</md-chip>

When to use

Section titled “When to use”
  • Filters over a result set (variant="filter").
  • Entered values the user can remove — recipients, tags (variant="input").
  • Suggestions the user can accept (variant="suggestion").
  • Contextual, supplemental actions related to nearby content (variant="assist").

When not to use

Section titled “When not to use”
SituationUse instead
The primary or final action in a taskmd-button
Moving to the next or previous stepmd-button
A single standalone optionNothing — M3: chips must appear in a set
Exclusive choice among 2–5 visible optionsmd-segmented-button
A long list of selectable valuesmd-multi-select
A status label that isn’t interactivemd-badge / md-status-dot
Navigationmd-tabs / md-navigation-bar
A filter with only one possible valueNothing — M3: filter chips need more than one option

Decision cues

Section titled “Decision cues”
NeedSetting
Contextual action next to contentvariant="assist"
Toggle a filter on or offvariant="filter"
A user-entered token you can deletevariant="input"
A dynamically offered optionvariant="suggestion"
Raised off a busy backgroundappearance="elevated"
Status meaning (success, warning…)color
Unavailable but still discoverablesoft-disabled
Shorter chipsdensity="-1…-4"
A chip a layout has stretched, label flush leftcontent-align="start"

Variants

Section titled “Variants”

variant selects the M3 chip type. It also decides the default behaviour of selectable and removable — see below.

VariantPurposeTypically
assistDefault. A contextual action tied to nearby contentLeading icon, not selectable
filterToggle a filter on or offSelectable, shows a checkmark
inputA value the user enteredRemovable
suggestionA recommendation to acceptNot selectable
The four variants Open in Storybook
Directions Unread alice@example.com Add a caption
Show code for each technology 
<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-chip variant="assist" icon="directions">Directions</md-chip>
<md-chip variant="filter">Unread</md-chip>
<md-chip variant="input">alice@example.com</md-chip>
<md-chip variant="suggestion">Add a caption</md-chip>

selectable and removable are tri-state

Section titled “selectable and removable are tri-state”

Both props are boolean | undefined and default to undefined, not false. Left unset they are derived from variant — filter chips select, input chips remove. Set them explicitly only to override that default, for instance selectable="false" on an input chip that is purely a token, so clicking the body doesn’t flash a misleading “active” state.

Derived versus explicit selectable / removable Open in Storybook
Selectable by default Removable by default Token — remove only Opted out of removal Explicitly selectable Explicitly removable
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-chip variant="filter">Selectable by default</md-chip>
<md-chip variant="input">Removable by default</md-chip>
<md-chip variant="input" selectable="false">Token — remove only</md-chip>
<md-chip variant="input" removable="false">Opted out of removal</md-chip>
<md-chip variant="assist" selectable>Explicitly selectable</md-chip>
<md-chip variant="suggestion" removable>Explicitly removable</md-chip>

Appearance and colour

Section titled “Appearance and colour”

appearance is the surface style and is independent of variant — any chip type can be outlined, filled or elevated. color tints it.

NeedSetting
Standard look on a normal backgroundappearance="outlined" (default)
More weightappearance="filled"
Sitting on an imageappearance="elevated"
Semantic tonecolor="primary|secondary|tertiary|error|success|warning|info"
Three appearances Open in Storybook
Outlined Filled Elevated
Show code for each technology 
<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-chip appearance="outlined" icon="event">Outlined</md-chip>
<md-chip appearance="filled" icon="event">Filled</md-chip>
<md-chip appearance="elevated" icon="event">Elevated</md-chip>

color resolves <name> to the --md-sys-color-<name> token family at runtime, so it accepts any role your theme defines, not just the listed union — color="brand" works as soon as the theme ships those tokens, and an undefined name degrades to the neutral treatment rather than rendering broken. Only the named roles above are contrast-verified.

Semantic colour roles Open in Storybook
Primary Secondary Tertiary Overdue Paid Expiring Updated Outlined error
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-chip appearance="filled" color="primary">Primary</md-chip>
<md-chip appearance="filled" color="secondary">Secondary</md-chip>
<md-chip appearance="filled" color="tertiary">Tertiary</md-chip>
<md-chip appearance="filled" color="error">Overdue</md-chip>
<md-chip appearance="filled" color="success">Paid</md-chip>
<md-chip appearance="filled" color="warning">Expiring</md-chip>
<md-chip appearance="filled" color="info">Updated</md-chip>
<md-chip appearance="outlined" color="error">Outlined error</md-chip>

Icons

Section titled “Icons”

A leading icon comes from the icon prop or the leading-icon slot; the slot wins, and takes any glyph — SVG, an icon font, an emoji. trailing-icon and its matching slot cover the trailing side.

Prop icons and slotted icons Open in Storybook
Search Verified Contact Slotted SVG 🚀 Slotted emoji
Show code for each technology 
<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-chip icon="search">Search</md-chip>
<md-chip variant="filter" icon="check_circle" selected>Verified</md-chip>
<md-chip variant="input" icon="person">Contact</md-chip>
<md-chip>
  <svg slot="leading-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>
  Slotted SVG
</md-chip>
<md-chip>
  <span slot="leading-icon">🚀</span>
  Slotted emoji
</md-chip>

Content alignment

Section titled “Content alignment”

content-align decides where the content row sits when the chip is wider than its content. It does nothing to a normal chip: :host is display: inline-flex, so a chip shrink-wraps its label and there is no spare width to align within. It starts to matter the moment a layout gives the chip a width — a grid column, align-self: stretch, an explicit inline-size — and then the default center leaves the label adrift in the middle of the box, which reads as an empty input rather than a chip.

Reach for start when a stretched chip is labelling something beneath it: the two then share a leading edge and read as one unit.

Three alignments, each in a 220px grid column Open in Storybook
start center (default) end
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display:grid;grid-template-columns:repeat(3,220px);gap:12px;">
  <md-chip appearance="filled" color="primary" content-align="start">start</md-chip>
  <md-chip appearance="filled" color="primary">center (default)</md-chip>
  <md-chip appearance="filled" color="primary" content-align="end">end</md-chip>
</div>

States

Section titled “States”
States — try tabbing through them Open in Storybook
Enabled Selected Disabled Disabled selected Soft-disabled
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-chip variant="filter">Enabled</md-chip>
<md-chip variant="filter" selected>Selected</md-chip>
<md-chip variant="filter" disabled>Disabled</md-chip>
<md-chip variant="filter" disabled selected>Disabled selected</md-chip>
<md-chip variant="filter" soft-disabled>Soft-disabled</md-chip>

disabled leaves the tab order. soft-disabled keeps the same visuals but stays focusable, so an unavailable filter is still discoverable.

Filter sets

Section titled “Filter sets”

A set needs a container with role="group" and an aria-label describing what it filters. Selection is conveyed by a checkmark as well as by colour, so it survives a colour-blind reader. The chip does not manage the set — wrapping, scrolling and overflow are yours.

A filter set — click to toggle Open in Storybook
Unread Starred Has attachment Muted
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div role="group" aria-label="Message filters" style="display: flex; gap: 8px; flex-wrap: wrap;">
  <md-chip variant="filter">Unread</md-chip>
  <md-chip variant="filter" selected>Starred</md-chip>
  <md-chip variant="filter">Has attachment</md-chip>
  <md-chip variant="filter">Muted</md-chip>
</div>

For a set that outgrows its row, M3 prefers horizontal scrolling over wrapping into a wall of chips:

A horizontally scrolling set Open in Storybook
Italian Japanese Mexican Thai Ethiopian Vietnamese Lebanese Peruvian
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div role="group" aria-label="Cuisine filters" style="display: flex; gap: 8px; overflow-x: auto; inline-size: 100%; padding-block-end: 8px;">
  <md-chip variant="filter" style="flex: none;">Italian</md-chip>
  <md-chip variant="filter" style="flex: none;">Japanese</md-chip>
  <md-chip variant="filter" style="flex: none;">Mexican</md-chip>
  <md-chip variant="filter" style="flex: none;">Thai</md-chip>
  <md-chip variant="filter" style="flex: none;">Ethiopian</md-chip>
  <md-chip variant="filter" style="flex: none;">Vietnamese</md-chip>
  <md-chip variant="filter" style="flex: none;">Lebanese</md-chip>
  <md-chip variant="filter" style="flex: none;">Peruvian</md-chip>
</div>

Removal — the chip does not remove itself

Section titled “Removal — the chip does not remove itself”

mdRemove is a request, not the removal. The chip stays in the DOM until you take it out. The event is cancelable, so preventDefault() lets you insert a confirmation step.

Input chips with a remove affordance Open in Storybook
alice@example.com bob@example.com carol@example.com
Show code for each technology 
<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<div role="group" aria-label="Recipients" style="display: flex; gap: 8px; flex-wrap: wrap;">
  <md-chip variant="input" icon="person">alice@example.com</md-chip>
  <md-chip variant="input" icon="person">bob@example.com</md-chip>
  <md-chip variant="input" icon="person">carol@example.com</md-chip>
</div>

Events

Section titled “Events”
EventCancelableDetailFires
mdClicknovoidThe chip body was activated
mdSelectno{ selected }Selection toggled — selectable chips only
mdRemoveyesvoidThe remove affordance was used, or Delete/Backspace pressed on the chip

Only mdRemove is cancelable. To veto a selection you set selected back on the element; preventDefault() on mdSelect does nothing.

API Reference

Section titled “API Reference”

Properties

Property Attribute Type Default Reflects
variant variant 'assist' | 'filter' | 'input' | 'suggestion' 'assist' Yes
icon icon string '' —
trailingIcon trailing-icon string '' —
selected selected boolean false Yes
selectable selectable boolean — —
appearance appearance 'outlined' | 'filled' | 'elevated' 'outlined' Yes
color color | 'primary' | 'secondary' | 'tertiary' | 'error' | 'success' | 'warning' | 'info' | (string & {}) — Yes
elevated elevated boolean false Yes
disabled disabled boolean false Yes
softDisabled soft-disabled boolean false Yes
removable removable boolean — Yes
label label string '' —
contentAlign content-align 'start' | 'center' | 'end' 'center' Yes
density density 0 | -1 | -2 | -3 | -4 0 Yes

Slots

Slot Description
(default) —
leading-icon Custom leading icon
trailing-icon Custom trailing icon

CSS Custom Properties

Override on the host element for per-instance theming:

Property Description
--md-chip-container-color Container background
--md-chip-container-color-selected Selected container background
--md-chip-label-color Label text color
--md-chip-label-color-selected Selected label text color
--md-chip-icon-color Leading/trailing icon color
--md-chip-icon-size Icon dimensions
--md-chip-container-shape Border-radius override
--md-chip-container-height Height override
--md-chip-outline-color Outline color
--md-chip-outline-width Outline width
--md-chip-state-layer-color State layer color override
--md-chip-elevation Box-shadow override

CSS Shadow Parts

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

Part Description
state-layer Hover/press overlay
outline Border element
primary —
checkmark Filter chip checkmark
icon Leading icon
label Label text wrapper
remove Input chip remove button
trailing-icon Trailing icon

Accessibility

Section titled “Accessibility”
  • Wrap a set in a container with role="group" and an aria-label describing what the set filters or holds.
  • Selection state is conveyed by a checkmark as well as by colour.
  • A removable chip’s remove affordance needs a clear accessible name that includes the chip’s label — “Remove” alone is ambiguous in a list of ten chips.
  • disabled leaves the tab order; soft-disabled stays focusable.
  • Keep the whole chip as the hit target on touch. M3’s compact-window rule is explicit: don’t shrink the target to just the trailing icon.
  • Delete and Backspace trigger removal from the chip itself, so a keyboard user never has to reach the ”×”.

Keyboard

Section titled “Keyboard”
KeyAction
TabFocus the chip (disabled is skipped, soft-disabled is not), then its remove affordance
Enter / SpaceActivate — toggles a filter chip’s selection
Delete / BackspaceFire mdRemove from the chip itself
A named group — Tab across it, Delete to remove Open in Storybook
Unread Starred ada@example.com grace@example.com Add to calendar
Show code for each technology 
<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<div role="group" aria-label="Applied filters" style="display:flex;gap:8px;flex-wrap:wrap;">
  <md-chip variant="filter" selected>Unread</md-chip>
  <md-chip variant="filter">Starred</md-chip>
  <md-chip variant="input" removable>ada@example.com</md-chip>
  <md-chip variant="input" removable>grace@example.com</md-chip>
  <md-chip variant="assist" soft-disabled icon="event">Add to calendar</md-chip>
</div>

RTL, density & i18n

Section titled “RTL, density & i18n”

RTL — leading and trailing icon sides mirror automatically. Directional glyphs still need swapping for their meaning to survive. See RTL. content-align is logical too — start is the leading edge in both directions.

Same markup, dir=ltr vs dir=rtl — icon and remove sides swap Open in Storybook
ltr
Unread Ada Lovelace Add to calendar
rtl
غير مقروء إيمي إلسنر إضافة إلى التقويم
Show code for each technology 
<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:16px;align-items:center;">
  <span style="inline-size:2.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:8px;flex-wrap:wrap;">
    <md-chip variant="filter" selected icon="check">Unread</md-chip>
    <md-chip variant="input" removable icon="person">Ada Lovelace</md-chip>
    <md-chip variant="assist" icon="event">Add to calendar</md-chip>
  </div>
  <span style="inline-size:2.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:8px;flex-wrap:wrap;">
    <md-chip variant="filter" selected icon="check">غير مقروء</md-chip>
    <md-chip variant="input" removable icon="person">إيمي إلسنر</md-chip>
    <md-chip variant="assist" icon="event">إضافة إلى التقويم</md-chip>
  </div>
</div>

Density — density="-1…-4" reduces height and padding. See Density.

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

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:12px 16px;align-items:center;">
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <div style="display:flex;gap:8px;flex-wrap:wrap;"><md-chip density="0" variant="filter" selected>Unread</md-chip><md-chip density="0" variant="assist" icon="event">Calendar</md-chip><md-chip density="0" variant="input" removable>Token</md-chip></div>
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:8px;flex-wrap:wrap;"><md-chip density="-1" variant="filter" selected>Unread</md-chip><md-chip density="-1" variant="assist" icon="event">Calendar</md-chip><md-chip density="-1" variant="input" removable>Token</md-chip></div>
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:8px;flex-wrap:wrap;"><md-chip density="-2" variant="filter" selected>Unread</md-chip><md-chip density="-2" variant="assist" icon="event">Calendar</md-chip><md-chip density="-2" variant="input" removable>Token</md-chip></div>
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:8px;flex-wrap:wrap;"><md-chip density="-3" variant="filter" selected>Unread</md-chip><md-chip density="-3" variant="assist" icon="event">Calendar</md-chip><md-chip density="-3" variant="input" removable>Token</md-chip></div>
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:8px;flex-wrap:wrap;"><md-chip density="-4" variant="filter" selected>Unread</md-chip><md-chip density="-4" variant="assist" icon="event">Calendar</md-chip><md-chip density="-4" variant="input" removable>Token</md-chip></div>
</div>

i18n — translate label (or the slotted label content) and the remove affordance’s accessible name. Translated labels routinely run past M3’s ~20-character guidance, so plan for scrolling or truncation before the translations arrive.

Theming

Section titled “Theming”
Custom propertyPurposeDefault
--md-chip-container-color / --md-chip-container-color-selectedBackground by statePer appearance
--md-chip-label-color / --md-chip-label-color-selectedLabel by statePer appearance
--md-chip-icon-color / --md-chip-icon-sizeIconsInherits label / 18px
--md-chip-container-shape / --md-chip-container-heightGeometry8px / 32px
--md-chip-outline-color / --md-chip-outline-widthOutlineoutline / 1px
--md-chip-state-layer-colorHover/press overlayon-surface
--md-chip-elevationBox-shadow overrideelevation-0 (the elevated appearance sets its own)
Themed instances Open in Storybook
Squared off Taller Heavy outline
Show code for each technology 
<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-chip appearance="filled" style="--md-chip-container-shape: 4px;">Squared off</md-chip>
<md-chip style="--md-chip-container-height: 40px; --md-chip-icon-size: 22px;" icon="event">Taller</md-chip>
<md-chip style="--md-chip-outline-color: var(--md-sys-color-primary); --md-chip-outline-width: 2px;">Heavy outline</md-chip>

Every default resolves through an md-sys-color role, so a chip that sets no custom properties follows the theme on its own:

Untouched defaults — follows the page theme Open in Storybook
Assist Filter, selected Input Suggestion Elevated
Show code for each technology 
<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<div style="display:flex;gap:8px;flex-wrap:wrap;">
  <md-chip variant="assist" icon="event">Assist</md-chip>
  <md-chip variant="filter" selected>Filter, selected</md-chip>
  <md-chip variant="input" removable icon="person">Input</md-chip>
  <md-chip variant="suggestion">Suggestion</md-chip>
  <md-chip appearance="elevated">Elevated</md-chip>
</div>

CSS parts

Section titled “CSS parts”
PartElement
primaryThe chip’s main interactive box
outlineThe border ring
state-layerHover / focus / press overlay
checkmarkThe selected tick on a filter chip
iconLeading icon
labelLabel text
trailing-iconTrailing icon
removeThe remove affordance on a removable chip
label, outline, checkmark and remove Open in Storybook
Selected Unselected Removable
Show code for each technology 
<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<style>
  .parts-chip::part(label) { text-transform: uppercase; letter-spacing: .08em; font-size: 11px; }
  .parts-chip::part(outline) { border-width: 2px; border-color: var(--md-sys-color-primary); }
  .parts-chip::part(checkmark) { color: var(--md-sys-color-tertiary); }
  .parts-chip::part(remove) { color: var(--md-sys-color-error); }
</style>
<div style="display:flex;gap:8px;flex-wrap:wrap;">
  <md-chip class="parts-chip" variant="filter" selected>Selected</md-chip>
  <md-chip class="parts-chip" variant="filter">Unselected</md-chip>
  <md-chip class="parts-chip" variant="input" removable icon="person">Removable</md-chip>
</div>
md-chip::part(label) {
  letter-spacing: 0.3px;
}
Section titled “Related”

md-button · md-segmented-button · md-multi-select · md-badge · md-status-dot · md-menu · md-ripple

AI / LLM Context

Section titled “AI / LLM Context”

For AI Agents — md-chip

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-chip spec card

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

Main-LLM spec

AWC UI Operator's Manual

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

Open spec

md-chip readme.md 

# md-chip

<!-- llm:meta
tag: md-chip
category: selection
status: md3-mapped
m3-guidelines: https://m3.material.io/components/chips/guidelines
form-associated: false
depends-on: md-ripple
used-by: md-autocomplete, md-multi-select
-->

**A compact, contextual option — always part of a set.**
Four semantic variants (assist / filter / input / suggestion) cross with three
surface appearances (outlined / filled / elevated), plus theme colour roles,
optional selection and optional removal.

> 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

- **Filters** over a result set (`variant="filter"`).
- **Entered values** the user can remove — recipients, tags (`variant="input"`).
- **Suggestions** the user can accept (`variant="suggestion"`).
- **Contextual, supplemental actions** related to nearby content
  (`variant="assist"`).

## When NOT to use

| Situation | Use instead |
|---|---|
| The primary or final action in a task | `md-button` |
| Moving to the next/previous step | `md-button` |
| A single standalone option | Nothing — M3: chips must appear in a set |
| Exclusive choice among 2–5 visible options | `md-segmented-button-set` |
| A long list of selectable values | `md-multi-select` |
| A status label that isn't interactive | `md-badge` / `md-status-dot` |
| Navigation | `md-tabs` / `md-navigation-bar` |
| A filter with only one possible value | Nothing — M3: filter chips need >1 option |

## Decision cues

| Variant | Purpose | Defaults it implies |
|---|---|---|
| `assist` (default) | A contextual action tied to nearby content | Not selectable, not removable |
| `filter` | Toggle a filter on/off | Selectable; shows a checkmark when selected with no leading icon |
| `input` | A value the user entered | Selectable **and** removable |
| `suggestion` | A recommendation to accept | Not selectable, not removable |

| Need | Setting |
|---|---|
| Standard look on a normal background | `appearance="outlined"` (default) |
| More weight | `appearance="filled"` |
| Sitting on an image | `appearance="elevated"` |
| A theme colour role | `color="primary\|secondary\|tertiary\|error\|success\|warning\|info"` |
| A remove "✕" on a non-input chip | `removable` |
| Suppress the input chip's ✕ | `removable="false"` |
| A display-only token whose ✕ is the only action | `selectable="false"` + `removable` |
| Turn off toggling on a filter chip | `selectable="false"` |
| A chip stretched by its layout, label flush to the edge | `content-align="start"` |

## API contract

```html
<md-chip
  variant="assist|filter|input|suggestion"    <!-- default: assist -->
  appearance="outlined|filled|elevated"       <!-- default: outlined -->
  color="primary|secondary|tertiary|error|success|warning|info"  <!-- default: none -->
  label="Unread"                              <!-- default: "" -->
  icon="mail"                                 <!-- default: "" — leading glyph -->
  trailing-icon="expand_more"                 <!-- default: "" -->
  selectable="true|false"                     <!-- default: derived from variant -->
  selected                                    <!-- default: false -->
  removable="true|false"                      <!-- default: derived from variant -->
  disabled                                    <!-- default: false -->
  soft-disabled                               <!-- default: false -->
  content-align="start|center|end"            <!-- default: center -->
  density="-1|-2|-3|-4"                       <!-- default: 0 (uncompacted) -->
></md-chip>
```

**Deprecated — don't emit it:** `elevated` (boolean). It is an alias that
forces `appearance="elevated"` and **wins over** an explicit `appearance`.
Write `appearance="elevated"` instead.

**Events** — all three bubble, are composed, and are dispatched with
`event.cancelable === true` (the framework default). Only `mdRemove` has a
**default action** for `preventDefault()` to cancel; calling it on the other two
does nothing.

| Event | Default action (cancelable) | Detail | Fires |
|---|---|---|---|
| `mdClick` | none | `void` | Chip body activated (click, Enter, Space), unless disabled |
| `mdSelect` | none | `{ selected }` | Selection toggled — only when the chip is selectable |
| `mdRemove` | **the chip removes itself from the DOM** | `void` | Remove ✕ used, or Delete/Backspace on a removable chip |

**Methods** — none.

**Slots** — `(default)`: label content, an alternative to `label`;
`leading-icon`: replaces the `icon` glyph; `trailing-icon`: replaces the
trailing glyph — and on a **removable** chip it replaces the ✕ artwork
*inside* the remove button rather than sitting beside it.

**Parts** — `state-layer`, `outline` (not rendered when the deprecated
`elevated` boolean is set), `primary`, `checkmark`, `icon`, `label`, `remove`,
`trailing-icon`.

### Behavioral contract worth knowing

- **`mdRemove` removes the chip.** The default action of the event is
  `this.el.remove()`. Call `event.preventDefault()` to keep the chip mounted —
  that is the hook for a confirmation step, or for when your state layer owns
  the list and will re-render without it. Do **not** also call `chip.remove()`
  in the handler; that is the default.
- `selectable` and `removable` are **tri-state** (`undefined` by default): left
  unset they are derived from `variant` — `filter` and `input` chips select,
  `input` chips remove. Set them explicitly only to override that.
- **The host role changes with the composition.** A chip whose body is
  interactive and which has **no** remove button is a single `role="button"`
  host with `tabindex` and `aria-pressed`. Add a remove button and the host
  steps down to `role="group"` with an `aria-label`, and the body action moves
  to an inner `part="primary"` element — so the chip then has **two** tab stops
  (body, then ✕), not one. `aria-roledescription="chip"` is present either way.
- `selectable="false"` **together with** `removable` makes the host a labelled
  `group` whose only tab stop is the ✕ — the display-token shape used by
  `md-multi-select`.
- `color` takes a **theme role name**, not a colour value. It is validated
  against `/^[a-z][a-z0-9-]*$/i` and expanded into
  `--md-sys-color-<name>` / `-<name>-container` / `--md-sys-color-on-<name>` /
  `-on-<name>-container`. A hex, `rgb()`, or any other CSS colour is rejected
  and the chip renders neutral. A role your theme does not define also falls
  back rather than breaking.
- The filter checkmark renders only for `variant="filter"` when `selected` and
  there is **no** leading icon — a leading icon takes the slot instead.
- `disabled` sets `tabindex="-1"` on the interactive elements and blocks
  activation; `soft-disabled` keeps `tabindex="0"` but blocks activation too.
- The accessible name for the ✕ button is generated as `Remove {label}`, where
  the label is `label` or the chip's own text content — you do not need to
  supply one.
- `content-align` does nothing until something stretches the chip. `:host` is
  `display: inline-flex`, so a chip normally shrink-wraps its label and there is
  no spare width to align within. Give it a width — a grid column, `align-self:
  stretch`, an explicit `inline-size` — and the default `center` leaves the label
  adrift in the middle of the box; `start` puts it back on the leading edge.
- The chip does not manage a set: wrapping, scrolling and overflow are yours.

---

## Do / Don't

Sourced from [M3 · Chips · Guidelines](https://m3.material.io/components/chips/guidelines).

| ✅ Do | ❌ Don't |
|---|---|
| Use chips for contextual, supplemental options | Avoid replacing major actions with chips |
| Use buttons for the final step in a task | Avoid using chips to finish or progress a task |
| Show chips in a **set** | Don't display a single chip by itself |
| Let a chip set scroll horizontally when it overflows | Don't wrap a long set into a wall of chips without thought |
| Use an outline on regular backgrounds | Don't elevate chips placed directly on the page |
| Use elevation only when the chip sits on an image | Don't use elevation to indicate the pressed state — the ripple does that |
| Keep labels short | Avoid labels longer than about 20 characters |
| Offer more than one option in a filter set | Filter chips shouldn't present only a single option |
| In compact windows, make the **whole chip** open its menu | Don't shrink the target to just the trailing icon |

---

## Patterns

```html
<!-- Filter set -->
<div role="group" aria-label="Filters" style="display: flex; gap: 8px;">
  <md-chip variant="filter" label="Unread"></md-chip>
  <md-chip variant="filter" label="Starred" selected></md-chip>
  <md-chip variant="filter" label="Has attachment"></md-chip>
</div>

<script type="module">
  document.querySelectorAll('md-chip[variant="filter"]').forEach((chip) => {
    chip.addEventListener('mdSelect', (e) => applyFilter(chip.label, e.detail.selected));
  });
</script>
```

```html
<!-- Input chips: the chip removes itself, you just sync your model -->
<md-chip id="recipient" variant="input" label="alice@example.com"></md-chip>

<script type="module">
  const chip = document.getElementById('recipient');
  chip.addEventListener('mdRemove', () => {
    // The chip is about to remove itself from the DOM — drop it from state too.
    recipients.delete(chip.label);
  });
</script>
```

```html
<!-- Confirm before removing: preventDefault keeps the chip mounted -->
<md-chip id="tag" variant="input" label="urgent"></md-chip>

<script type="module">
  const chip = document.getElementById('tag');
  chip.addEventListener('mdRemove', (e) => {
    if (!confirm('Remove this tag?')) {
      e.preventDefault();   // chip stays in the DOM
    }
  });
</script>
```

```html
<!-- Assist chip with a leading icon -->
<md-chip variant="assist" label="Directions" icon="directions"></md-chip>

<!-- Theme colour roles -->
<md-chip label="Overdue" color="error" appearance="filled"></md-chip>
<md-chip label="Paid" color="success"></md-chip>

<!-- On imagery -->
<md-chip label="Featured" appearance="elevated"></md-chip>

<!-- Display-only token: only the ✕ is interactive -->
<md-chip variant="input" label="alice@example.com" selectable="false" removable></md-chip>

<!-- Horizontally scrolling set -->
<div role="group" aria-label="Tags" style="display: flex; gap: 8px; overflow-x: auto;">
  <md-chip variant="filter" label="Design"></md-chip>
  <md-chip variant="filter" label="Engineering"></md-chip>
</div>
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| Calling `chip.remove()` inside an `mdRemove` handler | Just update your state | Removal is the event's default action; doing it twice is redundant. |
| Expecting the chip to stay after `mdRemove` | `event.preventDefault()` to keep it | Otherwise the chip removes itself. |
| `preventDefault()` on `mdSelect` or `mdClick` | Set `selected` back yourself | They report `cancelable: true` but have no default action, so cancelling them is a no-op — only `mdRemove` has one. |
| `color="#ff0000"` | `color="error"`, or set `--md-chip-container-color` | `color` is a theme **role name**; a hex is rejected and the chip renders neutral. |
| `elevated` | `appearance="elevated"` | `elevated` is deprecated and overrides `appearance`. |
| `aria-label="Remove"` on the chip to name the ✕ | Set `label` (or slot text) | The remove button is already named `Remove {label}`. |
| Assuming a removable chip is one tab stop | Expect two: body, then ✕ | A remove button forces the host down to `role="group"`. |
| A lone chip as a call to action | `md-button` | M3: chips appear in sets; actions are buttons. |
| "Next"/"Submit" as a chip | `md-button` | M3: don't progress tasks with chips. |
| `appearance="elevated"` on a plain page | `outlined` | Elevation is for chips over imagery. |
| Elevation as the pressed state | Let the ripple show press | M3 explicit rule. |
| A 40-character chip label | Keep under ~20 characters | M3 explicit rule. |
| A filter set containing one chip | Show the real options, or drop the filter | M3 explicit rule. |
| Only the trailing ✕ clickable on mobile | Make the whole chip the target | M3 compact-window caution. |
| `md-chip` for a non-interactive status | `md-badge` / `md-status-dot` | Chips imply interactivity. |

## Accessibility, RTL, density, i18n

**Accessibility**
- Wrap a set in a container with `role="group"` and an `aria-label` describing
  what the set filters or holds — the chip does not create the set.
- Selection is conveyed by the checkmark as well as by colour, and by
  `aria-pressed` on the interactive element.
- The remove button's accessible name (`Remove {label}`) is generated for you,
  so give every removable chip a real `label` or text content.
- `disabled` leaves the tab order (`tabindex="-1"`); `soft-disabled` stays
  focusable so the option remains discoverable. Both block activation and set
  `aria-disabled="true"`.
- A removable chip has two tab stops. Don't wrap it in another interactive
  element — nested interactive controls fail automated a11y checks.
- Keep the whole chip as the hit target on touch.

**RTL** — the leading/trailing regions use logical properties and mirror under
`dir="rtl"`. Directional glyphs passed to `icon` / `trailing-icon` still need
swapping by you.
`content-align` is logical too — `start` is the leading edge in both directions.

**Density** — `density="-1…-4"` (or an inherited `data-density` rung) reduces
height, label size and icon size via `--md-sys-density-scale`; height floors at
24px. Rung `0` is the uncompacted default and has no rule of its own. To pin
one chip back to full size under a global rung, set
`style="--md-sys-density-scale: 0"` on it. Check the touch target and that
labels don't clip at deep rungs.

**i18n** — translate `label`. Note that the remove button's accessible name is
built as the English word `Remove` plus your label, and the component exposes no
prop to change that verb; in a non-English UI, name the surrounding group so the
context is still clear. Translated labels run longer than M3's ~20-character
guidance — plan for scrolling or truncation.

## Related components

`md-button` · `md-segmented-button-set` · `md-multi-select` · `md-autocomplete` ·
`md-badge` · `md-status-dot` · `md-menu` · `md-ripple`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-chip-container-color` | Container fill | `transparent` (outlined); role/surface tone for filled & elevated |
| `--md-chip-container-color-selected` | Fill while selected | `--md-sys-color-secondary-container` |
| `--md-chip-label-color` | Label colour | `--md-sys-color-on-surface-variant` |
| `--md-chip-label-color-selected` | Label colour while selected | `--md-sys-color-on-secondary-container` |
| `--md-chip-icon-color` | Leading / trailing glyph colour | `--md-sys-color-primary` (varies by variant) |
| `--md-chip-icon-size` | Glyph box | `max(14px, 18px + density × 1px)` |
| `--md-chip-container-shape` | Corner radius | `--md-sys-shape-corner-small` (`8px`) |
| `--md-chip-container-height` | Base height before the density trim | `32px` |
| `--md-chip-outline-color` | Outline colour | `--md-sys-color-outline` |
| `--md-chip-outline-width` | Outline width | `1px` |
| `--md-chip-state-layer-color` | Hover / press overlay | `--md-sys-color-on-surface` |
| `--md-chip-elevation` | Box-shadow | `--md-sys-elevation-0`; `--md-sys-elevation-1` for `elevated` |

**CSS parts** — `state-layer`, `outline`, `primary`, `checkmark`, `icon`,
`label`, `remove`, `trailing-icon`.

```css
md-chip.brand {
  --md-chip-outline-color: var(--md-sys-color-tertiary);
  --md-chip-label-color: var(--md-sys-color-tertiary);
}
```

<!-- Auto Generated Below -->


## Properties

| Property       | Attribute       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Type                                                                                                                | Default      |
| -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------ |
| `appearance`   | `appearance`    | Surface style of the chip. Distinct from `variant`, which selects the M3 chip TYPE (assist / filter / input / suggestion); a chip has both.  - `outlined` (default) — transparent container with a 1px outline. - `filled` — tonal container, no outline. - `elevated` — tonal container with elevation and no outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"elevated" \| "filled" \| "outlined"`                                                                              | `'outlined'` |
| `color`        | `color`         | Colour role applied to the chip's outline / label / container, depending on `appearance`. Omit for the neutral surface treatment.  Any role name the THEME defines is accepted, not just a fixed list — the chip resolves `<name>` to the `--md-sys-color-<name>` / `-<name>-container` / `-on-<name>-container` family at runtime. So `color="brand"` works as soon as a theme ships those tokens, and a name the theme does not define degrades to the neutral treatment rather than rendering broken.  `primary` \| `secondary` \| `tertiary` \| `error` are the baseline M3 roles; `success` \| `warning` \| `info` ship in packages/tokens on the same tonal recipe. The union below is a hint for editor autocomplete only — the `string` arm is what makes custom roles work. | `"error" \| "info" \| "primary" \| "secondary" \| "success" \| "tertiary" \| "warning" \| string & {} \| undefined` | `undefined`  |
| `contentAlign` | `content-align` | Inline-axis alignment of the chip's content row — leading icon, label and trailing icon together.  `center` (the default) is a no-op on a normal chip, which shrink-wraps its label: the content box and the container are the same size, so there is nothing to align. It matters only once a layout gives the chip a width — a grid column, `align-self: stretch`, an explicit `inline-size` — and then centre is usually wrong. The label floats in the middle of a wide outlined box and reads as an empty input rather than a chip, and a chip labelling something beneath it no longer shares a left edge with what it names.  `start` reads left in LTR / right in RTL, `end` the reverse, `center` is direction-agnostic. Use `::part(label)` for finer control.             | `"center" \| "end" \| "start"`                                                                                      | `'center'`   |
| `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`      | Disables the chip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `boolean`                                                                                                           | `false`      |
| `elevated`     | `elevated`      | <span style="color:red">**[DEPRECATED]**</span> Use `appearance="elevated"`. Kept as an alias so existing markup keeps working: when true it forces the elevated appearance and wins over `appearance`, since a consumer setting it is being explicit.<br/><br/>Whether the chip is elevated (adds shadow instead of outline).                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `boolean`                                                                                                           | `false`      |
| `icon`         | `icon`          | Material Symbols icon name for the leading icon                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `string`                                                                                                            | `''`         |
| `label`        | `label`         | Label text — alternative to default slot                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `string`                                                                                                            | `''`         |
| `removable`    | `removable`     | When `true`, the chip renders a trailing remove ("✕") button and responds to Delete / Backspace from the chip itself. Works on every variant.  `variant="input"` is removable by default (per MD3 spec) — setting `removable="false"` explicitly opts out of that behavior.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `boolean \| undefined`                                                                                              | `undefined`  |
| `selectable`   | `selectable`    | Whether clicking the chip body toggles `selected`. Defaults to true for `filter`/`input` variants. Set `selectable="false"` for a token that is only a display of a value (e.g. a multi-select's removable chips) — clicking the body then does nothing and the ✕ remove button is the only action, so the chip doesn't flash a misleading "active" state.                                                                                                                                                                                                                                                                                                                                                                                                                           | `boolean \| undefined`                                                                                              | `undefined`  |
| `selected`     | `selected`      | Whether the chip is selected (filter/input variants)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `boolean`                                                                                                           | `false`      |
| `softDisabled` | `soft-disabled` | Soft-disabled: disabled visuals but remains focusable                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `boolean`                                                                                                           | `false`      |
| `trailingIcon` | `trailing-icon` | Material Symbols icon name for the trailing icon (filter/input only)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `string`                                                                                                            | `''`         |
| `variant`      | `variant`       | Chip variant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `"assist" \| "filter" \| "input" \| "suggestion"`                                                                   | `'assist'`   |


## Events

| Event      | Description                                                                                                                                                                                                                                                                                                                                                                                       | Type                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `mdClick`  | Emits when the chip is clicked or activated via keyboard                                                                                                                                                                                                                                                                                                                                          | `CustomEvent<void>`                   |
| `mdRemove` | Fires when the trailing remove ("✕") button is activated on a removable chip (by click, Enter, Space, Delete, or Backspace).  The event is **cancelable**: by default, after `mdRemove` is dispatched the chip removes itself from the DOM. Call `event.preventDefault()` in a handler to keep the chip mounted (e.g. when your state layer owns the list and will re-render with the chip gone). | `CustomEvent<void>`                   |
| `mdSelect` | Emits when the selected state changes (filter/input)                                                                                                                                                                                                                                                                                                                                              | `CustomEvent<{ selected: boolean; }>` |


## Shadow Parts

| Part              | Description |
| ----------------- | ----------- |
| `"checkmark"`     |             |
| `"icon"`          |             |
| `"label"`         |             |
| `"outline"`       |             |
| `"primary"`       |             |
| `"remove"`        |             |
| `"state-layer"`   |             |
| `"trailing-icon"` |             |


## Dependencies

### Used by

 - [md-autocomplete](../md-autocomplete)
 - [md-multi-select](../md-multi-select)

### Depends on

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

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

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

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

AWC UI Operator’s Manual 

# main-llm.md — AWC UI build director

<!-- llm:meta
role: director
audience: llm
library: "@awc-ui/core"
component-count: 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.