Split Button

One default action plus a menu of variations. Two fused segments: a leading button that runs the default action, and a trailing toggle that opens a menu. The component renders the button — you supply and position the menu.

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-split-button variant="filled" icon="save" label="Save" menu-label="More save options"></md-split-button>
<md-split-button variant="tonal" icon="add" label="Create" menu-label="More create options"></md-split-button>
<md-split-button variant="elevated" icon="send" label="Send" menu-label="Send options"></md-split-button>
<md-split-button variant="outlined" icon="merge" label="Merge" menu-label="Other merge strategies"></md-split-button>

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

export function Demo() {
  return (
    <>
      <MdSplitButton variant="filled" icon="save" label="Save" menuLabel="More save options"></MdSplitButton>
      <MdSplitButton variant="tonal" icon="add" label="Create" menuLabel="More create options"></MdSplitButton>
      <MdSplitButton variant="elevated" icon="send" label="Send" menuLabel="Send options"></MdSplitButton>
      <MdSplitButton variant="outlined" icon="merge" label="Merge" menuLabel="Other merge strategies"></MdSplitButton>
    </>
  );
}

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

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

<!-- app.component.html -->
<md-split-button variant="filled" icon="save" label="Save" menu-label="More save options"></md-split-button>
<md-split-button variant="tonal" icon="add" label="Create" menu-label="More create options"></md-split-button>
<md-split-button variant="elevated" icon="send" label="Send" menu-label="Send options"></md-split-button>
<md-split-button variant="outlined" icon="merge" label="Merge" menu-label="Other merge strategies"></md-split-button>

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

<template>
  <md-split-button variant="filled" icon="save" label="Save" menu-label="More save options"></md-split-button>
  <md-split-button variant="tonal" icon="add" label="Create" menu-label="More create options"></md-split-button>
  <md-split-button variant="elevated" icon="send" label="Send" menu-label="Send options"></md-split-button>
  <md-split-button variant="outlined" icon="merge" label="Merge" menu-label="Other merge strategies"></md-split-button>
</template>

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

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

<md-split-button variant="filled" icon="save" label="Save" menu-label="More save options"></md-split-button>
<md-split-button variant="tonal" icon="add" label="Create" menu-label="More create options"></md-split-button>
<md-split-button variant="elevated" icon="send" label="Send" menu-label="Send options"></md-split-button>
<md-split-button variant="outlined" icon="merge" label="Merge" menu-label="Other merge strategies"></md-split-button>

Install

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


<md-split-button></md-split-button>

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

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


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

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

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

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


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

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

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

<template>
  <MdSplitButton></MdSplitButton>
</template>


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

<template>
  <md-split-button></md-split-button>
</template>

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

<md-split-button></md-split-button>


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

<md-split-button></md-split-button>

When to use

There is a clear default action, plus closely-related variants of it: Save / Save as…, Send / Schedule send, Merge / Squash / Rebase.
Users pick the default the large majority of the time, and the alternatives are genuinely alternatives — not unrelated commands.

When not to use

Situation	Use instead
No obvious default among the options	`md-button` + `md-menu`, or `md-select`
The options are unrelated commands	`md-icon-button` + `md-menu`
Choosing a value rather than running an action	`md-select` / `md-segmented-button`
2–5 equal, mutually exclusive choices	`md-segmented-button`
Several equal actions as a unit	`md-button-group`
A single action	`md-button`
The trailing side toggles state rather than opening a popup	`md-button` `toggle`, or set `haspopup="false"`

This is the component’s entire purpose, so it is worth spelling out. Four things have to be wired:

Wire	How	Why
Default action	`mdLeadingClick`	The leading segment never opens anything
Open / close	`mdTrailingClick` → `menu.show()` / `menu.close()`	The component owns no popup
ARIA	`haspopup="menu"` + `controls="<menu id>"`	Announces “opens a menu” and links trigger to popup
Chevron + `aria-expanded`	`menu`’s `mdClose` → `split.trailingChecked = false`	Otherwise the chevron lies after an outside click or `Escape`

e.detail.checked on mdTrailingClick is the new state of the toggle, so it maps directly onto show/close.

Show code for each technology

<md-split-button
id="sb-save" icon="save" label="Save" variant="filled"
menu-label="More save options"
haspopup="menu" controls="sb-save-menu"
></md-split-button>

<md-menu id="sb-save-menu" anchor="sb-save" placement="bottom-end">
<md-menu-item headline="Save as…"></md-menu-item>
<md-menu-item headline="Save a copy"></md-menu-item>
<md-menu-item headline="Save and close"></md-menu-item>
</md-menu>

<script type="module">
const split = document.getElementById('sb-save');
const menu  = document.getElementById('sb-save-menu');

split.addEventListener('mdLeadingClick', () => save());

split.addEventListener('mdTrailingClick', (e) => {
  e.detail.checked ? menu.show() : menu.close();
});

// Outside click, Escape or an item pick all close the menu — resync the chevron.
menu.addEventListener('mdClose', () => { split.trailingChecked = false; });
</script>

import { useState } from 'react';
import { MdSplitButton, MdMenu, MdMenuItem } from '@awc-ui/react';

export function SaveSplitButton() {
// One piece of state drives both the chevron (trailingChecked) and the menu
// (open) — no refs, no imperative show()/close().
const [open, setOpen] = useState(false);

return (
  <>
    <MdSplitButton
      id="sb-save"
      icon="save"
      label="Save"
      variant="filled"
      menuLabel="More save options"
      haspopup="menu"
      controls="sb-save-menu"
      trailingChecked={open}
      onMdLeadingClick={() => save()}
      onMdTrailingClick={(e) => setOpen(e.detail.checked)}
    />

    <MdMenu
      id="sb-save-menu"
      anchor="sb-save"
      placement="bottom-end"
      open={open}
      onMdClose={() => setOpen(false)}
    >
      <MdMenuItem headline="Save as…" />
      <MdMenuItem headline="Save a copy" />
      <MdMenuItem headline="Save and close" />
    </MdMenu>
  </>
);
}

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

@Component({
selector: 'app-save-split-button',
template: `
  <md-split-button
    id="sb-save" icon="save" label="Save" variant="filled"
    menu-label="More save options"
    haspopup="menu" controls="sb-save-menu"
    [trailingChecked]="open"
    (mdLeadingClick)="save()"
    (mdTrailingClick)="open = $event.detail.checked"
  ></md-split-button>

  <md-menu id="sb-save-menu" anchor="sb-save" placement="bottom-end"
           [open]="open" (mdClose)="open = false">
    <md-menu-item headline="Save as…"></md-menu-item>
    <md-menu-item headline="Save a copy"></md-menu-item>
    <md-menu-item headline="Save and close"></md-menu-item>
  </md-menu>
`,
})
export class SaveSplitButtonComponent {
open = false;

save() { /* default action */ }
}

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

const open = ref(false);

function save() { /* default action */ }
</script>

<template>
<md-split-button
  id="sb-save" icon="save" label="Save" variant="filled"
  menu-label="More save options"
  haspopup="menu" controls="sb-save-menu"
  :trailing-checked="open"
  @mdLeadingClick="save"
  @mdTrailingClick="open = $event.detail.checked"
/>

<md-menu id="sb-save-menu" anchor="sb-save" placement="bottom-end"
         :open="open" @mdClose="open = false">
  <md-menu-item headline="Save as…" />
  <md-menu-item headline="Save a copy" />
  <md-menu-item headline="Save and close" />
</md-menu>
</template>

<script lang="ts">
let open = false;

function save() { /* default action */ }
</script>

<md-split-button
id="sb-save" icon="save" label="Save" variant="filled"
menu-label="More save options"
haspopup="menu" controls="sb-save-menu"
trailing-checked={open || undefined}
on:mdLeadingClick={save}
on:mdTrailingClick={(e) => (open = e.detail.checked)}
></md-split-button>

<md-menu id="sb-save-menu" anchor="sb-save" placement="bottom-end"
       open={open || undefined} on:mdClose={() => (open = false)}>
<md-menu-item headline="Save as…"></md-menu-item>
<md-menu-item headline="Save a copy"></md-menu-item>
<md-menu-item headline="Save and close"></md-menu-item>
</md-menu>

The same four wires carry any flow. Two more, live — a send menu and a version-control merge menu, each with its own md-menu:

Show code for each technology

<md-split-button
id="sb-send" icon="send" label="Send" variant="tonal"
menu-label="Send options" haspopup="menu" controls="sb-send-menu"
></md-split-button>

<md-menu id="sb-send-menu" anchor="sb-send" placement="bottom-end">
<md-menu-item headline="Schedule send"></md-menu-item>
<md-menu-item headline="Send without attachments"></md-menu-item>
<md-menu-item headline="Send and archive"></md-menu-item>
</md-menu>

<md-split-button
id="sb-merge" icon="merge" label="Merge pull request" variant="outlined"
menu-label="Other merge strategies" haspopup="menu" controls="sb-merge-menu"
></md-split-button>

<md-menu id="sb-merge-menu" anchor="sb-merge" placement="bottom-end">
<md-menu-item headline="Squash and merge"></md-menu-item>
<md-menu-item headline="Rebase and merge"></md-menu-item>
<md-menu-item headline="Create a merge commit" divider></md-menu-item>
<md-menu-item headline="Merge without waiting for checks"></md-menu-item>
</md-menu>

<script type="module">
// The same four wires, once per pair.
for (const [triggerId, menuId] of [
  ['sb-send', 'sb-send-menu'],
  ['sb-merge', 'sb-merge-menu'],
]) {
  const split = document.getElementById(triggerId);
  const menu = document.getElementById(menuId);

  split.addEventListener('mdTrailingClick', (e) => {
    e.detail.checked ? menu.show() : menu.close();
  });
  menu.addEventListener('mdClose', () => { split.trailingChecked = false; });
}
</script>

import { useState } from 'react';
import { MdSplitButton, MdMenu, MdMenuItem } from '@awc-ui/react';

export function Toolbar() {
// One boolean per pair — the chevron and the menu read the same state.
const [sendOpen, setSendOpen] = useState(false);
const [mergeOpen, setMergeOpen] = useState(false);

return (
  <>
    <MdSplitButton
      id="sb-send"
      icon="send"
      label="Send"
      variant="tonal"
      menuLabel="Send options"
      haspopup="menu"
      controls="sb-send-menu"
      trailingChecked={sendOpen}
      onMdTrailingClick={(e) => setSendOpen(e.detail.checked)}
    />
    <MdMenu
      id="sb-send-menu"
      anchor="sb-send"
      placement="bottom-end"
      open={sendOpen}
      onMdClose={() => setSendOpen(false)}
    >
      <MdMenuItem headline="Schedule send" />
      <MdMenuItem headline="Send without attachments" />
      <MdMenuItem headline="Send and archive" />
    </MdMenu>

    <MdSplitButton
      id="sb-merge"
      icon="merge"
      label="Merge pull request"
      variant="outlined"
      menuLabel="Other merge strategies"
      haspopup="menu"
      controls="sb-merge-menu"
      trailingChecked={mergeOpen}
      onMdTrailingClick={(e) => setMergeOpen(e.detail.checked)}
    />
    <MdMenu
      id="sb-merge-menu"
      anchor="sb-merge"
      placement="bottom-end"
      open={mergeOpen}
      onMdClose={() => setMergeOpen(false)}
    >
      <MdMenuItem headline="Squash and merge" />
      <MdMenuItem headline="Rebase and merge" />
      <MdMenuItem headline="Create a merge commit" divider />
      <MdMenuItem headline="Merge without waiting for checks" />
    </MdMenu>
  </>
);
}

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

@Component({
selector: 'app-toolbar',
template: `
  <md-split-button
    id="sb-send" icon="send" label="Send" variant="tonal"
    menu-label="Send options" haspopup="menu" controls="sb-send-menu"
    [trailingChecked]="sendOpen"
    (mdTrailingClick)="sendOpen = $event.detail.checked"
  ></md-split-button>

  <md-menu id="sb-send-menu" anchor="sb-send" placement="bottom-end"
           [open]="sendOpen" (mdClose)="sendOpen = false">
    <md-menu-item headline="Schedule send"></md-menu-item>
    <md-menu-item headline="Send without attachments"></md-menu-item>
    <md-menu-item headline="Send and archive"></md-menu-item>
  </md-menu>

  <md-split-button
    id="sb-merge" icon="merge" label="Merge pull request" variant="outlined"
    menu-label="Other merge strategies" haspopup="menu" controls="sb-merge-menu"
    [trailingChecked]="mergeOpen"
    (mdTrailingClick)="mergeOpen = $event.detail.checked"
  ></md-split-button>

  <md-menu id="sb-merge-menu" anchor="sb-merge" placement="bottom-end"
           [open]="mergeOpen" (mdClose)="mergeOpen = false">
    <md-menu-item headline="Squash and merge"></md-menu-item>
    <md-menu-item headline="Rebase and merge"></md-menu-item>
    <md-menu-item headline="Create a merge commit" divider></md-menu-item>
    <md-menu-item headline="Merge without waiting for checks"></md-menu-item>
  </md-menu>
`,
})
export class ToolbarComponent {
sendOpen = false;
mergeOpen = false;
}

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

const sendOpen = ref(false);
const mergeOpen = ref(false);
</script>

<template>
<md-split-button
  id="sb-send" icon="send" label="Send" variant="tonal"
  menu-label="Send options" haspopup="menu" controls="sb-send-menu"
  :trailing-checked="sendOpen"
  @mdTrailingClick="sendOpen = $event.detail.checked"
/>
<md-menu id="sb-send-menu" anchor="sb-send" placement="bottom-end"
         :open="sendOpen" @mdClose="sendOpen = false">
  <md-menu-item headline="Schedule send" />
  <md-menu-item headline="Send without attachments" />
  <md-menu-item headline="Send and archive" />
</md-menu>

<md-split-button
  id="sb-merge" icon="merge" label="Merge pull request" variant="outlined"
  menu-label="Other merge strategies" haspopup="menu" controls="sb-merge-menu"
  :trailing-checked="mergeOpen"
  @mdTrailingClick="mergeOpen = $event.detail.checked"
/>
<md-menu id="sb-merge-menu" anchor="sb-merge" placement="bottom-end"
         :open="mergeOpen" @mdClose="mergeOpen = false">
  <md-menu-item headline="Squash and merge" />
  <md-menu-item headline="Rebase and merge" />
  <md-menu-item headline="Create a merge commit" divider />
  <md-menu-item headline="Merge without waiting for checks" />
</md-menu>
</template>

<script lang="ts">
let sendOpen = false;
let mergeOpen = false;
</script>

<md-split-button
id="sb-send" icon="send" label="Send" variant="tonal"
menu-label="Send options" haspopup="menu" controls="sb-send-menu"
trailing-checked={sendOpen || undefined}
on:mdTrailingClick={(e) => (sendOpen = e.detail.checked)}
></md-split-button>

<md-menu id="sb-send-menu" anchor="sb-send" placement="bottom-end"
       open={sendOpen || undefined} on:mdClose={() => (sendOpen = false)}>
<md-menu-item headline="Schedule send"></md-menu-item>
<md-menu-item headline="Send without attachments"></md-menu-item>
<md-menu-item headline="Send and archive"></md-menu-item>
</md-menu>

<md-split-button
id="sb-merge" icon="merge" label="Merge pull request" variant="outlined"
menu-label="Other merge strategies" haspopup="menu" controls="sb-merge-menu"
trailing-checked={mergeOpen || undefined}
on:mdTrailingClick={(e) => (mergeOpen = e.detail.checked)}
></md-split-button>

<md-menu id="sb-merge-menu" anchor="sb-merge" placement="bottom-end"
       open={mergeOpen || undefined} on:mdClose={() => (mergeOpen = false)}>
<md-menu-item headline="Squash and merge"></md-menu-item>
<md-menu-item headline="Rebase and merge"></md-menu-item>
<md-menu-item headline="Create a merge commit" divider></md-menu-item>
<md-menu-item headline="Merge without waiting for checks"></md-menu-item>
</md-menu>

Variants

variant sets the emphasis of the whole control — both segments move together. The default is filled.

Variant	Emphasis	Use for
`filled`	Highest	The one primary action on the screen
`tonal`	High	A strong action that isn’t the primary one
`elevated`	Medium	Action sitting on a busy or coloured surface
`outlined`	Low	Secondary action next to a filled one

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-split-button variant="filled" icon="save" label="Filled" menu-label="More options"></md-split-button>
<md-split-button variant="tonal" icon="save" label="Tonal" menu-label="More options"></md-split-button>
<md-split-button variant="elevated" icon="save" label="Elevated" menu-label="More options"></md-split-button>
<md-split-button variant="outlined" icon="save" label="Outlined" menu-label="More options"></md-split-button>

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

export function Demo() {
  return (
    <>
      <MdSplitButton variant="filled" icon="save" label="Filled" menuLabel="More options"></MdSplitButton>
      <MdSplitButton variant="tonal" icon="save" label="Tonal" menuLabel="More options"></MdSplitButton>
      <MdSplitButton variant="elevated" icon="save" label="Elevated" menuLabel="More options"></MdSplitButton>
      <MdSplitButton variant="outlined" icon="save" label="Outlined" menuLabel="More options"></MdSplitButton>
    </>
  );
}

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

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

<!-- app.component.html -->
<md-split-button variant="filled" icon="save" label="Filled" menu-label="More options"></md-split-button>
<md-split-button variant="tonal" icon="save" label="Tonal" menu-label="More options"></md-split-button>
<md-split-button variant="elevated" icon="save" label="Elevated" menu-label="More options"></md-split-button>
<md-split-button variant="outlined" icon="save" label="Outlined" menu-label="More options"></md-split-button>

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

<template>
  <md-split-button variant="filled" icon="save" label="Filled" menu-label="More options"></md-split-button>
  <md-split-button variant="tonal" icon="save" label="Tonal" menu-label="More options"></md-split-button>
  <md-split-button variant="elevated" icon="save" label="Elevated" menu-label="More options"></md-split-button>
  <md-split-button variant="outlined" icon="save" label="Outlined" menu-label="More options"></md-split-button>
</template>

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

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

<md-split-button variant="filled" icon="save" label="Filled" menu-label="More options"></md-split-button>
<md-split-button variant="tonal" icon="save" label="Tonal" menu-label="More options"></md-split-button>
<md-split-button variant="elevated" icon="save" label="Elevated" menu-label="More options"></md-split-button>
<md-split-button variant="outlined" icon="save" label="Outlined" menu-label="More options"></md-split-button>

Sizes

Size	Height
`xs`	32px
`sm` (default)	40px
`md`	56px
`lg`	96px
`xl`	136px

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-split-button size="xs" icon="save" label="Extra small" menu-label="More options"></md-split-button>
<md-split-button size="sm" icon="save" label="Small" menu-label="More options"></md-split-button>
<md-split-button size="md" icon="save" label="Medium" menu-label="More options"></md-split-button>
<md-split-button size="lg" icon="save" label="Large" menu-label="More options"></md-split-button>
<md-split-button size="xl" icon="save" label="Extra large" menu-label="More options"></md-split-button>

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

export function Demo() {
  return (
    <>
      <MdSplitButton size="xs" icon="save" label="Extra small" menuLabel="More options"></MdSplitButton>
      <MdSplitButton size="sm" icon="save" label="Small" menuLabel="More options"></MdSplitButton>
      <MdSplitButton size="md" icon="save" label="Medium" menuLabel="More options"></MdSplitButton>
      <MdSplitButton size="lg" icon="save" label="Large" menuLabel="More options"></MdSplitButton>
      <MdSplitButton size="xl" icon="save" label="Extra large" menuLabel="More options"></MdSplitButton>
    </>
  );
}

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

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

<!-- app.component.html -->
<md-split-button size="xs" icon="save" label="Extra small" menu-label="More options"></md-split-button>
<md-split-button size="sm" icon="save" label="Small" menu-label="More options"></md-split-button>
<md-split-button size="md" icon="save" label="Medium" menu-label="More options"></md-split-button>
<md-split-button size="lg" icon="save" label="Large" menu-label="More options"></md-split-button>
<md-split-button size="xl" icon="save" label="Extra large" menu-label="More options"></md-split-button>

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

<template>
  <md-split-button size="xs" icon="save" label="Extra small" menu-label="More options"></md-split-button>
  <md-split-button size="sm" icon="save" label="Small" menu-label="More options"></md-split-button>
  <md-split-button size="md" icon="save" label="Medium" menu-label="More options"></md-split-button>
  <md-split-button size="lg" icon="save" label="Large" menu-label="More options"></md-split-button>
  <md-split-button size="xl" icon="save" label="Extra large" menu-label="More options"></md-split-button>
</template>

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

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

<md-split-button size="xs" icon="save" label="Extra small" menu-label="More options"></md-split-button>
<md-split-button size="sm" icon="save" label="Small" menu-label="More options"></md-split-button>
<md-split-button size="md" icon="save" label="Medium" menu-label="More options"></md-split-button>
<md-split-button size="lg" icon="save" label="Large" menu-label="More options"></md-split-button>
<md-split-button size="xl" icon="save" label="Extra large" menu-label="More options"></md-split-button>

Icons

The two segments take their glyphs from two different props. icon is the leading action’s Material Symbols name and is optional; trailing-icon is the toggle’s glyph and defaults to keyboard_arrow_down. Both scale with size.

Prop	Segment	Default
`icon`	Leading	`''` — no icon
`trailing-icon`	Trailing toggle	`'keyboard_arrow_down'`

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-split-button icon="save" label="With an icon" menu-label="More options"></md-split-button>
<md-split-button label="Label only" menu-label="More options"></md-split-button>
<md-split-button icon="filter_list" label="Filter" trailing-icon="expand_more" menu-label="Filter options"></md-split-button>
<md-split-button icon="palette" label="Theme" trailing-icon="more_vert" menu-label="Theme options" variant="outlined"></md-split-button>

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

export function Demo() {
  return (
    <>
      <MdSplitButton icon="save" label="With an icon" menuLabel="More options"></MdSplitButton>
      <MdSplitButton label="Label only" menuLabel="More options"></MdSplitButton>
      <MdSplitButton icon="filter_list" label="Filter" trailingIcon="expand_more" menuLabel="Filter options"></MdSplitButton>
      <MdSplitButton icon="palette" label="Theme" trailingIcon="more_vert" menuLabel="Theme options" variant="outlined"></MdSplitButton>
    </>
  );
}

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

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

<!-- app.component.html -->
<md-split-button icon="save" label="With an icon" menu-label="More options"></md-split-button>
<md-split-button label="Label only" menu-label="More options"></md-split-button>
<md-split-button icon="filter_list" label="Filter" trailing-icon="expand_more" menu-label="Filter options"></md-split-button>
<md-split-button icon="palette" label="Theme" trailing-icon="more_vert" menu-label="Theme options" variant="outlined"></md-split-button>

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

<template>
  <md-split-button icon="save" label="With an icon" menu-label="More options"></md-split-button>
  <md-split-button label="Label only" menu-label="More options"></md-split-button>
  <md-split-button icon="filter_list" label="Filter" trailing-icon="expand_more" menu-label="Filter options"></md-split-button>
  <md-split-button icon="palette" label="Theme" trailing-icon="more_vert" menu-label="Theme options" variant="outlined"></md-split-button>
</template>

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

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

<md-split-button icon="save" label="With an icon" menu-label="More options"></md-split-button>
<md-split-button label="Label only" menu-label="More options"></md-split-button>
<md-split-button icon="filter_list" label="Filter" trailing-icon="expand_more" menu-label="Filter options"></md-split-button>
<md-split-button icon="palette" label="Theme" trailing-icon="more_vert" menu-label="Theme options" variant="outlined"></md-split-button>

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-split-button icon="edit" aria-label="Edit item" menu-label="More edit options" variant="tonal"></md-split-button>

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

export function Demo() {
  return (
    <>
      <MdSplitButton icon="edit" aria-label="Edit item" menuLabel="More edit options" variant="tonal"></MdSplitButton>
    </>
  );
}

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

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

<!-- app.component.html -->
<md-split-button icon="edit" aria-label="Edit item" menu-label="More edit options" variant="tonal"></md-split-button>

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

<template>
  <md-split-button icon="edit" aria-label="Edit item" menu-label="More edit options" variant="tonal"></md-split-button>
</template>

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

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

<md-split-button icon="edit" aria-label="Edit item" menu-label="More edit options" variant="tonal"></md-split-button>

States

disabled disables both segments and drops them from the tab order; soft-disabled keeps them focusable so an unavailable action stays discoverable.

State	Focusable	Use when
default	yes	The action is available
`disabled`	no	The action is gone and its absence needs no explanation
`soft-disabled`	yes	The action is temporarily unavailable and users must be able to find out why

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-split-button icon="save" label="Enabled" menu-label="More options"></md-split-button>
<md-split-button icon="save" label="Disabled" menu-label="More options" disabled></md-split-button>
<md-split-button icon="save" label="Soft-disabled" menu-label="More options" soft-disabled></md-split-button>

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

export function Demo() {
  return (
    <>
      <MdSplitButton icon="save" label="Enabled" menuLabel="More options"></MdSplitButton>
      <MdSplitButton icon="save" label="Disabled" menuLabel="More options" disabled></MdSplitButton>
      <MdSplitButton icon="save" label="Soft-disabled" menuLabel="More options" soft-disabled></MdSplitButton>
    </>
  );
}

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

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

<!-- app.component.html -->
<md-split-button icon="save" label="Enabled" menu-label="More options"></md-split-button>
<md-split-button icon="save" label="Disabled" menu-label="More options" disabled></md-split-button>
<md-split-button icon="save" label="Soft-disabled" menu-label="More options" soft-disabled></md-split-button>

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

<template>
  <md-split-button icon="save" label="Enabled" menu-label="More options"></md-split-button>
  <md-split-button icon="save" label="Disabled" menu-label="More options" disabled></md-split-button>
  <md-split-button icon="save" label="Soft-disabled" menu-label="More options" soft-disabled></md-split-button>
</template>

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

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

<md-split-button icon="save" label="Enabled" menu-label="More options"></md-split-button>
<md-split-button icon="save" label="Disabled" menu-label="More options" disabled></md-split-button>
<md-split-button icon="save" label="Soft-disabled" menu-label="More options" soft-disabled></md-split-button>

trailing-checked is the toggle’s own state and drives both the chevron rotation and aria-expanded. When the trailing side toggles state rather than opening a popup, set haspopup="false" so nothing is announced as a popup.

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-split-button icon="notifications" label="Follow" menu-label="Notification settings" haspopup="false"></md-split-button>
<md-split-button icon="notifications" label="Following" menu-label="Notification settings" haspopup="false" trailing-checked></md-split-button>

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

export function Demo() {
  return (
    <>
      <MdSplitButton icon="notifications" label="Follow" menuLabel="Notification settings" haspopup="false"></MdSplitButton>
      <MdSplitButton icon="notifications" label="Following" menuLabel="Notification settings" haspopup="false" trailing-checked></MdSplitButton>
    </>
  );
}

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

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

<!-- app.component.html -->
<md-split-button icon="notifications" label="Follow" menu-label="Notification settings" haspopup="false"></md-split-button>
<md-split-button icon="notifications" label="Following" menu-label="Notification settings" haspopup="false" trailing-checked></md-split-button>

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

<template>
  <md-split-button icon="notifications" label="Follow" menu-label="Notification settings" haspopup="false"></md-split-button>
  <md-split-button icon="notifications" label="Following" menu-label="Notification settings" haspopup="false" trailing-checked></md-split-button>
</template>

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

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

<md-split-button icon="notifications" label="Follow" menu-label="Notification settings" haspopup="false"></md-split-button>
<md-split-button icon="notifications" label="Following" menu-label="Notification settings" haspopup="false" trailing-checked></md-split-button>

Full width

full-width grows the leading segment to fill the container and truncates its label with an ellipsis; the trailing toggle keeps its intrinsic width so it stays a fixed-size target.

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="inline-size: 100%; max-inline-size: 420px; display: flex; flex-direction: column; gap: 16px;">
  <md-split-button full-width icon="cloud_upload" label="Upload" variant="filled" menu-label="Upload options"></md-split-button>
  <md-split-button full-width icon="description" label="Save and continue to the next step" variant="outlined" menu-label="Save options"></md-split-button>
</div>

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

export function Demo() {
  return (
    <>
      <div style={{ inlineSize: '100%', maxInlineSize: '420px', display: 'flex', flexDirection: 'column', gap: '16px' }}>
        <MdSplitButton fullWidth icon="cloud_upload" label="Upload" variant="filled" menuLabel="Upload options"></MdSplitButton>
        <MdSplitButton fullWidth icon="description" label="Save and continue to the next step" variant="outlined" menuLabel="Save options"></MdSplitButton>
      </div>
    </>
  );
}

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

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

<!-- app.component.html -->
<div style="inline-size: 100%; max-inline-size: 420px; display: flex; flex-direction: column; gap: 16px;">
  <md-split-button full-width icon="cloud_upload" label="Upload" variant="filled" menu-label="Upload options"></md-split-button>
  <md-split-button full-width icon="description" label="Save and continue to the next step" variant="outlined" menu-label="Save options"></md-split-button>
</div>

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

<template>
  <div style="inline-size: 100%; max-inline-size: 420px; display: flex; flex-direction: column; gap: 16px;">
    <md-split-button full-width icon="cloud_upload" label="Upload" variant="filled" menu-label="Upload options"></md-split-button>
    <md-split-button full-width icon="description" label="Save and continue to the next step" variant="outlined" menu-label="Save options"></md-split-button>
  </div>
</template>

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

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

<div style="inline-size: 100%; max-inline-size: 420px; display: flex; flex-direction: column; gap: 16px;">
  <md-split-button full-width icon="cloud_upload" label="Upload" variant="filled" menu-label="Upload options"></md-split-button>
  <md-split-button full-width icon="description" label="Save and continue to the next step" variant="outlined" menu-label="Save options"></md-split-button>
</div>

Events

Event	Cancelable	Detail	Fires
`mdLeadingClick`	no	`void`	The leading (default action) segment is activated
`mdTrailingClick`	no	`{ checked: boolean }`	The trailing toggle is activated; `checked` is the new state

There is no single generic event covering both segments — that is deliberate, since the whole point is telling them apart.

Neither detail has a named exported type — mdTrailingClick is declared inline as EventEmitter<{ checked: boolean }>, so there is nothing to import from @awc-ui/core. Type your handler against the shape directly:

function onTrailing(
  e: CustomEvent<{
    /** The state the toggle has just moved INTO — map it onto show/close. */
    checked: boolean;
  }>,
) {
  e.detail.checked ? menu.show() : menu.close();
}

Click the label, then the chevron. Both segments report separately.

Show code for each technology

<md-split-button id="sb" icon="save" label="Save" menu-label="More save options"></md-split-button>

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

sb.addEventListener('mdLeadingClick', () => save());
sb.addEventListener('mdTrailingClick', (e) => {
  console.log('toggle is now', e.detail.checked);
});
</script>

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

export function SaveSplitButton() {
return (
  <MdSplitButton
    icon="save"
    label="Save"
    menuLabel="More save options"
    onMdLeadingClick={() => save()}
    onMdTrailingClick={(e) => console.log('toggle is now', e.detail.checked)}
  />
);
}

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

@Component({
selector: 'app-save-split-button',
template: `
  <md-split-button
    icon="save" label="Save" menu-label="More save options"
    (mdLeadingClick)="save()"
    (mdTrailingClick)="onTrailing($event)"
  ></md-split-button>
`,
})
export class SaveSplitButtonComponent {
save() { /* … */ }
onTrailing(e: CustomEvent<{ checked: boolean }>) {
  console.log('toggle is now', e.detail.checked);
}
}

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

function onTrailing(e: CustomEvent) {
console.log('toggle is now', e.detail.checked);
}
</script>

<template>
<md-split-button
  icon="save" label="Save" menu-label="More save options"
  @mdLeadingClick="save"
  @mdTrailingClick="onTrailing"
/>
</template>

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

function onTrailing(e: CustomEvent) {
  console.log('toggle is now', e.detail.checked);
}
</script>

<md-split-button
icon="save" label="Save" menu-label="More save options"
on:mdLeadingClick={save}
on:mdTrailingClick={onTrailing}
></md-split-button>

API Reference

Property	Attribute	Type	Default	Reflects
`variant`	`variant`	`'elevated' \| 'filled' \| 'tonal' \| 'outlined'`	`'filled'`	—
`size`	`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'sm'`	—
`disabled`	`disabled`	`boolean`	`false`	Yes
`softDisabled`	`soft-disabled`	`boolean`	`false`	Yes
`icon`	`icon`	`string`	`''`	—
`label`	`label`	`string`	`''`	—
`trailingIcon`	`trailing-icon`	`string`	`'keyboard_arrow_down'`	—
`trailingChecked`	`trailing-checked`	`boolean`	`false`	Yes
`menuLabel`	`menu-label`	`string`	`'Toggle menu'`	—
`haspopup`	`haspopup`	`\| 'menu' \| 'listbox' \| 'dialog' \| 'grid' \| 'tree' \| 'true' \| 'false'`	`'menu'`	—
`controls`	`controls`	`string`	`''`	—
`fullWidth`	`full-width`	`boolean`	`false`	Yes
`ripple`	`ripple`	`boolean`	`true`	—
`density`	`density`	`0 \| -1 \| -2 \| -3 \| -4`	`0`	Yes

Slot	Description
`(default)`	—

Override on the host element for per-instance theming:

Property	Description
`--md-split-button-container-color`	Container background
`--md-split-button-label-color`	Label + icon color
`--md-split-button-icon-color`	Icon override
`--md-split-button-outline-color`	Outlined border
`--md-split-button-container-shape`	Outer corner override
`--md-split-button-icon-size`	Icon dimensions

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

Part	Description
`leading`	Leading button
`leading-state-layer`	Leading state overlay
`icon`	Leading icon
`label`	Label text
`trailing`	Trailing button
`trailing-state-layer`	Trailing state overlay
`trailing-icon`	Trailing menu icon

Accessibility

The control is two separate buttons. The leading one is named by label (or the host aria-label); the trailing one is named only by menu-label (WCAG 4.1.2) — its default is the English "Toggle menu".
haspopup sets aria-haspopup on the trailing button and controls sets aria-controls. Set haspopup="false" when nothing pops up.
aria-expanded is driven by trailing-checked. Keep it truthful — resync it from the menu’s mdClose, not just from your own click handler.
Both segments activate on Enter and Space, and each takes its own tab stop, so the default action is always reachable without opening the menu.
disabled disables both segments and drops them from the tab order; soft-disabled keeps them focusable.

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-split-button id="sb-a11y-sort" icon="sort" label="Sort" variant="tonal" haspopup="menu" controls="sb-a11y-sort-menu" menu-label="Sort options"></md-split-button>
<md-split-button icon="favorite" label="Like" variant="outlined" haspopup="false" menu-label="Toggle like"></md-split-button>
<md-split-button icon="save" label="Unavailable" soft-disabled menu-label="More save options"></md-split-button>

<md-menu id="sb-a11y-sort-menu" anchor="sb-a11y-sort" placement="bottom-end">
  <md-menu-item headline="Newest first"></md-menu-item>
  <md-menu-item headline="Oldest first"></md-menu-item>
  <md-menu-item headline="Alphabetical"></md-menu-item>
</md-menu>

<script type="module">
  var sort = document.getElementById('sb-a11y-sort');
  var sortMenu = document.getElementById('sb-a11y-sort-menu');

  sort.addEventListener('mdTrailingClick', function (e) {
    if (e.detail.checked) { sortMenu.show(); } else { sortMenu.close(); }
  });
  sortMenu.addEventListener('mdClose', function () { sort.trailingChecked = false; });
</script>

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

export function Demo() {
  const sortRef = useRef(null);
  const sortMenuRef = useRef(null);

  useEffect(() => {
    const sort = sortRef.current;
    const sortMenu = sortMenuRef.current;

    sort.addEventListener('mdTrailingClick', function (e) {
      if (e.detail.checked) { sortMenu.show(); } else { sortMenu.close(); }
    });
    sortMenu.addEventListener('mdClose', function () { sort.trailingChecked = false; });
  }, []);

  return (
    <>
      <MdSplitButton id="sb-a11y-sort" ref={sortRef} icon="sort" label="Sort" variant="tonal" haspopup="menu" controls="sb-a11y-sort-menu" menuLabel="Sort options"></MdSplitButton>
      <MdSplitButton icon="favorite" label="Like" variant="outlined" haspopup="false" menuLabel="Toggle like"></MdSplitButton>
      <MdSplitButton icon="save" label="Unavailable" softDisabled menuLabel="More save options"></MdSplitButton>

      <MdMenu id="sb-a11y-sort-menu" ref={sortMenuRef} anchor="sb-a11y-sort" placement="bottom-end">
        <MdMenuItem headline="Newest first"></MdMenuItem>
        <MdMenuItem headline="Oldest first"></MdMenuItem>
        <MdMenuItem headline="Alphabetical"></MdMenuItem>
      </MdMenu>
    </>
  );
}

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

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

// app.component.ts
import { AfterViewInit, Component, ElementRef, ViewChild } from '@angular/core';

@Component({
  selector: 'app-demo',
  templateUrl: './app.component.html',
})
export class DemoComponent implements AfterViewInit {
  @ViewChild('sort') sortRef!: ElementRef;
  @ViewChild('sortMenu') sortMenuRef!: ElementRef;

  ngAfterViewInit() {
    const sort = this.sortRef.nativeElement;
    const sortMenu = this.sortMenuRef.nativeElement;

    sort.addEventListener('mdTrailingClick', function (e) {
      if (e.detail.checked) { sortMenu.show(); } else { sortMenu.close(); }
    });
    sortMenu.addEventListener('mdClose', function () { sort.trailingChecked = false; });
  }
}

<!-- app.component.html -->
<md-split-button id="sb-a11y-sort" #sort icon="sort" label="Sort" variant="tonal" haspopup="menu" controls="sb-a11y-sort-menu" menu-label="Sort options"></md-split-button>
<md-split-button icon="favorite" label="Like" variant="outlined" haspopup="false" menu-label="Toggle like"></md-split-button>
<md-split-button icon="save" label="Unavailable" soft-disabled menu-label="More save options"></md-split-button>

<md-menu id="sb-a11y-sort-menu" #sortMenu anchor="sb-a11y-sort" placement="bottom-end">
  <md-menu-item headline="Newest first"></md-menu-item>
  <md-menu-item headline="Oldest first"></md-menu-item>
  <md-menu-item headline="Alphabetical"></md-menu-item>
</md-menu>

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

const sortRef = ref(null);
const sortMenuRef = ref(null);

onMounted(() => {
  const sort = sortRef.value;
  const sortMenu = sortMenuRef.value;

  sort.addEventListener('mdTrailingClick', function (e) {
    if (e.detail.checked) { sortMenu.show(); } else { sortMenu.close(); }
  });
  sortMenu.addEventListener('mdClose', function () { sort.trailingChecked = false; });
});
</script>

<template>
  <md-split-button id="sb-a11y-sort" ref="sortRef" icon="sort" label="Sort" variant="tonal" haspopup="menu" controls="sb-a11y-sort-menu" menu-label="Sort options"></md-split-button>
  <md-split-button icon="favorite" label="Like" variant="outlined" haspopup="false" menu-label="Toggle like"></md-split-button>
  <md-split-button icon="save" label="Unavailable" soft-disabled menu-label="More save options"></md-split-button>

  <md-menu id="sb-a11y-sort-menu" ref="sortMenuRef" anchor="sb-a11y-sort" placement="bottom-end">
    <md-menu-item headline="Newest first"></md-menu-item>
    <md-menu-item headline="Oldest first"></md-menu-item>
    <md-menu-item headline="Alphabetical"></md-menu-item>
  </md-menu>
</template>

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

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

  let sortRef;
  let sortMenuRef;

  onMount(() => {
    const sort = sortRef;
    const sortMenu = sortMenuRef;

    sort.addEventListener('mdTrailingClick', function (e) {
      if (e.detail.checked) { sortMenu.show(); } else { sortMenu.close(); }
    });
    sortMenu.addEventListener('mdClose', function () { sort.trailingChecked = false; });
  });
</script>

<md-split-button id="sb-a11y-sort" bind:this={sortRef} icon="sort" label="Sort" variant="tonal" haspopup="menu" controls="sb-a11y-sort-menu" menu-label="Sort options"></md-split-button>
<md-split-button icon="favorite" label="Like" variant="outlined" haspopup="false" menu-label="Toggle like"></md-split-button>
<md-split-button icon="save" label="Unavailable" soft-disabled menu-label="More save options"></md-split-button>

<md-menu id="sb-a11y-sort-menu" bind:this={sortMenuRef} anchor="sb-a11y-sort" placement="bottom-end">
  <md-menu-item headline="Newest first"></md-menu-item>
  <md-menu-item headline="Oldest first"></md-menu-item>
  <md-menu-item headline="Alphabetical"></md-menu-item>
</md-menu>

RTL, density & i18n

RTL — the segments swap order automatically under dir="rtl"; the corner radii and padding use logical properties, so the outer pill always lands on the inline-start edge and the split corner on the inline-end edge. The default chevron (keyboard_arrow_down) is vertical and needs no mirroring — a custom horizontal glyph does. See RTL.

<div dir="rtl">
  <md-split-button icon="edit" label="تعديل" menu-label="تبديل القائمة"></md-split-button>
</div>

The same split buttons in both directions. Nothing is re-authored between the rows — only dir changes:

ltr

rtl

Show code for each technology

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

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="filled" icon="edit" label="Edit" menu-label="Toggle menu"></md-split-button>
    <md-split-button variant="outlined" icon="add" label="Create" menu-label="Create options"></md-split-button>
    <md-split-button variant="elevated" icon="save" label="Save" menu-label="More save options"></md-split-button>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="filled" icon="edit" label="تعديل" menu-label="تبديل القائمة"></md-split-button>
    <md-split-button variant="outlined" icon="add" label="إنشاء" menu-label="خيارات الإنشاء"></md-split-button>
    <md-split-button variant="elevated" icon="save" label="حفظ" menu-label="خيارات الحفظ"></md-split-button>
  </div>
</div>

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>ltr</span>
        <div dir="ltr" style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdSplitButton variant="filled" icon="edit" label="Edit" menuLabel="Toggle menu"></MdSplitButton>
          <MdSplitButton variant="outlined" icon="add" label="Create" menuLabel="Create options"></MdSplitButton>
          <MdSplitButton variant="elevated" icon="save" label="Save" menuLabel="More save options"></MdSplitButton>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>rtl</span>
        <div dir="rtl" style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdSplitButton variant="filled" icon="edit" label="تعديل" menuLabel="تبديل القائمة"></MdSplitButton>
          <MdSplitButton variant="outlined" icon="add" label="إنشاء" menuLabel="خيارات الإنشاء"></MdSplitButton>
          <MdSplitButton variant="elevated" icon="save" label="حفظ" menuLabel="خيارات الحفظ"></MdSplitButton>
        </div>
      </div>
    </>
  );
}

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

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

<!-- app.component.html -->
<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="filled" icon="edit" label="Edit" menu-label="Toggle menu"></md-split-button>
    <md-split-button variant="outlined" icon="add" label="Create" menu-label="Create options"></md-split-button>
    <md-split-button variant="elevated" icon="save" label="Save" menu-label="More save options"></md-split-button>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="filled" icon="edit" label="تعديل" menu-label="تبديل القائمة"></md-split-button>
    <md-split-button variant="outlined" icon="add" label="إنشاء" menu-label="خيارات الإنشاء"></md-split-button>
    <md-split-button variant="elevated" icon="save" label="حفظ" menu-label="خيارات الحفظ"></md-split-button>
  </div>
</div>

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

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
    <div dir="ltr" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
      <md-split-button variant="filled" icon="edit" label="Edit" menu-label="Toggle menu"></md-split-button>
      <md-split-button variant="outlined" icon="add" label="Create" menu-label="Create options"></md-split-button>
      <md-split-button variant="elevated" icon="save" label="Save" menu-label="More save options"></md-split-button>
    </div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
    <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
      <md-split-button variant="filled" icon="edit" label="تعديل" menu-label="تبديل القائمة"></md-split-button>
      <md-split-button variant="outlined" icon="add" label="إنشاء" menu-label="خيارات الإنشاء"></md-split-button>
      <md-split-button variant="elevated" icon="save" label="حفظ" menu-label="خيارات الحفظ"></md-split-button>
    </div>
  </div>
</template>

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

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="filled" icon="edit" label="Edit" menu-label="Toggle menu"></md-split-button>
    <md-split-button variant="outlined" icon="add" label="Create" menu-label="Create options"></md-split-button>
    <md-split-button variant="elevated" icon="save" label="Save" menu-label="More save options"></md-split-button>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="filled" icon="edit" label="تعديل" menu-label="تبديل القائمة"></md-split-button>
    <md-split-button variant="outlined" icon="add" label="إنشاء" menu-label="خيارات الإنشاء"></md-split-button>
    <md-split-button variant="elevated" icon="save" label="حفظ" menu-label="خيارات الحفظ"></md-split-button>
  </div>
</div>

Only the trailing glyph can point the wrong way

The layout mirrors itself, so the one thing left to get wrong is trailing-icon. The default keyboard_arrow_down points along the block axis and reads identically in both directions. Swap in a horizontal glyph and it now points away from the menu it opens under RTL — compare the rows:

correct

wrong

Show code for each technology

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

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="tonal" icon="edit" label="تعديل" menu-label="تبديل القائمة"></md-split-button>
    <md-split-button variant="tonal" icon="add" label="إنشاء" trailing-icon="expand_more" menu-label="خيارات الإنشاء"></md-split-button>
    <md-split-button variant="tonal" icon="save" label="حفظ" trailing-icon="more_vert" menu-label="خيارات الحفظ"></md-split-button>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="outlined" icon="edit" label="تعديل" trailing-icon="chevron_right" menu-label="تبديل القائمة"></md-split-button>
    <md-split-button variant="outlined" icon="add" label="إنشاء" trailing-icon="arrow_forward" menu-label="خيارات الإنشاء"></md-split-button>
    <md-split-button variant="outlined" icon="save" label="حفظ" trailing-icon="double_arrow" menu-label="خيارات الحفظ"></md-split-button>
  </div>
</div>

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>correct</span>
        <div dir="rtl" style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdSplitButton variant="tonal" icon="edit" label="تعديل" menuLabel="تبديل القائمة"></MdSplitButton>
          <MdSplitButton variant="tonal" icon="add" label="إنشاء" trailingIcon="expand_more" menuLabel="خيارات الإنشاء"></MdSplitButton>
          <MdSplitButton variant="tonal" icon="save" label="حفظ" trailingIcon="more_vert" menuLabel="خيارات الحفظ"></MdSplitButton>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>wrong</span>
        <div dir="rtl" style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdSplitButton variant="outlined" icon="edit" label="تعديل" trailingIcon="chevron_right" menuLabel="تبديل القائمة"></MdSplitButton>
          <MdSplitButton variant="outlined" icon="add" label="إنشاء" trailingIcon="arrow_forward" menuLabel="خيارات الإنشاء"></MdSplitButton>
          <MdSplitButton variant="outlined" icon="save" label="حفظ" trailingIcon="double_arrow" menuLabel="خيارات الحفظ"></MdSplitButton>
        </div>
      </div>
    </>
  );
}

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

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

<!-- app.component.html -->
<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="tonal" icon="edit" label="تعديل" menu-label="تبديل القائمة"></md-split-button>
    <md-split-button variant="tonal" icon="add" label="إنشاء" trailing-icon="expand_more" menu-label="خيارات الإنشاء"></md-split-button>
    <md-split-button variant="tonal" icon="save" label="حفظ" trailing-icon="more_vert" menu-label="خيارات الحفظ"></md-split-button>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="outlined" icon="edit" label="تعديل" trailing-icon="chevron_right" menu-label="تبديل القائمة"></md-split-button>
    <md-split-button variant="outlined" icon="add" label="إنشاء" trailing-icon="arrow_forward" menu-label="خيارات الإنشاء"></md-split-button>
    <md-split-button variant="outlined" icon="save" label="حفظ" trailing-icon="double_arrow" menu-label="خيارات الحفظ"></md-split-button>
  </div>
</div>

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

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
    <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
      <md-split-button variant="tonal" icon="edit" label="تعديل" menu-label="تبديل القائمة"></md-split-button>
      <md-split-button variant="tonal" icon="add" label="إنشاء" trailing-icon="expand_more" menu-label="خيارات الإنشاء"></md-split-button>
      <md-split-button variant="tonal" icon="save" label="حفظ" trailing-icon="more_vert" menu-label="خيارات الحفظ"></md-split-button>
    </div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
    <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
      <md-split-button variant="outlined" icon="edit" label="تعديل" trailing-icon="chevron_right" menu-label="تبديل القائمة"></md-split-button>
      <md-split-button variant="outlined" icon="add" label="إنشاء" trailing-icon="arrow_forward" menu-label="خيارات الإنشاء"></md-split-button>
      <md-split-button variant="outlined" icon="save" label="حفظ" trailing-icon="double_arrow" menu-label="خيارات الحفظ"></md-split-button>
    </div>
  </div>
</template>

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

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="tonal" icon="edit" label="تعديل" menu-label="تبديل القائمة"></md-split-button>
    <md-split-button variant="tonal" icon="add" label="إنشاء" trailing-icon="expand_more" menu-label="خيارات الإنشاء"></md-split-button>
    <md-split-button variant="tonal" icon="save" label="حفظ" trailing-icon="more_vert" menu-label="خيارات الحفظ"></md-split-button>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div dir="rtl" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="outlined" icon="edit" label="تعديل" trailing-icon="chevron_right" menu-label="تبديل القائمة"></md-split-button>
    <md-split-button variant="outlined" icon="add" label="إنشاء" trailing-icon="arrow_forward" menu-label="خيارات الإنشاء"></md-split-button>
    <md-split-button variant="outlined" icon="save" label="حفظ" trailing-icon="double_arrow" menu-label="خيارات الحفظ"></md-split-button>
  </div>
</div>

Every density rung

density="-1…-4" is a local override of the inherited data-density; 0 is the default value, not an override, so the first row below carries no attribute at all. The default plus all four rungs, same split button, so the taper is visible in one place:

-1

-2

-3

-4

Show code for each technology

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

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-1" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-1" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-2" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-2" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-3" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-3" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-4" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-4" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
</div>

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>0</span>
        <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}><MdSplitButton variant="filled" icon="save" label="Save" menuLabel="More save options"></MdSplitButton><MdSplitButton variant="outlined" icon="add" label="Create" menuLabel="Create options"></MdSplitButton></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-1</span>
        <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}><MdSplitButton variant="filled" density="-1" icon="save" label="Save" menuLabel="More save options"></MdSplitButton><MdSplitButton variant="outlined" density="-1" icon="add" label="Create" menuLabel="Create options"></MdSplitButton></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-2</span>
        <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}><MdSplitButton variant="filled" density="-2" icon="save" label="Save" menuLabel="More save options"></MdSplitButton><MdSplitButton variant="outlined" density="-2" icon="add" label="Create" menuLabel="Create options"></MdSplitButton></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-3</span>
        <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}><MdSplitButton variant="filled" density="-3" icon="save" label="Save" menuLabel="More save options"></MdSplitButton><MdSplitButton variant="outlined" density="-3" icon="add" label="Create" menuLabel="Create options"></MdSplitButton></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-4</span>
        <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}><MdSplitButton variant="filled" density="-4" icon="save" label="Save" menuLabel="More save options"></MdSplitButton><MdSplitButton variant="outlined" density="-4" icon="add" label="Create" menuLabel="Create options"></MdSplitButton></div>
      </div>
    </>
  );
}

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

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

<!-- app.component.html -->
<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-1" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-1" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-2" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-2" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-3" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-3" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-4" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-4" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
</div>

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

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
    <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
    <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-1" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-1" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
    <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-2" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-2" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
    <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-3" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-3" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
    <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-4" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-4" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  </div>
</template>

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

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

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-1" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-1" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-2" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-2" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-3" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-3" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;"><md-split-button variant="filled" density="-4" icon="save" label="Save" menu-label="More save options"></md-split-button><md-split-button variant="outlined" density="-4" icon="add" label="Create" menu-label="Create options"></md-split-button></div>
</div>

Each rung takes 4px off the height — 40, 36, 32, 28, 24 at the default sm size — and trims the inline padding, the label type and the icon↔label gap alongside, which pulls the whole control in from 133px wide to 92px. Both segments shrink together, so the 2px gap between them never breaks.

The glyphs do not taper. Both the leading icon and the chevron are sized purely from size (18px and 22px at sm), so they stay put at every rung — which is what keeps the trailing toggle legible as the container closes in on it. Resize them yourself with --md-split-button-icon-size if you need to.

Set it per instance, or inherit it from an ancestor and let a whole toolbar tighten at once:

<div data-density="-2">
  <md-split-button label="Save" icon="save" menu-label="More"></md-split-button>
</div>

Density and direction together

The two are independent signals, so they compose without any extra wiring — a wrapper sets the rung for everything inside it, and any one control can take a tighter rung of its own.

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 dir="rtl" data-density="-2" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
  <md-split-button variant="filled" icon="save" label="حفظ" menu-label="خيارات الحفظ"></md-split-button>
  <md-split-button variant="outlined" icon="add" label="إنشاء" menu-label="خيارات الإنشاء"></md-split-button>
  <md-split-button variant="tonal" icon="edit" label="أكثر إحكاما" density="-4" menu-label="تبديل القائمة"></md-split-button>
  <md-split-button variant="tonal" icon="edit" label="افتراضي" style="--md-sys-density-scale: 0;" menu-label="تبديل القائمة"></md-split-button>
</div>

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

export function Demo() {
  return (
    <>
      <div dir="rtl" data-density="-2" style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
        <MdSplitButton variant="filled" icon="save" label="حفظ" menuLabel="خيارات الحفظ"></MdSplitButton>
        <MdSplitButton variant="outlined" icon="add" label="إنشاء" menuLabel="خيارات الإنشاء"></MdSplitButton>
        <MdSplitButton variant="tonal" icon="edit" label="أكثر إحكاما" density="-4" menuLabel="تبديل القائمة"></MdSplitButton>
        <MdSplitButton variant="tonal" icon="edit" label="افتراضي" style={{ '--md-sys-density-scale': '0' }} menuLabel="تبديل القائمة"></MdSplitButton>
      </div>
    </>
  );
}

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

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

<!-- app.component.html -->
<div dir="rtl" data-density="-2" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
  <md-split-button variant="filled" icon="save" label="حفظ" menu-label="خيارات الحفظ"></md-split-button>
  <md-split-button variant="outlined" icon="add" label="إنشاء" menu-label="خيارات الإنشاء"></md-split-button>
  <md-split-button variant="tonal" icon="edit" label="أكثر إحكاما" density="-4" menu-label="تبديل القائمة"></md-split-button>
  <md-split-button variant="tonal" icon="edit" label="افتراضي" style="--md-sys-density-scale: 0;" menu-label="تبديل القائمة"></md-split-button>
</div>

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

<template>
  <div dir="rtl" data-density="-2" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
    <md-split-button variant="filled" icon="save" label="حفظ" menu-label="خيارات الحفظ"></md-split-button>
    <md-split-button variant="outlined" icon="add" label="إنشاء" menu-label="خيارات الإنشاء"></md-split-button>
    <md-split-button variant="tonal" icon="edit" label="أكثر إحكاما" density="-4" menu-label="تبديل القائمة"></md-split-button>
    <md-split-button variant="tonal" icon="edit" label="افتراضي" style="--md-sys-density-scale: 0;" menu-label="تبديل القائمة"></md-split-button>
  </div>
</template>

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

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

<div dir="rtl" data-density="-2" style="display:flex;gap:12px;flex-wrap:wrap;align-items:center;">
  <md-split-button variant="filled" icon="save" label="حفظ" menu-label="خيارات الحفظ"></md-split-button>
  <md-split-button variant="outlined" icon="add" label="إنشاء" menu-label="خيارات الإنشاء"></md-split-button>
  <md-split-button variant="tonal" icon="edit" label="أكثر إحكاما" density="-4" menu-label="تبديل القائمة"></md-split-button>
  <md-split-button variant="tonal" icon="edit" label="افتراضي" style="--md-sys-density-scale: 0;" menu-label="تبديل القائمة"></md-split-button>
</div>

Density — density="-1…-4" shrinks both segments together and locally overrides the inherited data-density rung; 0 is the default value, not an override. See Density.

i18n — translate label (or the slotted text) and menu-label. Translated labels run longer; prefer full-width with truncation over a label that wraps.

Theming

Custom property	Purpose	Default
`--md-split-button-container-color`	Segment background	Per variant — `--md-sys-color-primary` on `filled`, `transparent` on `outlined`
`--md-split-button-label-color`	Label + icon color	Per variant — `--md-sys-color-on-primary` on `filled`
`--md-split-button-icon-color`	Icon override	Inherits the label color
`--md-split-button-outline-color`	`outlined` border	`--md-sys-color-outline`
`--md-split-button-container-shape`	Outer corner radius	Half the segment height (a pill)
`--md-split-button-icon-size`	Leading icon size	Per size — 18px at `sm`

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-split-button icon="delete" label="Delete" menu-label="More delete options" style="--md-split-button-container-color: var(--md-sys-color-error); --md-split-button-label-color: var(--md-sys-color-on-error); --md-split-button-icon-color: var(--md-sys-color-on-error);"></md-split-button>
<md-split-button icon="save" label="Squared off" menu-label="More save options" style="--md-split-button-container-shape: 6px;"></md-split-button>
<md-split-button variant="outlined" icon="tune" label="Custom outline" menu-label="More options" style="--md-split-button-outline-color: var(--md-sys-color-tertiary); --md-split-button-label-color: var(--md-sys-color-tertiary); --md-split-button-icon-size: 24px;"></md-split-button>

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

export function Demo() {
  return (
    <>
      <MdSplitButton icon="delete" label="Delete" menuLabel="More delete options" style={{ '--md-split-button-container-color': 'var(--md-sys-color-error)', '--md-split-button-label-color': 'var(--md-sys-color-on-error)', '--md-split-button-icon-color': 'var(--md-sys-color-on-error)' }}></MdSplitButton>
      <MdSplitButton icon="save" label="Squared off" menuLabel="More save options" style={{ '--md-split-button-container-shape': '6px' }}></MdSplitButton>
      <MdSplitButton variant="outlined" icon="tune" label="Custom outline" menuLabel="More options" style={{ '--md-split-button-outline-color': 'var(--md-sys-color-tertiary)', '--md-split-button-label-color': 'var(--md-sys-color-tertiary)', '--md-split-button-icon-size': '24px' }}></MdSplitButton>
    </>
  );
}

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

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

<!-- app.component.html -->
<md-split-button icon="delete" label="Delete" menu-label="More delete options" style="--md-split-button-container-color: var(--md-sys-color-error); --md-split-button-label-color: var(--md-sys-color-on-error); --md-split-button-icon-color: var(--md-sys-color-on-error);"></md-split-button>
<md-split-button icon="save" label="Squared off" menu-label="More save options" style="--md-split-button-container-shape: 6px;"></md-split-button>
<md-split-button variant="outlined" icon="tune" label="Custom outline" menu-label="More options" style="--md-split-button-outline-color: var(--md-sys-color-tertiary); --md-split-button-label-color: var(--md-sys-color-tertiary); --md-split-button-icon-size: 24px;"></md-split-button>

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

<template>
  <md-split-button icon="delete" label="Delete" menu-label="More delete options" style="--md-split-button-container-color: var(--md-sys-color-error); --md-split-button-label-color: var(--md-sys-color-on-error); --md-split-button-icon-color: var(--md-sys-color-on-error);"></md-split-button>
  <md-split-button icon="save" label="Squared off" menu-label="More save options" style="--md-split-button-container-shape: 6px;"></md-split-button>
  <md-split-button variant="outlined" icon="tune" label="Custom outline" menu-label="More options" style="--md-split-button-outline-color: var(--md-sys-color-tertiary); --md-split-button-label-color: var(--md-sys-color-tertiary); --md-split-button-icon-size: 24px;"></md-split-button>
</template>

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

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

<md-split-button icon="delete" label="Delete" menu-label="More delete options" style="--md-split-button-container-color: var(--md-sys-color-error); --md-split-button-label-color: var(--md-sys-color-on-error); --md-split-button-icon-color: var(--md-sys-color-on-error);"></md-split-button>
<md-split-button icon="save" label="Squared off" menu-label="More save options" style="--md-split-button-container-shape: 6px;"></md-split-button>
<md-split-button variant="outlined" icon="tune" label="Custom outline" menu-label="More options" style="--md-split-button-outline-color: var(--md-sys-color-tertiary); --md-split-button-label-color: var(--md-sys-color-tertiary); --md-split-button-icon-size: 24px;"></md-split-button>

Seven CSS parts are exposed: leading, leading-state-layer, icon, label, trailing, trailing-state-layer and trailing-icon — enough to reach either segment, its state overlay and its glyph independently.

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>
  .sb-parts-demo::part(trailing) { min-inline-size: 56px; }
  .sb-parts-demo::part(label) { text-transform: uppercase; letter-spacing: .08em; }
  .sb-parts-demo::part(trailing-icon) { color: var(--md-sys-color-tertiary); }
</style>
<md-split-button class="sb-parts-demo" variant="outlined" icon="download" label="Export" menu-label="Export options"></md-split-button>
<md-split-button variant="outlined" icon="download" label="Export" menu-label="Export options"></md-split-button>

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

export function Demo() {
  return (
    <>
      <style>
        .sb-parts-demo::part(trailing) { min-inline-size: 56px; }
        .sb-parts-demo::part(label) { text-transform: uppercase; letter-spacing: .08em; }
        .sb-parts-demo::part(trailing-icon) { color: var(--md-sys-color-tertiary); }
      </style>
      <MdSplitButton className="sb-parts-demo" variant="outlined" icon="download" label="Export" menuLabel="Export options"></MdSplitButton>
      <MdSplitButton variant="outlined" icon="download" label="Export" menuLabel="Export options"></MdSplitButton>
    </>
  );
}

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

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

<!-- app.component.html -->
<style>
  .sb-parts-demo::part(trailing) { min-inline-size: 56px; }
  .sb-parts-demo::part(label) { text-transform: uppercase; letter-spacing: .08em; }
  .sb-parts-demo::part(trailing-icon) { color: var(--md-sys-color-tertiary); }
</style>
<md-split-button class="sb-parts-demo" variant="outlined" icon="download" label="Export" menu-label="Export options"></md-split-button>
<md-split-button variant="outlined" icon="download" label="Export" menu-label="Export options"></md-split-button>

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

<template>
  <style>
    .sb-parts-demo::part(trailing) { min-inline-size: 56px; }
    .sb-parts-demo::part(label) { text-transform: uppercase; letter-spacing: .08em; }
    .sb-parts-demo::part(trailing-icon) { color: var(--md-sys-color-tertiary); }
  </style>
  <md-split-button class="sb-parts-demo" variant="outlined" icon="download" label="Export" menu-label="Export options"></md-split-button>
  <md-split-button variant="outlined" icon="download" label="Export" menu-label="Export options"></md-split-button>
</template>

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

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

<style>
  .sb-parts-demo::part(trailing) { min-inline-size: 56px; }
  .sb-parts-demo::part(label) { text-transform: uppercase; letter-spacing: .08em; }
  .sb-parts-demo::part(trailing-icon) { color: var(--md-sys-color-tertiary); }
</style>
<md-split-button class="sb-parts-demo" variant="outlined" icon="download" label="Export" menu-label="Export options"></md-split-button>
<md-split-button variant="outlined" icon="download" label="Export" menu-label="Export options"></md-split-button>

md-split-button::part(trailing) {
  min-inline-size: 48px;
}

md-button · md-button-group · md-menu · md-menu-item · md-segmented-button · md-icon-button · md-ripple

AI / LLM Context

For AI Agents — `md-split-button`

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

Per-component

`md-split-button` spec card

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

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-split-button` readme.md

# md-split-button

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

**One default action plus a menu of variations.** Two fused segments: a leading
button that runs the default action, and a trailing toggle that opens a menu.
The component renders the button — **you supply and position the menu**.

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

---

## When to use

- There is a clear **default action**, plus closely-related variants of it:
  *Save* / Save as…, *Send* / Schedule send, *Merge* / Squash / Rebase.
- Users pick the default the large majority of the time, and the alternatives
  are genuinely alternatives — not unrelated commands.

## When NOT to use

| Situation | Use instead |
|---|---|
| No obvious default among the options | `md-button` + `md-menu`, or `md-select` |
| The options are unrelated commands | `md-icon-button` + `md-menu` |
| Choosing a value rather than running an action | `md-select` / `md-segmented-button-set` |
| 2–5 equal, mutually exclusive choices | `md-segmented-button-set` |
| Several equal actions as a unit | `md-button-group` |
| A single action | `md-button` |
| The trailing side toggles state rather than opening a popup | `md-button toggle`, or set `haspopup="false"` |

## Decision cues

| Need | Setting |
|---|---|
| Standard emphasis | `variant="filled"` (default) |
| Secondary emphasis | `variant="tonal"` or `"outlined"` |
| Separation from a prominent background | `variant="elevated"` |
| Fill the container, truncating the label if tight | `full-width` |
| Trailing side opens a listbox, not a menu | `haspopup="listbox"` |
| Trailing side toggles state, opens nothing | `haspopup="false"` |
| Link the trigger to your popup for AT | `controls="<popup id>"` |

| `size` | Height | Leading icon |
|---|---|---|
| `xs` | 32px | 16px |
| `sm` | 40px | 18px — **default** |
| `md` | 56px | 24px |
| `lg` | 96px | 36px |
| `xl` | 136px | 48px |

Heights taper with density (24px floor); the icon sizes do not.

## API contract

```html
<md-split-button
  variant="filled|tonal|outlined|elevated"   <!-- default: filled -->
  size="xs|sm|md|lg|xl"                       <!-- default: sm -->
  icon="save" label="Save"
  trailing-icon="keyboard_arrow_down"         <!-- default -->
  trailing-checked
  menu-label="More save options"              <!-- accessible name of trailing btn -->
  haspopup="menu|listbox|dialog|grid|tree|true|false"
  controls="save-menu"
  full-width
  disabled | soft-disabled
  ripple
  density="-1|-2|-3|-4"                       <!-- omit for the default rung -->
></md-split-button>
```

**Slot** — `(default)`: extra leading-button content. It renders **after** the
`label`, not instead of it, so use one or the other. There is no slot for the
trailing segment — its glyph comes from `trailing-icon`.

**Methods** — none.

**Events**

| Event | Detail | Fires |
|---|---|---|
| `mdLeadingClick` | `void` | Leading (default action) segment activated |
| `mdTrailingClick` | `{ checked: boolean }` | Trailing toggle activated; `checked` is the new state |

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

### Behavioral contract worth knowing

- **The menu is not included.** The component emits `mdTrailingClick`; you open,
  position, and close your own `md-menu`, and you keep `trailing-checked` in
  sync with its open state.
- `trailing-checked` **flips itself** on every trailing activation and the new
  value is what `mdTrailingClick.detail.checked` reports. What it cannot know is
  your menu closing by some other route (outside click, `Escape`, item picked) —
  set it back to `false` from your menu's `mdClose`, or the chevron rotation
  desyncs.
- `aria-expanded` is mirrored from `trailing-checked` onto the trailing button
  **unconditionally**, including when `haspopup="false"`. If the trailing side
  genuinely toggles state rather than disclosing something, that is the
  attribute you are living with.
- `disabled` sets the **native** `disabled` attribute on both inner `<button>`s,
  so both segments leave the tab order entirely. `soft-disabled` leaves them
  focusable and only blocks activation.
- An `aria-label` on the host is forwarded to the leading button **only when
  `label` is empty**; with a `label` set, the label is the name and the host's
  `aria-label` is ignored.
- In dev builds, a split button with neither `label` nor a host `aria-label`
  logs a `console.warn` naming the WCAG failure.
- `menu-label` is the trailing button's **only** accessible name. It defaults to
  the English `"Toggle menu"` — localize it.
- `controls` wires `aria-controls` from the trailing button to your popup's
  `id`. Both must be in the same DOM scope for the IDREF to resolve — a popup
  inside another shadow root will not link.
- `full-width` grows the leading segment (label truncates with an ellipsis);
  the trailing toggle keeps its intrinsic width.

---

## Do / Don't

Sourced from [M3 · Split button · Guidelines](https://m3.material.io/components/split-button/guidelines).

| ✅ Do | ❌ Don't |
|---|---|
| Open a menu from the trailing side | Don't modify the menu in unusual ways — keep it a conventional menu |
| Keep the leading label short | Don't use very long labels |
| Keep the stock chevron as the trailing glyph | Don't change the trailing icon (see note) |
| Make the leading action the genuine default | Don't make users open the menu for the common case |
| Keep menu items as variations of the leading action | Don't fill the menu with unrelated commands |
| Localize `menu-label` | Don't ship the default `"Toggle menu"` in a translated app |
| Keep `trailing-checked` in sync with your menu | Don't let the chevron point the wrong way |

**Trailing-icon note.** M3 says don't change the trailing icon, yet
`trailing-icon` exists. Treat it as an escape hatch for genuinely different
popup semantics (e.g. an overflow `more_vert` when the trailing side opens a
full menu rather than variations) — not as decoration. Default to the chevron.

---

## Patterns

```html
<md-split-button
  id="save-split"
  icon="save" label="Save"
  menu-label="More save options"
  controls="save-menu"
></md-split-button>

<md-menu id="save-menu" anchor="save-split">
  <md-menu-item headline="Save as…"></md-menu-item>
  <md-menu-item headline="Save a copy"></md-menu-item>
  <md-menu-item headline="Save and close"></md-menu-item>
</md-menu>

<script type="module">
  const split = document.querySelector('md-split-button');
  const menu  = document.getElementById('save-menu');

  split.addEventListener('mdLeadingClick', () => console.log('save'));

  split.addEventListener('mdTrailingClick', async (e) => {
    if (e.detail.checked) await menu.show();
    else await menu.close();
  });

  // keep the chevron in sync when the menu closes by any other means.
  // md-menu's mdClose does NOT bubble or compose — listen on the menu itself.
  menu.addEventListener('mdClose', () => { split.trailingChecked = false; });
</script>
```

```html
<!-- Full-width primary CTA with variations -->
<md-split-button full-width variant="filled" size="md"
                 icon="send" label="Send now" menu-label="Send options"></md-split-button>

<!-- Trailing side toggles state rather than opening a popup -->
<md-split-button label="Follow" haspopup="false"
                 trailing-icon="expand_more" menu-label="Notification settings"></md-split-button>
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| Expecting a built-in menu | Render your own `md-menu` and drive it | The component is the button only. |
| Leaving `menu-label` at its default in a localized app | Translate it | It's the trailing button's only accessible name. |
| Never updating `trailing-checked` | Sync it with the menu's open state | Otherwise the chevron rotation lies. |
| `controls` pointing at an id inside another shadow root | Keep trigger and popup in one scope | IDREFs don't cross shadow boundaries. |
| Unrelated commands in the menu | Keep them variations of the leading action | That's what makes it a *split* button. |
| Using it when there's no default action | `md-button` + `md-menu` | A split button asserts a default. |
| A long leading label | Shorten it | M3 calls out long labels; `full-width` truncates. |
| Two icons of independent meaning | Leading `icon` + chevron only | The trailing glyph is a disclosure affordance. |
| Listening for a single generic `click` | Use `mdLeadingClick` / `mdTrailingClick` | The segments stop propagation of their own clicks; you can't tell them apart otherwise. |
| Setting `trailing-checked` yourself inside `mdTrailingClick` | Read `e.detail.checked` | The component already flipped it before emitting — writing it again double-toggles. |
| `<md-menu-item label="…">` in the paired menu | `<md-menu-item headline="…">` | `md-menu-item` has no `label` prop. |
| Both `label` and slotted text on the leading segment | Pick one | The slot renders *after* the label, so you get both strings. |

## Accessibility, RTL, density, i18n

**Accessibility**
- Two separate buttons: the leading one is named by its label/slot; the trailing
  one **only** by `menu-label` (WCAG 4.1.2).
- `haspopup` sets `aria-haspopup` on the trailing button; `controls` sets
  `aria-controls`. Set `haspopup="false"` when nothing pops up.
- Manage `aria-expanded` through `trailing-checked`, keeping it truthful.
- `disabled` disables both segments and leaves the tab order; `soft-disabled`
  keeps them focusable.

**RTL** — the segments swap order automatically under `dir="rtl"`. The default
chevron (`keyboard_arrow_down`) is vertical, so it needs no mirroring; a custom
horizontal glyph does.

**Density** — `density="-1…-4"` shrinks both segments together (24px height
floor); only those four rungs exist and omitting the attribute is the
uncompacted default. `density="0"` does **not** opt out of an ancestor's
`data-density` rung — reset the scale with
`style="--md-sys-density-scale: 0"` instead. Icon sizes are fixed per `size`
and do not taper.

**i18n** — translate `label` (or slotted text) **and** `menu-label`. Translated
labels run longer; prefer `full-width` with truncation over a wrapping label.

## Related components

`md-button` · `md-button-group` · `md-menu` · `md-menu-item` ·
`md-segmented-button-set` · `md-icon-button` · `md-ripple`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-split-button-container-color` | Segment background | Per variant |
| `--md-split-button-label-color` | Label color | Per variant |
| `--md-split-button-icon-color` | Icon color | Follows the label color |
| `--md-split-button-outline-color` | `outlined` border color | `--md-sys-color-outline` |
| `--md-split-button-container-shape` | Outer corner radius | Half the size's height |
| `--md-split-button-icon-size` | Leading icon size | 16/18/24/36/48px per size |

The **trailing** chevron's size is fixed per `size` (22–50px) and has no
custom property; change the glyph with `trailing-icon`, not with CSS.

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

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

<!-- Auto Generated Below -->


## Properties

| Property          | Attribute          | Description                                                                                                                                                                                                                    | Type                                                                       | Default                 |
| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ----------------------- |
| `controls`        | `controls`         | `id` of the element the trailing button controls (the menu/listbox it opens). Wires `aria-controls` so assistive tech links trigger → popup.                                                                                   | `string`                                                                   | `''`                    |
| `density`         | `density`          | Local density rung. Drives the same `--md-sys-density-scale` signal that a global `data-density` ancestor sets, so a local value simply overrides the inherited one. 0 = default, -4 = ultra-compact.                          | `-1 \| -2 \| -3 \| -4 \| 0`                                                | `0`                     |
| `disabled`        | `disabled`         | Disable the entire split button                                                                                                                                                                                                | `boolean`                                                                  | `false`                 |
| `fullWidth`       | `full-width`       | Stretch the split button to fill its container. The leading segment grows and its label truncates with an ellipsis when space is tight; the trailing toggle keeps its intrinsic width.                                         | `boolean`                                                                  | `false`                 |
| `haspopup`        | `haspopup`         | `aria-haspopup` value for the trailing button — the kind of popup it opens. Defaults to `'menu'` (the split-button menu-trigger pattern). Set to `'false'` when the trailing button toggles state rather than opening a popup. | `"dialog" \| "false" \| "grid" \| "listbox" \| "menu" \| "tree" \| "true"` | `'menu'`                |
| `icon`            | `icon`             | Material Symbols icon name for the leading button                                                                                                                                                                              | `string`                                                                   | `''`                    |
| `label`           | `label`            | Leading button label text                                                                                                                                                                                                      | `string`                                                                   | `''`                    |
| `menuLabel`       | `menu-label`       | Accessible label for the trailing (menu-toggle) button. Localize per the page locale. (WCAG 4.1.2 — the icon-only trailing button needs a name.)                                                                               | `string`                                                                   | `'Toggle menu'`         |
| `ripple`          | `ripple`           | Enable/disable ripple                                                                                                                                                                                                          | `boolean`                                                                  | `true`                  |
| `size`            | `size`             | Size                                                                                                                                                                                                                           | `"lg" \| "md" \| "sm" \| "xl" \| "xs"`                                     | `'sm'`                  |
| `softDisabled`    | `soft-disabled`    | Visually disabled but remains focusable for screen readers                                                                                                                                                                     | `boolean`                                                                  | `false`                 |
| `trailingChecked` | `trailing-checked` | Whether the trailing button is in "open/checked" state                                                                                                                                                                         | `boolean`                                                                  | `false`                 |
| `trailingIcon`    | `trailing-icon`    | Trailing button icon (default: keyboard_arrow_down)                                                                                                                                                                            | `string`                                                                   | `'keyboard_arrow_down'` |
| `variant`         | `variant`          | Color variant                                                                                                                                                                                                                  | `"elevated" \| "filled" \| "outlined" \| "tonal"`                          | `'filled'`              |


## Events

| Event             | Description                                | Type                                 |
| ----------------- | ------------------------------------------ | ------------------------------------ |
| `mdLeadingClick`  | Fired when the leading button is activated | `CustomEvent<void>`                  |
| `mdTrailingClick` | Fired when the trailing button is toggled  | `CustomEvent<{ checked: boolean; }>` |


## Shadow Parts

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


## Dependencies

### Depends on

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

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

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

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

AWC UI Operator’s Manual

# main-llm.md — AWC UI build director

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

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

Your job, in order:

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

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

---

## §1 — Interview the user

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

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

### 1.1 Scope and shape

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

### 1.2 Look and feel

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

### 1.3 Internationalization

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

### 1.4 Data and forms

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

### 1.5 Constraints

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

---

## §2 — Map answers to configuration

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

### 2.1 Global switches — the complete set

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

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

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

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

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

---

## §3 — Install and bootstrap

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

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

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

defineCustomElements(window);
```

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

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

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

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

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

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

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

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

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

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

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

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

---

## §4 — Global configuration reference

### 4.1 The token system

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

#### Color roles

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

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

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

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

#### Shape tokens

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

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

#### Elevation tokens

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

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

#### Motion tokens

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

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

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

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

#### State-layer opacities

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

#### Typography, spacing and layering

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

### 4.2 Theming and rebranding

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

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

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

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

### 4.3 Density

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

Two details that bite:

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

### 4.4 Dark mode

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

### 4.5 RTL

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

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

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

### 4.6 Internationalization

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

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

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

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

### 4.7 Forms and validation

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

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

Rules:

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

---

## §5 — Component decision matrix

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

### 5.1 Actions

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

### 5.2 Text input

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

### 5.3 Selection

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

### 5.4 Navigation

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

### 5.5 Containment and feedback

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

### 5.6 Data

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

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

### 5.7 Choosing the variant

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

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

### 5.8 Not in the library

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

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

---

## §6 — Component inventory

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

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

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

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

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

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

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

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

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

---

## §7 — Composition rules

### 7.1 What nests inside what

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

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

### 7.2 Pairs that belong together

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

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

### 7.3 Nesting that is always wrong

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

---

## §8 — Page recipes

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

### 8.1 Login screen

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

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

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

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

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

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

### 8.2 Settings page (mobile)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### 8.4 Dashboard with a FAB

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

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

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

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

### 8.5 Destructive confirmation dialog

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

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

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

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

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

### 8.6 Tabbed content page

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

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

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

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

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

### 8.7 The full recipe library

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

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

---

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

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

### 9.1 API and styling

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

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

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

### 9.2 Content and hierarchy

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

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

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

### 9.3 Accessibility contract

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

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

---

## §10 — Before you ship

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

Split Button

Install

When to use

When not to use

The menu

Variants

Sizes

Icons

States

Trailing toggle without a menu

Full width

Events

API Reference

Properties

Slots

CSS Custom Properties

CSS Shadow Parts

Accessibility

RTL, density & i18n

Only the trailing glyph can point the wrong way

Every density rung

Density and direction together

Theming

AI / LLM Context

For AI Agents — `md-split-button`

`md-split-button` spec card

AWC UI Operator's Manual

`md-split-button` readme.md

AWC UI Operator’s Manual