@zeyos/zx 4.3.4 → 5.0.0

package/src/components/app-sidebar/app-sidebar.css

@@ -1,4 +1,50 @@
+/*
+ * AppSidebar — the surface an application is judged by before it is read.
+ *
+ * Everything here hangs off one spacing scale declared on the root. Item height, icon gutter,
+ * row gap, group gap and indentation are derived from the tier-2 control and spacing tokens
+ * rather than picked per rule, so a theme that changes `--zx-space-unit` or
+ * `--zx-control-height` changes the rhythm of the whole nav instead of one row of it.
+ *
+ * Three deliberate choices worth stating:
+ *
+ * - **Labels wrap, they never truncate.** German runs 20-35% longer than English and a nav is
+ *   where that shows first: "Belege & Rechnungen" is two lines in a 16.5rem sidebar. An ellipsis
+ *   there hides the word that distinguishes one destination from another, so the row grows
+ *   instead and the fixed icon column keeps the second line aligned under the first.
+ * - **The active state never rests on colour alone.** It is a neutral fill and a heavier label —
+ *   where you are, not something you picked, so it takes the `--zx-color-bg-current` role rather
+ *   than the accent. The weight survives greyscale and a reduced-transparency page, and forced
+ *   colours swap the fill for the system's own selected pair. Nothing is docked to the edge.
+ * - **A child never starts further in than its parent's label.** A text-only child lines up with
+ *   the words above it; a child with its own icon steps in only far enough for that icon to clear
+ *   the guide line. A parent list without icons indents its children by a short text step.
+ */
+
 .zx-app-sidebar {
+  /* The scale. A row is exactly one control tall, the icon column is as wide as the 24px module
+     chips at the default unit, and every gap and inset is a step of the spacing scale. */
+  --zx-app-sidebar-gutter: var(--zx-space-2);
+  --zx-app-sidebar-icon: var(--zx-space-6);
+  --zx-app-sidebar-item-gap: var(--zx-space-2);
+  --zx-app-sidebar-item-height: var(--zx-control-height);
+  --zx-app-sidebar-pad-x: var(--zx-space-2);
+  --zx-app-sidebar-row-gap: 2px;
+  --zx-app-sidebar-group-gap: var(--zx-space-3);
+  /* The indent under a parent list that has no icon column to hand down. */
+  --zx-app-sidebar-indent: var(--zx-space-3);
+  /* The indent of a child list that brings icons of its own: enough for them to clear the guide,
+     not a whole icon column, so a deep branch never walks across the sidebar. */
+  --zx-app-sidebar-icon-indent: var(--zx-space-4);
+  --zx-app-sidebar-radius: var(--zx-radius-md);
+  /* Three steps of one overlay: hover, the current row, and press. The hover and current roles
+     mix the *text* colour into whatever sits behind, which moves the fill away from the page in
+     whichever direction the theme runs, so a sidebar on the grey chrome tone and one on a white
+     surface both read correctly. Hover stays below the current fill, so pointing at a row never
+     looks like being on it; press goes one step past it. */
+  --zx-app-sidebar-hover: var(--zx-color-bg-hover);
+  --zx-app-sidebar-current: var(--zx-color-bg-current);
+  --zx-app-sidebar-press: color-mix(in srgb, var(--zx-color-text) 12%, transparent);
   display: flex;
   min-block-size: 0;
   border: 1px solid var(--zx-color-glass-border);
@@ -29,57 +75,336 @@
 .zx-app-sidebar__expanded[hidden],
 .zx-app-sidebar__rail[hidden] { display: none; }
 
+/* The header carries no rule. It is a brand slot above a nav, not a boundary between two kinds
+   of content, and a hairline there reads as leftover scaffolding. The footer keeps its rule:
+   an identity control below navigation is a different region and the line is doing work. */
 .zx-app-sidebar__header {
   display: grid;
   grid-template-columns: minmax(0, 1fr) auto;
   align-items: center;
   gap: var(--zx-space-2);
-  min-block-size: calc(var(--zx-control-height) + var(--zx-space-3));
-  border-block-end: 1px solid var(--zx-color-border);
-  padding: var(--zx-space-2);
+  min-block-size: calc(var(--zx-control-height) + var(--zx-space-4));
+  padding: var(--zx-space-2) var(--zx-space-3);
 }
 
 .zx-app-sidebar__header-content { min-inline-size: 0; }
-.zx-app-sidebar__nav { min-block-size: 0; overflow: auto; padding: var(--zx-space-2); }
+
+/* `collapsible: false` hides the minimise button; the icon-button display rule must not show it. */
+.zx-app-sidebar .zx-app-sidebar__collapse[hidden] { display: none; }
+
+/* The block padding is not decoration: the focus ring is a 3px outer glow, and a nav that padded
+   its scroll box by less would clip the ring off the first and last row. */
+.zx-app-sidebar__nav {
+  min-block-size: 0;
+  overflow: auto;
+  padding: var(--zx-space-2) var(--zx-app-sidebar-gutter) var(--zx-space-3);
+}
+
 .zx-app-sidebar__list,
-.zx-app-sidebar__sublist { display: grid; gap: var(--zx-space-1); margin: 0; padding: 0; list-style: none; }
-.zx-app-sidebar__sublist { margin-block-start: var(--zx-space-1); }
+.zx-app-sidebar__sublist {
+  display: grid;
+  gap: var(--zx-app-sidebar-row-gap);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* A list whose items carry no icons should not pay for an empty gutter; one that has even a
+   single icon keeps the column on every row so the labels stay in one line down the list. Each
+   list answers for its own rows only — a branch of plain labels under iconned parents drops the
+   column without taking it from the parents. */
+.zx-app-sidebar__list:not(:has(> .zx-app-sidebar__row > .zx-app-sidebar__item .zx-app-sidebar__item-icon)),
+.zx-app-sidebar__sublist:not(:has(> .zx-app-sidebar__row > .zx-app-sidebar__item .zx-app-sidebar__item-icon)) {
+  --zx-app-sidebar-icon: 0px;
+  --zx-app-sidebar-item-gap: 0px;
+}
+
+/* Where a branch's children start, measured from the row padding, and where the guide that scopes
+   them runs. Both are resolved on the parent row — where the parent's own icon column is still
+   the one in force — and inherited from there, so a child list that drops its column cannot pull
+   the indent or the guide back with it. A row's step is its icon column, or the text indent when
+   it has none; level 3 adds its own step to the one level 2 already sits at. */
+.zx-app-sidebar__row[data-level="1"] {
+  --zx-app-sidebar-step-1: max(var(--zx-app-sidebar-indent), var(--zx-app-sidebar-icon) + var(--zx-app-sidebar-item-gap));
+  --zx-app-sidebar-guide: calc(var(--zx-app-sidebar-pad-x) + max(var(--zx-app-sidebar-indent), var(--zx-app-sidebar-icon)) / 2);
+}
+
+.zx-app-sidebar__row[data-level="2"] {
+  --zx-app-sidebar-step-2: calc(var(--zx-app-sidebar-step-1) + max(var(--zx-app-sidebar-indent), var(--zx-app-sidebar-icon) + var(--zx-app-sidebar-item-gap)));
+  --zx-app-sidebar-guide: calc(var(--zx-app-sidebar-pad-x) + var(--zx-app-sidebar-step-1) + max(var(--zx-app-sidebar-indent), var(--zx-app-sidebar-icon)) / 2);
+}
+
+/* Children with icons of their own step in by the shorter icon indent instead: their icons sit
+   just past the guide rather than under the parent's label. Text-only children keep lining up
+   with the words above them. */
+.zx-app-sidebar__row[data-level="1"]:has(> .zx-app-sidebar__sublist > .zx-app-sidebar__row > .zx-app-sidebar__item .zx-app-sidebar__item-icon) {
+  --zx-app-sidebar-step-1: max(var(--zx-app-sidebar-indent), var(--zx-app-sidebar-icon-indent));
+}
+
+.zx-app-sidebar__row[data-level="2"]:has(> .zx-app-sidebar__sublist > .zx-app-sidebar__row > .zx-app-sidebar__item .zx-app-sidebar__item-icon) {
+  --zx-app-sidebar-step-2: calc(var(--zx-app-sidebar-step-1) + max(var(--zx-app-sidebar-indent), var(--zx-app-sidebar-icon-indent)));
+}
+
+.zx-app-sidebar__sublist { position: relative; margin-block-start: var(--zx-app-sidebar-row-gap); }
 .zx-app-sidebar__sublist[hidden] { display: none; }
 
+/* The one rule in the component that carries meaning: a guide dropped from the centre of the
+   parent's icon that scopes the open branch to the row that opened it. */
+.zx-app-sidebar__sublist::before {
+  content: "";
+  position: absolute;
+  inset-block: 2px;
+  inset-inline-start: var(--zx-app-sidebar-guide);
+  inline-size: 1px;
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-border);
+}
+
+/* Groups are separated by space, not by rules: a top-level branch opens a group, and the row
+   after that group closes it. The first row never gets the gap. */
+.zx-app-sidebar__list > .zx-app-sidebar__row:has(> .zx-app-sidebar__sublist),
+.zx-app-sidebar__list > .zx-app-sidebar__row:has(> .zx-app-sidebar__sublist) + .zx-app-sidebar__row {
+  margin-block-start: var(--zx-app-sidebar-group-gap);
+}
+
+.zx-app-sidebar__list > .zx-app-sidebar__row:first-child { margin-block-start: 0; }
+
 .zx-app-sidebar__item {
+  position: relative;
   display: grid;
-  grid-template-columns: auto minmax(0, 1fr) auto auto;
+  /* The icon track is composed here and not in a variable on the root: a custom property
+     substitutes its `var()`s where it is declared, so a track precomputed on the component would
+     ignore the list-level override below and keep an empty 36px gutter on an icon-less sidebar. */
+  grid-template-columns: calc(var(--zx-app-sidebar-icon) + var(--zx-app-sidebar-item-gap)) minmax(0, 1fr) auto auto;
   align-items: center;
-  gap: var(--zx-space-2);
+  column-gap: 0;
   inline-size: 100%;
-  min-block-size: var(--zx-control-height);
-  border-color: transparent;
-  border-radius: var(--zx-radius-md);
+  min-block-size: var(--zx-app-sidebar-item-height);
+  border: 0;
+  border-radius: var(--zx-app-sidebar-radius);
   background: transparent;
-  padding-inline: var(--zx-space-3);
-  color: inherit;
+  /* The icon column fills the row exactly; a row without one keeps a space-1 margin round its
+     label. Either way a single-line row is one control tall, and a wrapped one grows. */
+  padding-block: min(var(--zx-space-1), (var(--zx-app-sidebar-item-height) - var(--zx-app-sidebar-icon)) / 2);
+  padding-inline: var(--zx-app-sidebar-pad-x);
+  color: var(--zx-color-text);
+  font-size: var(--zx-text-md);
+  font-weight: 500;
+  line-height: 1.35;
   text-align: start;
   text-decoration: none;
 }
 
-.zx-app-sidebar__row[data-level="2"] > .zx-app-sidebar__item { padding-inline-start: calc(var(--zx-space-3) + var(--zx-space-5)); }
-.zx-app-sidebar__row[data-level="3"] > .zx-app-sidebar__item { padding-inline-start: calc(var(--zx-space-3) + var(--zx-space-7)); }
-.zx-app-sidebar__item:hover,
-.zx-app-sidebar__item:focus-visible,
-.zx-app-sidebar__item[data-active-descendant="true"],
-.zx-app-sidebar__item[aria-current="page"] { background: var(--zx-color-bg-hover); color: var(--zx-color-accent); }
-.zx-app-sidebar__item[aria-disabled="true"] { color: var(--zx-color-text-muted); cursor: not-allowed; opacity: .65; }
-.zx-app-sidebar__item-icon,
-.zx-app-sidebar__item-disclosure { display: inline-flex; }
-.zx-app-sidebar__item-badge { color: var(--zx-color-text-muted); font-size: var(--zx-text-xs); }
+/* A nav is a touch target before it is a dense list. The drawn row is one control tall, and a
+   coarse pointer puts the hit area back to 40px whatever the theme's control height says. */
+@media (pointer: coarse) {
+  .zx-app-sidebar__item { min-block-size: 40px; }
+}
+
+.zx-app-sidebar__row[data-level="2"] > .zx-app-sidebar__item { padding-inline-start: calc(var(--zx-app-sidebar-pad-x) + var(--zx-app-sidebar-step-1)); }
+.zx-app-sidebar__row[data-level="3"] > .zx-app-sidebar__item { padding-inline-start: calc(var(--zx-app-sidebar-pad-x) + var(--zx-app-sidebar-step-2)); }
+
+.zx-app-sidebar__item-icon {
+  grid-column: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: var(--zx-app-sidebar-icon);
+  color: var(--zx-color-text-muted);
+}
+
+/* No nowrap and no ellipsis: the row grows instead. `hyphens` is what makes that bearable for a
+   German compound — where the document declares a language the browser breaks "Rechnungsausgang"
+   at a syllable, and `overflow-wrap` is only the last resort behind it for a word that fits
+   nowhere at all. */
+.zx-app-sidebar__item-label {
+  grid-column: 2;
+  min-inline-size: 0;
+  hyphens: auto;
+  overflow-wrap: break-word;
+}
+
+.zx-app-sidebar__item-badge {
+  grid-column: 3;
+  margin-inline-start: var(--zx-space-2);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+}
+
+.zx-app-sidebar__item-disclosure {
+  grid-column: 4;
+  display: inline-flex;
+  margin-inline-start: var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+}
+
+.zx-app-sidebar__item:hover { background: var(--zx-app-sidebar-hover); }
+.zx-app-sidebar__item:hover .zx-app-sidebar__item-icon,
+.zx-app-sidebar__item:hover .zx-app-sidebar__item-disclosure { color: var(--zx-color-text); }
+.zx-app-sidebar__item:active { background: var(--zx-app-sidebar-press); }
+
+/* A branch that is closed over the active route carries the heavier label, so the way back to
+   the current page is visible without opening it; a branch that is open says so with its chevron
+   and shows the active row itself. */
+.zx-app-sidebar__item[data-active-descendant="true"][aria-expanded="false"] {
+  font-weight: var(--zx-weight-semibold);
+}
+
+.zx-app-sidebar__item[data-active-descendant="true"][aria-expanded="false"] .zx-app-sidebar__item-icon {
+  color: var(--zx-color-text);
+}
+
+/* The current page: a neutral fill, the full text colour, a heavier label. Focus is a ring on top
+   of it, never a replacement for it, so a keyboard user arrowing past the active route can still
+   tell which row is current — the shared `--zx-focus-ring` reads on a neutral fill as it does on
+   none. */
+.zx-app-sidebar__item[aria-current="page"] {
+  background: var(--zx-app-sidebar-current);
+  color: var(--zx-color-text);
+  font-weight: var(--zx-weight-semibold);
+}
+
+.zx-app-sidebar__item[aria-current="page"]:active {
+  background: var(--zx-app-sidebar-press);
+}
+
+.zx-app-sidebar__item[aria-current="page"] .zx-app-sidebar__item-icon,
+.zx-app-sidebar__item[aria-current="page"] .zx-app-sidebar__item-disclosure {
+  color: var(--zx-color-text);
+}
+
+/* Unavailable, and still readable. A blanket `opacity` on the row took the label under 3:1, which
+   is the one thing a destination a user cannot reach still has to do: say where it would go. The
+   icon carries the dimming instead, and the label keeps the muted text role. */
+.zx-app-sidebar__item[aria-disabled="true"] {
+  color: var(--zx-color-text-muted);
+  cursor: not-allowed;
+}
+
+.zx-app-sidebar__item[aria-disabled="true"] .zx-app-sidebar__item-icon { opacity: .55; }
+
+.zx-app-sidebar__item[aria-disabled="true"]:hover,
+.zx-app-sidebar__item[aria-disabled="true"]:active { background: transparent; }
 
 .zx-app-sidebar__footer {
   border-block-start: 1px solid var(--zx-color-border);
-  padding: var(--zx-space-2);
+  padding: var(--zx-space-2) var(--zx-space-3);
 }
 .zx-app-sidebar__footer[hidden] { display: none; }
+
 .zx-app-sidebar__rail-header { display: grid; gap: var(--zx-space-1); }
 
+/*
+ * The minimized rail. Only the presentation changes; the same vocabulary applies — the neutral
+ * current fill, the full text colour for a branch over the active route, a badge that survives
+ * the loss of the label.
+ */
+.zx-app-sidebar__rail .zx-app-rail__item {
+  color: var(--zx-color-text-muted);
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item:not([aria-current="page"]):hover,
+.zx-app-sidebar__rail .zx-app-rail__item:not([aria-current="page"])[aria-expanded="true"] {
+  background: var(--zx-app-sidebar-hover);
+  color: var(--zx-color-text);
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item:active {
+  background: var(--zx-app-sidebar-press);
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item[aria-current="page"] {
+  background: var(--zx-app-sidebar-current);
+  color: var(--zx-color-text);
+}
+
+/* A rail item whose flyout holds the active route says so the way a closed branch does in the
+   tree: in the full text colour, without a fill of its own. */
+.zx-app-sidebar__rail .zx-app-rail__item[data-active-descendant="true"]:not([aria-current="page"]) {
+  color: var(--zx-color-text);
+}
+
+/*
+ * The count a minimized rail would otherwise lose. `data-zx-badge` is set by the component from
+ * the item's own badge: a number that fits stays a number, and one that does not becomes a dot,
+ * because a three-digit pill on a 30px target stops being a badge and starts being a label. The
+ * figure itself moves into the control's accessible name either way, so nothing is dropped —
+ * only redrawn.
+ */
+.zx-app-sidebar__rail .zx-app-rail__item-badge {
+  inset-block-start: 0;
+  inset-inline-end: 0;
+  min-inline-size: var(--zx-space-4);
+  block-size: var(--zx-space-4);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-accent);
+  box-shadow: 0 0 0 2px var(--zx-color-bg-surface);
+  padding-inline: var(--zx-space-1);
+  color: var(--zx-color-on-accent);
+  font-size: var(--zx-text-xs);
+  font-variant-numeric: tabular-nums;
+  font-weight: var(--zx-weight-semibold);
+  line-height: var(--zx-space-4);
+  text-align: center;
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item-badge[data-zx-badge="dot"] {
+  min-inline-size: 0;
+  inline-size: var(--zx-space-2);
+  block-size: var(--zx-space-2);
+  padding: 0;
+  font-size: 0;
+  line-height: 0;
+}
+
+/*
+ * Motion. Everything here is decoration on a state change that is already expressed statically,
+ * so all of it is opt-in.
+ *
+ * The expanded tree is re-rendered wholesale on every branch toggle, which is why the disclosure
+ * animation is driven by `data-branch-motion` — an attribute the component sets on exactly the
+ * sublist it just opened, so the branches that were already open do not replay it.
+ */
+@media (prefers-reduced-motion: no-preference) {
+  .zx-app-sidebar__item,
+  .zx-app-sidebar__rail .zx-app-rail__item {
+    transition: background-color var(--zx-dur-fast) var(--zx-ease),
+      color var(--zx-dur-fast) var(--zx-ease),
+      box-shadow var(--zx-dur-fast) var(--zx-ease);
+  }
+
+  .zx-app-sidebar__item:active,
+  .zx-app-sidebar__rail .zx-app-rail__item:active { transform: scale(.985); }
+
+  .zx-app-sidebar__expanded,
+  .zx-app-sidebar__rail { animation: zx-app-sidebar-mode var(--zx-dur-base) var(--zx-ease); }
+
+  .zx-app-sidebar__sublist[data-branch-motion="expand"] { animation: zx-app-sidebar-branch var(--zx-dur-base) var(--zx-ease); }
+}
+
+@keyframes zx-app-sidebar-mode {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes zx-app-sidebar-branch {
+  from { opacity: 0; transform: translateY(-4px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+/* Forced colours drop author backgrounds, so the current fill would disappear. The system's own
+   selected-item pair carries the state there instead. */
+@media (forced-colors: active) {
+  .zx-app-sidebar__item[aria-current="page"],
+  .zx-app-sidebar__rail .zx-app-rail__item[aria-current="page"],
+  .zx-app-sidebar__rail .zx-app-rail__item-badge {
+    background: Highlight;
+    color: HighlightText;
+  }
+}
+
 @media (prefers-reduced-transparency: reduce) {
   .zx-app-sidebar {
     border-color: var(--zx-color-border);

package/src/components/app-sidebar/app-sidebar.js

@@ -1,5 +1,6 @@
 import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
+import { printf } from '../../core/i18n.js';
 import { icon } from '../../core/icons.js';
 import { uid } from '../../core/util.js';
 import {
@@ -77,7 +78,9 @@ export class AppSidebar extends Component {
   /** @returns {HTMLElement} */
   render() {
     this._createdRoot = this.el === null;
-    const root = /** @type {HTMLElement} */ (this.el ?? h('aside'));
+    // A plain box: the <nav> inside is the landmark. An <aside> here would add an unnamed
+    // complementary landmark around every navigation column.
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
     this.el = root;
     this._original = this._createdRoot ? null : {
       attributes: Array.from(root.attributes, (attribute) => [attribute.name, attribute.value]),
@@ -99,17 +102,20 @@ export class AppSidebar extends Component {
   setItems(items) {
     this._items = normalizeAppItems(items);
     this._reconcileExpanded();
-    if (this._rail) this._rail.setItems(this._items);
-    else this._renderTree();
+    if (this._rail) {
+      this._rail.setItems(this._items);
+      this._decorateRail();
+    } else this._renderTree();
     return this;
   }
 
-  /** Returns a shallow copy of normalized items. @returns {AppNavItem[]} */
+  /**
+   * Returns a copy of the normalized items. A leaf has no `children` property, as it was written,
+   * rather than the empty list normalization gives it.
+   * @returns {AppNavItem[]}
+   */
   getItems() {
-    return this._items.map((item) => ({
-      ...item,
-      children: item.children?.map((child) => ({ ...child }))
-    }));
+    return copyItems(this._items);
   }
 
   /** Sets the active id without routing. @param {string|number|null} id @returns {this} */
@@ -151,7 +157,10 @@ export class AppSidebar extends Component {
     const expanded = !this._expanded.has(key);
     if (expanded) this._expanded.add(key);
     else this._expanded.delete(key);
-    if (!this._rail) this._renderTree();
+    if (!this._rail) {
+      this._renderTree();
+      if (expanded) this._markBranchMotion(key);
+    }
     if (!silent) this.emit('branchchange', {
       item,
       id: item.id,
@@ -298,7 +307,7 @@ export class AppSidebar extends Component {
     const collapseButton = h('button', {
       class: 'zx-app-sidebar__collapse zx-icon-btn',
       type: 'button',
-      ariaLabel: 'Minimize application sidebar'
+      ariaLabel: this._message('appSidebar.minimize', 'Minimize application sidebar')
     }, icon(this._side === 'right' ? 'chevron-right' : 'chevron-left'));
     collapseButton.hidden = !this.options.collapsible;
     const footer = h('footer', { class: 'zx-app-sidebar__footer' });
@@ -330,7 +339,7 @@ export class AppSidebar extends Component {
       const expandButton = h('button', {
         class: 'zx-app-sidebar__rail-toggle zx-icon-btn',
         type: 'button',
-        ariaLabel: 'Expand application sidebar'
+        ariaLabel: this._message('appSidebar.expand', 'Expand application sidebar')
       }, icon(this._side === 'right' ? 'chevron-left' : 'chevron-right'));
       railHeader.append(expandButton);
       this._railExpandButton = expandButton;
@@ -356,6 +365,31 @@ export class AppSidebar extends Component {
     });
     this._listenMode(railHost, 'zx-select', (event) => event.stopPropagation());
     this._listenMode(railHost, 'zx-flyoutchange', (event) => event.stopPropagation());
+    this._decorateRail();
+  }
+
+  /**
+   * Keeps a minimized rail's counts readable and audible.
+   *
+   * A rail destination is icon-only, so its accessible name is the label alone and the badge the
+   * expanded tree showed as text is announced by nothing. Here the figure is folded back into the
+   * name, and `data-zx-badge` tells the stylesheet whether the count still fits the target or has
+   * to be drawn as a dot. Presentation only: no item, option, event, or listener is touched.
+   * @returns {void}
+   */
+  _decorateRail() {
+    const rail = this.refs.rail;
+    if (!rail) return;
+    for (const control of rail.querySelectorAll('.zx-app-rail__item[data-app-nav-value-id]')) {
+      const badge = control.querySelector(':scope > .zx-app-rail__item-badge');
+      if (!badge) continue;
+      const item = findItem(this._items, control.getAttribute('data-app-nav-value-id'));
+      if (!item || item.badge == null) continue;
+      const count = String(item.badge);
+      badge.dataset.zxBadge = count.length > 2 ? 'dot' : 'count';
+      control.setAttribute('aria-label',
+        this._message('appSidebar.itemBadge', '%1 (%2)', item.label, count));
+    }
   }
 
   /** @param {EventTarget} target @param {string} type @param {EventListener} listener @returns {void} */
@@ -494,6 +528,35 @@ export class AppSidebar extends Component {
     }
   }
 
+  /**
+   * Flags the sublist a branch toggle just opened so the stylesheet can animate that one branch.
+   *
+   * `_renderTree()` rebuilds every row on every toggle, so a transition declared on the sublist
+   * alone would replay on branches that never moved. The attribute is written after the rebuild
+   * and disappears with the element on the next one, which is why it needs no teardown.
+   * @param {string} key Branch id as a string.
+   * @returns {void}
+   */
+  _markBranchMotion(key) {
+    if (!this.refs.list) return;
+    const control = [...this.refs.list.querySelectorAll('[data-app-nav-id]')]
+      .find((candidate) => candidate.getAttribute('data-app-nav-id') === key) ?? null;
+    const sublist = control?.parentElement?.querySelector(':scope > .zx-app-sidebar__sublist');
+    if (sublist instanceof HTMLElement) sublist.dataset.branchMotion = 'expand';
+  }
+
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   * @param {string} key Message key.
+   * @param {string} fallback Built-in text, with `%1`-style placeholders.
+   * @param {...unknown} args Interpolation values.
+   * @returns {string}
+   */
+  _message(key, fallback, ...args) {
+    const message = this.msg(key, ...args);
+    return message === key ? printf(fallback, args) : message;
+  }
+
   /** @returns {void} */
   _reconcileExpanded() {
     const branchIds = new Set();
@@ -584,5 +647,17 @@ function normalizeSide(orientation, side) {
 
 /** Fired when a destination/action is activated. @event AppSidebar#select @type {CustomEvent<AppNavSelectDetail>} */
 /** Fired when an inline branch changes. @event AppSidebar#branchchange @type {CustomEvent<{item: AppNavItem|null, id: string|number|null, expanded: boolean|null, ids: Array<string|number>}>} */
+/**
+ * Copies a navigation tree, leaving out the empty `children` lists normalization adds to leaves.
+ * @param {AppNavItem[]} items Normalized items.
+ * @returns {AppNavItem[]}
+ */
+function copyItems(items) {
+  return items.map((item) => {
+    const { children, ...rest } = item;
+    return children?.length ? { ...rest, children: copyItems(children) } : rest;
+  });
+}
+
 /** Fired when expanded/minimized presentation changes. @event AppSidebar#collapsechange @type {CustomEvent<{collapsed: boolean}>} */
 /** Fired when a minimized flyout changes. @event AppSidebar#flyoutchange @type {CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>} */

package/src/components/aurora/aurora.css

@@ -1,8 +1,10 @@
 .zx-aurora {
+  /* The brand accent, then three chart series: decoration takes categorical colour, never the
+     status set, so the light behind a page never reads as a success or a warning. */
   --zx-aurora-color-1: var(--zx-color-accent);
-  --zx-aurora-color-2: var(--zx-color-info);
-  --zx-aurora-color-3: var(--zx-color-success);
-  --zx-aurora-color-4: var(--zx-color-warning);
+  --zx-aurora-color-2: var(--zx-color-chart-1);
+  --zx-aurora-color-3: var(--zx-color-chart-3);
+  --zx-aurora-color-4: var(--zx-color-chart-4);
   --zx-aurora-core: 7%;
   --zx-aurora-wash: 4%;
   --zx-aurora-faint: 2%;

package/src/components/avatar/avatar.css

@@ -1,5 +1,11 @@
+/*
+ * The fallback is the avatar most people see, so it carries an identity of its own: initials on a
+ * tint from the categorical tone palette, picked by a stable hash of the name and written as
+ * `data-tone` by the component. No ring — the tint is the edge. The three presets are steps of the
+ * spacing scale: 24 / 32 / 40px at the default unit.
+ */
 .zx-avatar {
-  --zx-avatar-size: var(--zx-control-height);
+  --zx-avatar-size: var(--zx-space-7);
   position: relative;
   display: inline-grid;
   flex: none;
@@ -11,12 +17,22 @@
   vertical-align: middle;
 }
 
-.zx-avatar[data-size="sm"] { --zx-avatar-size: calc(var(--zx-control-height) * .75); }
-.zx-avatar[data-size="lg"] { --zx-avatar-size: calc(var(--zx-control-height) * 1.25); }
+.zx-avatar[data-size="sm"] { --zx-avatar-size: var(--zx-space-6); }
+.zx-avatar[data-size="lg"] { --zx-avatar-size: var(--zx-space-8); }
 .zx-avatar[data-shape="circle"] { border-radius: 50%; }
 .zx-avatar[data-shape="rounded"] { border-radius: var(--zx-radius-md); }
 .zx-avatar[data-shape="square"] { border-radius: 0; }
 
+.zx-avatar[data-tone="blue"] { --zx-avatar-bg: var(--zx-color-tone-blue-bg); --zx-avatar-fg: var(--zx-color-tone-blue-fg); }
+.zx-avatar[data-tone="teal"] { --zx-avatar-bg: var(--zx-color-tone-teal-bg); --zx-avatar-fg: var(--zx-color-tone-teal-fg); }
+.zx-avatar[data-tone="green"] { --zx-avatar-bg: var(--zx-color-tone-green-bg); --zx-avatar-fg: var(--zx-color-tone-green-fg); }
+.zx-avatar[data-tone="amber"] { --zx-avatar-bg: var(--zx-color-tone-amber-bg); --zx-avatar-fg: var(--zx-color-tone-amber-fg); }
+.zx-avatar[data-tone="orange"] { --zx-avatar-bg: var(--zx-color-tone-orange-bg); --zx-avatar-fg: var(--zx-color-tone-orange-fg); }
+.zx-avatar[data-tone="red"] { --zx-avatar-bg: var(--zx-color-tone-red-bg); --zx-avatar-fg: var(--zx-color-tone-red-fg); }
+.zx-avatar[data-tone="pink"] { --zx-avatar-bg: var(--zx-color-tone-pink-bg); --zx-avatar-fg: var(--zx-color-tone-pink-fg); }
+.zx-avatar[data-tone="violet"] { --zx-avatar-bg: var(--zx-color-tone-violet-bg); --zx-avatar-fg: var(--zx-color-tone-violet-fg); }
+.zx-avatar[data-tone="slate"] { --zx-avatar-bg: var(--zx-color-tone-slate-bg); --zx-avatar-fg: var(--zx-color-tone-slate-fg); }
+
 .zx-avatar__image,
 .zx-avatar__fallback {
   inline-size: 100%;
@@ -35,14 +51,18 @@
   display: none;
 }
 
+/* Initials at 0.4 of the size, never under 10px; one of them below 24px (the component decides). */
 .zx-avatar__fallback {
   display: grid;
   place-items: center;
-  border: 1px solid var(--zx-color-border);
-  background: var(--zx-color-bg-muted);
-  font-size: calc(var(--zx-avatar-size) * .34);
-  font-weight: 700;
+  overflow: hidden;
+  background: var(--zx-avatar-bg, var(--zx-color-bg-muted));
+  color: var(--zx-avatar-fg, var(--zx-color-text-muted));
+  font-size: max(10px, calc(var(--zx-avatar-size) * .4));
+  font-weight: var(--zx-weight-semibold);
+  letter-spacing: 0;
   line-height: 1;
+  white-space: nowrap;
 }
 
 .zx-avatar__status {
@@ -59,3 +79,8 @@
 .zx-avatar__status[data-status="online"] { background: var(--zx-color-success); }
 .zx-avatar__status[data-status="away"] { background: var(--zx-color-warning); }
 .zx-avatar__status[data-status="busy"] { background: var(--zx-color-danger); }
+
+/* Forced colours drop the tint; a system-coloured edge keeps the fallback a shape. */
+@media (forced-colors: active) {
+  .zx-avatar__fallback { border: 1px solid CanvasText; }
+}