prime-ui-kit 0.9.2 → 0.9.3

package/src/components/tabs/examples/orientation.tsx

@@ -1,40 +1,94 @@
-/** Tabs over the panel and a side list of sections that stacks on top below 600px — `orientation`. */
-import { Tabs, Typography } from "prime-ui-kit";
+/** Account settings with a side list of sections: the active section reaches out of the panel, and below 600px the list moves above it — `orientation`. */
+import { Button, Icon, Input, Switch, Tabs, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const SECTIONS = [
-  { value: "profile", label: "Профиль", text: "Имя, должность и контакты сотрудника." },
-  { value: "notifications", label: "Уведомления", text: "Письма о заказах и еженедельная сводка." },
-  { value: "deletion", label: "Удаление", text: "Аккаунт и все данные будут удалены." },
-];
-
 export default function TabsOrientationExample() {
   return (
-    <>
-      {(["horizontal", "vertical"] as const).map((orientation) => (
-        <Tabs.Root
-          key={orientation}
-          orientation={orientation}
-          defaultValue="notifications"
-          className={styles.frame}
-        >
-          <Tabs.List aria-label="Настройки">
-            {SECTIONS.map((section) => (
-              <Tabs.Item key={section.value} value={section.value}>
-                {section.label}
-              </Tabs.Item>
-            ))}
-          </Tabs.List>
-          {SECTIONS.map((section) => (
-            <Tabs.Panel key={section.value} value={section.value}>
-              <Typography variant="body-m" tone="secondary">
-                {section.text}
-              </Typography>
-            </Tabs.Panel>
-          ))}
-        </Tabs.Root>
-      ))}
-    </>
+    <Tabs.Root orientation="vertical" defaultValue="notifications" className={styles.wide}>
+      <Tabs.List aria-label="Настройки аккаунта">
+        <Tabs.Item value="profile">
+          <Tabs.Icon>
+            <Icon name="object.user" />
+          </Tabs.Icon>
+          <Tabs.Label>Профиль</Tabs.Label>
+        </Tabs.Item>
+        <Tabs.Item value="notifications">
+          <Tabs.Icon>
+            <Icon name="object.bell" />
+          </Tabs.Icon>
+          <Tabs.Label>Уведомления</Tabs.Label>
+        </Tabs.Item>
+        <Tabs.Item value="security">
+          <Tabs.Icon>
+            <Icon name="object.key" />
+          </Tabs.Icon>
+          <Tabs.Label>Безопасность</Tabs.Label>
+        </Tabs.Item>
+        <Tabs.Separator />
+        <Tabs.Item value="deletion">
+          <Tabs.Icon>
+            <Icon name="action.delete" />
+          </Tabs.Icon>
+          <Tabs.Label>Удаление</Tabs.Label>
+        </Tabs.Item>
+      </Tabs.List>
+
+      <Tabs.Panel value="profile">
+        <div className={styles.form}>
+          <Input.Root label="Имя и фамилия">
+            <Input.Wrapper>
+              <Input.Field defaultValue="Анна Смирнова" autoComplete="name" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Input.Root label="Должность">
+            <Input.Wrapper>
+              <Input.Field defaultValue="Руководитель отдела продаж" />
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      </Tabs.Panel>
+
+      <Tabs.Panel value="notifications">
+        <div className={styles.form}>
+          <Switch.Root defaultChecked hint="Письмо, как только заказ оплачен или отменён">
+            <Switch.Label>Статусы заказов</Switch.Label>
+          </Switch.Root>
+          <Switch.Root defaultChecked hint="По понедельникам в 09:00">
+            <Switch.Label>Сводка за неделю</Switch.Label>
+          </Switch.Root>
+          <Switch.Root hint="Новые функции и вебинары">
+            <Switch.Label>Новости продукта</Switch.Label>
+          </Switch.Root>
+        </div>
+      </Tabs.Panel>
+
+      <Tabs.Panel value="security">
+        <div className={styles.form}>
+          <Input.Root label="Новый пароль" hint="Не короче 12 символов">
+            <Input.Wrapper>
+              <Input.Field type="password" autoComplete="new-password" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Switch.Root defaultChecked hint="Код из приложения при каждом входе">
+            <Switch.Label>Двухфакторная проверка</Switch.Label>
+          </Switch.Root>
+        </div>
+      </Tabs.Panel>
+
+      <Tabs.Panel value="deletion">
+        <div className={styles.form}>
+          <Typography variant="body-m" tone="secondary">
+            Аккаунт и все данные будут удалены через 30 дней. До этого срока удаление можно
+            отменить.
+          </Typography>
+          <div>
+            <Button.Root tone="danger" variant="soft">
+              Удалить аккаунт
+            </Button.Root>
+          </div>
+        </div>
+      </Tabs.Panel>
+    </Tabs.Root>
   );
 }

package/src/components/tooltip/COMPONENT.md

@@ -74,16 +74,18 @@ No DOM: clones the single child, composes its `ref`, appends the tooltip id to i
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "role" \| "onPointerEnter" \| "onPointerLeave">` | — | `className`, `style` and the other attributes of the chip. |
 
 ## Variants
-Tooltip has no `variant` or `tone`: it is always a flat inverse chip (`tooltip-bg`, `tooltip-text`) with an arrow and no shadow, so it reads the same on canvas, cards and floating layers. The arrow (`--prime-tooltip-arrow-width` × `--prime-tooltip-arrow-height`) always points at the trigger's centre, also after flipping, aligning or shifting, and never slides into the chip's rounded corner.
+Tooltip has no `variant` or `tone`: it is always a flat inverse chip (`tooltip-bg`, `tooltip-text`) — dark in the light theme, light in the dark one — with an arrow and no shadow, so it reads the same on every layer. The chip is a host of its own: it points the text and fill roles at `tooltip-muted` / `tooltip-fill`, so a Kbd or a secondary line inside reads on it. Content flows inline: a label and its key stay on one line, block children stack. The arrow (`--prime-tooltip-arrow-width` × `--prime-tooltip-arrow-height`) always points at the trigger's centre, also after flipping, aligning or shifting, and never slides into the chip's rounded corner.
 
 ### size (Content)
+A chip of tier T is as tall as a menu item of tier T; text, padding and radius step together (`--prime-tooltip-<tier>-*`).
+
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | caption 12/16, padding 4 × 8 | Next to xs controls | |
-| `s` | caption 12/16, padding 4 × 8 | Dense toolbars, s controls | |
-| `m` | caption 12/16, padding 4 × 8 | Most controls | yes |
-| `l` | body-s 13/20, padding 4 × 8 | l controls, longer sentences | |
-| `xl` | body-s 13/20, padding 8 × 12 | xl controls | |
+| `xs` | 12/16, padding 4 × 6, radius 4 — 24 tall | Next to xs controls | |
+| `s` | 12/16, padding 6 × 8, radius 6 — 28 tall | Dense toolbars, s controls | |
+| `m` | 13/20, padding 6 × 10, radius 6 — 32 tall | Most controls | yes |
+| `l` | 14/20, padding 8 × 12, radius 8 — 36 tall | l controls, longer sentences | |
+| `xl` | 16/24, padding 8 × 16, radius 8 — 40 tall | xl controls | |
 
 ### side (Content)
 | Value | Looks like | Use when | Default |

package/src/components/tooltip/examples/examples.module.css

@@ -7,8 +7,8 @@
   gap: var(--prime-space-1);
   padding: var(--prime-space-1);
   border-radius: var(--prime-radius-l);
-  background: var(--prime-color-card-bg);
-  box-shadow: var(--prime-card-shadow);
+  background: var(--prime-color-layer-nested);
+  box-shadow: var(--prime-shadow-raised);
 }
 
 /* disabled-trigger.tsx: a focusable wrapper around the disabled button, with the outer ring. */

package/src/layout/app-header/COMPONENT.md

@@ -134,7 +134,7 @@ AppHeader.Root               <header>, one sticky row as high as the Sidebar bra
 - Gaps: `--prime-space-3` between zones, `--prime-space-2` inside Start and Actions; `AppHeader.Separator` adds `--prime-space-2` on each side (16 in all) and is 20 high.
 - `AppHeader.Icon` is a 36 tile with the radius and fill of a soft neutral button m, so it lines up with the buttons on the bar.
 - On the panel surface with no divider or shadow (depth from fill); `z-index: --prime-z-sticky`.
-- Search: up to 288 wide, shrinks first; field tier m and the surface field fill. Controls inside are size `m`.
+- Search: up to 288 wide, shrinks first; field tier m and the fill of the panel layer it sits on. Controls inside are size `m`.
 
 ## Accessibility
 

package/src/layout/app-header/examples/examples.module.css

@@ -1,12 +1,12 @@
 /* Layout of the AppHeader scenarios: an app window and a phone-wide screen. Semantic tokens only. */
 
-/* The top of an app window: the content panel surface with the header on it. */
+/* The top of an app window: the content panel (the page) with the header on it. */
 .window {
   box-sizing: border-box;
   width: 100%;
   overflow: hidden;
   border-radius: var(--prime-card-radius);
-  background: var(--prime-color-bg-surface);
+  background: var(--prime-color-layer-current);
   box-shadow:
     0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
     var(--prime-shadow-raised);
@@ -18,7 +18,7 @@
   margin-inline: auto;
 }
 
-/* in-app-shell.tsx: a whole app window with the rail on the canvas. */
+/* in-app-shell.tsx: a whole app window with the rail on the page. */
 .stage {
   box-sizing: border-box;
   display: flex;
@@ -26,7 +26,7 @@
   height: calc(var(--prime-space-24) * 4);
   overflow: hidden;
   border-radius: var(--prime-card-radius);
-  background: var(--prime-color-bg-canvas);
+  background: var(--prime-color-layer-current);
   box-shadow:
     0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
     var(--prime-shadow-raised);

package/src/layout/app-shell/COMPONENT.md

@@ -3,11 +3,11 @@
 **Category:** page
 **Kind:** layout
 
-> The app frame: a navigation rail on the canvas and a content panel on the surface.
+> The app frame: a content panel that is the page itself and a navigation rail one layer above it.
 
 ## When to use
 - The root layout of an application: navigation column, an optional AppHeader, scrolling main column, a bottom bar for phone navigation.
-- Any page that needs the kit's responsive gutters and the surface context for cards and fields.
+- Any page that needs the kit's responsive gutters and the surface ladder for cards and fields.
 
 ## When not to use
 - The navigation itself → use [Sidebar](../sidebar/COMPONENT.md) inside `AppShell.Nav`, [BottomNav](../bottom-nav/COMPONENT.md) inside `AppShell.Footer`.
@@ -23,8 +23,8 @@ import { AppShell } from "prime-ui-kit";
 
 ## Anatomy
 ```
-AppShell.Root                grid: nav column | content panel (bg-surface)
-├─ AppShell.Nav              navigation column on the canvas (usually Sidebar.Root)
+AppShell.Root                grid: nav column | content panel (the page, layer 0)
+├─ AppShell.Nav              navigation column (usually Sidebar.Root, a surface one layer above the page)
 ├─ AppHeader.Root            sticky top bar of the panel (a separate component)
 ├─ AppShell.Main             <main>, scrolls, carries the gutters
 └─ AppShell.Footer           sticky bottom bar of the panel (usually BottomNav.Root)
@@ -37,7 +37,7 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### AppShell.Root
-`ref` → `HTMLDivElement`. Grid of the nav column (canvas) and the content panel (surface); every child that is not `AppShell.Nav` goes into the panel.
+`ref` → `HTMLDivElement`. Grid of the nav column (Sidebar, a surface one layer above the page) and the content panel (the page itself); every child that is not `AppShell.Nav` goes into the panel.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -96,7 +96,7 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 ### Structure
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| with `AppShell.Nav` | Two columns: canvas rail + surface panel | Apps with navigation | |
+| with `AppShell.Nav` | Two columns: a rail one layer above the page + the panel that is the page | Apps with navigation | |
 | without Nav | Panel takes the full width | Single-page tools, auth screens | |
 | with `AppHeader.Root` | Sticky bar at the top of the panel | Title or breadcrumbs, global search, actions, the mobile menu button | |
 | with `AppShell.Footer` | Sticky bar at the bottom of the panel, shown while it holds a visible bar | BottomNav on a phone | |
@@ -111,10 +111,10 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 | footer bar | panel width (container `prime-shell-footer` on Footer) | BottomNav inside leaves from 640px of panel width; the empty footer takes no room |
 
 ## Layout & spacing
-- Two full-height planes edge to edge: no inset, radius, shadow or border — the boundary is the fill change (canvas → surface).
+- Two full-height planes edge to edge: no inset, radius, shadow or border — the boundary is the fill change (the Sidebar rail is layer 1, the panel the page: white rail beside a gray page in light, a rail one step lighter than the near-black page in dark).
 - Gutters in Main: `--prime-layout-gutter-s` (16) → `-m` (24) from 640px → `-l` (32) from 1024px. Main top padding `--prime-space-6` (24) → `--prime-space-10` (40) from 1024px; bottom `--prime-space-16`.
 - Footer: no padding of its own (BottomNav keeps the bottom safe-area inset), sticky at the bottom, `z-index: --prime-z-sticky`.
-- The panel is a surface context: fields use the surface field fill, Cards inside become sunken tiles without shadow.
+- The panel is the page (layer 0 of the surface ladder, gray in light): fields on it take the page fill, a Card inside is layer 1 — white in light with the raised whisper — and cards in cards go deeper.
 
 ## Accessibility
 

package/src/layout/app-shell/examples/examples.module.css

@@ -7,8 +7,8 @@
   height: calc(var(--prime-space-24) * 5);
   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);
@@ -37,7 +37,7 @@
   margin-inline: auto;
   overflow: hidden;
   border-radius: var(--prime-card-radius);
-  background: var(--prime-color-bg-surface);
+  background: var(--prime-color-layer-current);
   box-shadow:
     0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
     var(--prime-shadow-raised);

package/src/layout/bottom-nav/COMPONENT.md

@@ -99,7 +99,7 @@ Without flags the bar is flat at the screen edge on the surface, with a faint to
 | disabled | `disabled` | `disabled` / `aria-disabled`, `data-disabled` |
 | hidden | inside `AppShell.Footer` 640px wide or more | `display: none` (container `prime-shell-footer`) |
 | floating / icon only | `floating` / `iconOnly` | `data-floating="true"` / `data-icon-only="true"` on the `<nav>` |
-| less transparency | `prefers-reduced-transparency: reduce` | a floating capsule turns opaque (`--prime-color-bg-raised`), no blur |
+| less transparency | `prefers-reduced-transparency: reduce` | a floating capsule turns opaque (`--prime-color-layer-floating-bg`), no blur |
 
 Motion: the color of the icon and the label changes over `fast`; in the floating capsule the selection capsule grows in from 92% and fades in (`fast`, enter easing), instant under reduced motion. No hover or press feedback: an item is either current or not.
 

package/src/layout/bottom-nav/examples/examples.module.css

@@ -10,7 +10,7 @@
   margin-inline: auto;
   overflow: hidden;
   border-radius: var(--prime-card-radius);
-  background: var(--prime-color-bg-surface);
+  background: var(--prime-color-layer-current);
   box-shadow:
     0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
     var(--prime-shadow-raised);

package/src/layout/sidebar/COMPONENT.md

@@ -243,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 |
@@ -311,9 +311,9 @@ 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. 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.
+- 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 (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
@@ -322,7 +322,7 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
   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

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] *,

package/src/styles/theme-dark.css

@@ -6,32 +6,21 @@
   --prime-color-accent-soft: var(--prime-ref-color-cobalt-950);
   --prime-color-accent-soft-hover: color-mix(in srgb, var(--prime-ref-color-cobalt-500) 28%, transparent);
   --prime-color-accent-text: var(--prime-ref-color-cobalt-400);
-  --prime-color-bg-canvas: var(--prime-ref-color-gray-950);
   --prime-color-bg-edge-shadow: rgba(0, 0, 0, 0.5);
   --prime-color-bg-glass: color-mix(in srgb, var(--prime-ref-color-gray-875) 56%, transparent);
   --prime-color-bg-glass-edge: rgba(255, 255, 255, 0.16);
   --prime-color-bg-inverse: var(--prime-ref-color-gray-100);
-  --prime-color-bg-raised: var(--prime-ref-color-gray-875);
   --prime-color-bg-scrim: rgba(0, 0, 0, 0.6);
-  --prime-color-bg-sunken: var(--prime-ref-color-gray-950);
-  --prime-color-bg-surface: var(--prime-ref-color-gray-900);
   --prime-color-border-default: var(--prime-ref-color-gray-750);
   --prime-color-border-faint: var(--prime-ref-color-gray-850);
   --prime-color-border-subtle: var(--prime-ref-color-gray-800);
-  --prime-color-control-selected: var(--prime-ref-color-gray-750);
   --prime-color-control-thumb: var(--prime-ref-color-gray-100);
   --prime-color-danger-border: var(--prime-ref-color-red-400);
   --prime-color-danger-hover: var(--prime-ref-color-red-500);
   --prime-color-danger-soft: color-mix(in srgb, var(--prime-ref-color-red-500) 16%, transparent);
   --prime-color-danger-text: var(--prime-ref-color-red-300);
-  --prime-color-field-bg: color-mix(in srgb, var(--prime-ref-color-gray-100) 6%, transparent);
   --prime-color-field-bg-disabled: color-mix(in srgb, var(--prime-ref-color-gray-100) 4%, transparent);
-  --prime-color-field-bg-focus: var(--prime-ref-color-gray-925);
-  --prime-color-field-bg-hover: color-mix(in srgb, var(--prime-ref-color-gray-100) 12%, transparent);
-  --prime-color-field-bg-surface: color-mix(in srgb, var(--prime-ref-color-gray-100) 6%, transparent);
   --prime-color-fill-faint: rgba(233, 235, 240, 0.02);
-  --prime-color-fill-muted: color-mix(in srgb, var(--prime-ref-color-gray-100) 7%, transparent);
-  --prime-color-fill-muted-hover: color-mix(in srgb, var(--prime-ref-color-gray-100) 10%, transparent);
   --prime-color-fill-strong: color-mix(in srgb, var(--prime-ref-color-gray-100) 16%, transparent);
   --prime-color-fill-strong-hover: color-mix(in srgb, var(--prime-ref-color-gray-100) 22%, transparent);
   --prime-color-fill-subtle: rgba(233, 235, 240, 0.05);
@@ -41,6 +30,38 @@
   --prime-color-info-fg: var(--prime-ref-color-gray-950);
   --prime-color-info-soft: color-mix(in srgb, var(--prime-ref-color-sky-500) 16%, transparent);
   --prime-color-info-text: var(--prime-ref-color-sky-300);
+  --prime-color-layer-0-bg: #0d0f13;
+  --prime-color-layer-0-fill: #14161a;
+  --prime-color-layer-0-fill-hover: #1a1c21;
+  --prime-color-layer-0-selected: #212428;
+  --prime-color-layer-1-bg: #14161a;
+  --prime-color-layer-1-fill: #1a1c21;
+  --prime-color-layer-1-fill-hover: #212428;
+  --prime-color-layer-1-selected: #292b2f;
+  --prime-color-layer-2-bg: #1a1c21;
+  --prime-color-layer-2-fill: #212428;
+  --prime-color-layer-2-fill-hover: #292b2f;
+  --prime-color-layer-2-selected: #303237;
+  --prime-color-layer-3-bg: #212428;
+  --prime-color-layer-3-fill: #292b2f;
+  --prime-color-layer-3-fill-hover: #303237;
+  --prime-color-layer-3-selected: #383a3f;
+  --prime-color-layer-4-bg: #292b2f;
+  --prime-color-layer-4-fill: #303237;
+  --prime-color-layer-4-fill-hover: #383a3f;
+  --prime-color-layer-4-selected: #3f4247;
+  --prime-color-layer-floating-bg: #1a1c21;
+  --prime-color-layer-floating-fill: #212428;
+  --prime-color-layer-floating-fill-hover: #292b2f;
+  --prime-color-layer-floating-selected: #303237;
+  --prime-color-layer-floating1-bg: #212328;
+  --prime-color-layer-floating1-fill: #282a2f;
+  --prime-color-layer-floating1-fill-hover: #303237;
+  --prime-color-layer-floating1-selected: #373a3e;
+  --prime-color-layer-floating2-bg: #282a2f;
+  --prime-color-layer-floating2-fill: #303237;
+  --prime-color-layer-floating2-fill-hover: #373a3e;
+  --prime-color-layer-floating2-selected: #3f4146;
   --prime-color-palette-blue-soft: color-mix(in srgb, var(--prime-ref-color-cobalt-500) 16%, transparent);
   --prime-color-palette-blue-solid: var(--prime-ref-color-cobalt-400);
   --prime-color-palette-blue-solid-fg: var(--prime-ref-color-gray-950);
@@ -90,8 +111,10 @@
   --prime-color-text-placeholder: var(--prime-ref-color-gray-400);
   --prime-color-text-primary: var(--prime-ref-color-gray-100);
   --prime-color-text-secondary: var(--prime-ref-color-gray-300);
-  --prime-color-tooltip-bg: var(--prime-ref-color-gray-750);
-  --prime-color-tooltip-text: var(--prime-ref-color-gray-100);
+  --prime-color-tooltip-bg: var(--prime-ref-color-gray-100);
+  --prime-color-tooltip-fill: rgba(17, 19, 24, 0.08);
+  --prime-color-tooltip-muted: var(--prime-ref-color-gray-600);
+  --prime-color-tooltip-text: var(--prime-ref-color-gray-925);
   --prime-color-warning-default: var(--prime-ref-color-orange-400);
   --prime-color-warning-fg: var(--prime-ref-color-gray-950);
   --prime-color-warning-soft: color-mix(in srgb, var(--prime-ref-color-orange-500) 16%, transparent);