prime-ui-kit 0.15.0 → 0.16.0

package/dist/skill/reference/layout/sidebar/examples/persist.tsx

@@ -10,9 +10,7 @@ export default function SidebarPersistExample() {
         <Sidebar.Header>
           <Sidebar.Brand href="#home" description="Отдел продаж">
             <Sidebar.BrandLogo>
-              <span className={styles.logo}>
-                <Icon name="nav.layoutGrid" />
-              </span>
+              <Icon name="nav.layoutGrid" />
             </Sidebar.BrandLogo>
             Прайм CRM
           </Sidebar.Brand>

package/dist/skill/reference/layout/sidebar/examples/router.tsx

@@ -1,13 +1,13 @@
-/** Router links as the brand and the items: the router sets `aria-current` and the item shows as current; render it inside a router — `asChild`. */
-import { Icon, Sidebar } from "prime-ui-kit";
+/** Router links as the brand and the items: the router marks the current link and the item shows it as current; render it inside a router — `asChild`. */
+import { Icon, type IconName, Sidebar } from "prime-ui-kit";
 import { Link, NavLink } from "react-router-dom";
 
 import styles from "./examples.module.css";
 
-const LINKS = [
-  { to: "/app-shell", label: "AppShell" },
-  { to: "/page-content", label: "PageContent" },
-  { to: "/sidebar", label: "Sidebar" },
+const LINKS: { to: string; label: string; icon: IconName }[] = [
+  { to: "/", label: "Обзор", icon: "nav.home" },
+  { to: "/deals", label: "Сделки", icon: "object.funnel" },
+  { to: "/clients", label: "Клиенты", icon: "object.users" },
 ];
 
 export default function SidebarRouterExample() {
@@ -15,23 +15,22 @@ export default function SidebarRouterExample() {
     <div className={styles.stage}>
       <Sidebar.Root offCanvas="never">
         <Sidebar.Header>
-          <Sidebar.Brand asChild description="Документация">
+          <Sidebar.Brand asChild description="Отдел продаж">
             <Link to="/">
               <Sidebar.BrandLogo>
-                <span className={styles.logo}>
-                  <Icon name="object.book" />
-                </span>
+                <Icon name="nav.layoutGrid" />
               </Sidebar.BrandLogo>
-              Prime UI
+              Прайм CRM
             </Link>
           </Sidebar.Brand>
         </Sidebar.Header>
         <Sidebar.Content>
           {LINKS.map((link) => (
             <Sidebar.Item key={link.to} asChild>
-              <NavLink to={link.to}>
+              {/* `end`: the overview is current only on its own page, not under every route. */}
+              <NavLink to={link.to} end={link.to === "/"}>
                 <Sidebar.ItemIcon>
-                  <Icon name="nav.layoutGrid" />
+                  <Icon name={link.icon} />
                 </Sidebar.ItemIcon>
                 {link.label}
               </NavLink>

package/dist/skill/reference/layout/sidebar/examples/sizes.tsx

@@ -7,12 +7,9 @@ const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function SidebarSizesExample() {
   return (
-    <div className={styles.sizes}>
+    <>
       {SIZES.map((size) => (
-        <div key={size} className={styles.sizeColumn}>
-          <Typography as="span" variant="caption" tone="muted">
-            {size}
-          </Typography>
+        <div key={size}>
           <div className={`${styles.stage} ${styles.stageShort}`}>
             <Sidebar.Root size={size} offCanvas="never">
               <Sidebar.Content>
@@ -32,8 +29,11 @@ export default function SidebarSizesExample() {
               </Sidebar.Content>
             </Sidebar.Root>
           </div>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
         </div>
       ))}
-    </div>
+    </>
   );
 }

package/dist/skill/responsive.md

@@ -22,15 +22,16 @@ single function. Most of it is built into the components; this file says what th
 
 ## Breakpoints
 
-The kit has one set: **640 · 768 · 1024 · 1280**. Use them only in media queries of the app frame;
+The kit has one set: **640 · 768 · 1024 · 1280**. Use them only in media queries of the app frame and
+of an overlay's form (a panel that becomes a bottom sheet on a phone) — the kit's own scope;
 everything inside a page breaks by its container.
 
 | Width | Typical | What changes |
 |---|---|---|
 | < 640 | phone | one column; floating layers become bottom sheets; Modal is a bottom sheet; Drawer full width; `BottomNav` in `AppShell.Footer` |
-| 640–767 | small tablet | gutters 24; two-column grids by `auto-fill`; the Sidebar is still off-canvas, so BottomNav stays |
+| 640–767 | small tablet | gutters 24; intrinsic grids reach two columns; the Sidebar is still off-canvas, so BottomNav stays |
 | 768–1023 | tablet | Sidebar on-canvas (`offCanvas="auto"`) |
-| 1024–1279 | laptop | gutters 32; list + details side by side when the content asks for it |
+| 1024–1279 | laptop | gutters 32 |
 | ≥ 1280 | desktop | extra columns or a side panel; tables and dashboards use every pixel |
 
 - Write "below 640" as `@media (max-width: 639px)`, "from 640" as `@media (min-width: 640px)`.
@@ -41,6 +42,19 @@ everything inside a page breaks by its container.
 - Required minimum: `<meta name="viewport" content="width=device-width, initial-scale=1">`, no
   `user-scalable=no`, no horizontal page scroll at 320px.
 
+## Intrinsic grids
+
+A layout inside a page needs no breakpoint: it takes its columns from the room it has.
+
+- The tiles of a page (KPI cards, charts, panels) are one `PageContent.Grid` with a
+  `PageContent.Cell span` per tile: it folds by its own width (below 30rem every tile takes the row,
+  then small tiles pair up, from 64rem each its span).
+- A grid inside one block (thumbnails, short fields of one record) is the block's own
+  `grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--prime-layout-tile-min-width)), 1fr))`
+  — `auto-fill`, so a lone item keeps its column width instead of stretching across the row.
+- A main column with a side column: flex-wrap with a large `flex-grow` on the main one; the side one
+  drops below when the main one runs out of room.
+
 ## What the kit already does
 
 Use these as they are; never wrap them in your own breakpoints.
@@ -48,10 +62,10 @@ Use these as they are; never wrap them in your own breakpoints.
 | Need | Built in |
 |---|---|
 | app frame | AppShell gutters 16 → 24 → 32; `AppHeader` un-sticks on screens lower than 480px, respects safe areas and, below 36rem of its width, drops the title icon, the title and its line of data truncate |
-| app navigation | Sidebar: on-canvas from 768px, an off-canvas panel below (`offCanvas="auto"`) opened by `AppHeader.MenuButton`, which shows itself below 768px; `BottomNav` in `AppShell.Footer` for 2–6 app sections on phones — flat or a floating glass capsule (`floating`) with an optional round `BottomNav.Action`, icons with or without labels (`iconOnly`); the shell hides it by itself while the Sidebar rail is on screen (from 768px with `offCanvas="auto"`) |
-| page panel | `PageToolbar` — search and filter first, one row when wide, stacked rows when narrow (below) |
-| page header | `AppHeader`: the page's tools wrap under the title (`AppHeader.Tools`), the primary action takes its own row when the search would be squeezed; a document page's `PageContent.Header`: actions wrap under the title |
-| switchers | SegmentedControl and Tabs never wrap: they scroll inside themselves (hidden scrollbar, faded edges, a vertical wheel scrolls them sideways), the active item is scrolled into view, stretched items tend to equal width, the indicator moves only after a person's choice; Tabs collapse icons and descriptions first |
+| app navigation | Sidebar: on-canvas from 768px, an off-canvas panel below (`offCanvas="auto"`) opened by the menu button the AppHeader draws by itself while the Sidebar is off-canvas; `BottomNav` in `AppShell.Footer` for 2–6 app sections on phones — flat or a floating glass capsule (`floating`) with an optional round `BottomNav.Action`, icons with or without labels (`iconOnly`); the shell hides it by itself while the Sidebar rail is on screen (from 768px with `offCanvas="auto"`) |
+| page panel | `PageToolbar` — search and filter first, one row when wide, stacked rows when narrow, the primary action on its own row when the search would get less than 18rem beside it ([below](#page-panel--pagetoolbar)) |
+| page header | `AppHeader`: the page's tools wrap under the title (`AppHeader.Tools`); a document page's `PageContent.Header`: actions wrap under the title |
+| switchers | [Switchers](#switchers) never wrap or truncate: they scroll inside themselves |
 | tables | DataTable scrolls inside itself, edge shadows show hidden columns, `stickyFirstColumn`, `DataTable.ColumnsMenu` for a column chooser, the toolbar stacks below a 30rem table, sticky head off on short screens |
 | floating layers | Popover (opened from a Trigger), Dropdown, Select (and Datepicker, ColorPresets) never wider than the viewport − 16, 8 from the edges, flip when out of room; below 640 they open as a bottom sheet — scrim, grab handle, swipe down to close, page scroll locked; Tooltip and TagSelect stay anchored |
 | dialogs | Modal is a bottom sheet with a handle below 640 (swipe down closes it while `closeOnOutsideClick` allows); footer actions stack on phones and in a dialog narrower than 360px; `Sheet` is a bottom sheet for a short task at every width (centred at 560 on a tablet or desktop) and closes with a swipe down from its handle or header; a Drawer has no swipe — buttons, Escape and the scrim close it |
@@ -66,34 +80,18 @@ Use these as they are; never wrap them in your own breakpoints.
 
 ## Page panel — `PageToolbar`
 
-One strip at the top of the page holds up to five slots, each in a fixed place. The order is a rule:
-search and filter first, then the sections, the view and the primary action last; the active filters
-always sit right under the search and filter. Every row is 12 from the next; a slot alone in its row
-stretches to the full width. Write the slots in JSX in that order — it is the Tab order.
+One strip at the top of the page — on an app page, the page's tools row in `AppHeader.Tools` — holds
+up to five slots. It renders them in one fixed order whatever the JSX order (that is also the Tab
+order) and lays them out from its own width; how each slot moves at every width is in
+[PageToolbar COMPONENT.md → Layout by width](reference/components/page-toolbar/COMPONENT.md#layout-by-width).
 
-| Slot | Holds | Place |
-|---|---|---|
-| `PageToolbar.Tools` | search + filter button: `SmartFilter.Toolbar` | first, the stretchy item of the top row |
-| `PageToolbar.Sections` | sections of the page: a `fullWidth` SegmentedControl with counts | after the Tools when wide; its own row under the chips when narrow |
-| `PageToolbar.View` | period, table / cards, columns | by content when wide; its own row when narrow |
-| `PageToolbar.Actions` | the primary action («Создать», «Сохранить 3 изменения») | top row, at the end, always |
-| `PageToolbar.Chips` | active filters: `SmartFilter.Chips` | right under the search and filter, only while there are chips |
-
-```text
-Wide (toolbar ≥ 56rem) — one row, chips under the search:
-[ Search ————————— ][ Filter ][ Sections ][ Period ][ + Create ]
-[ Город: Москва × ][ + Добавить фильтр ]
-
-Narrow — rows, every one 12 from the next:
-[ Search ———————————— ][ Filter ]   [ + ]
-[ Город: Москва × ][ + Добавить фильтр ]
-[ Section 1 ][ Section 2 ][ Section 3 ] —— stretch ——
-[ ⏱ 7 дней ———————————————————————————— ⌄ ]
-
-Narrow, no search — the sections take the first row:
-[ Overview ][ Activity ][ Resources ]
-[ ⏱ 24 часа ———————————————————————————————— ⌄ ]
-```
+| Slot | Holds |
+|---|---|
+| `PageToolbar.Tools` | search + filter button: `SmartFilter.Toolbar` |
+| `PageToolbar.Sections` | sections of the page: a `fullWidth` SegmentedControl with counts |
+| `PageToolbar.View` | period, table / cards, columns |
+| `PageToolbar.Actions` | the primary action («Создать», «Сохранить 3 изменения») |
+| `PageToolbar.Chips` | active filters: `SmartFilter.Chips` |
 
 ```tsx
 import {
@@ -168,17 +166,14 @@ export function OrdersPanel() {
 }
 ```
 
-- Write the slots in the reading order of the wide layout; the toolbar reorders them visually.
 - One tier for the whole panel (default `m`): never `size` on one control inside — wrapped rows must
-  stay level. A denser page wraps the toolbar in `<ControlSizeProvider value="s">` and gives
-  `SmartFilter.Root` and `Select.Root` `size="s"` too — they do not read the host tier.
-- The primary action never leaves the top row. On a phone it may become icon-only with `aria-label`;
-  it never disappears.
+  stay level. A denser page wraps the toolbar in `<ControlSizeProvider value="s">`; every kit control
+  inside takes that tier.
+- The primary action is always there: on a phone it may take its own row or become icon-only with
+  `aria-label`; it never disappears.
 - Section totals go into `SegmentedControl.Count`, not into stat cards above the table.
 - A long form saves through the panel's action with a count («Сохранить 3 изменения»), never a sticky
   bar at the bottom of a phone screen.
-- The search first, the filter button after it at its own width (`SmartFilter.Toolbar` lays them out);
-  chips under the panel, one tier smaller, wrapping, with «Сбросить все».
 - Do not duplicate search: if the panel has one, the list below filters by it.
 
 ## Switchers
@@ -187,9 +182,14 @@ export function OrdersPanel() {
   narrow (a `fullWidth` SegmentedControl inside `PageToolbar.Sections` — the toolbar decides).
 - Sections of a page → SegmentedControl in `PageToolbar.Sections`; panels inside a card or a section →
   Tabs (the folder look belongs to its panel).
-- Items that do not fit scroll inside the switcher — never wrap to a second line, never truncate. The
-  switcher is a sideways `ScrollContainer`: its hidden edges fade, a vertical mouse wheel scrolls it
-  sideways, touch pans it.
+- Every switcher — Tabs, SegmentedControl, a horizontal ButtonGroup and BottomNav — scrolls inside
+  itself when its items do not fit: never a second line, never a truncated item. Its hidden edges
+  fade, a vertical mouse wheel scrolls it sideways, touch pans it, the current item is scrolled into
+  view, and the indicator moves only after a person's choice. A SegmentedControl whose items all have
+  icons collapses to icons (each named by its tooltip) before it scrolls.
+- Your duty as its host: give the switcher a bounded width. A flex or grid child that holds one sets
+  `min-width: 0`, otherwise the switcher grows the row instead of scrolling
+  ([foundation §9](reference/foundation.md#9-layout-and-responsiveness)).
 - A long page split into sections (settings, dashboard): the switcher scrolls to the section and marks
   the current one.
 
@@ -208,11 +208,8 @@ export function OrdersPanel() {
 `toolbar`; the key column `hideable: false`); `stickyFirstColumn` for the name. On phones a table / cards switch in `PageToolbar.View` is fine — silently dropping columns
 by breakpoint is not. Never ask to rotate the phone.
 
-**Card grids.** The tiles of a page are `PageContent.Grid` + `PageContent.Cell span`: it folds by its own
-width (below 30rem every tile takes the row, then small tiles pair up, from 64rem each its span),
-not by the window. Tiles of a row share one height; a card with a list shows 6–8 rows and scrolls inside
-(`ScrollContainer`). A grid inside one block (thumbnails, fields) is the block's own
-`repeat(auto-fill, minmax(min(100%, …), 1fr))`.
+**Card grids.** [Intrinsic grids](#intrinsic-grids), never a breakpoint. Tiles of a row share one
+height; a card with a list shows 6–8 rows and scrolls inside (`ScrollContainer`).
 
 **Forms.** One column on phones. Pairs («от / до», two buttons) wrap with
 `flex: 1 1 calc(var(--prime-space-24) * 2)` instead of shrinking. Labels above fields (the kit's
@@ -232,7 +229,7 @@ images with `srcset` + `sizes` (Thumbnail and Avatar already reserve their box).
 | minimum touch target (WCAG 2.5.8 AA) | 24 × 24px or a free 24px circle |
 | recommended target for primary actions and `(pointer: coarse)` | 44 × 44px |
 | reflow without horizontal scroll (WCAG 1.4.10) | 320px wide = 1280px at 400% zoom |
-| text contrast | 4.5:1; large (≥ 24px) 3:1 |
+| text contrast | 4.5:1; large text (≥ 24px, or ≥ 18.66px bold) 3:1 |
 
 - Nothing important only on hover: whatever hover shows is reachable by focus and visible (or a tap
   away) under `(hover: none)`. Your own hover styles go inside `@media (hover: hover)`.
@@ -260,7 +257,7 @@ Target CLS ≤ 0.1: nothing moves while loading or when a filter changes.
 Drag the window through 320, 390, 768, 1024, 1280 and 1920px — continuously, not only at these points.
 
 - [ ] No horizontal page scroll at any width (tables and switchers scroll inside themselves).
-- [ ] The primary action is in the top row of the panel at every width.
+- [ ] The primary action is on screen at every width — never hidden ([the page panel](#page-panel--pagetoolbar)).
 - [ ] Every item alone in its row stretches; items of stretched switchers are equal.
 - [ ] All controls in a row share one height; no «staircase» after a wrap.
 - [ ] Text never overlaps and is cut only at its own block's edge; cut text has a tooltip or `title`.

package/dist/skill/ux.md

@@ -27,7 +27,7 @@ adds text that explains what the layout failed to show.
 |---|---|---|
 | One record, read | label · value pairs | `DescriptionList` |
 | One record, edited | a form: fields 20 apart, groups 32 apart | `Fieldset`, fields |
-| One record of 2–4 short fields in a form | one row of fields | an `auto-fit` grid |
+| One record of 2–4 short fields in a form | one row of fields | an [intrinsic grid](responsive.md#intrinsic-grids) |
 | Records of one shape a person adds, edits, removes | one row per record, the headings once above | `FieldList` |
 | Records of one shape a person reads, sorts, filters | a table | `DataTable` |
 | One value in several units or currencies (a deposit in ₽, $, ฿) | the fields side by side in one row under one heading, the unit in each field | `Input.InlineAffix` |
@@ -35,10 +35,13 @@ adds text that explains what the layout failed to show.
 | Small attributes of a record (an icon, a color, a flag) | compact controls in the record's row, not fields of their own | icon-only `Select`, `ColorPresets`, `Checkbox` |
 | Short texts in an order the person sets | one column, a handle per row | `FieldList` `reorderable` |
 | Settings that most people never touch | behind a disclosure, after the common ones | `Accordion`, a «Дополнительно» section |
-| A choice of 2–5 options | all visible | `Radio.Group`, `SegmentedControl` |
-| A choice of 6+ options | a list that opens | `Select` |
+| One of a few options, sent with a form | all visible | `Radio.Group` |
+| One of a few modes of what the screen shows | all visible | `SegmentedControl` |
+| One of many options | a list that opens | `Select` |
 | Many values picked from options | tags | `TagSelect` |
 
+How many options count as «a few» and the other selection cases: [choosing.md](choosing.md#2-inside-a-category).
+
 One record is one row or one block, never half a record per line. If a record does not fit one
 row, it is not a row: open it in a `Drawer`.
 
@@ -67,8 +70,9 @@ The kit's UI language is Russian; these are the rules of its copy.
 
 - **Buttons say the verb and the object:** «Выставить счёт», «Добавить позицию», «Удалить проект».
   Never «ОК», «Да», «Подтвердить», «Отправить» without an object when the object is not obvious.
-- **A confirm names the thing and the loss:** «Удалить проект «Север»? Задачи и файлы удалятся
-  без возможности восстановления.» — not «Вы уверены?».
+- **A confirm names the thing and the consequence:** «Удалить проект «Север»? Задачи и файлы
+  удалятся без возможности восстановления.», «Выставить счёт на 48 000 ₽ ООО «Север»? Счёт уйдёт
+  клиенту на почту.» — not «Вы уверены?».
 - **An error says how to fix it:** «Формат: +7 912 404-18-20», «Не больше 2 000 символов» — not
   «Неверное значение», «Ошибка».
 - **An empty state says what to do next** and offers it: «Счетов пока нет» + «Выставить счёт». A
@@ -91,17 +95,24 @@ Pick the lightest step that keeps the person safe ([choosing.md](choosing.md) ha
 |---|---|
 | Reversible, frequent (remove a row, archive, move) | do it at once, «Отменить» in a `Notification` (`action`, commit in `onDismiss`) |
 | One standalone action that is easy to redo by hand | `Button.Root holdToConfirm` |
-| Irreversible loss of work, or a weighty outward action (send an invoice) | `ConfirmDialog` that names the thing and the loss |
+| Irreversible loss of work, or an outward action that cannot be called back once it leaves the product (an invoice or a message sent to a client, a payment) | `ConfirmDialog` that names the thing and the consequence |
 | Bulk destructive | `ConfirmDialog` that names the count («Удалить 12 счетов?») |
 | Leaving a form with changes | `Modal.Guard` / `Drawer.Guard dirty` |
 
 A confirm on every action trains people to click through it; the one that mattered is then missed.
+Which button starts each step and how the confirm behaves:
+[api-contract.md](api-contract.md#destructive-actions).
 
 ## 6. Nothing to guess
 
 - **A disabled control says why** when the reason is not on screen: a `hint` under the field, a
-  line beside the button («Не больше 3», as `FieldList` does at `max`), a `Tooltip` on a wrapper.
-  An action a person may never take (no permission) is hidden, not disabled.
+  line beside the button («Не больше 3», as `FieldList` does at `max`), or the disabled control
+  itself in `Tooltip.Trigger`. An action a person may never take (no permission) is hidden, not
+  disabled.
+- **The screen answers the latest question.** A request a value starts (a search, a filter, a page,
+  a period) is cancelled when the value changes again — abort it (`AbortController`) or drop its
+  answer — so a slow answer never replaces a newer one. A simulated request (a `setTimeout` standing
+  in for the server) is cancelled the same way, in the effect's cleanup.
 - **The state of a screen is in the URL:** the tab, the filters, the search, the page, the open
   record. A link copied from the address bar opens the same view; Back undoes the last navigation.
 - **Visible status for every action** (the kit does it when you use it): `loading` on the button,
@@ -137,7 +148,8 @@ A confirm on every action trains people to click through it; the one that matter
 
 Code that passes every check can still read badly. Open the screen in a browser and look:
 
-- **Both themes**, **1280 px and 375 px** wide, and the narrow container of every panel.
+- **Both themes**, every width of [the responsive checklist](responsive.md#checklist-before-handing-a-screen-over),
+  and the narrow container of every panel.
 - **Count:** labels on a form of rows (§3), primary buttons per area (one), sizes per row (one).
 - **Read every text aloud:** a word that repeats its neighbour, a hint that explains the layout, a
   button without an object — remove or rewrite it.

package/dist/theme/applyTheme.d.ts

@@ -1,14 +1,15 @@
 export type ThemeScheme = "light" | "dark";
-/** Attribute that turns transitions off while a theme switch is painted (see globals.css). */
+/** Attribute that sets every motion clock to 0 while a theme switch is painted (see globals.css). */
 export declare const THEME_SWITCHING_ATTRIBUTE = "data-theme-switching";
 /**
- * Freezes transitions on `element` and its subtree for the frame in which the theme changes.
- * Without it every element with a color transition would interpolate from the old theme's
- * colors and visibly blink. Call it right before the theme attribute changes.
+ * Paints a theme change on `element` and its subtree with no transition: every motion clock is 0
+ * while `change` runs and the styles are flushed, then the clocks come back in the same task, so
+ * nothing interpolates from the old theme's colors. `change` sets the theme attribute; without it,
+ * call this right after the attribute changed (before the browser paints).
  */
-export declare function suspendTransitions(element: HTMLElement): void;
+export declare function suspendTransitions(element: HTMLElement, change?: () => void): void;
 /**
  * Switches the theme instantly: sets `data-theme` on `element` (default `<html>`) with transitions
- * suspended for that frame. Use it instead of setting the attribute by hand.
+ * suspended. Use it instead of setting the attribute by hand.
  */
 export declare function applyTheme(scheme: ThemeScheme, element?: HTMLElement): void;

package/dist/tokens/hues.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Palette hues (`color` props of Badge, Avatar, Tag…) and the primitive ramp each one is drawn
+ * from. One list for both themes: `semantic.ts` and `themes/dark.ts` build their palette from it.
+ */
+export declare const hues: readonly ["blue", "green", "orange", "red", "yellow", "purple", "sky", "pink", "teal"];
+export type Hue = (typeof hues)[number];
+/** Hue → primitive ramp (`color.<ramp>.<step>`): blue is the brand cobalt. */
+export declare const hueRef: Record<Hue, string>;

package/dist/tokens/layers.d.ts

@@ -1,8 +1,4 @@
-/** ΔL in OKLab between neighbouring layers. */
-export declare const LAYER_STEP = 0.03;
-/** Layers 0…4: the page and four nested surfaces. */
-export declare const LAYER_DEPTH = 4;
-export type LayerTheme = {
+type LayerTheme = {
     /** The page color (layer 0). */
     page: string;
     /** Lightness window: no color goes outside it. */
@@ -13,13 +9,7 @@ export type LayerTheme = {
 };
 export declare const LIGHT_LAYERS: LayerTheme;
 export declare const DARK_LAYERS: LayerTheme;
-export declare const lightnessOf: (hex: string) => number;
-/**
- * `steps` steps from L towards `dir`. Reflects when less than half a step of room is left (unless
- * `reflect` is off), snaps to the edge when less than half a step would remain after the move.
- */
-export declare function move(theme: LayerTheme, L: number, dir: 1 | -1, steps?: number, reflect?: boolean): number;
-export type LayerColors = {
+type LayerColors = {
     /** The layer itself. */
     bg: string;
     /** Fields, chips, segmented tracks, neutral buttons on this layer. */
@@ -29,9 +19,6 @@ export type LayerColors = {
     /** The selected segment (thumb) on a track of this layer. */
     selected: string;
 };
-/** Layers 0…LAYER_DEPTH of a theme, each one step from its parent. */
-export declare function layerLadder(theme: LayerTheme): LayerColors[];
-/** Floating layers (popovers, menus, modals, drawers) sit one step above a card and never reflect. */
-export declare function floatingLayer(theme: LayerTheme): LayerColors;
 /** Token tree for `color.layer`: `0`…`4` plus `floating` and the two layers nested in it. */
 export declare function layerTokens(theme: LayerTheme): Record<string, LayerColors>;
+export {};

package/dist/tokens/offGrid.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The deliberate exceptions to the 4px grid (foundation §1 rule 2), each with its reason: the one
+ * source of the list. `bun run tokens:build` fails on a length named here that lands on the grid
+ * or on one off the grid missing from here, and writes the list into foundation §1 rule 2;
+ * `src/styles/tokens.test.ts` allows exactly the lengths foundation lists.
+ */
+export declare const OFF_GRID: Record<string, string>;

package/dist/tokens/primitives.d.ts

@@ -6,9 +6,10 @@
 export declare const primitiveTokens: {
     readonly color: {
         readonly white: "#ffffff";
-        /** Graphite: cool neutral, slight blue bias. 0–100 light surfaces, 750–950 dark surfaces. */
+        /** The ink of the dark theme's scrim, washes and shadows. */
+        readonly black: "#000000";
+        /** Graphite: cool neutral, slight blue bias. White and 50–100 light surfaces, 750–950 dark. */
         readonly gray: {
-            readonly 0: "#ffffff";
             readonly 50: "#f3f4f6";
             readonly 75: "#eef0f3";
             readonly 100: "#e8eaee";
@@ -97,8 +98,9 @@ export declare const primitiveTokens: {
         /**
          * Categorical chart hues: not ramps but one set, validated together (dataviz checks — OKLCH
          * lightness band, chroma floor, CVD and normal-vision separation of neighbours in the
-         * `color.chart` order, ≥ 3:1 on the layer grounds). Light steps for gray.0–50 grounds, dark steps
-         * for gray.950–850. Blue is cobalt (600 light, 500 dark). Change one only by re-running the checks.
+         * `color.chart` order, ≥ 3:1 on every layer ground — `src/theme/chartColors.test.ts` keeps the
+         * contrast). Light steps for the light ladder, dark steps for the dark one. Blue is cobalt (600
+         * light, 500 dark). Change one only by re-running the checks.
          */
         readonly chart: {
             readonly light: {
@@ -115,7 +117,8 @@ export declare const primitiveTokens: {
                 readonly teal: "#199e70";
                 readonly yellow: "#c98500";
                 readonly pink: "#d55181";
-                readonly green: "#008300";
+                /** A step lighter than light's green: 3:1 holds up to the deepest layer (4). */
+                readonly green: "#008a00";
                 readonly purple: "#9085e9";
                 readonly red: "#e66767";
             };
@@ -159,8 +162,9 @@ export declare const primitiveTokens: {
     };
     readonly font: {
         readonly family: {
-            readonly sans: "\"Golos Text\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
-            readonly mono: "\"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
+            /** `… Fallback`: the metric-matched local faces of the opt-in `fonts.css`. */
+            readonly sans: "\"Golos Text\", \"Golos Text Fallback\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
+            readonly mono: "\"JetBrains Mono\", \"JetBrains Mono Fallback\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
         };
         /** Modular scale, ~1.2 in the body range, ~1.25 for headings. */
         readonly size: {
@@ -212,12 +216,15 @@ export declare const primitiveTokens: {
         readonly 32: "2rem";
     };
     readonly duration: {
+        readonly 0: "0ms";
         readonly 80: "80ms";
         readonly 150: "150ms";
         readonly 230: "230ms";
         readonly 300: "300ms";
         readonly 380: "380ms";
         readonly 570: "570ms";
+        readonly 1200: "1200ms";
+        readonly never: "600000s";
     };
     readonly easing: {
         /**
@@ -235,8 +242,16 @@ export declare const primitiveTokens: {
      * Stacking order. Every overlay (modal, drawer, popover, menu, listbox, tooltip) portals to
      * `<body>` when it opens and shares one level: the DOM order is the open order, so a layer opened
      * later — a Select inside a Modal, a Tooltip inside a Popover — is on top without its own number.
+     * `below`, `0`…`5` order the parts stacked inside one component (a mark over a picture).
      */
     readonly zIndex: {
+        readonly below: "-1";
+        readonly 0: "0";
+        readonly 1: "1";
+        readonly 2: "2";
+        readonly 3: "3";
+        readonly 4: "4";
+        readonly 5: "5";
         readonly sticky: "100";
         readonly overlay: "1000";
         readonly toast: "10000";