prime-ui-kit 0.9.1 → 0.9.3

package/src/layout/bottom-nav/examples/floating.tsx

@@ -0,0 +1,89 @@
+/** A glass capsule over the page: the client list scrolls under its blur, with labels or icons alone — `floating`, `iconOnly`. */
+import {
+  AppHeader,
+  AppShell,
+  Avatar,
+  BottomNav,
+  Icon,
+  PageContent,
+  Switch,
+  Typography,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { id: "home", label: "Главная", icon: "nav.home" },
+  { id: "clients", label: "Клиенты", icon: "object.users" },
+  { id: "inbox", label: "Входящие", icon: "object.inbox" },
+  { id: "settings", label: "Настройки", icon: "action.settings" },
+] as const;
+
+const CLIENTS = [
+  { name: "ООО «Север»", initials: "СЕ", color: "blue", deals: "4 сделки" },
+  { name: "ИП Котов", initials: "КО", color: "green", deals: "1 сделка" },
+  { name: "ООО «Вектор»", initials: "ВЕ", color: "orange", deals: "7 сделок" },
+  { name: "АО «Меридиан»", initials: "МЕ", color: "purple", deals: "2 сделки" },
+  { name: "ООО «Полюс»", initials: "ПО", color: "red", deals: "5 сделок" },
+  { name: "ИП Белова", initials: "БЕ", color: "teal", deals: "3 сделки" },
+  { name: "ООО «Гранит»", initials: "ГР", color: "yellow", deals: "6 сделок" },
+  { name: "АО «Ладога»", initials: "ЛА", color: "sky", deals: "2 сделки" },
+] as const;
+
+export default function BottomNavFloatingExample() {
+  const [section, setSection] = React.useState<string>("clients");
+  const [iconOnly, setIconOnly] = React.useState(false);
+
+  return (
+    <div className={styles.phone}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppHeader.Root>
+          <AppHeader.Start>
+            <AppHeader.Title>Клиенты</AppHeader.Title>
+          </AppHeader.Start>
+          <AppHeader.Actions>
+            <Switch.Root checked={iconOnly} onCheckedChange={setIconOnly}>
+              <Switch.Label>Только иконки</Switch.Label>
+            </Switch.Root>
+          </AppHeader.Actions>
+        </AppHeader.Root>
+        <AppShell.Main>
+          <PageContent.Section>
+            <PageContent.Body>
+              {CLIENTS.map((client) => (
+                <div key={client.name} className={styles.client}>
+                  <Avatar.Root color={client.color} aria-hidden="true">
+                    <Avatar.Fallback>{client.initials}</Avatar.Fallback>
+                  </Avatar.Root>
+                  <div>
+                    <Typography variant="body-m">{client.name}</Typography>
+                    <Typography variant="body-s" tone="muted">
+                      {client.deals}
+                    </Typography>
+                  </div>
+                </div>
+              ))}
+            </PageContent.Body>
+          </PageContent.Section>
+        </AppShell.Main>
+        <AppShell.Footer>
+          <BottomNav.Root floating iconOnly={iconOnly}>
+            {SECTIONS.map((item) => (
+              <BottomNav.Item
+                key={item.id}
+                current={item.id === section}
+                onClick={() => setSection(item.id)}
+              >
+                <BottomNav.ItemIcon>
+                  <Icon name={item.icon} />
+                </BottomNav.ItemIcon>
+                {item.label}
+              </BottomNav.Item>
+            ))}
+          </BottomNav.Root>
+        </AppShell.Footer>
+      </AppShell.Root>
+    </div>
+  );
+}

package/src/layout/bottom-nav/examples/icon-only.tsx

@@ -0,0 +1,41 @@
+/** Icons alone: the labels are hidden but still name the sections for screen readers — `iconOnly`. */
+import { BottomNav, Icon, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { id: "home", label: "Главная", icon: "nav.home" },
+  { id: "orders", label: "Заказы", icon: "object.package" },
+  { id: "inbox", label: "Входящие", icon: "object.inbox" },
+  { id: "profile", label: "Профиль", icon: "object.user" },
+] as const;
+
+export default function BottomNavIconOnlyExample() {
+  const [section, setSection] = React.useState<string>("home");
+  const current = SECTIONS.find((item) => item.id === section) ?? SECTIONS[0];
+
+  return (
+    <div className={styles.phone}>
+      <div className={styles.screen}>
+        <Typography as="h2" variant="title-m">
+          {current.label}
+        </Typography>
+      </div>
+      <BottomNav.Root iconOnly>
+        {SECTIONS.map((item) => (
+          <BottomNav.Item
+            key={item.id}
+            current={item.id === section}
+            onClick={() => setSection(item.id)}
+          >
+            <BottomNav.ItemIcon>
+              <Icon name={item.icon} />
+            </BottomNav.ItemIcon>
+            {item.label}
+          </BottomNav.Item>
+        ))}
+      </BottomNav.Root>
+    </div>
+  );
+}

package/src/layout/bottom-nav/examples/in-app-shell.tsx

@@ -0,0 +1,64 @@
+/** The app frame on a phone: the AppHeader, the page and the bar in the footer, which leaves once the panel is 640px wide — `AppShell.Footer`. */
+import {
+  AppHeader,
+  AppShell,
+  BottomNav,
+  Button,
+  Icon,
+  PageContent,
+  Typography,
+} from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { label: "Главная", icon: "nav.home" },
+  { label: "Заказы", icon: "object.package" },
+  { label: "Клиенты", icon: "object.users" },
+  { label: "Ещё", icon: "action.more" },
+] as const;
+
+const ORDERS = ["№ 4821 · ООО «Север»", "№ 4820 · ИП Котов", "№ 4819 · ООО «Вектор»"];
+
+export default function BottomNavInAppShellExample() {
+  return (
+    <div className={styles.phone}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppHeader.Root>
+          <AppHeader.Start>
+            <AppHeader.Title>Заказы</AppHeader.Title>
+          </AppHeader.Start>
+        </AppHeader.Root>
+        <AppShell.Main>
+          <PageContent.Section>
+            <PageContent.Body>
+              {ORDERS.map((order) => (
+                <Typography key={order} variant="body-m">
+                  {order}
+                </Typography>
+              ))}
+              <Button.Root variant="soft" tone="neutral">
+                <Button.Icon>
+                  <Icon name="action.add" />
+                </Button.Icon>
+                Новый заказ
+              </Button.Root>
+            </PageContent.Body>
+          </PageContent.Section>
+        </AppShell.Main>
+        <AppShell.Footer>
+          <BottomNav.Root>
+            {SECTIONS.map((item, index) => (
+              <BottomNav.Item key={item.label} current={index === 1}>
+                <BottomNav.ItemIcon>
+                  <Icon name={item.icon} />
+                </BottomNav.ItemIcon>
+                {item.label}
+              </BottomNav.Item>
+            ))}
+          </BottomNav.Root>
+        </AppShell.Footer>
+      </AppShell.Root>
+    </div>
+  );
+}

package/src/layout/bottom-nav/examples/overview.tsx

@@ -0,0 +1,44 @@
+/** Four sections of the app, the current one in the primary color and a tap moves it — `current`, `BottomNav.ItemIcon`. */
+import { BottomNav, Icon, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { id: "home", label: "Главная", icon: "nav.home", summary: "Выручка за неделю — 1,2 млн ₽" },
+  { id: "orders", label: "Заказы", icon: "object.package", summary: "37 заказов ждут отгрузки" },
+  { id: "clients", label: "Клиенты", icon: "object.users", summary: "214 активных клиентов" },
+  { id: "settings", label: "Настройки", icon: "action.settings", summary: "Профиль и уведомления" },
+] as const;
+
+export default function BottomNavOverviewExample() {
+  const [section, setSection] = React.useState<string>("orders");
+  const current = SECTIONS.find((item) => item.id === section) ?? SECTIONS[0];
+
+  return (
+    <div className={styles.phone}>
+      <div className={styles.screen}>
+        <Typography as="h2" variant="title-m">
+          {current.label}
+        </Typography>
+        <Typography variant="body-m" tone="secondary">
+          {current.summary}
+        </Typography>
+      </div>
+      <BottomNav.Root>
+        {SECTIONS.map((item) => (
+          <BottomNav.Item
+            key={item.id}
+            current={item.id === section}
+            onClick={() => setSection(item.id)}
+          >
+            <BottomNav.ItemIcon>
+              <Icon name={item.icon} />
+            </BottomNav.ItemIcon>
+            {item.label}
+          </BottomNav.Item>
+        ))}
+      </BottomNav.Root>
+    </div>
+  );
+}

package/src/layout/bottom-nav/examples/router.tsx

@@ -0,0 +1,31 @@
+/** A router link as the item: the router sets `aria-current` and the item shows as current; render it inside a router — `asChild`. */
+import { BottomNav, Icon } from "prime-ui-kit";
+import { NavLink } from "react-router-dom";
+
+import styles from "./examples.module.css";
+
+const LINKS = [
+  { to: "/app-shell", label: "Каркас", icon: "nav.layoutGrid" },
+  { to: "/bottom-nav", label: "Навигация", icon: "nav.menu" },
+  { to: "/sidebar", label: "Сайдбар", icon: "nav.sidebarExpand" },
+] as const;
+
+export default function BottomNavRouterExample() {
+  return (
+    <div className={styles.phone}>
+      <div className={styles.screen} />
+      <BottomNav.Root>
+        {LINKS.map((link) => (
+          <BottomNav.Item key={link.to} asChild>
+            <NavLink to={link.to}>
+              <BottomNav.ItemIcon>
+                <Icon name={link.icon} />
+              </BottomNav.ItemIcon>
+              {link.label}
+            </NavLink>
+          </BottomNav.Item>
+        ))}
+      </BottomNav.Root>
+    </div>
+  );
+}

package/src/layout/bottom-nav/examples/structure.tsx

@@ -0,0 +1,47 @@
+/** Counts on the icons and a section that is not available yet — `BottomNav.ItemCount`, `disabled`. */
+import { BottomNav, Icon, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function BottomNavStructureExample() {
+  return (
+    <div className={styles.phone}>
+      <div className={styles.screen}>
+        <Typography as="h2" variant="title-m">
+          Главная
+        </Typography>
+        <Typography variant="body-m" tone="secondary">
+          12 новых заказов и 3 сообщения от клиентов.
+        </Typography>
+      </div>
+      <BottomNav.Root>
+        <BottomNav.Item current>
+          <BottomNav.ItemIcon>
+            <Icon name="nav.home" />
+          </BottomNav.ItemIcon>
+          Главная
+        </BottomNav.Item>
+        <BottomNav.Item>
+          <BottomNav.ItemIcon>
+            <Icon name="object.package" />
+          </BottomNav.ItemIcon>
+          <BottomNav.ItemCount>12</BottomNav.ItemCount>
+          Заказы
+        </BottomNav.Item>
+        <BottomNav.Item>
+          <BottomNav.ItemIcon>
+            <Icon name="object.message" />
+          </BottomNav.ItemIcon>
+          <BottomNav.ItemCount color="blue">3</BottomNav.ItemCount>
+          Сообщения
+        </BottomNav.Item>
+        <BottomNav.Item disabled>
+          <BottomNav.ItemIcon>
+            <Icon name="object.chart" />
+          </BottomNav.ItemIcon>
+          Отчёты
+        </BottomNav.Item>
+      </BottomNav.Root>
+    </div>
+  );
+}

package/src/layout/sidebar/COMPONENT.md

@@ -1,6 +1,6 @@
 # Sidebar
 
-**Category:** layout
+**Category:** navigation
 **Kind:** layout
 
 > App side navigation in three modes — expanded, compact, hidden — and an off-canvas panel on narrow screens.
@@ -22,7 +22,8 @@ same place. Structure it by what people do, not by how the backend is split.
   tooltip), so start sibling labels differently («Продажи» and «Проекты» both read «Про»).
 - **Fold only what is secondary.** Make a group `collapsible` when the list is long (about 12+
   items) or the group is used rarely; keep the main group open and fixed. `defaultOpen={false}`
-  only for rarely used groups — a group with the current page opens by itself.
+  only for rarely used groups — a group with the current page opens by itself (on the compact rail
+  it stays folded; its `…` row marks the page).
 - **One level of nesting.** `Sidebar.Sub` is one section with 2–6 views of the same objects
   (Сделки → Новые · В работе · Закрытые). The parent only discloses; an overview page is the first
   child («Все сделки»). Never a sub-list inside a sub-list — split the section or use page tabs.
@@ -128,7 +129,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (Groups, Items, Subs), `className` and the other attributes. |
 
 ### Sidebar.Group
-`ref` → `HTMLDivElement`. `<div role="group">` named by its label. With `collapsible` the heading is a disclosure button (`aria-expanded`, `aria-controls`) with a chevron at its end; the items fold away (inert). On the compact rail the heading keeps its height and layout: its text slides toward the edge, scales down and is cut by the rail with a fade, so the first letters still name the section. An open group keeps its items on the rail; a folded one stays folded and becomes one `…` row (named by the label, `aria-haspopup="dialog"`) whose items open in a flyout, like a sub-list. A folded group with a count that needs attention inside shows its dot (after the heading, or on the `…` row).
+`ref` → `HTMLDivElement`. `<div role="group">` named by its label. With `collapsible` the heading is a disclosure button (`aria-expanded`, `aria-controls`) with a chevron at its end; the items fold away (inert). On the compact rail the heading keeps its height and layout: its text slides toward the edge, scales down and is cut by the rail with a fade, so the first letters still name the section, and it still folds and unfolds the group. An open group keeps its items on the rail; a folded one stays folded and becomes one `…` row (named by the label, `aria-haspopup="dialog"`) whose items open in a flyout, like a sub-list. A folded group with a count that needs attention inside shows its dot (after the heading, or on the `…` row).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -136,7 +137,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `collapsible` | `boolean` | `false` | The heading shows and hides the items. Needs `label`. |
 | `open` | `boolean` | — | Items shown (controlled). |
 | `onOpenChange` | `(open: boolean) => void` | — | Called with the new open state (click, keyboard, a current page moving inside). |
-| `defaultOpen` | `boolean` | `true` | Initial state (uncontrolled). A closed group opens by itself when the current page moves into it. |
+| `defaultOpen` | `boolean` | `true` | Initial state (uncontrolled). Off the compact rail a closed group opens by itself when the current page moves into it; on the rail it stays folded and its `…` row marks the page. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `children` (Items, Subs), `className` and the other div attributes. |
 
 ### Sidebar.Item
@@ -178,7 +179,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Sidebar.ItemAction
-`ref` → `HTMLButtonElement`. A row action (create, add): a ghost icon `Button` one tier down with a tooltip, next to the item element — never inside it. It shows on hover and focus of the row while the trail (count, hint) steps aside; hidden on the compact rail.
+`ref` → `HTMLButtonElement`. A row action (create, add): a ghost icon `Button` one tier down with a tooltip, next to the item element — never inside it. It shows on hover and focus of the row, always on touch screens, while the trail (count, hint) steps aside; hidden on the compact rail.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -242,7 +243,7 @@ Hook for custom parts inside `Sidebar.Root` (throws outside). Returns the fields
 | `size · navId · labels` | `ControlSize · string · SidebarLabels` | — | Tier, id of the `<nav>` (for `aria-controls` on your own menu button), resolved strings. |
 
 ## Variants
-The rail sits on `bg-canvas` without a border or card; items are transparent rows with `text-secondary`, `fill-subtle` on hover; the current item is lifted to `bg-surface` + `shadow-raised` with primary text.
+The rail is a surface beside the page, one layer above it on the surface ladder (`data-depth`): white on the light gray page, one step lighter than the near-black page in dark; no border or card. Items are transparent rows with `text-secondary`, `fill-subtle` on hover; the current item takes the rail's fill two ladder steps off it (`fill-muted-hover`) with primary text.
 
 ### mode (Root)
 | Value | Looks like | Use when | Default |
@@ -289,7 +290,7 @@ The rail width does not depend on `size`.
 | `current` (Item) | surface fill + raised shadow, primary text and icon | the current page | off |
 | `disabled` (Item) | `text-disabled`, no hover, `cursor: not-allowed` | an unavailable section | off |
 
-Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header, or `Sidebar.Toggle` in the footer for a rail without a brand; on phones (`offCanvas="auto"`) or always (`offCanvas="always"`) pair it with a menu button in `AppShell.Header` (`open` / `onOpenChange`). One current item at a time; give every top-level item an icon when the rail can go compact (child items need none).
+Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header, or `Sidebar.Toggle` in the footer for a rail without a brand; on phones (`offCanvas="auto"`) or always (`offCanvas="always"`) pair it with `AppHeader.MenuButton` (`open` / `onOpenChange`). One current item at a time; give every top-level item an icon when the rail can go compact (child items need none).
 
 ## States
 | State | Driven by | DOM |
@@ -297,7 +298,7 @@ Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header,
 | mode | `mode` / `defaultMode` | Root `data-mode`, `data-panel-mode` (the last visible mode while hidden); `<nav inert>` while hidden |
 | off-canvas | `offCanvas="always"`, or `"auto"` + viewport < 768px | Root `data-off-canvas`, `data-state="open" \| "closed"`; `<nav inert>` while closed |
 | current | `current` or a router's `aria-current` | Item `aria-current="page"`, `data-state="active"` |
-| active path | a child of a Sub (or an item of a Group) is current | SubTrigger `data-active-path`; a closed Sub / Group opens |
+| active path | a child of a Sub (or an item of a Group) is current | SubTrigger (or the `…` row of a folded Group) `data-active-path`; a closed Sub opens, a closed Group opens off the compact rail |
 | group open | Group `open` / `defaultOpen` (`collapsible`) | heading `aria-expanded`; region `data-state`, `inert` while closed |
 | sub open | Sub `open` / `defaultOpen` | SubTrigger `aria-expanded`; SubContent `data-state`, `inert` while closed |
 | flyout | hover / click / keyboard on a SubTrigger, or on the `…` row of a folded group, in compact mode | the row `aria-haspopup="dialog"`, `aria-expanded`; a Popover `role="dialog"` |
@@ -310,18 +311,18 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 ## Layout & spacing
 - Panel padding: `--prime-space-3` block, `--prime-space-2` inline; regions 8 apart; groups 16 apart, items 4 apart.
 - Item horizontal padding is derived from the compact width so icons and the brand logo sit on one axis in every mode (the account avatar joins that axis on the rail).
-- Header is one row of the item height + 8. The header toggle (xs, 28) sits at its end, 8 from the rail edge; in compact mode it moves half past the edge, scales to 3/4, turns round and gets a canvas ring. The root clips with `clip-path`, reaching past the edge by the toggle's half-width and ring beside the header only; everywhere else the panel ends exactly at the spacer edge.
+- Header is one row of the item height + 8. The header toggle (xs, 28) sits at its end, 8 from the rail edge; in compact mode it moves half past the edge, scales to 3/4, turns round and gets a ring in the rail color. The root clips with `clip-path`, reaching past the edge by the toggle's half-width and ring beside the header only; everywhere else the panel ends exactly at the spacer edge.
 - Collapsible group: heading 28 high with the chevron (14) at its end, aligned with the item trail; items start 4 below. A folded group's attention dot sits before the chevron.
-- On the rail a heading keeps its 28 and its layout: the text slides 8 toward the edge, scales to 0.85 and is cut at the rail box with a 12 fade into the canvas. A folded group adds one `…` row under its heading.
+- On the rail a heading keeps its 28 and its layout: the text slides 8 toward the edge, scales to 0.85 and is cut at the rail box with a 12 fade into the rail. A folded group adds one `…` row under its heading. The items and the row share one place: folding or unfolding on the rail glides the group's height one way (list ↔ row) while the two cross-fade, so the rows below never move back.
 - Sub-list: a 1px `border-default` guide line on the parent icon's centre; every child branches off it with an 8 elbow and a 6 bend; child labels line up with the parent label.
-- Trail (count, key hint, trailing icon) sits at the row end; a row action (one tier down) appears there on hover / focus and the trail moves aside.
+- Trail (count, key hint, trailing icon) sits at the row end; a row action (one tier down) appears there on hover / focus (always on touch screens) and the trail moves aside.
 - Footer: items 4 apart; the account is set 8 apart below them. It is its own card-like row: the
   avatar of the tier (xs 20, s 24, m·l 32, xl 40) sits in an even frame — the inset before it, the
   gap to the text and the air above and below are one value, the tier gap (xs 4, s·m·l 8, xl 12),
   so the row is the avatar + 2 × gap high (48 at m). On the compact rail the start inset becomes the
   one that centres the avatar on the icon axis, as part of the rail motion.
 - Compact flyout: the kit Popover (flush) to the right, aligned with the parent row, with the metrics of a kit menu — rows of the tier's menu item height (32 at m), the panel padding, no title (the row names it), no guide line; current child is a `fill-subtle-active` wash.
-- Motion: two layers on one clock. `Sidebar.Root` is the spacer: it reserves the rail width in the page, paints the canvas and clips the panel to its own box; its width is the only layout that moves (the page column follows). The `<nav>` panel inside is positioned at the expanded width in every mode and never lays out again, so nothing re-wraps and nothing switches at the end. Every part is a plain CSS transition over `base` with the `standard` (ease-in-out) easing, started by the same mode change and ending with the rail: text fades through its fill colour (paint-only, no compositor layer per label), chevrons through their stroke, trailing boxes (a coloured count, a key hint) through `opacity`; coloured counts turn into dots; the account avatar slides onto the icon axis; the header toggle rides the edge by `translate` / `scale`. Rows stay full width: a row with a fill or a ring (current, on the active path, hovered, open, focused) draws them on a pseudo-element whose end edge travels to the icon box and clips its content there, so it always ends rail padding before the moving edge and is a rounded square around the icon at rest. Group headings keep their height and layout: their text slides toward the edge and scales down by transform while the moving cut ends it with a fade; the text box narrows only once the rail has closed (under the cut, never seen), so the dot and the chevron after it stay in place and fade. The `…` row of a folded group grows in and out on the same clock (grid track height), as do the attention dots (opacity and scale). Hidden keeps the look of the last visible mode and is clipped as one piece; the header toggle stays at its place and fades, and coming back from hidden it fades in at its final place. Collapsible groups that open for the rail and sub-lists that close for it move on the same clock (grid track height); chevrons rotate (base). All durations are tokens: under reduced motion every mode change is instant.
+- Motion: two layers on one clock. `Sidebar.Root` is the spacer: it reserves the rail width in the page, paints the rail and clips the panel to its own box; its width is the only layout that moves (the page column follows). The `<nav>` panel inside is positioned at the expanded width in every mode and never lays out again, so nothing re-wraps and nothing switches at the end. Every part is a plain CSS transition over `base` with the `standard` (ease-in-out) easing, started by the same mode change and ending with the rail: text fades through its fill colour (paint-only, no compositor layer per label), chevrons through their stroke, trailing boxes (a coloured count, a key hint) through `opacity`; coloured counts turn into dots; the account avatar slides onto the icon axis; the header toggle rides the edge by `translate` / `scale`. Rows stay full width: a row with a fill or a ring (current, on the active path, hovered, open, focused) draws them on a pseudo-element whose end edge travels to the icon box and clips its content there, so it always ends rail padding before the moving edge and is a rounded square around the icon at rest. Group headings keep their height and layout: their text slides toward the edge and scales down by transform while the moving cut ends it with a fade; the text box narrows only once the rail has closed (under the cut, never seen), so the dot and the chevron after it stay in place and fade. The `…` row of a folded group grows in and out on the same clock (grid track height), as do the attention dots (opacity and scale). Hidden keeps the look of the last visible mode and is clipped as one piece; the header toggle stays at its place and fades, and coming back from hidden it fades in at its final place. Collapsible groups that open for the rail and sub-lists that close for it move on the same clock (grid track height); chevrons rotate (base). All durations are tokens: under reduced motion every mode change is instant.
 - Layers of a row on the rail (compact tooltips, the sub-list flyout, a `Dropdown` around `Sidebar.Account`) anchor to the visible part of the row — the icon box — not to its full-width box. The brand has no compact tooltip: the logo speaks for itself and a tooltip would cover the edge toggle.
 - Off-canvas panel width: min(sidebar width, 100% − `--prime-space-12`).
 - Inside `AppShell.Nav` the rail takes the full height. The root is `height: 100%` and the panel is
@@ -344,7 +345,7 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 - The current item has `aria-current="page"`; in compact mode the label shows as a tooltip, so icon-only items keep a visible name.
 - A collapsible group heading and a SubTrigger are buttons with `aria-expanded` and `aria-controls`; folded content is `inert`.
 - On the compact rail a SubTrigger and the `…` row of a folded group have `aria-haspopup="dialog"`; the flyout is a non-modal dialog named by the parent (the `…` row by the group label).
-- On the rail a group heading is out of the tab order and hidden from screen readers (the group keeps its name); hovering it shows the whole name in a tooltip.
+- On the rail a collapsible group heading stays the same disclosure button (folding it there brings the `…` row); hovering it shows the whole name in a tooltip.
 - An attention dot is decorative: the count it stands for is read inside.
 - A row action is its own button next to the item (never nested), named by `label` with a tooltip.
 - The account avatar is hidden from screen readers; the name and the muted line name the button.

package/src/layout/sidebar/examples/examples.module.css

@@ -1,4 +1,4 @@
-/* Layout for the Sidebar examples: small "app windows" (canvas rail + surface content). Semantic tokens only. */
+/* Layout for the Sidebar examples: small "app windows" (the page with a rail one layer above it). Semantic tokens only. */
 
 .stage {
   box-sizing: border-box;
@@ -7,8 +7,8 @@
   height: calc(var(--prime-space-24) * 4);
   overflow: hidden;
   border-radius: var(--prime-card-radius);
-  background: var(--prime-color-bg-canvas);
-  /* The rail shares the preview's canvas fill: a hairline keeps the window edge visible. */
+  background: var(--prime-color-layer-current);
+  /* The window is a page on the preview's page: a hairline keeps its edge visible. */
   box-shadow:
     0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
     var(--prime-shadow-raised);
@@ -24,13 +24,13 @@
   height: calc(var(--prime-space-24) * 2);
 }
 
-/* Content plane next to the rail, like AppShell: surface fill, edge to edge. */
+/* Content plane next to the rail, like AppShell: the page itself, edge to edge. */
 .content {
   box-sizing: border-box;
   flex: 1 1 auto;
   min-width: 0;
   padding: var(--prime-space-4);
-  background: var(--prime-color-bg-surface);
+  background: var(--prime-color-layer-current);
 }
 
 /* The product mark inside `Sidebar.BrandLogo`: an accent tile with a glyph. */

package/src/styles/globals.css

@@ -8,7 +8,7 @@
 :root {
   font-family: var(--prime-font-family-sans);
   color: var(--prime-color-text-primary);
-  background: var(--prime-color-bg-canvas);
+  background: var(--prime-color-layer-0-bg);
   text-rendering: optimizeLegibility;
   font-kerning: normal;
   font-feature-settings: "cv11", "ss01";
@@ -23,7 +23,7 @@
 }
 
 body {
-  background: var(--prime-color-bg-canvas);
+  background: var(--prime-color-layer-0-bg);
   color: var(--prime-color-text-primary);
   font-size: var(--prime-text-body-m-size);
   line-height: var(--prime-text-body-m-line-height);
@@ -88,6 +88,129 @@ input::-moz-focus-inner {
   }
 }
 
+/*
+ * Surface depth (foundation §4). The page (and the AppShell panel) is layer 0; every surface (Card,
+ * Sidebar, Accordion, DataTable…) sets `data-depth` one above the surface around it, floating layers set
+ * `floating`. Each depth points the context variables at its row of `--prime-color-layer-*`:
+ *   layer-current   the surface's own fill        layer-nested    a surface placed on it
+ *   field-bg(-hover/-focus), fill-muted(-hover)   controls on it: one step from the surface
+ *   control-selected                              the selected thumb on a track of it
+ *   layer-shadow                                  a whisper only on a card that sits on the page
+ * A theme island (`data-theme`) starts again at layer 0.
+ */
+:root,
+[data-theme],
+[data-depth="0"] {
+  --prime-color-layer-current: var(--prime-color-layer-0-bg);
+  --prime-color-layer-nested: var(--prime-color-layer-1-bg);
+  --prime-color-field-bg: var(--prime-color-layer-0-fill);
+  --prime-color-field-bg-hover: var(--prime-color-layer-0-fill-hover);
+  --prime-color-field-bg-focus: var(--prime-color-layer-0-bg);
+  --prime-color-fill-muted: var(--prime-color-layer-0-fill);
+  --prime-color-fill-muted-hover: var(--prime-color-layer-0-fill-hover);
+  --prime-color-control-selected: var(--prime-color-layer-0-selected);
+  --prime-layer-shadow: none;
+}
+
+[data-depth="1"] {
+  --prime-color-layer-current: var(--prime-color-layer-1-bg);
+  --prime-color-layer-nested: var(--prime-color-layer-2-bg);
+  --prime-color-field-bg: var(--prime-color-layer-1-fill);
+  --prime-color-field-bg-hover: var(--prime-color-layer-1-fill-hover);
+  --prime-color-field-bg-focus: var(--prime-color-layer-1-bg);
+  --prime-color-fill-muted: var(--prime-color-layer-1-fill);
+  --prime-color-fill-muted-hover: var(--prime-color-layer-1-fill-hover);
+  --prime-color-control-selected: var(--prime-color-layer-1-selected);
+  --prime-layer-shadow: var(--prime-shadow-raised);
+}
+
+[data-depth="2"] {
+  --prime-color-layer-current: var(--prime-color-layer-2-bg);
+  --prime-color-layer-nested: var(--prime-color-layer-3-bg);
+  --prime-color-field-bg: var(--prime-color-layer-2-fill);
+  --prime-color-field-bg-hover: var(--prime-color-layer-2-fill-hover);
+  --prime-color-field-bg-focus: var(--prime-color-layer-2-bg);
+  --prime-color-fill-muted: var(--prime-color-layer-2-fill);
+  --prime-color-fill-muted-hover: var(--prime-color-layer-2-fill-hover);
+  --prime-color-control-selected: var(--prime-color-layer-2-selected);
+  --prime-layer-shadow: none;
+}
+
+[data-depth="3"] {
+  --prime-color-layer-current: var(--prime-color-layer-3-bg);
+  --prime-color-layer-nested: var(--prime-color-layer-4-bg);
+  --prime-color-field-bg: var(--prime-color-layer-3-fill);
+  --prime-color-field-bg-hover: var(--prime-color-layer-3-fill-hover);
+  --prime-color-field-bg-focus: var(--prime-color-layer-3-bg);
+  --prime-color-fill-muted: var(--prime-color-layer-3-fill);
+  --prime-color-fill-muted-hover: var(--prime-color-layer-3-fill-hover);
+  --prime-color-control-selected: var(--prime-color-layer-3-selected);
+  --prime-layer-shadow: none;
+}
+
+/* The deepest layer: a surface nested in it keeps its color (deeper nesting is not supported). */
+[data-depth="4"] {
+  --prime-color-layer-current: var(--prime-color-layer-4-bg);
+  --prime-color-layer-nested: var(--prime-color-layer-4-bg);
+  --prime-color-field-bg: var(--prime-color-layer-4-fill);
+  --prime-color-field-bg-hover: var(--prime-color-layer-4-fill-hover);
+  --prime-color-field-bg-focus: var(--prime-color-layer-4-bg);
+  --prime-color-fill-muted: var(--prime-color-layer-4-fill);
+  --prime-color-fill-muted-hover: var(--prime-color-layer-4-fill-hover);
+  --prime-color-control-selected: var(--prime-color-layer-4-selected);
+  --prime-layer-shadow: none;
+}
+
+/* Floating layers (menus, popovers, modals, drawers): one step above a card, depth comes from the
+   shadow; two layers can nest inside. */
+[data-depth="floating"] {
+  --prime-color-layer-current: var(--prime-color-layer-floating-bg);
+  --prime-color-layer-nested: var(--prime-color-layer-floating1-bg);
+  --prime-color-field-bg: var(--prime-color-layer-floating-fill);
+  --prime-color-field-bg-hover: var(--prime-color-layer-floating-fill-hover);
+  --prime-color-field-bg-focus: var(--prime-color-layer-floating-bg);
+  --prime-color-fill-muted: var(--prime-color-layer-floating-fill);
+  --prime-color-fill-muted-hover: var(--prime-color-layer-floating-fill-hover);
+  --prime-color-control-selected: var(--prime-color-layer-floating-selected);
+  --prime-layer-shadow: none;
+}
+
+[data-depth="floating-1"] {
+  --prime-color-layer-current: var(--prime-color-layer-floating1-bg);
+  --prime-color-layer-nested: var(--prime-color-layer-floating2-bg);
+  --prime-color-field-bg: var(--prime-color-layer-floating1-fill);
+  --prime-color-field-bg-hover: var(--prime-color-layer-floating1-fill-hover);
+  --prime-color-field-bg-focus: var(--prime-color-layer-floating1-bg);
+  --prime-color-fill-muted: var(--prime-color-layer-floating1-fill);
+  --prime-color-fill-muted-hover: var(--prime-color-layer-floating1-fill-hover);
+  --prime-color-control-selected: var(--prime-color-layer-floating1-selected);
+  --prime-layer-shadow: none;
+}
+
+[data-depth="floating-2"] {
+  --prime-color-layer-current: var(--prime-color-layer-floating2-bg);
+  --prime-color-layer-nested: var(--prime-color-layer-floating2-bg);
+  --prime-color-field-bg: var(--prime-color-layer-floating2-fill);
+  --prime-color-field-bg-hover: var(--prime-color-layer-floating2-fill-hover);
+  --prime-color-field-bg-focus: var(--prime-color-layer-floating2-bg);
+  --prime-color-fill-muted: var(--prime-color-layer-floating2-fill);
+  --prime-color-fill-muted-hover: var(--prime-color-layer-floating2-fill-hover);
+  --prime-color-control-selected: var(--prime-color-layer-floating2-selected);
+  --prime-layer-shadow: none;
+}
+
+/* A host off the ladder (a tinted banner, an accent wash, an image): its own fill stays, controls
+   on it take translucent washes, which read on any color. */
+[data-depth="tinted"] {
+  --prime-color-field-bg: var(--prime-color-fill-subtle-active);
+  --prime-color-field-bg-hover: var(--prime-color-fill-strong);
+  --prime-color-field-bg-focus: var(--prime-color-layer-floating-bg);
+  --prime-color-fill-muted: var(--prime-color-fill-subtle-active);
+  --prime-color-fill-muted-hover: var(--prime-color-fill-strong);
+  --prime-color-control-selected: var(--prime-color-layer-floating-bg);
+  --prime-layer-shadow: none;
+}
+
 /* Theme switches are instant: a running color transition would start from the old theme and blink. */
 [data-theme-switching],
 [data-theme-switching] *,