prime-ui-kit 0.9.2 → 0.10.0

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/tag-select/COMPONENT.md

@@ -96,7 +96,7 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | collapsed / expanded | focus inside or the list open | `data-expanded="true"` on the control: every chip on up to three rows (then scroll with edge fades); the height animates |
 | open | focus, typing, arrows | `data-state="open"` on the control; list `data-state`, `data-side` |
 | overflow | more chips than fit at rest | a «+N» Badge button with `labels.more` and the hidden labels in `title` |
-| invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the input |
+| invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the input; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | `data-disabled="true"`, native `disabled` on the input |
 | option highlighted / selected / disabled | keyboard and pointer / value / option `disabled` | `data-highlighted`, `aria-selected` + checked indicator, `data-disabled` |
 
@@ -147,13 +147,13 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | [overview.tsx](examples/overview.tsx) | A labelled tag field: focus opens the list, typing filters it, picked tags become chips — `label`, `options`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier with two picked tags; chips sit one tier below the field — `size`. |
 | [states.tsx](examples/states.tsx) | A default field next to a disabled and an invalid one, with a disabled option in the list — `disabled`, `invalid`. |
-| [validation.tsx](examples/validation.tsx) | Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. |
+| [validation.tsx](examples/validation.tsx) | Live validation: removing the last region shakes the field and drops the error in, adding one clears it; required and optional markers and a hint — `required`, `optional`, `hint`, `error`. |
 | [creatable.tsx](examples/creatable.tsx) | A typed text that is not in the list becomes a new tag from the Create row or Enter — `creatable`, `onCreate`, `defaultColor`. |
 | [many-tags.tsx](examples/many-tags.tsx) | More tags than fit: at rest one row with «+N», focused every tag on up to three wrapped rows that scroll — `defaultValue`. |
 | [manage-tags.tsx](examples/manage-tags.tsx) | Users keep their own tag dictionary: the row «⋯» menu renames, recolors or deletes an option — `onOptionUpdate`, `onOptionDelete`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the value: a preset button replaces the tags and the count follows them — `value`, `onValueChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the list: a button opens it from code, Escape or an outside press closes it — `open`, `onOpenChange`. |
-| [in-form.tsx](examples/in-form.tsx) | A new task form: the required labels field is checked on submit and its error replaces the hint — `required`, `error`, `creatable`. |
+| [in-form.tsx](examples/in-form.tsx) | A new task form: the required labels field is checked on submit, its error shakes the field and leaves once a label is added, a calm note confirms the task — `required`, `error`, `creatable`. |
 
 ## Mistakes
 - `TagSelect.Root` → TagSelect is a single export: `<TagSelect …/>`.

package/src/components/tag-select/examples/examples.module.css

@@ -10,6 +10,7 @@
 
 .actions {
   display: flex;
+  align-items: center;
   justify-content: flex-end;
   gap: var(--prime-space-2);
 }

package/src/components/tag-select/examples/in-form.tsx

@@ -1,4 +1,4 @@
-/** A new task form: the required labels field is checked on submit and its error replaces the hint — `required`, `error`, `creatable`. */
+/** A new task form: the required labels field is checked on submit, its error shakes the field and leaves once a label is added, a calm note confirms the task — `required`, `error`, `creatable`. */
 import { Button, Input, TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -19,10 +19,12 @@ const PEOPLE: TagSelectOption[] = [
 export default function TagSelectInFormExample() {
   const [labels, setLabels] = React.useState<string[]>([]);
   const [error, setError] = React.useState<string>();
+  const [saved, setSaved] = React.useState(false);
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
     setError(labels.length ? undefined : "Добавьте хотя бы одну метку");
+    setSaved(labels.length > 0);
   };
 
   return (
@@ -45,13 +47,28 @@ export default function TagSelectInFormExample() {
         onValueChange={(next) => {
           setLabels(next);
           setError(undefined);
+          setSaved(false);
         }}
         creatable
         placeholder="Добавить метку"
       />
       <TagSelect label="Наблюдатели" optional options={PEOPLE} placeholder="Добавить человека" />
       <div className={styles.actions}>
-        <Button.Root variant="ghost" tone="neutral" type="reset">
+        {saved ? (
+          <Typography as="p" variant="body-s" tone="secondary">
+            Задача создана
+          </Typography>
+        ) : null}
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          type="reset"
+          onClick={() => {
+            setLabels([]);
+            setError(undefined);
+            setSaved(false);
+          }}
+        >
           Отмена
         </Button.Root>
         <Button.Root type="submit">Создать задачу</Button.Root>

package/src/components/tag-select/examples/validation.tsx

@@ -1,5 +1,6 @@
-/** Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. */
+/** Live validation: removing the last region shakes the field and drops the error in, adding one clears it; required and optional markers and a hint — `required`, `optional`, `hint`, `error`. */
 import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+import * as React from "react";
 
 const CITIES: TagSelectOption[] = [
   { value: "msk", label: "Москва", color: "blue" },
@@ -13,6 +14,8 @@ const PEOPLE: TagSelectOption[] = [
 ];
 
 export default function TagSelectValidationExample() {
+  const [regions, setRegions] = React.useState(["msk"]);
+
   return (
     <>
       <TagSelect
@@ -25,8 +28,10 @@ export default function TagSelectValidationExample() {
       <TagSelect
         label="Регионы"
         required
-        error="Добавьте хотя бы один регион"
+        error={regions.length ? undefined : "Добавьте хотя бы один регион"}
         options={CITIES}
+        value={regions}
+        onValueChange={setRegions}
         placeholder="Добавить регион"
       />
       <TagSelect label="Наблюдатели" optional options={PEOPLE} placeholder="Добавить человека" />

package/src/components/textarea/COMPONENT.md

@@ -100,7 +100,7 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 | hover | — | fill darkens (not when focused, disabled or read-only) |
 | focus | keyboard focus | focus fill and inset focus ring on the field box; clicking the box padding focuses the textarea |
 | no focus ring | `focusRing={false}` | `data-focus-ring="false"` on the field box |
-| invalid | `invalid` or non-empty `error` | `data-invalid="true"` on the outer wrapper and the field box, `aria-invalid="true"`, danger ring |
+| invalid | `invalid` or non-empty `error` | `data-invalid="true"` on the outer wrapper and the field box, `aria-invalid="true"`, danger ring; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | `data-disabled="true"` on the field box, disabled fill and text; label and hint dimmed |
 | read-only | `readOnly` | `data-readonly="true"` on the field box, no hover, default cursor |
 | reserved support row | `reserveSupportRow` | `data-reserve="true"` on the support row |
@@ -141,11 +141,11 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 | [overview.tsx](examples/overview.tsx) | A labelled multi-line field with a hint; the height follows the text — `label`, `hint`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier; text, padding, label and hint follow the tier — `size`. |
 | [states.tsx](examples/states.tsx) | A default field next to a read-only and a disabled one — `readOnly`, `disabled`. |
-| [validation.tsx](examples/validation.tsx) | Required and optional markers, a hint, an error and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. |
+| [validation.tsx](examples/validation.tsx) | Live validation: an error shakes the field as it arrives, drops in and leaves as soon as the text is fixed; required and optional markers, a hint and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. |
 | [auto-resize.tsx](examples/auto-resize.tsx) | A field that grows with its text next to a fixed one with a resize handle — `autoResize`, `rows`. |
 | [without-focus-ring.tsx](examples/without-focus-ring.tsx) | A single reply composer where the caret and the lighter fill show focus — `focusRing`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the text; the counter follows it and `maxLength` stops extra input — `value`, `onValueChange`, `Textarea.Counter`, `maxLength`. |
-| [in-form.tsx](examples/in-form.tsx) | Support request form: the description is checked on submit and its error does not shift the form — `required`, `error`, `reserveSupportRow`. |
+| [in-form.tsx](examples/in-form.tsx) | Support request form: the description is checked on submit, its error leaves as soon as the text is long enough and does not shift the form, a sent request turns the button green — `required`, `error`, `reserveSupportRow`. |
 
 ## Mistakes
 - `<Textarea.Root><textarea /></Textarea.Root>` → Textarea.Root renders the textarea itself; pass native props to the root.

package/src/components/textarea/examples/in-form.tsx

@@ -1,4 +1,4 @@
-/** Support request form: the description is checked on submit and its error does not shift the form — `required`, `error`, `reserveSupportRow`. */
+/** Support request form: the description is checked on submit, its error leaves as soon as the text is long enough and does not shift the form, a sent request turns the button green — `required`, `error`, `reserveSupportRow`. */
 import { Button, Input, Textarea, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -9,13 +9,16 @@ const MIN_LENGTH = 20;
 
 export default function TextareaInFormExample() {
   const [message, setMessage] = React.useState("");
-  const [error, setError] = React.useState<string>();
+  const [checked, setChecked] = React.useState(false);
+  const [sent, setSent] = React.useState(false);
+  const tooShort = message.trim().length < MIN_LENGTH;
+  // After the first submit the check is live: the error leaves as soon as the text is long enough.
+  const error = checked && tooShort ? "Опишите проблему хотя бы в 20 символах" : undefined;
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
-    setError(
-      message.trim().length < MIN_LENGTH ? "Опишите проблему хотя бы в 20 символах" : undefined,
-    );
+    setChecked(true);
+    setSent(!tooShort);
   };
 
   return (
@@ -44,7 +47,10 @@ export default function TextareaInFormExample() {
           error={error}
           value={message}
           maxLength={LIMIT}
-          onValueChange={setMessage}
+          onValueChange={(value) => {
+            setMessage(value);
+            setSent(false);
+          }}
           counter={<Textarea.Counter current={message.length} max={LIMIT} />}
         />
       </div>
@@ -53,11 +59,17 @@ export default function TextareaInFormExample() {
           variant="ghost"
           tone="neutral"
           type="reset"
-          onClick={() => setError(undefined)}
+          onClick={() => {
+            setMessage("");
+            setChecked(false);
+            setSent(false);
+          }}
         >
           Отменить
         </Button.Root>
-        <Button.Root type="submit">Отправить</Button.Root>
+        <Button.Root type="submit" tone={sent ? "success" : "accent"}>
+          {sent ? "Отправлено" : "Отправить"}
+        </Button.Root>
       </div>
     </form>
   );

package/src/components/textarea/examples/validation.tsx

@@ -1,9 +1,15 @@
-/** Required and optional markers, a hint, an error and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. */
+/** Live validation: an error shakes the field as it arrives, drops in and leaves as soon as the text is fixed; required and optional markers, a hint and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. */
 import { Button, Textarea } from "prime-ui-kit";
 import * as React from "react";
 
+const MIN_REASON = 20;
+
 export default function TextareaValidationExample() {
-  const [checked, setChecked] = React.useState(false);
+  const [reason, setReason] = React.useState("Нет");
+  const [comment, setComment] = React.useState("Оплата частями");
+  const [commentError, setCommentError] = React.useState<string>();
+
+  const send = () => setCommentError(/\d{3,}/.test(comment) ? undefined : "Укажите номер договора");
 
   return (
     <>
@@ -16,18 +22,28 @@ export default function TextareaValidationExample() {
       <Textarea.Root
         label="Причина отказа"
         required
-        defaultValue="Нет"
-        error="Опишите причину хотя бы в 20 символах"
+        value={reason}
+        onValueChange={setReason}
+        hint="Клиент получит её в письме"
+        error={
+          reason.trim().length < MIN_REASON
+            ? `Опишите причину хотя бы в ${MIN_REASON} символах`
+            : undefined
+        }
       />
       <Textarea.Root
         label="Комментарий для бухгалтерии"
         optional
         reserveSupportRow
-        defaultValue="Оплата частями"
-        error={checked ? "Укажите номер договора" : undefined}
+        value={comment}
+        onValueChange={(value) => {
+          setComment(value);
+          setCommentError(undefined);
+        }}
+        error={commentError}
       />
-      <Button.Root variant="soft" tone="neutral" onClick={() => setChecked((value) => !value)}>
-        {checked ? "Сбросить проверку" : "Проверить комментарий"}
+      <Button.Root variant="soft" tone="neutral" onClick={send}>
+        Отправить в бухгалтерию
       </Button.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