@universal-material/web 3.8.0 → 3.9.0

package/skills/dialog/SKILL.md

@@ -0,0 +1,92 @@
+---
+description: Show modal dialogs — declarative u-dialog with slots, or imperative Dialog.message() / Dialog.confirm() builders.
+---
+
+# Dialog
+
+Two patterns: a declarative `<u-dialog>` you keep in markup and `show()`/`close()` programmatically, or one-shot imperative builders for the common alert/confirm flows.
+
+## Declarative
+
+```html
+<u-button (click)="dialog.show()">Open dialog</u-button>
+
+<u-dialog #dialog>
+  <span class="material-symbols-outlined" slot="icon">mobile_friendly</span>
+  <span slot="headline">Update available</span>
+  <span>A new version of the app is ready. Restart now to apply the update.</span>
+  <u-button slot="actions" variant="text" (click)="dialog.close('ok')">Restart</u-button>
+  <u-button slot="actions" variant="text" (click)="dialog.close('cancel')">Later</u-button>
+</u-dialog>
+```
+
+Slots: `icon`, `headline`, default (body), `actions`. Each is optional.
+
+API:
+- `show()` / `close(returnValue?)` — open / close. Closing with a value sets `dialog.returnValue`.
+- `open` property mirrors `show()`/`close()`.
+- `closed` and `cancel` events. Calling `event.preventDefault()` on `cancel` blocks dismissal.
+
+### `<form method="dialog">`
+
+Buttons with `form="form-id" value="…"` inside a `method="dialog"` form close the dialog with the submitter's value:
+
+```html
+<u-dialog #d>
+  <span slot="headline">Rename file</span>
+  <form id="rename" method="dialog">
+    <u-text-field label="File name" autofocus name="filename"></u-text-field>
+  </form>
+  <u-button slot="actions" variant="text" form="rename" value="save">Save</u-button>
+  <u-button slot="actions" variant="text" form="rename" value="cancel">Cancel</u-button>
+</u-dialog>
+```
+
+### Long content
+
+The dialog draws subtle dividers above the headline and below the actions when the body overflows. No extra setup needed — just put your content in the default slot.
+
+### Action button order
+
+`.actions` uses `flex-direction: row-reverse`, so the **first child in DOM order renders on the right** (the confirming action, per M3). Always put the affirmative button first in markup.
+
+## Imperative — message
+
+One-shot alert dialog with a single acknowledge button. Removes itself from the DOM on close.
+
+```ts
+import { Dialog } from '@universal-material/web';
+
+Dialog
+  .message('Your changes have been saved.')
+  .headline('Saved')
+  .acknowledgeButton({ label: 'Got it', variant: 'filled' })
+  .show();
+```
+
+## Imperative — confirm
+
+One-shot confirm dialog. `show()` returns a `Promise<boolean>` that resolves `true` on confirm, `false` on cancel/dismiss.
+
+```ts
+import { Dialog } from '@universal-material/web';
+
+const ok = await Dialog
+  .confirm('This action cannot be undone. Continue?')
+  .headline('Delete item')
+  .confirmButton({ label: 'Delete', variant: 'filled', color: 'error' })
+  .cancelButton({ label: 'Keep it' })
+  .show();
+
+if (ok) {
+  // …perform deletion
+}
+```
+
+`confirmButton` / `cancelButton` accept any `{ variant, color, label }` — omitted fields fall back to defaults from `config.dialog.confirmDefaults`.
+
+## Caveats
+
+- The dialog opens via `<dialog>.showModal()` so it stacks above everything (no z-index gymnastics) and traps focus.
+- The imperative builders run their lifecycle outside any framework's change-detection zone (the closed event fires from a transition listener). In Angular, call `ChangeDetectorRef.detectChanges()` after `await …show()` if the resolved value drives template bindings.
+- Don't import `'@universal-material/web/dialog/dialog-builder.js'` directly — it doesn't register `u-button`; use the package root or the dialog entry which already pulls it in.

package/skills/drawer/SKILL.md

@@ -0,0 +1,94 @@
+---
+description: Add a side navigation drawer to an app — sections with headlines, drawer items with icons and badges, toggleable on mobile.
+---
+
+# Side navigation drawer
+
+`<u-side-navigation>` wraps a page with a left-side drawer (`<u-drawer>`) that toggles open/closed. Inside the drawer, group items with `<u-drawer-headline>` and use `<u-drawer-item>` for each link.
+
+## Basic usage
+
+```html
+<u-side-navigation #nav>
+  <u-top-app-bar headline="My app">
+    <u-icon-button slot="leading-icon" type="button"
+      (click)="nav.toggleDrawer = !nav.toggleDrawer">
+      <span class="material-symbols-outlined">menu</span>
+    </u-icon-button>
+  </u-top-app-bar>
+
+  <u-drawer slot="drawer">
+    <u-drawer-headline>Library</u-drawer-headline>
+    <u-drawer-item active>
+      <span class="material-symbols-outlined" slot="icon">home</span>
+      Home
+    </u-drawer-item>
+    <u-drawer-item>
+      <span class="material-symbols-outlined" slot="icon">favorite</span>
+      Favorites
+      <span slot="badge">12</span>
+    </u-drawer-item>
+
+    <u-drawer-headline>Account</u-drawer-headline>
+    <u-drawer-item>
+      <span class="material-symbols-outlined" slot="icon">settings</span>
+      Settings
+    </u-drawer-item>
+  </u-drawer>
+
+  <!-- the main page content goes here as light DOM -->
+  <div class="u-container">
+    Page body
+  </div>
+</u-side-navigation>
+```
+
+The side-navigation:
+- responsively shows the drawer permanently on wide viewports and toggles it as an overlay on narrow ones,
+- sets `--u-app-bar-offset` so the slotted top app bar slides with the drawer,
+- exposes `.toggleDrawer` (boolean) for programmatic control.
+
+## Drawer items
+
+`<u-drawer-item>` slots:
+- default — the label,
+- `icon` — leading icon (24dp),
+- `badge` — trailing badge **content** (plain text in a `<span slot="badge">`, e.g. a count). The drawer item styles this itself — it pins the content to the trailing edge inline with the row.
+
+**Don't put a `<u-badge>` in the `badge` slot.** `<u-badge>` is the *floating* badge used to dot the corner of an icon (notification bell, rail item); it's `position: absolute`. Dropped into a drawer item's inline `badge` slot it floats out of place instead of sitting at the row's trailing edge. Pass the value as a `<span slot="badge">12</span>` — the drawer item provides the badge treatment. (Note this differs from `<u-navigation-rail-item>`, whose collapsed state *does* take a `<u-badge>` because the badge floats over the icon there.)
+
+Attributes:
+- `active` — highlights the item with the secondary-container pill (M3 active state).
+- `href` / `target` — renders as a link instead of a button.
+- `keep-drawer-open` — by default, clicking an item auto-closes the drawer on mobile; set this to disable.
+
+## Routing
+
+For framework routing, set `routerLink` (Angular) / `to` (Vue Router) / `href` on the item and let the framework's link directive handle navigation; the drawer item still emits a click and auto-closes the drawer.
+
+## Sections
+
+Group items with `<u-drawer-headline>` between them. The headline renders a small label-style title above its section.
+
+## Background — and the trap when slotting a drawer into a pane
+
+`<u-drawer>` paints its own background, and that color is **breakpoint-dependent**:
+- below `lg`: `--u-modal-drawer-bg-color` (default `surface-container-low`) — the modal drawer surface;
+- at `lg`+: `--u-standard-drawer-bg-color` (default `surface` / body) — a *standard* permanent drawer is meant to read as part of the page background, so it deliberately matches `surface`.
+
+That default is correct for a drawer used directly inside `<u-side-navigation>`. **But if you slot a `<u-drawer>` into a `<u-pane variant="filled">` (e.g. a settings section-nav in a list-detail), the drawer's surface paints over the pane's filled background.** The visible bug: the nav column shows a background at small/medium widths, then goes flat/background-less on desktop — because at `lg`+ the drawer flips to `surface` (= the scaffold body) and erases the pane's fill. It looks like the pane "lost its background"; really the drawer is painting on top with body color.
+
+Fix it at the drawer: when the pane is the surface, make the drawer transparent so the pane shows through at every breakpoint.
+
+```html
+<u-pane variant="filled" style="--u-modal-drawer-bg-color: transparent; --u-standard-drawer-bg-color: transparent;">
+  <u-drawer>…</u-drawer>
+</u-pane>
+```
+
+(The two custom properties are inherited, so setting them on the pane reaches the drawer.) Don't try to fix it by raising the *pane's* `--u-pane-filled-bg-color` — the drawer still paints over it on desktop, so the column stays flat.
+
+## Caveats
+
+- The drawer is a sibling of the page content inside `<u-side-navigation>`, not a child of the top bar. Don't nest it under the bar.
+- On wide viewports the drawer is permanent; the toggle button still works but the drawer never closes. Use `keep-drawer-open` on items you'd otherwise want auto-closing only on mobile — it's safe either way.

package/skills/expansion-panel/SKILL.md

@@ -0,0 +1,65 @@
+---
+description: Use u-expansion-panel for collapsible sections; wrap in u-expansion-panel-container for accordion behavior.
+---
+
+# Expansion panel
+
+Collapsible surface with a clickable header (with ripple + chevron). Animates via the internal [[collapse]] component.
+
+## Single panel
+
+```html
+<u-expansion-panel>
+  <span slot="header">What is Material 3 Expressive?</span>
+  <div style="padding: 0 1rem 1rem;">
+    Material 3 Expressive is the latest iteration of Material Design.
+  </div>
+</u-expansion-panel>
+```
+
+## Accordion (exclusive)
+
+Wrap multiple panels in `u-expansion-panel-container` — opening one closes the others.
+
+```html
+<u-expansion-panel-container>
+  <u-expansion-panel>
+    <span slot="header">Account</span>
+    <div style="padding: 0 1rem 1rem;">Manage email, password, and connected services.</div>
+  </u-expansion-panel>
+  <u-expansion-panel>
+    <span slot="header">Notifications</span>
+    <div style="padding: 0 1rem 1rem;">Choose how and when you want to be notified.</div>
+  </u-expansion-panel>
+</u-expansion-panel-container>
+```
+
+## Multi (independent panels)
+
+Add `multi` to keep multiple panels open simultaneously.
+
+```html
+<u-expansion-panel-container multi>
+  <u-expansion-panel expanded>
+    <span slot="header">Always-open</span>
+    <div style="padding: 0 1rem 1rem;">Set <code>expanded</code> for the initial state.</div>
+  </u-expansion-panel>
+  <u-expansion-panel>
+    <span slot="header">Independent</span>
+    <div style="padding: 0 1rem 1rem;">Stays open when others open.</div>
+  </u-expansion-panel>
+</u-expansion-panel-container>
+```
+
+## Attributes
+
+- `expanded` — current open state. Reflects to the attribute; dispatches `change` (bubbles, composed) when toggled.
+- `disabled` — prevents toggling and silences the ripple.
+- `hide-toggle` — hides the default chevron icon.
+- `multi` (container) — allow multiple panels open at once.
+
+## Caveats
+
+- Put the header content in `slot="header"`. The default slot is the panel body (wrapped internally in `u-collapse`).
+- The container coordinates panels via the `change` event bubbling out of each panel — works with panels added/removed dynamically.
+- Sibling-close logic uses `querySelectorAll('u-expansion-panel')` against direct descendants of the container only — nested containers operate independently.

package/skills/fab/SKILL.md

@@ -0,0 +1,79 @@
+---
+description: Add a floating action button — u-fab (single primary action), u-fab-menu (expandable speed-dial with multiple items).
+---
+
+# FAB and FAB menu
+
+## `<u-fab>` — single primary action
+
+```html
+<u-fab>
+  <span class="material-symbols-outlined">edit</span>
+</u-fab>
+```
+
+Colors: `primary` (default), `secondary`, `tertiary`, `surface`, `branded`.
+Sizes: `small`, `medium` (default), `large`.
+
+Extended FAB (with label):
+
+```html
+<u-fab label="Compose">
+  <span class="material-symbols-outlined">edit</span>
+</u-fab>
+```
+
+Lowered elevation:
+
+```html
+<u-fab lowered>
+  <span class="material-symbols-outlined">add</span>
+</u-fab>
+```
+
+## Positioning
+
+Inside a `<u-scaffold>`, drop the FAB in the `fab` slot — it's anchored to the scaffold's bottom-right with the correct M3 16dp gap, and offsets above the navigation bar automatically:
+
+```html
+<u-scaffold>
+  <!-- … top-bar, content, bottom-bar … -->
+  <u-fab slot="fab" color="primary">
+    <span class="material-symbols-outlined">edit</span>
+  </u-fab>
+</u-scaffold>
+```
+
+For ad-hoc placement, wrap the FAB in a positioned container.
+
+## `<u-fab-menu>` — speed-dial
+
+A FAB that toggles into multiple `<u-fab-menu-item>`s when clicked:
+
+```html
+<u-fab-menu color="primary">
+  <span class="material-symbols-outlined" slot="icon">add</span>
+
+  <u-fab-menu-item label="New doc">
+    <span class="material-symbols-outlined">description</span>
+  </u-fab-menu-item>
+  <u-fab-menu-item label="New folder">
+    <span class="material-symbols-outlined">folder</span>
+  </u-fab-menu-item>
+  <u-fab-menu-item label="Upload">
+    <span class="material-symbols-outlined">upload</span>
+  </u-fab-menu-item>
+</u-fab-menu>
+```
+
+Slots on `<u-fab-menu>`:
+- `icon` — the closed-state icon (e.g. `add`),
+- `close-icon` — the open-state icon (defaults to an "×").
+
+The toggle FAB animates between the two icons; menu items animate in/out around it.
+
+## Caveats
+
+- `<u-fab-menu>` keeps `pointer-events: none` on its host so the invisible menu-items area (when closed) passes clicks through to whatever is behind it. Don't blanket-override slotted children with `pointer-events: auto`.
+- When slotted into `<u-scaffold>` the scaffold neutralizes the FAB menu's internal `--u-fab-menu-toggle-margin` so the visible toggle aligns with the wrapper box (otherwise it would sit too close to the bottom bar).
+- A FAB does not auto-react to scroll yet — the `scrollContainer` attribute is reserved for future hide-on-scroll behavior.

package/skills/list/SKILL.md

@@ -0,0 +1,105 @@
+---
+description: Render Material 3 lists — u-list + u-list-item, with leading icons, supporting text, badges and trailing actions.
+---
+
+# List
+
+`<u-list>` is a vertical stack of `<u-list-item>`s. Each item supports leading and trailing slots, supporting text and selection states.
+
+## Basic
+
+```html
+<u-list>
+  <u-list-item>Inbox</u-list-item>
+  <u-list-item>Drafts</u-list-item>
+  <u-list-item>Sent</u-list-item>
+</u-list>
+```
+
+## Two-line items with icons
+
+```html
+<u-list>
+  <u-list-item>
+    <span class="material-symbols-outlined" slot="leading-icon">person</span>
+    Maria Andrade
+    <span slot="supporting-text">maria@example.com</span>
+  </u-list-item>
+
+  <u-list-item>
+    <span class="material-symbols-outlined" slot="leading-icon">person</span>
+    Carlos Pereira
+    <span slot="supporting-text">carlos@example.com</span>
+  </u-list-item>
+</u-list>
+```
+
+## Trailing content
+
+```html
+<u-list-item>
+  <span class="material-symbols-outlined" slot="leading-icon">archive</span>
+  Archive
+  <u-icon-button slot="trailing-icon">
+    <span class="material-symbols-outlined">chevron_right</span>
+  </u-icon-button>
+</u-list-item>
+```
+
+## Selectable rows
+
+`selectable` adds the ripple + hover **state layer** so the row reads as interactive:
+
+```html
+<u-list>
+  <u-list-item selectable onclick="…">One</u-list-item>
+  <u-list-item selectable onclick="…">Two</u-list-item>
+</u-list>
+```
+
+For a persistent **active / selected** highlight (e.g. the open row in a list-detail or mail list), use the **`selected`** attribute/property — it paints the M3 selected container (`secondary-container` / `on-secondary-container`):
+
+```html
+<u-list>
+  <u-list-item selectable selected>One</u-list-item>
+  <u-list-item selectable>Two</u-list-item>
+</u-list>
+<script>
+  list.addEventListener('click', (e) => {
+    const item = e.target.closest('u-list-item');
+    if (!item) return;
+    list.querySelectorAll('u-list-item[selected]').forEach((i) => (i.selected = false));
+    item.selected = true;
+  });
+</script>
+```
+
+Override the selected colors per call site with `--u-list-item-selected-container-color` / `--u-list-item-selected-label-color`. For selection lists tied to a form value, use the dedicated `<u-checkbox-list-item>`, `<u-radio-list-item>`, or `<u-switch-list-item>` (see the **selection-controls** skill).
+
+## Aligning a row flush (`no-inset`)
+
+List items carry a 16dp inline inset, so their content sits indented from adjacent non-list content (section headings, paragraph labels). Add **`no-inset`** to pull the row flush — it cancels the inline padding with an equal negative inline margin, so the content lines up with the surrounding labels (the state layer bleeds to the container edges):
+
+```html
+<div class="u-title-s">Channels</div>
+<u-list>
+  <u-list-item no-inset>Email</u-list-item>
+  <u-list-item no-inset>Push</u-list-item>
+</u-list>
+```
+
+The `*-list-item` selection variants accept `no-inset` too (it's forwarded to their inner list item) — handy in settings sections where the row should line up with the heading.
+
+## Three-line items
+
+A second line of supporting text wraps automatically when content exceeds one line; for an explicitly tall three-line variant, use multiple `<span slot="supporting-text">` lines.
+
+## Dividers and sections
+
+For grouped lists with headlines, mix `<u-drawer-headline>`-style elements between groups, or use the `card`/`outlined-card` containers around each section.
+
+## Caveats
+
+- `<u-list-item>` slots accept any node — keep leading/trailing icons inside `<span class="material-symbols-outlined">` or `<u-icon-button>` for consistent sizing.
+- `<u-list>` is unopinionated about scrolling. For long lists inside a constrained container, wrap the list in a `<div style="overflow:auto; max-height: …">`.
+- For very long lists (1000+ items), the M3 list is fine but consider virtualization (`@lit-labs/virtualizer`).

package/skills/menu/SKILL.md

@@ -0,0 +1,120 @@
+---
+description: Open contextual menus — u-menu and u-menu-item for popovers anchored to a trigger, plus u-overflow-menu for action bars that auto-collapse on narrow widths.
+---
+
+# Menus
+
+## `<u-menu>` + `<u-menu-item>` — popover
+
+A floating surface anchored to a trigger. Open with `.show()`/`.toggle()`/`.close()` (or by setting `open`):
+
+```html
+<u-icon-button (click)="menu.toggle()">
+  <span class="material-symbols-outlined">more_vert</span>
+</u-icon-button>
+
+<u-menu #menu>
+  <u-menu-item>
+    <span class="material-symbols-outlined" slot="leading-icon">edit</span>
+    Edit
+  </u-menu-item>
+  <u-menu-item>
+    <span class="material-symbols-outlined" slot="leading-icon">content_copy</span>
+    Duplicate
+  </u-menu-item>
+  <u-menu-item>
+    <span class="material-symbols-outlined" slot="leading-icon">delete</span>
+    Delete
+  </u-menu-item>
+</u-menu>
+```
+
+By default the menu anchors to its parent element. Set `anchorElement` explicitly when needed:
+
+```ts
+menu.anchorElement = triggerButton;
+```
+
+## Positioning
+
+- **`anchor-corner`** — which corner of the anchor the menu attaches to. Supports `start-start`, `start-end`, `end-start`, `end-end`, plus `auto-start` / `auto-end` (auto picks top vs bottom based on space).
+- **`direction`** — which way the menu grows: `up-start`, `up-end`, `down-start`, `down-end` (default).
+
+For a dropdown right under the trigger, the defaults work. For a "more" menu in a top app bar, use `anchor-corner="end-end"`:
+
+```html
+<u-menu anchor-corner="end-end" direction="down-start">…</u-menu>
+```
+
+## Clipped containers
+
+If the menu lives inside a `overflow: hidden` or scrollable wrapper, set `positioning="fixed"` so it escapes:
+
+```html
+<u-menu positioning="fixed">…</u-menu>
+```
+
+## Auto-close
+
+- `autoclose="outside"` (default-ish) — closes on outside clicks but not on clicks inside the menu.
+- `autoclose="true"` — closes on any click anywhere.
+- `autoclose="false"` — never auto-closes; you manage it.
+
+## `<u-overflow-menu>` — responsive action bar
+
+A horizontal row of `<u-overflow-menu-item>`s that automatically collapses items into a "more" menu when there isn't enough horizontal space:
+
+```html
+<u-overflow-menu>
+  <u-overflow-menu-item label="Bold">
+    <span class="material-symbols-outlined">format_bold</span>
+  </u-overflow-menu-item>
+  <u-overflow-menu-item label="Italic">
+    <span class="material-symbols-outlined">format_italic</span>
+  </u-overflow-menu-item>
+  <u-overflow-menu-item label="Underline">
+    <span class="material-symbols-outlined">format_underlined</span>
+  </u-overflow-menu-item>
+  <u-overflow-menu-item label="Strikethrough">
+    <span class="material-symbols-outlined">format_strikethrough</span>
+  </u-overflow-menu-item>
+
+  <!-- Items marked collapse="always" never render inline -->
+  <u-overflow-menu-item label="Delete" collapse="always">
+    <span class="material-symbols-outlined">delete</span>
+  </u-overflow-menu-item>
+</u-overflow-menu>
+```
+
+Inside a clipped wrapper (e.g. a card with `overflow: hidden`), set `menuPositioning="fixed"` so the popover can escape:
+
+```html
+<u-overflow-menu menuPositioning="fixed">…</u-overflow-menu>
+```
+
+### Row "kebab" (all actions behind one trigger)
+
+Mark every item `collapse="always"` so nothing renders inline and only the "more" trigger shows. Items render as **icon buttons** — the `label` is the tooltip/aria text, not visible — so give each an icon. Activation bubbles a `click` from the item; delegate and read it:
+
+```html
+<u-overflow-menu menuPositioning="fixed">
+  <u-overflow-menu-item label="Ver" collapse="always"><span class="material-symbols-outlined">visibility</span></u-overflow-menu-item>
+  <u-overflow-menu-item label="Editar" collapse="always"><span class="material-symbols-outlined">edit</span></u-overflow-menu-item>
+  <u-overflow-menu-item label="Excluir" collapse="always"><span class="material-symbols-outlined">delete</span></u-overflow-menu-item>
+</u-overflow-menu>
+
+<script>
+  table.addEventListener('click', (e) => {
+    const item = e.target.closest('u-overflow-menu-item');
+    if (item) doAction(item.getAttribute('label'), e.target.closest('tr'));
+  });
+</script>
+```
+
+For a single-trigger row menu, `<u-icon-button>` + `<u-menu>` (with `menu.anchorElement = theButton`) is often simpler than `<u-overflow-menu>`.
+
+## Caveats
+
+- A `<u-menu>` is not modal — it doesn't trap focus or scrim the background. Use `<u-dialog>` for modal flows.
+- The overflow menu watches its anchor size with a `ResizeObserver`. If you swap the anchor or animate the container, it re-runs the layout pass automatically.
+- `manualFocus` on `<u-menu>` disables the default auto-focus of the first item on open — useful when the menu wraps a calendar or other custom popover content.

package/skills/navigation-bar/SKILL.md

@@ -0,0 +1,87 @@
+---
+description: Build a Material 3 navigation bar — destinations with icon + label, vertical or horizontal layout, active indicator pill.
+---
+
+# Navigation bar
+
+`<u-navigation-bar>` hosts 3–5 top-level destinations at the bottom of a screen. Use `<u-navigation-bar-item>` for each destination — they render the active indicator pill, icon, and label per M3 expressive tokens.
+
+## Default (vertical) layout
+
+```html
+<u-navigation-bar>
+  <u-navigation-bar-item active>
+    <span class="material-symbols-outlined" slot="icon">home</span>
+    Home
+  </u-navigation-bar-item>
+  <u-navigation-bar-item>
+    <span class="material-symbols-outlined" slot="icon">explore</span>
+    Browse
+  </u-navigation-bar-item>
+  <u-navigation-bar-item>
+    <span class="material-symbols-outlined" slot="icon">radio</span>
+    Radio
+  </u-navigation-bar-item>
+  <u-navigation-bar-item>
+    <span class="material-symbols-outlined" slot="icon">library_music</span>
+    Library
+  </u-navigation-bar-item>
+</u-navigation-bar>
+```
+
+M3 tokens applied automatically:
+- container: 64dp height, `surface-container` color, level-2 elevation
+- active indicator pill: 56×32dp, `secondary-container`
+- icon: 24dp, `on-secondary-container` (active) / `on-surface-variant` (inactive)
+- label: label-medium, `secondary` (active) / `on-surface-variant` (inactive)
+
+## Horizontal variant
+
+For wider items where icon and label sit side-by-side inside a 40dp pill:
+
+```html
+<u-navigation-bar>
+  <u-navigation-bar-item variant="horizontal" active>
+    <span class="material-symbols-outlined" slot="icon">home</span>
+    Home
+  </u-navigation-bar-item>
+  <u-navigation-bar-item variant="horizontal">
+    <span class="material-symbols-outlined" slot="icon">explore</span>
+    Browse
+  </u-navigation-bar-item>
+</u-navigation-bar>
+```
+
+## Slots on `<u-navigation-bar-item>`
+
+| Slot | Content |
+| --- | --- |
+| default | Destination label (text). |
+| `icon` | 24dp icon (`<span class="material-symbols-outlined">…</span>`). |
+| `badge` | Optional `<u-badge>` — auto-positions over the icon. |
+
+## Tracking selection
+
+```html
+<u-navigation-bar id="nav">…</u-navigation-bar>
+
+<script>
+  const nav = document.getElementById('nav');
+  nav.addEventListener('click', (e) => {
+    const item = e.target.closest('u-navigation-bar-item');
+    if (!item) return;
+    [...nav.children].forEach(i => i.active = i === item);
+  });
+</script>
+```
+
+In Angular/React, bind `[active]="route === 'home'"` on each item and switch the route on click.
+
+## Positioning
+
+Same model as `<u-top-app-bar>`: `position="fixed"` by default (viewport bottom), or `position="absolute"` when slotted in a `<u-scaffold>` (auto-set). The internal `.spacing` filler reserves the bar's height in the scrolled flow so content isn't obscured.
+
+## Caveats
+
+- Each item should have an icon AND a label per M3 spec; icon-only items look broken at 64dp.
+- Don't use `<u-icon-button>` instead of `<u-navigation-bar-item>` — you'll lose the active indicator pill, label, and badge slot.