Skip to content
AWC UI

Organization Chart

A tree of nodes with connectors. Renders a hierarchy — reporting lines, categories, taxonomies — as avatar cards joined by connector lines, with collapsible branches, optional single or multiple selection, and the full WAI-ARIA tree keyboard model.

Live preview Open in Storybook
Show code for each technology 
<md-organization-chart label="Reporting structure" selection-mode="single"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "ceo",
      name: "Ada Lovelace",
      title: "Founder & CEO",
      children: [
        {
          id: "prod",
          name: "Grace Hopper",
          title: "Product Lead",
          children: [
            {
              id: "ux",
              name: "Anna Fali",
              title: "UX Designer"
            },
            {
              id: "pm",
              name: "Bernardo Dominic",
              title: "Product Manager"
            }
          ]
        },
        {
          id: "eng",
          name: "Alan Turing",
          title: "Engineering Lead",
          children: [
            {
              id: "fe",
              name: "Elwin Sharvill",
              title: "Frontend Engineer"
            },
            {
              id: "be",
              name: "Stephen Shaw",
              title: "Backend Engineer"
            }
          ]
        }
      ]
    }
  ];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes });
</script>

Install

Section titled “Install”

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


<md-organization-chart></md-organization-chart>

When to use

Section titled “When to use”
  • Visualising a hierarchy where the parent/child relationships are the point: org charts, category trees, dependency trees.
  • The user needs to expand and collapse branches to manage size.

When not to use

Section titled “When not to use”
SituationUse instead
A flat listmd-list
Tabular datamd-table
A file-tree navigation sidebarmd-list with indentation, or a tree control
Where-am-I in a pathmd-breadcrumbs
Progressive disclosure of sectionsmd-accordion
Quantities or trendsThe chart components
A very large graph (thousands of nodes)A dedicated graph library

Decision cues

Section titled “Decision cues”
NeedSetting
Top-down chartorientation="vertical" (default)
Left-to-right chartorientation="horizontal"
Fold togglers on the cardscollapsible (default on) — pointer affordance only
Pick one nodeselection-mode="single"
Pick severalselection-mode="multiple"
PreselectselectedIds (array property)
Tighter rowsdensity="-1…-4"

The data model

Section titled “The data model”

The whole chart is one prop. nodes is the tree; everything else on the element is presentation.

const el = document.querySelector('md-organization-chart');
el.nodes = [{ id: 'ceo', name: 'Ada Lovelace', title: 'CEO', avatar: '/u/ada.jpg',
              children: [{ id: 'cto', name: 'Grace Hopper', title: 'CTO' }] }];
el.selectedIds = ['cto'];

The attribute form is what makes the chart usable from plain markup — a CMS field, or a server-rendered template with no script to run:

<md-organization-chart
  nodes='[{"id":"ceo","name":"Ada Lovelace","title":"CEO",
           "children":[{"id":"cto","name":"Grace Hopper","title":"CTO"}]}]'
></md-organization-chart>

That markup is the demo below — nothing feeds it, the attribute is the data:

Rendered from the nodes attribute alone
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-organization-chart label="Reporting structure" nodes='[{"id":"ceo","name":"Ada Lovelace","title":"CEO","children":[{"id":"cto","name":"Grace Hopper","title":"CTO"},{"id":"cfo","name":"Katherine Johnson","title":"CFO"}]}]'></md-organization-chart>

Node identity is id. selectedIds and every event payload key off it, so ids must be unique across the whole tree, not just within a branch.

The node shape

Section titled “The node shape”
FieldTypePurpose
idstringRequired. Stable identity for selection, expansion and events
namestringRequired. Primary label, in the emphasis weight
titlestringSecondary label, muted, under the name
avatarstringAvatar image URL
avatarInitialsstringExplicit initials, overriding the name-derived ones
accentstringReserved per-node accent colour — accepted, but currently has no visual effect
expandedbooleanInitial branch state — false starts collapsed
selectablebooleanfalse opts the node out of selection
childrenOrgChartNode[]The branch below this node

Everything except id and name is optional, so the terse form — an id, a name and a children array — is a complete tree:

The minimum viable node — id, name, children
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-organization-chart label="Category tree" nodes='[{"id":"all","name":"Catalogue","children":[{"id":"hw","name":"Hardware"},{"id":"sw","name":"Software"}]}]'></md-organization-chart>

Orientation

Section titled “Orientation”

Two layouts, one ARIA model. orientation changes the visual flow only — the tree semantics and the keyboard model are identical either way, so the arrows still expand and collapse regardless of which direction the connectors run.

ValueFlowSuits
verticalTop-downDefault. Wide, shallow trees — the classic org chart
horizontalAlong the reading directionDeep, narrow trees; long names

horizontal flows from the reading start. Don’t force vertical when doing so forces horizontal scrolling.

Horizontal
Show code for each technology 
<md-organization-chart orientation="horizontal" label="Reporting structure" selection-mode="single"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "root",
      name: "Ada Lovelace",
      title: "CEO",
      children: [
        {
          id: "a",
          name: "Grace Hopper",
          title: "CTO",
          children: [
            {
              id: "a1",
              name: "Alan Turing",
              title: "Engineer"
            }
          ]
        },
        {
          id: "b",
          name: "Katherine Johnson",
          title: "CFO"
        }
      ]
    }
  ];

  const selectedIds = ["a"];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes, selectedIds });
</script>

Multiple roots

Section titled “Multiple roots”

nodes is an array, not a single root. Pass several and they render side by side as independent trees inside one role="tree" — for a company with parallel divisions, or a taxonomy with no single top term.

Two roots, side by side
Show code for each technology 
<md-organization-chart label="Regional structure"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "r1",
      name: "Sales",
      title: "Region West",
      children: [
        {
          id: "r1a",
          name: "Team A",
          title: "6 people"
        }
      ]
    },
    {
      id: "r2",
      name: "Sales",
      title: "Region East",
      children: [
        {
          id: "r2b",
          name: "Team B",
          title: "4 people"
        }
      ]
    }
  ];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes });
</script>

Selection

Section titled “Selection”

selection-mode is none by default — nodes rove focus but expose no aria-selected. Keep it honest: only turn selection on when nodes really are selectable.

Modearia-selectedBehaviour
noneNot exposedDefault. Nodes take focus; Enter toggles the branch instead
singleOn selectable nodesOne at a time; re-activating the sole selection clears it
multipleOn selectable nodesAccumulates; the tree gains aria-multiselectable
Single selection — picking another swaps it, picking the same one clears it
Show code for each technology 
<md-organization-chart selection-mode="single" label="Reporting structure"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "ceo",
      name: "Ada Lovelace",
      title: "Founder & CEO",
      children: [
        {
          id: "prod",
          name: "Grace Hopper",
          title: "Product Lead",
          children: [
            {
              id: "ux",
              name: "Anna Fali",
              title: "UX Designer"
            }
          ]
        },
        {
          id: "eng",
          name: "Alan Turing",
          title: "Engineering Lead",
          children: [
            {
              id: "fe",
              name: "Elwin Sharvill",
              title: "Frontend Engineer"
            }
          ]
        }
      ]
    }
  ];

  const selectedIds = ["prod"];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes, selectedIds });
</script>
Multiple selection — clicking an already-selected node removes it
Show code for each technology 
<md-organization-chart selection-mode="multiple" label="Team picker"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "lead",
      name: "Ada Lovelace",
      title: "Team lead",
      children: [
        {
          id: "m1",
          name: "Grace Hopper",
          title: "Engineer"
        },
        {
          id: "m2",
          name: "Alan Turing",
          title: "Engineer"
        },
        {
          id: "m3",
          name: "Katherine Johnson",
          title: "Analyst"
        }
      ]
    }
  ];

  const selectedIds = ["m1", "m3"];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes, selectedIds });
</script>

Opting a node out

Section titled “Opting a node out”

A node with selectable: false stays focusable and still takes the roving tabindex — it simply never advertises or accepts a selection. Use it for group headers and structural rows that exist to hold a branch, not to be picked.

Two nodes opted out — they take focus but never select
Show code for each technology 
<md-organization-chart selection-mode="single" label="Team picker"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "lead",
      name: "Team Lead",
      title: "Group",
      selectable: false,
      children: [
        {
          id: "locked",
          name: "Locked Node",
          title: "Read-only",
          selectable: false
        },
        {
          id: "open",
          name: "Open Node",
          title: "Selectable"
        }
      ]
    }
  ];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes });
</script>

Avatars and initials

Section titled “Avatars and initials”

avatar takes an image URL. Without one the node falls back to avatarInitials, and without that to initials derived from name — so a node never renders an empty or broken avatar.

Node fieldsWhat renders
avatar: '/u/ada.jpg'The image
avatarInitials: 'AC'AC
Neither, name: 'Ada Lovelace'AL
Initials fallback — no avatar URLs anywhere in this tree
Show code for each technology 
<md-organization-chart label="Departments"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "org",
      name: "Acme Corp",
      title: "Group",
      avatarInitials: "AC",
      children: [
        {
          id: "d1",
          name: "Ada Lovelace",
          title: "Research"
        },
        {
          id: "d2",
          name: "Grace Hopper",
          title: "Engineering"
        }
      ]
    }
  ];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes });
</script>

Collapsing

Section titled “Collapsing”

collapsible is on by default; each node’s initial state comes from its own expanded field. Collapse deep branches by default — the component does not virtualize, so a fully-expanded 500-node tree is slow and unreadable, and deep trees are hard to navigate by keyboard.

Collapsed branches — click a toggle to open one
Show code for each technology 
<md-organization-chart label="Taxonomy"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "root",
      name: "Catalogue",
      title: "All products",
      children: [
        {
          id: "c1",
          name: "Hardware",
          title: "12 items",
          expanded: false,
          children: [
            {
              id: "c1a",
              name: "Laptops",
              title: "5 items"
            },
            {
              id: "c1b",
              name: "Phones",
              title: "7 items"
            }
          ]
        },
        {
          id: "c2",
          name: "Software",
          title: "8 items",
          expanded: false,
          children: [
            {
              id: "c2a",
              name: "Licences",
              title: "8 items"
            }
          ]
        }
      ]
    }
  ];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes });
</script>

collapsible="false" removes the pointer affordance, not the folding. The keyboard model is untouched — ← still collapses an expanded parent, → still expands a collapsed one, and Enter / Space still toggles when nothing is selectable — and a node authored expanded: false still starts collapsed. So a branch folded that way has no visible toggler to reopen it: only the arrow keys will. Use collapsible="false" for a tree small enough that no branch ships folded, and leave every expanded field alone when you do.

Empty state

Section titled “Empty state”

Slot your own copy into empty rather than rendering a blank area. The container carries role="status", so the message is announced when a tree resolves to nothing.

Empty state
No people yet. Invite someone to get started.
Show code for each technology 
<md-organization-chart label="Reporting structure"><div slot="empty">No people yet. Invite someone to get started.</div></md-organization-chart>

<script type="module">
  const nodes = [];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes });
</script>

This is also where a malformed nodes string lands: invalid JSON parses to nothing rather than throwing, so a bad feed degrades into your empty copy instead of a blank rectangle.

Lazy branches

Section titled “Lazy branches”

The chart doesn’t fetch or lazy-load anything — it renders exactly what you give it. mdNodeToggle tells you a branch opened, which is where you load the children and reassign nodes.

A branch with no children renders no toggler at all, so a lazy branch needs a placeholder child to be openable. Open either branch below: the placeholder is swapped for the fetched rows about half a second later.

Lazy branches — open one and watch the placeholder be replaced
Show code for each technology 
<md-organization-chart label="Reporting structure"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "ceo",
      name: "Ada Lovelace",
      title: "Founder & CEO",
      children: [
        {
          id: "prod",
          name: "Grace Hopper",
          title: "Product Lead",
          expanded: false,
          children: [
            {
              id: "prod-pending",
              name: "Loading…"
            }
          ]
        },
        {
          id: "eng",
          name: "Alan Turing",
          title: "Engineering Lead",
          expanded: false,
          children: [
            {
              id: "eng-pending",
              name: "Loading…"
            }
          ]
        }
      ]
    }
  ];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes });

  // Stands in for the network. Your version awaits a fetch.
  const fetchReports = (id) => new Promise((resolve) => setTimeout(() => resolve({
    prod: [
      { id: 'ux', name: 'Anna Fali', title: 'UX Designer' },
      { id: 'pm', name: 'Bernardo Dominic', title: 'Product Manager' },
    ],
    eng: [
      { id: 'fe', name: 'Elwin Sharvill', title: 'Frontend Engineer' },
      { id: 'be', name: 'Stephen Shaw', title: 'Backend Engineer' },
    ],
  }[id] || []), 500));

  const loaded = new Set();

  // Rebuild the branch rather than mutating it — a reassignment of 'nodes' is
  // what re-renders. 'expanded' is re-read from the data every time, so every
  // branch the user has already opened has to keep saying expanded: true.
  const insertChildren = (list, id, children) => list.map((n) => {
    const next = Object.assign({}, n, loaded.has(n.id) ? { expanded: true } : null);
    if (n.id === id) next.children = children;
    else if (n.children) next.children = insertChildren(n.children, id, children);
    return next;
  });

  const onToggle = async (e) => {
    const node = e.detail.node;
    if (!e.detail.expanded || loaded.has(node.id)) return;
    loaded.add(node.id);
    el.nodes = insertChildren(el.nodes, node.id, await fetchReports(node.id));
  };

  el.addEventListener('mdNodeToggle', onToggle);
  return () => el.removeEventListener('mdNodeToggle', onToggle);
</script>

Events

Section titled “Events”
EventCancelableDetailFires
mdSelectionChangenoOrgChartSelectionChangeDetail — { node, selectedIds }A node’s selected state changes
mdNodeTogglenoOrgChartToggleDetail — { node, expanded }A branch is expanded or collapsed
interface OrgChartSelectionChangeDetail {
  node: OrgChartNode;      // the node the user acted on
  selectedIds: string[];   // the WHOLE selection after the change
}


interface OrgChartToggleDetail {
  node: OrgChartNode;
  expanded: boolean;       // the state the branch has just taken
}

Which event to listen to

Section titled “Which event to listen to”
You want to…Listen to
Show a detail panel for the node just pickedmdSelectionChange — detail.node
Persist the current selectionmdSelectionChange — detail.selectedIds
Fetch a branch’s children on first openmdNodeToggle — guard on detail.expanded
Remember which branches the user foldedmdNodeToggle

Both events, live. Pick a node, pick it again to clear it, and fold a branch — every payload lands in the log:

Both events, logged live — select a node, then fold a branch
No people yet.
 Pick a node, or fold a branch — both events land here.
Show code for each technology 
<md-organization-chart id="org" selection-mode="single" label="Reporting structure">
<div slot="empty">No people yet.</div>
</md-organization-chart>

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

org.nodes = [{
  id: 'ceo', name: 'Ada Lovelace', title: 'CEO',
  children: [
    { id: 'cto', name: 'Grace Hopper', title: 'CTO',
      children: [{ id: 'eng1', name: 'Alan Turing', title: 'Engineer' }] },
    { id: 'cfo', name: 'Katherine Johnson', title: 'CFO' },
  ],
}];

org.addEventListener('mdSelectionChange', (e) => {
  console.log(e.detail.node.id, e.detail.selectedIds);
});
org.addEventListener('mdNodeToggle', (e) => {
  console.log(e.detail.node.id, e.detail.expanded);
});
</script>

API Reference

Section titled “API Reference”

Properties

PropertyAttributeTypeDefaultReflects
nodesJS onlyNodeInput[]—
selectionModeselection-mode'none' | 'single' | 'multiple''none'Yes
selectedIdsJS onlystring[][]—
collapsiblecollapsiblebooleantrue—
orientationorientation'vertical' | 'horizontal''vertical'Yes
labellabelstring'Organization chart'—
expandLabelexpand-labelstring'Expand'—
collapseLabelcollapse-labelstring'Collapse'—
densitydensity0 | -1 | -2 | -3 | -40Yes

Slots

SlotDescription
emptyCustom empty-state content

CSS Shadow Parts

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

PartDescription
state-layerHover / selected overlay
avatarThe md-avatar
namePrimary label
titleSecondary label
toggleExpand / collapse affordance
groupA role="group" child list
viewportScroll/pan container
emptyEmpty-state container
treeThe role="tree" root list
avatar-imageThe avatar's <img> (exported)

Accessibility

Section titled “Accessibility”
  • The tree implements the WAI-ARIA tree pattern: role="tree" on the root list, role="treeitem" nodes, a roving tabindex, Arrow / Home / End navigation and Enter / Space to select (or to toggle when nothing is selectable).
  • label names the chart region. expand-label / collapse-label name the branch toggles — translate all three.
  • Every node exposes aria-level, aria-setsize and aria-posinset; parents expose aria-expanded; selectable nodes expose aria-selected, and the tree gains aria-multiselectable in multiple mode.
  • Selection state is exposed per node. Keep selection-mode honest — use none when nodes are not selectable.
  • Deep trees are hard to navigate by keyboard, so collapsing by default helps everyone.

Keyboard

Section titled “Keyboard”
KeyAction
TabA single stop for the whole chart (roving tabindex); Tab again leaves it
↓ / ↑Next / previous visible node, depth-first
→Collapsed parent → expand it; expanded parent → move to its first child
←Expanded parent → collapse it; otherwise move to the parent node
Home / EndFirst / last visible node
Enter / SpaceSelect the focused node — or toggle it when nothing is selectable

Tab into this chart and drive it entirely from the keyboard — one Tab stop, then the arrows walk the tree:

Keyboard and screen-reader behaviour Open in Storybook
Show code for each technology 
<md-organization-chart label="Company org chart" selection-mode="single"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "ceo",
      name: "Ada Lovelace",
      title: "Founder & CEO",
      children: [
        {
          id: "prod",
          name: "Grace Hopper",
          title: "Product Lead",
          children: [
            {
              id: "ux",
              name: "Anna Fali",
              title: "UX Designer"
            },
            {
              id: "pm",
              name: "Bernardo Dominic",
              title: "Product Manager"
            }
          ]
        },
        {
          id: "eng",
          name: "Alan Turing",
          title: "Engineering Lead",
          children: [
            {
              id: "fe",
              name: "Elwin Sharvill",
              title: "Frontend Engineer"
            }
          ]
        }
      ]
    }
  ];

  const selectedIds = ["prod"];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes, selectedIds });
</script>

RTL, density & i18n

Section titled “RTL, density & i18n”

RTL — both orientations mirror. Connectors and elbows are authored with logical properties throughout, and the tree’s rows are flex containers, so the inherited direction decides sibling order: a root with children [CTO, CFO] paints CTO on the left in LTR and on the right in RTL. horizontal mirrors more obviously, because its levels also advance along the reading direction — but a vertical chart is not symmetric, it re-orders. See RTL.

The same charts in both directions. Nothing is re-authored between them — only dir changes. Watch the CTO / CFO order flip in the vertical chart, and the whole flow flip in the horizontal one:

Same markup, dir=ltr vs dir=rtl — vertical and horizontal
ltr
rtl
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display:grid;grid-template-columns:auto 1fr;gap:20px 16px;align-items:center;">
  <span style="inline-size:2.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:32px;flex-wrap:wrap;align-items:flex-start;">
    <md-organization-chart label="Reporting structure" nodes='[{"id":"ceo","name":"Ada Lovelace","title":"CEO","children":[{"id":"cto","name":"Grace Hopper","title":"CTO"},{"id":"cfo","name":"Katherine Johnson","title":"CFO"}]}]'></md-organization-chart>
    <md-organization-chart orientation="horizontal" label="Reporting structure" nodes='[{"id":"ceo","name":"Ada Lovelace","title":"CEO","children":[{"id":"cto","name":"Grace Hopper","title":"CTO"},{"id":"cfo","name":"Katherine Johnson","title":"CFO"}]}]'></md-organization-chart>
  </div>
  <span style="inline-size:2.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:32px;flex-wrap:wrap;align-items:flex-start;">
    <md-organization-chart label="Reporting structure" nodes='[{"id":"ceo","name":"Ada Lovelace","title":"CEO","children":[{"id":"cto","name":"Grace Hopper","title":"CTO"},{"id":"cfo","name":"Katherine Johnson","title":"CFO"}]}]'></md-organization-chart>
    <md-organization-chart orientation="horizontal" label="Reporting structure" nodes='[{"id":"ceo","name":"Ada Lovelace","title":"CEO","children":[{"id":"cto","name":"Grace Hopper","title":"CTO"},{"id":"cfo","name":"Katherine Johnson","title":"CFO"}]}]'></md-organization-chart>
  </div>
</div>

Let the chart inherit dir — never pin it

Section titled “Let the chart inherit dir — never pin it”

There is no mirror prop, because there is nothing per-node to mirror: the flow follows the inherited direction. Pinning dir="ltr" on a horizontal chart inside an RTL page is the one way to get it wrong — the tree then grows away from the reading direction, and ← / → swap meaning relative to everything around it. Both rows below sit inside the same dir="rtl" block:

Inherited dir vs a pinned dir=ltr, both inside an RTL block
correct wrong
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div dir="rtl" style="display:grid;grid-template-columns:auto 1fr;gap:20px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <md-organization-chart orientation="horizontal" label="الهيكل التنظيمي" expand-label="توسيع" collapse-label="طي" nodes='[{"id":"c","name":"إيمي إلسنر","title":"الرئيس التنفيذي","children":[{"id":"p","name":"آسيا جافايانت","title":"قائدة المنتج"},{"id":"e","name":"أونياما ليمبا","title":"قائد الهندسة"}]}]'></md-organization-chart>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div dir="ltr">
    <md-organization-chart orientation="horizontal" label="الهيكل التنظيمي" expand-label="توسيع" collapse-label="طي" nodes='[{"id":"c","name":"إيمي إلسنر","title":"الرئيس التنفيذي","children":[{"id":"p","name":"آسيا جافايانت","title":"قائدة المنتج"},{"id":"e","name":"أونياما ليمبا","title":"قائد الهندسة"}]}]'></md-organization-chart>
  </div>
</div>

Every density rung

Section titled “Every density rung”

density is a local override of the inherited data-density. It tapers node padding, the avatar, the name and title type scale, the toggler, and both the level and sibling gaps — the whole tree contracts, not just the cards.

Density 0 through -4 — cards, type and gaps all taper
0 -1 -2 -3 -4
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display:grid;grid-template-columns:auto 1fr;gap:24px 16px;align-items:center;">
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">0</span>
  <md-organization-chart density="0" label="Density 0" nodes='[{"id":"r","name":"Ada Lovelace","title":"CEO","children":[{"id":"a","name":"Grace Hopper","title":"CTO"},{"id":"b","name":"Katherine Johnson","title":"CFO"}]}]'></md-organization-chart>
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <md-organization-chart density="-1" label="Density -1" nodes='[{"id":"r","name":"Ada Lovelace","title":"CEO","children":[{"id":"a","name":"Grace Hopper","title":"CTO"},{"id":"b","name":"Katherine Johnson","title":"CFO"}]}]'></md-organization-chart>
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <md-organization-chart density="-2" label="Density -2" nodes='[{"id":"r","name":"Ada Lovelace","title":"CEO","children":[{"id":"a","name":"Grace Hopper","title":"CTO"},{"id":"b","name":"Katherine Johnson","title":"CFO"}]}]'></md-organization-chart>
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <md-organization-chart density="-3" label="Density -3" nodes='[{"id":"r","name":"Ada Lovelace","title":"CEO","children":[{"id":"a","name":"Grace Hopper","title":"CTO"},{"id":"b","name":"Katherine Johnson","title":"CFO"}]}]'></md-organization-chart>
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <md-organization-chart density="-4" label="Density -4" nodes='[{"id":"r","name":"Ada Lovelace","title":"CEO","children":[{"id":"a","name":"Grace Hopper","title":"CTO"},{"id":"b","name":"Katherine Johnson","title":"CFO"}]}]'></md-organization-chart>
</div>

Density and direction together

Section titled “Density and direction together”

The two are independent signals, so they compose without any extra wiring — a right-to-left horizontal tree at rung -2, with one node’s branch folded:

dir=rtl with data-density=-2 — flow and taper compose
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div dir="rtl" data-density="-2">
  <md-organization-chart orientation="horizontal" label="الهيكل التنظيمي" expand-label="توسيع" collapse-label="طي" nodes='[{"id":"c","name":"إيمي إلسنر","title":"الرئيس التنفيذي","children":[{"id":"p","name":"آسيا جافايانت","title":"قائدة المنتج","expanded":false,"children":[{"id":"u","name":"آنا فالي","title":"مصممة تجربة"}]},{"id":"e","name":"أونياما ليمبا","title":"قائد الهندسة"}]}]'></md-organization-chart>
</div>

Density — density="-1…-4" locally overrides the inherited data-density rung, tapering node padding, the avatar, both type sizes, the toggler and both gaps at once. See Density.

i18n — node name and title come from your data; label, expand-label and collapse-label are the only strings the component authors, and shipping their English defaults is a bug in a localized app. dir and lang are inherited from any ancestor, so a localized subtree needs no chart-specific wiring. See RTL.

PropDefaultNames
labelOrganization chartThe role="tree" region
expand-labelExpandThe toggler on a collapsed branch
collapse-labelCollapseThe toggler on an expanded branch

Plus the empty slot content, which is entirely yours.

Localised affordance labels — German and Arabic
de ar
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display:grid;grid-template-columns:auto 1fr;gap:24px 16px;align-items:center;">
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">de</span>
  <md-organization-chart label="Organigramm" expand-label="Erweitern" collapse-label="Reduzieren" nodes='[{"id":"c","name":"Amy Elsner","title":"Gründerin und CEO","children":[{"id":"p","name":"Asiya Javayant","title":"Produktleitung"},{"id":"e","name":"Onyama Limba","title":"Technische Leitung"}]}]'></md-organization-chart>
  <span style="inline-size:2rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ar</span>
  <div dir="rtl">
    <md-organization-chart label="الهيكل التنظيمي" expand-label="توسيع" collapse-label="طي" nodes='[{"id":"c","name":"إيمي إلسنر","title":"المؤسِّسة والرئيس التنفيذي","children":[{"id":"p","name":"آسيا جافايانت","title":"قائدة المنتج"},{"id":"e","name":"أونياما ليمبا","title":"قائد الهندسة"}]}]'></md-organization-chart>
  </div>
</div>

Longer names widen nodes; --md-org-chart-node-max-width caps them, and the name and title truncate with an ellipsis rather than reflowing the tree.

Theming

Section titled “Theming”
Custom propertyPurposeDefault
--md-org-chart-connector-color / -connector-widthConnector linesoutline-variant / 1.5px
--md-org-chart-node-colorNode surfacesurface-container-low
--md-org-chart-node-outline-color / -outline-widthNode borderoutline-variant / 1px
--md-org-chart-node-shapeNode corner radiusshape-corner-medium
--md-org-chart-node-min-width / -max-widthNode width bounds176px / 260px
--md-org-chart-selected-colorSelected node accentprimary
--md-org-chart-state-layer-colorHover / press overlayon-surface
--md-org-chart-focus-ring-colorFocus ringsecondary
--md-org-chart-level-gap / -sibling-gapSpacing between generations and siblingsDensity-derived
--md-org-chart-toggle-sizeExpand / collapse affordanceDensity-derived
--md-org-chart-durationExpand / collapse timingmotion-duration-medium2 (300ms)
Branded instance — connectors, outline, radius and selection recoloured
Show code for each technology 
<md-organization-chart selection-mode="single" label="Reporting structure" style="--md-org-chart-connector-color: #7c4dff; --md-org-chart-node-outline-color: #7c4dff; --md-org-chart-node-shape: 20px; --md-org-chart-selected-color: #7c4dff; --md-org-chart-sibling-gap: 24px;"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "ceo",
      name: "Ada Lovelace",
      title: "Founder & CEO",
      children: [
        {
          id: "prod",
          name: "Grace Hopper",
          title: "Product Lead"
        },
        {
          id: "eng",
          name: "Alan Turing",
          title: "Engineering Lead"
        }
      ]
    }
  ];

  const selectedIds = ["prod"];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes, selectedIds });
</script>

Every default resolves through an md-sys-color role, so a chart that sets no custom properties follows the theme on its own. Switch this page between light and dark — the chart below is untouched markup:

Untouched defaults — follows the page theme
Show code for each technology 
<md-organization-chart selection-mode="single" label="Reporting structure"></md-organization-chart>

<script type="module">
  const nodes = [
    {
      id: "ceo",
      name: "Ada Lovelace",
      title: "Founder & CEO",
      children: [
        {
          id: "prod",
          name: "Grace Hopper",
          title: "Product Lead"
        },
        {
          id: "eng",
          name: "Alan Turing",
          title: "Engineering Lead"
        }
      ]
    }
  ];

  const selectedIds = ["eng"];

  const el = document.querySelector("md-organization-chart");
  Object.assign(el, { nodes, selectedIds });
</script>

CSS Parts reach inside the shadow root for what custom properties do not cover — the type treatment of a label, or a selected node’s ring:

CSS parts — click a node to see the selected ring
Show code for each technology 
<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<style>
  .parts-org::part(name)          { text-transform: uppercase; letter-spacing: .06em; }
  .parts-org::part(title)         { font-style: italic; opacity: .8; }
  .parts-org::part(node-selected) { box-shadow: 0 0 0 3px var(--md-sys-color-tertiary); }
</style>

<md-organization-chart class="parts-org" selection-mode="single"></md-organization-chart>

CSS parts — viewport, tree, group, node, node-selected, state-layer, avatar, avatar-image, name, title, toggle, empty. Slot — empty.

md-organization-chart.compact {
  --md-org-chart-node-max-width: 180px;
  --md-org-chart-level-gap: 24px;
  --md-org-chart-connector-color: var(--md-sys-color-outline-variant);
}
Section titled “Related”

md-list · md-accordion · md-breadcrumbs · md-avatar · md-tooltip · md-icon-button

AI / LLM Context

Section titled “AI / LLM Context”

For AI Agents — md-organization-chart

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-organization-chart 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-organization-chart readme.md 

# md-organization-chart

<!-- llm:meta
tag: md-organization-chart
category: data
status: custom
m3-guidelines: none — not an M3 component
form-associated: false
depends-on: md-ripple, md-avatar, md-tooltip, md-icon-button
used-by: none
-->

**A tree of avatar cards joined by connectors.** Renders a hierarchy —
reporting lines, categories, taxonomies — with collapsible branches, optional
selection and the full WAI-ARIA tree keyboard model.

> ⚠️ **Not a Material Design 3 component.** M3 has no org-chart page; the
> guidance below is house rules.

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

---

## When to use

- Visualising a **hierarchy** where the parent/child relationships are the
  point: org charts, category trees, dependency trees.
- The user needs to expand and collapse branches to manage size.
- Nodes are people or units that read well as an avatar + name + role card.

## When NOT to use

| Situation | Use instead |
|---|---|
| A flat list | `md-list` |
| A file-tree navigation sidebar | `md-list` with indentation, or a tree control |
| Where-am-I in a path | `md-breadcrumbs` |
| Progressive disclosure of sections | `md-accordion` |
| Quantities or trends | The chart components |
| A very large graph (thousands of nodes) | A dedicated graph library |

## Decision cues

| Need | Setting |
|---|---|
| Top-down chart | `orientation="vertical"` (default) |
| Left-to-right chart | `orientation="horizontal"` |
| Branches can be folded | `collapsible` (default on) |
| A branch starts folded | `expanded: false` on that node |
| Pick one node | `selection-mode="single"` |
| Pick several | `selection-mode="multiple"` |
| Exempt a node from selection | `selectable: false` on that node |
| Preselect | `selectedIds` (JS property) |
| Tint one node | `accent` on that node |
| Custom empty state | `empty` slot |

## API contract

```html
<md-organization-chart
  selection-mode="none|single|multiple"          <!-- default: none -->
  collapsible                                    <!-- default: ON; set collapsible="false" to lock branches open -->
  orientation="vertical|horizontal"              <!-- default: vertical -->
  label="Organization chart"                     <!-- accessible name of the tree -->
  expand-label="Expand"
  collapse-label="Collapse"
  density="-1|-2|-3|-4"                          <!-- default: 0 (uncompacted) -->
>
  <div slot="empty">No people yet.</div>
</md-organization-chart>
```

```js
const chart = document.querySelector('md-organization-chart');

chart.nodes = [{
  id: 'ceo', name: 'Ada Lovelace', title: 'CEO', avatar: '/u/ada.jpg',
  children: [
    { id: 'cto', name: 'Grace Hopper', title: 'CTO', accent: '#6750A4' },
    { id: 'cfo', name: 'Katherine Johnson', title: 'CFO',
      avatarInitials: 'KJ', expanded: false, selectable: false },
  ],
}];
chart.selectedIds = ['cto'];       // JS property — no attribute form
```

Each node (`OrgChartNode`): `id` and `name` are required; `title` (the muted
second line), `avatar` (image URL), `avatarInitials`, `accent` (a CSS colour
for the avatar ring and selected tint), `expanded` (`false` starts the subtree
folded), `selectable` (`false` exempts it) and `children` are optional.

**Events** — `mdSelectionChange` (`{ node, selectedIds }`), `mdNodeToggle`
(`{ node, expanded }` — `node` is the whole `OrgChartNode`, so read
`e.detail.node.id`). Both are the Stencil default — they bubble and cross
shadow boundaries.

**Methods** — none.

**Slots** — `empty` (replaces the default "No data" message; shown when `nodes`
resolves to an empty list).

**Parts** — `viewport`, `tree`, `group`, `node`, `node-selected` (present on a
node only while it is selected), `state-layer`, `avatar`, `avatar-image`
(forwarded from the inner `md-avatar`), `name`, `title`, `toggle`, `empty`.

### Behavioral contract worth knowing

- **`nodes` accepts either form.** As a JS property it takes an
  `OrgChartNode[]`; as an attribute it takes a **JSON string**, which is parsed
  (invalid JSON yields an empty tree). The property is the sane choice for
  anything non-trivial. `selectedIds` is property-only.
- **Multiple roots are supported** — a top-level array with several entries
  renders them side by side.
- **Reassigning `nodes` resets expand/collapse state.** The collapsed set is
  rebuilt from each node's `expanded` field, so branches the reader opened or
  closed revert. If you rebuild the tree (lazy loading, polling), carry the
  reader's state back into the data as `expanded: true/false`.
- **`selectedIds` is mutable and written back** by the component as the user
  selects. Watch `mdSelectionChange` rather than diffing the array.
- In `selection-mode="single"`, clicking the only selected node **deselects**
  it. In `multiple`, each click toggles that node.
- **Enter / Space selects** when the node is selectable, and otherwise
  **toggles** the branch. The chart uses a **roving tabindex** — exactly one
  node is in the tab order — with Arrow Down/Up moving through the visible
  nodes, Arrow forward expanding then descending, Arrow backward collapsing then
  ascending, and Home/End jumping to the ends. The forward/backward arrows swap
  under `dir="rtl"`.
- The expand/collapse button is **`aria-hidden` and out of the tab order** on
  purpose: expansion is already exposed on the tree item via `aria-expanded` and
  the arrow keys. Its visible name rides in an `md-tooltip` fed by
  `expand-label` / `collapse-label`.
- The **avatar is decorative** (`aria-hidden`), because the node's name is
  already the tree item's accessible text.
- The chart **doesn't fetch or lazy-load** branches. `mdNodeToggle` tells you a
  branch opened — load children there and reassign `nodes`.
- It doesn't virtualize. A few hundred nodes is fine; thousands will be slow —
  collapse by default, or use a graph library.
- The `viewport` part scrolls when the tree outgrows its container. **No
  panning or zooming is built in.**

---

## Do / Don't

House rules — M3 has no org-chart page, so the guidance below is this library's
own.

| ✅ Do | ❌ Don't |
|---|---|
| Give every node a stable, unique `id` | Don't reuse ids across branches |
| Collapse deep branches with `expanded: false` | Don't render a 500-node tree fully expanded |
| Load children on `mdNodeToggle` for big trees | Don't build the whole tree up front if it's huge |
| Carry expand state back into the data when you reassign `nodes` | Don't reassign and expect the reader's folds to survive |
| Keep node labels short (name + title) | Don't put a paragraph in a node |
| Use `orientation="horizontal"` for deep, narrow trees | Don't force vertical when it forces horizontal scrolling |
| Provide an `empty` slot state | Don't render a blank area |
| Localize `label`, `expand-label`, `collapse-label` | Don't ship the English defaults |
| Offer a non-visual alternative for the hierarchy | Don't make the chart the only representation |

---

## Patterns

```html
<md-organization-chart id="org" selection-mode="single" label="Reporting structure">
  <div slot="empty">No people yet.</div>
</md-organization-chart>

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

  org.nodes = [{
    id: 'ceo', name: 'Ada Lovelace', title: 'CEO',
    children: [
      { id: 'cto', name: 'Grace Hopper', title: 'CTO',
        children: [{ id: 'eng1', name: 'Alan Turing', title: 'Engineer' }] },
      { id: 'cfo', name: 'Katherine Johnson', title: 'CFO' },
    ],
  }];

  org.addEventListener('mdSelectionChange', (e) => {
    showProfile(e.detail.node.id, e.detail.selectedIds);
  });
</script>
```

```html
<!-- Lazy branches: mdNodeToggle carries the whole node -->
<md-organization-chart id="lazy" label="Reporting structure"></md-organization-chart>
<script type="module">
  const lazy = document.getElementById('lazy');
  const loaded = new Set();

  // A branch needs at least one REAL child to be togglable: `hasChildren` is
  // length-based, so `children: []` is a leaf — no toggler renders and
  // `mdNodeToggle` can never fire. Seed a placeholder and swap it out.
  lazy.nodes = [{
    id: 'ceo',
    name: 'Ada Lovelace',
    title: 'CEO',
    children: [{ id: 'ceo-placeholder', name: '…', selectable: false }],
  }];

  // Branches start EXPANDED (there is no initially-collapsed prop), so the
  // first toggle on a branch is a collapse. Fetch on the first toggle in
  // either direction rather than gating on `expanded`.
  lazy.addEventListener('mdNodeToggle', async (e) => {
    const { node } = e.detail;
    if (loaded.has(node.id)) return;
    loaded.add(node.id);
    // Rebuild the tree, marking already-open branches so the reassignment
    // doesn't fold them back up.
    lazy.nodes = insertChildren(lazy.nodes, node.id, await fetchReports(node.id));
  });
</script>
```

```html
<!-- Horizontal, dense, JSON via the attribute (small trees only) -->
<md-organization-chart
  orientation="horizontal"
  density="-2"
  nodes='[{"id":"a","name":"Root","children":[{"id":"b","name":"Child"}]}]'
></md-organization-chart>
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| `const { id } = e.detail` on `mdNodeToggle` | `const { node } = e.detail; node.id` | The detail is `{ node, expanded }`, not the node itself. |
| `selected-ids="a,b"` as an attribute | `chart.selectedIds = ['a', 'b']` | `selectedIds` has no attribute form. |
| Reassigning `nodes` and expecting folds to persist | Write `expanded` back into the data | The collapsed set is rebuilt from the data. |
| Duplicate node `id`s | Unique ids | Selection, toggling and focus key off them. |
| Expecting lazy loading | Load in `mdNodeToggle` | It renders what you give it. |
| Thousands of nodes fully expanded | Collapse, or use a graph library | No virtualization. |
| Expecting pan/zoom, or a `resize()` method | Wrap the `viewport` yourself | Neither is built in; the component has no methods. |
| Composing your own `md-avatar` inside a node | Feed the node data | The chart renders the node chrome itself. |
| Tabbing to the expand/collapse buttons | Use the arrow keys | The toggles are `aria-hidden` and untabbable by design. |
| Shipping English `expand-label` / `collapse-label` | Translate them | They name the toggles in the tooltip. |
| The chart as the only view of the hierarchy | Offer a list/table too | Visual-only structure excludes some users. |

## Accessibility, RTL, density, i18n

**Accessibility**
- The chart is a real `role="tree"` with `role="treeitem"` nodes carrying
  `aria-level`, `aria-setsize`, `aria-posinset`, `aria-expanded` and
  `aria-selected`; `aria-multiselectable` is set in `multiple` mode. `label`
  names the tree.
- Keyboard: roving tabindex (one node in the tab order), Arrow Up/Down between
  visible nodes, Arrow forward/backward to expand/descend and collapse/ascend
  (swapped in RTL), Home/End, Enter/Space to select — or to toggle when the node
  isn't selectable.
- The expand/collapse buttons are deliberately `aria-hidden` and untabbable, so
  there is no nested interactive control inside a tree item; `expand-label` /
  `collapse-label` name them for pointer users through `md-tooltip`.
- A connector-drawn tree is still a **visual** representation of structure.
  Offering an equivalent list or table view is the accessible thing to do for
  anything important.
- Keep `selection-mode` honest — `none` when nodes aren't selectable, so
  `aria-selected` isn't advertised on nodes that can't take it.

**RTL** — the layout is authored with logical properties, so the tree mirrors
under `dir="rtl"`; `orientation="horizontal"` flows from the reading start, and
the horizontal arrow keys swap with it.

**Density** — `density="-1"` through `density="-4"` tighten the toggler size and
the level/sibling gaps; check that names stay legible. Rung `0` is the
uncompacted default and has no rule of its own. To step *out* of an inherited
`data-density` rung, set `style="--md-sys-density-scale: 0"` — `density="0"`
will not do it.

**i18n** — node `name` / `title` come from your data. Translate `label`,
`expand-label`, `collapse-label`, and the `empty` slot content. Longer names
widen nodes — `--md-org-chart-node-max-width` caps them.

## Related components

`md-list` · `md-accordion` · `md-breadcrumbs` · `md-avatar` · `md-tooltip` ·
`md-icon-button` · `md-ripple`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-org-chart-connector-color` | Connector line colour | `--md-sys-color-outline-variant` |
| `--md-org-chart-connector-width` | Connector line thickness | `1.5px` |
| `--md-org-chart-node-color` | Node card background | `--md-sys-color-surface-container-low` |
| `--md-org-chart-node-outline-color` | Node card border colour | `--md-sys-color-outline-variant` |
| `--md-org-chart-node-outline-width` | Node card border width | `1px` |
| `--md-org-chart-node-shape` | Node card corner radius | `--md-sys-shape-corner-medium` (12px) |
| `--md-org-chart-node-min-width` | Node card minimum width | `176px` |
| `--md-org-chart-node-max-width` | Node card maximum width | `260px` |
| `--md-org-chart-selected-color` | Selected node accent (border + tint) | `--md-sys-color-primary` |
| `--md-org-chart-focus-ring-color` | Focus outline colour | `--md-sys-color-secondary` |
| `--md-org-chart-state-layer-color` | Hover / selected overlay colour | `--md-sys-color-on-surface` |
| `--md-org-chart-toggle-size` | Expand/collapse toggler diameter | `max(20px, 24px + density × 1px)` |
| `--md-org-chart-level-gap` | Gap between levels | `max(24px, 28px + density × 1px)` |
| `--md-org-chart-sibling-gap` | Gap between siblings | `max(8px, 12px + density × 1px)` |
| `--md-org-chart-duration` | Motion duration | `--md-sys-motion-duration-medium2` (300ms) |

A single node's tint is its `accent` field, not a custom property — it colours
that node's avatar ring and selected state only.

**CSS parts** — `viewport`, `tree`, `group`, `node`, `node-selected`,
`state-layer`, `avatar`, `avatar-image`, `name`, `title`, `toggle`, `empty`.

```css
md-organization-chart {
  --md-org-chart-node-max-width: 220px;
  --md-org-chart-connector-color: var(--md-sys-color-primary);
}
md-organization-chart::part(node-selected) {
  outline: 2px solid var(--md-sys-color-primary);
}
```

<!-- Auto Generated Below -->


## Overview

`md-organization-chart` — Material Design 3 Expressive organization chart.

Visualises hierarchical org data as a top-down tree of avatar cards joined
by connector lines. Data-driven (`nodes`), with collapsible subtrees,
optional single/multiple selection, and the full WAI-ARIA **tree** pattern
(roving tabindex, Arrow/Home/End navigation, Enter/Space to select).

The surface pans horizontally when it outgrows its container, so a wide org
stays usable on small screens. Direction-aware (RTL mirrors the layout and
swaps the horizontal arrow keys); every affordance label is a prop for
localisation.

```html
<md-organization-chart selection-mode="single"></md-organization-chart>
<script>
  document.querySelector('md-organization-chart').nodes = [{
    id: 'ceo', name: 'Amy Elsner', title: 'Founder & CEO',
    children: [{ id: 'prod', name: 'Asiya Javayant', title: 'Product Lead' }],
  }];
</script>
```

## Properties

| Property        | Attribute        | Description                                                                                                                                                                                                                                                                                 | Type                                            | Default                |
| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------- |
| `collapseLabel` | `collapse-label` | Toggler accessible label when a node is expanded (localisable).                                                                                                                                                                                                                             | `string`                                        | `'Collapse'`           |
| `collapsible`   | `collapsible`    | Show expand/collapse togglers on nodes that have children.                                                                                                                                                                                                                                  | `boolean`                                       | `true`                 |
| `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`                    |
| `expandLabel`   | `expand-label`   | Toggler accessible label when a node is collapsed (localisable).                                                                                                                                                                                                                            | `string`                                        | `'Expand'`             |
| `label`         | `label`          | Accessible name for the tree (localisable).                                                                                                                                                                                                                                                 | `string`                                        | `'Organization chart'` |
| `nodes`         | `nodes`          | The organization tree. Accepts an `OrgChartNode[]` (property) or a JSON string (attribute). Multiple roots are supported (rendered side by side).                                                                                                                                           | `OrgChartNode[] \| null \| string \| undefined` | `[]`                   |
| `orientation`   | `orientation`    | Layout direction of the tree:   - `'vertical'`   — top-down (default).   - `'horizontal'` — left-to-right; RTL mirrors it right-to-left.  Only the visual layout changes — the tree's ARIA semantics and keyboard model (Arrow Left/Right = collapse/expand, Up/Down = move) are unchanged. | `"horizontal" \| "vertical"`                    | `'vertical'`           |
| `selectedIds`   | --               | Selected node ids (controlled + initial). Kept in sync as the user selects.                                                                                                                                                                                                                 | `string[]`                                      | `[]`                   |
| `selectionMode` | `selection-mode` | Selection behaviour:   - `'none'`     — nodes are not selectable (default).   - `'single'`   — one node at a time.   - `'multiple'` — any number of nodes.                                                                                                                                  | `"multiple" \| "none" \| "single"`              | `'none'`               |


## Events

| Event               | Description                                 | Type                                         |
| ------------------- | ------------------------------------------- | -------------------------------------------- |
| `mdNodeToggle`      | Fired when a node is expanded or collapsed. | `CustomEvent<OrgChartToggleDetail>`          |
| `mdSelectionChange` | Fired when the selection changes.           | `CustomEvent<OrgChartSelectionChangeDetail>` |


## Shadow Parts

| Part            | Description |
| --------------- | ----------- |
| `"avatar"`      |             |
| `"empty"`       |             |
| `"group"`       |             |
| `"name"`        |             |
| `"state-layer"` |             |
| `"title"`       |             |
| `"toggle"`      |             |
| `"tree"`        |             |
| `"viewport"`    |             |


## Dependencies

### Depends on

- [md-ripple](../md-ripple)
- [md-avatar](../md-avatar)
- [md-tooltip](../md-tooltip)
- [md-icon-button](../md-icon-button)

### Graph
```mermaid
graph TD;
  md-organization-chart --> md-ripple
  md-organization-chart --> md-avatar
  md-organization-chart --> md-tooltip
  md-organization-chart --> md-icon-button
  md-icon-button --> md-ripple
  style md-organization-chart 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.