@usememos/ui 26.11.9 → 26.11.11

package/llms-full.txt

@@ -19,7 +19,7 @@ It is not a general-purpose UI library for outside developers. Components are ge
 | --- | --- |
 | [Principles and voice](principles.md) | The taste in six rules, and how interface text is written |
 | [Color](color.md) | Color roles, every color token in Light and Dark, and how themes are chosen |
-| [Depth](depth.md) | The tactile model: recessed, key, raised, popup and flat; shadow tokens |
+| [Depth](depth.md) | Flat surface roles, borders and focus without shadows or outlines |
 | [Typography](typography.md) | The system font, the type scale and text rules |
 | [Size, spacing and layout](layout.md) | Control sizes, the 4px scale, radius, layout widths, breakpoints and layers |
 | [Motion](motion.md) | Press, settle and fade timing, and reduced motion |
@@ -52,7 +52,7 @@ It is not a general-purpose UI library for outside developers. Components are ge
 
 1. **Content first.** The interface stays gray, so people's words, tags and images are the color on the page.
 2. **Ink is the emphasis.** The primary action, a checked box and a switch that is on use `primary` (near-black in Light, near-white in Dark). There is no brand hue in controls.
-3. **Depth means behavior.** Recessed parts hold a state (wells, tracks). Raised parts can be pressed (buttons, keys, knobs). Flat parts are content, including text fields. Never add depth for decoration. See [Depth](depth.md).
+3. **Flat surfaces, clear states.** Fills show controls and state; borders separate surfaces. No shadows, sheen, focus rings or visible outlines. Content stays unboxed. See [Surfaces and boundaries](depth.md).
 4. **Calm by default.** Hierarchy comes from text color, lightness steps and spacing, not from weight, size or extra color. Few sizes and two weights: see [Typography](typography.md).
 5. **Dense, not cramped.** Controls are 32px tall by default, and every gap comes from the 4px scale. See [Size, spacing and layout](layout.md).
 6. **One system, many products.** Components are generic. A product's screens are built from them and from the [patterns](patterns.md); nothing in the package knows what a note or a memo is.
@@ -87,33 +87,34 @@ Memos UI is ink on paper: pure-gray neutrals, `primary` ink for emphasis, one qu
 | Role | Tokens | Used for |
 | --- | --- | --- |
 | Surfaces | `canvas`, `surface`, `overlay` | The page; then inputs, menus, dialogs and toasts one step up. `overlay` dims the page behind dialogs |
-| Wells | `well`, `edge` | Switch, tab, checkbox and radio wells, pressed toggles, inline code. `edge` is the 1px border of wells and inputs |
+| Wells | `well` | Switch tracks, segmented groups, unchecked boxes and radios, pressed toggles, inline code |
 | Hover | `hover` | Rows, ghost buttons, the highlighted menu row. About 4% ink over surface |
-| Keys | `key`, `key-hover`, `key-sheen` | Neutral buttons, select triggers, the selected tab, switch knobs, kbd |
-| Text | `ink`, `ink-muted` | Primary and secondary text. Both pass 4.5:1 on every surface, well and key in both themes |
+| Keys | `key`, `key-hover` | Neutral buttons, select triggers, the selected tab, switch knobs, kbd |
+| Text | `text`, `text-secondary`, `text-disabled` | Primary, secondary and disabled text. Each keeps 4.5:1 on the backgrounds named in the token table below |
 | Emphasis | `primary`, `primary-hover`, `on-primary` | Primary button, checked checkbox and radio, switch when on, tooltip |
-| Meta | `accent`, `selection`, `focus`, `focus-edge` | Links and text selection (`accent`); the keyboard focus ring and the focused field edge (`focus`, `focus-edge`, both ink). Never a fill |
+| Meta | `accent`, `selection`, `focus`, `focus-edge` | Links and text selection (`accent`); the keyboard focus edge and the focused field edge (`focus`, `focus-edge`, both ink). Never a fill |
 | Status | `success`, `warning`, `danger` and their `-soft` pairs; `danger-key`, `on-danger` | Toasts, badges, field errors, danger buttons |
-| Lines | `line` | Separators, table rules, menu dividers |
+| Lines | `edge`, `control-edge`, `line` | Quiet borders on popups, badges, selects and switches; stronger boundaries on fields, buttons, checkboxes and radios; separators and table rules |
 
 ## Rules
 
 - Neutrals are pure gray, never tinted.
 - `accent` is a quiet blue used only for links and selection. If a screen has blue on it at rest, apart from links, something is wrong.
-- Focus is ink, not blue. A focused field darkens its own edge to `focus-edge`; a control reached by keyboard gets a 2px `focus` ring 1px outside its edge. See [States](states.md).
+- Focus is ink, not blue. A focused field darkens its own edge to `focus-edge`; a control reached by keyboard thickens its existing border to 2px `focus`. On primary and checked fills, the border uses `on-primary`; danger buttons use `on-danger`. See [States](states.md).
 - Status colors appear only when there is a status. Red is for destructive actions and errors, never for emphasis.
 - `danger` is tuned for text. `danger-key` is the danger button's fill; it is darker in Dark so the button is not the loudest thing on screen.
 - Always pair a status color with a word or an icon.
-- A color the user chooses, such as a tag's, is their content, not a role. It appears only as a tint behind `ink` text (Badge's `color`), never as text or as a fill under light text, because the package can't know its contrast.
+- A color the user chooses, such as a tag's, is their content, not a role. It appears only as a tint behind the `text` color (Badge's `color`), never as text or as a fill under light text, because the package can't know its contrast.
 - Use tokens through their CSS variables. Every token is a custom property with the `--mu-` prefix: the `well` token is `var(--mu-well)`. The prefix keeps the tokens apart from an app's own variables and from Tailwind's. Never copy raw values into component or product code.
 
 ## Themes
 
 There are two themes: **Light** (the default) and **Dark**.
 
-- Each theme sets every color token and every shadow token to an explicit value. Nothing is derived at runtime. The package's tests check the values against the tables on this page and in [Depth](depth.md), and check the contrast promised here.
-- Dark keeps the same depth model. Wells go darker than `canvas`, keys go lighter, `key-sheen` drops to 8%, and `primary` flips to near-white with a dark `on-primary`.
-- Non-text contrast: `edge` is about 1.5:1 in Light and Dark. That is the soft border people expect from a calm interface, and it is below WCAG's 3:1 for control boundaries. An app that needs 3:1 boundaries defines its own [app theme](#app-themes) with a darker `edge` and outlined keys.
+- `text`, `text-secondary` and `text-disabled` name content roles for text and icons, not fixed colors. App themes can set each one; they are not derived from `primary`.
+- Each theme sets every color token explicitly. The package's tests check the values against the table on this page and check the contrast promised here.
+- Dark keeps the same flat surface roles. Wells and keys are distinct gray fills, and `primary` flips to near-white with a dark `on-primary`.
+- Fields, neutral buttons, checkboxes and radios use `control-edge`, at least 3:1 against `canvas` and `surface` in both themes. Selects and switches use the quieter `edge` at rest. Segmented groups and their selected keys use fills without visible borders. Focus remains a strong edge; `line` separates content.
 
 ### Choosing a theme
 
@@ -125,8 +126,7 @@ The package does not read `prefers-color-scheme` itself. The app does, so that a
 
 An app sets only these tokens:
 
-- the 27 color tokens in the [table below](#color-tokens),
-- the five shadow tokens in [Depth](depth.md#shadow-tokens),
+- the 28 color tokens in the [table below](#color-tokens),
 - the three font tokens in [Typography](typography.md#fonts): `font-sans`, `font-display` and `font-mono`.
 
 Every other token (space, radius, sizes, layout widths, layers, motion) and every `mu-*` class rule is internal. Read those tokens in app CSS (`var(--mu-space-4)`), but don't override them, even though the cascade layer lets an app rule win: the products would drift apart, and the package's tests and screenshots cover only its own values. To change one element, pass `className` or `style` to that component (see [API conventions](building.md#api-conventions)).
@@ -135,19 +135,19 @@ Internal rules are not private classes. An app applies the [public classes](cust
 
 ### App themes
 
-An app can offer more themes than the two the package ships, such as a warm Paper theme in memos. An app theme is a rule that sets the color and shadow tokens under its own `data-theme` value:
+An app can offer more themes than the two the package ships, such as a warm Paper theme in memos. An app theme is a rule that sets the color tokens under its own `data-theme` value:
 
 ```css
 [data-theme="paper"] {
   color-scheme: light;
   --mu-canvas: #f5ede4;
   --mu-surface: #fbf6f0;
-  /* every other color token, and the five shadow tokens */
+  /* every other color token */
 }
 ```
 
-- Set every color token in the table below and the five shadow tokens in [Depth](depth.md). A token the theme leaves out keeps its Light value, so a partial theme mixes two palettes.
-- The package exports `themeTokens`, the custom property names of those 32 tokens (`--mu-canvas` to `--mu-shadow-pop`). Check in the app's tests that its theme sets each one:
+- Set every color token in the table below. A token the theme leaves out keeps its Light value, so a partial theme mixes two palettes.
+- The package exports `themeTokens`, the custom property names of those 28 tokens (`--mu-canvas` to `--mu-on-danger`). Check in the app's tests that its theme sets each one (Vitest reads a stylesheet with `?raw` only when `test.css` is `true` in its config; without it the file comes back empty):
 
   ```ts
   import { themeTokens } from "@usememos/ui";
@@ -168,23 +168,24 @@ An app can offer more themes than the two the package ships, such as a warm Pape
 | --- | --- | --- | --- |
 | `canvas` | `#fafafa` | `#0f0f0f` | Page background |
 | `surface` | `#ffffff` | `#1a1a1a` | One lightness step above canvas: inputs, menus, popovers, dialogs, toasts, table headers |
-| `well` | `#e4e4e4` | `#252525` | Recessed parts that hold a state: switch, tab, checkbox and radio wells, pressed toggles, inline code. Paired with `edge` and `shadow-track`. Not for text entry |
+| `well` | `#e4e4e4` | `#252525` | Flat parts that hold a state: switch, tab, checkbox and radio wells, pressed toggles, inline code. A boundary is added only where the component needs one. Not for enabled text entry |
 | `hover` | `#ececec` | `#252525` | Hover on rows, ghost buttons and wells; the highlighted row in menus and selects |
-| `key` | `#ffffff` | `#343434` | Raised parts you press: neutral buttons, select triggers, the selected tab, switch knobs, kbd. Paired with `shadow-key` or `shadow-raised` |
+| `key` | `#ffffff` | `#343434` | Controls and selected parts: neutral buttons, select triggers, the selected tab, switch knobs, kbd. Flat: buttons use `control-edge`, selects use `edge`, selected segments use fill only |
 | `key-hover` | `#fafafa` | `#3c3c3c` | Hover on a neutral key |
-| `key-sheen` | `rgba(255,255,255,0.18)` | `rgba(255,255,255,0.08)` | Top light on keys: a gradient from `key-sheen` at the top edge to clear at 60% of the height |
-| `edge` | `#d0d0d0` | `#343434` | 1px border of inputs and wells. About 1.5:1 on canvas |
+| `edge` | `#d0d0d0` | `#343434` | Quiet borders of popups, badges, selects, switch tracks and disabled controls |
+| `control-edge` | `#909090` | `#777777` | Boundaries of fields, neutral buttons, checkboxes and radios; at least 3:1 on `canvas` and `surface` |
 | `line` | `#dedede` | `#252525` | Separators, table rules and menu dividers. 1.25:1 in Light, so structural lines also need spacing or a heading |
 | `overlay` | `rgba(0,0,0,0.32)` | `rgba(0,0,0,0.6)` | Backdrop behind dialogs and sheets |
-| `ink` | `#1a1a1a` | `#ededed` | Primary text and icons on canvas, surface, well and key (13:1 or more in both themes) |
-| `ink-muted` | `#5e5e5e` | `#adadad` | Secondary text: descriptions, placeholders, unselected tabs and toggles, shortcuts, timestamps (4.9:1 or more on every surface) |
+| `text` | `#1a1a1a` | `#ededed` | Primary text and icons on canvas, surface, well and key (13:1 or more in both themes) |
+| `text-secondary` | `#5e5e5e` | `#adadad` | Secondary text: descriptions, placeholders, unselected tabs and toggles, shortcuts, timestamps (4.9:1 or more on every surface) |
+| `text-disabled` | `#666666` | `#9e9e9e` | Disabled text and icons, at least 4.5:1 on `canvas`, `surface`, `well` and `key`; never fade the whole control |
 | `primary` | `#1a1a1a` | `#e6e6e6` | The one emphasized action and every on state: primary buttons, checked boxes and radios, switches when on, tooltips. Ink, not a hue |
 | `primary-hover` | `#333333` | `#ffffff` | Hover on a primary key |
 | `on-primary` | `#ffffff` | `#0f0f0f` | Text, icons and the switch knob on `primary` (16:1 Light, 15:1 Dark) |
 | `accent` | `oklch(0.5 0.13 255)` | `oklch(0.78 0.11 255)` | The only hue at rest: links, the text cursor and selection. 5.8:1 on canvas in Light. Never a fill |
 | `selection` | `rgba(40,99,171,0.18)` | `rgba(135,186,253,0.28)` | Text selection and the selected range in an editor |
-| `focus` | `var(--mu-primary)` | `var(--mu-primary)` | Keyboard focus ring: 2px outline, 1px offset, on `:focus-visible` only |
-| `focus-edge` | `var(--mu-ink)` | `var(--mu-ink)` | Edge of a focused field (Input, Textarea, Combobox): 1.5px on any focus, in place of the 1px `edge` |
+| `focus` | `var(--mu-primary)` | `var(--mu-primary)` | 2px keyboard focus border, on `:focus-visible` only; contrasting text color on filled controls |
+| `focus-edge` | `var(--mu-text)` | `var(--mu-text)` | Edge of a focused field (Input, Textarea, Combobox): 2px on any focus, in place of the 1px `control-edge` |
 | `success` | `oklch(0.52 0.13 150)` | `oklch(0.78 0.14 150)` | Success text and icons on `surface` or `success-soft` (4.6:1 or more). Always with a word or icon |
 | `success-soft` | `#e9f4ec` | `#14261a` | Background of success badges and toasts |
 | `warning` | `oklch(0.5 0.11 70)` | `oklch(0.8 0.13 75)` | Warning text and icons on `surface` or `warning-soft` (5.5:1 or more) |
@@ -194,71 +195,44 @@ An app can offer more themes than the two the package ships, such as a warm Pape
 | `danger-soft` | `#fbeaea` | `#2c1616` | Background of danger badges and error toasts |
 | `on-danger` | `#ffffff` | `#ffffff` | Text on a danger key |
 
-Every text and background pair in this table keeps at least 4.5:1 in both themes. Depth (see [Depth](depth.md)) is added on top and never lowers contrast.
+Every text and background pair in this table keeps at least 4.5:1 in both themes. [Surface borders](depth.md) never lower text contrast.
 
 <!-- docs/depth.md -->
 
-# Depth
+# Surfaces and boundaries
 
-The default taste is "Light, tactile": restrained depth where depth shows behavior. Recessed parts hold a value. Raised parts can be pressed. Popups float. Everything else, including text fields and content, is flat.
+The interface is flat. Fills identify controls and state; borders separate adjacent or overlapping surfaces. No component uses shadows, key sheen, focus rings or visible CSS outlines.
 
 ## Roles
 
-| Role | Class | Used for | Background | Shadow |
-| --- | --- | --- | --- | --- |
-| Recessed | `mu-recessed` | Switch, tab, checkbox and radio wells, pressed toggles | `well` with a 1px `edge` | `shadow-track`, a soft inner shadow from the top |
-| Key in a well | `mu-key` | The selected tab or segment, switch knobs | `key` with the `key-sheen` gradient | `shadow-key` |
-| Raised | `mu-raised` | Buttons, select triggers, kbd | `key` or `primary` with `key-sheen` | `shadow-raised`; `shadow-pressed` while held |
-| Popup | `mu-popup` | Menus, popovers, dialogs, sheets, toasts | `surface` | `shadow-pop` |
-| Flat | none | Inputs and textareas, checked boxes and radios, content | `surface` with `edge`, or `primary` | None |
-
-Each depth class applies a whole role in one class. Use them for new parts before writing new shadows.
+| Role | Class | Used for | Treatment |
+| --- | --- | --- | --- |
+| Well | `mu-well` | Unchecked boxes and radios, pressed toggles | `well` with a 1px `control-edge` |
+| Key | `mu-key` | Bounded controls, such as neutral buttons | `key` with a 1px `control-edge` where a boundary is needed |
+| Popup | `mu-popup` | Menus, popovers, dialogs and toasts | `surface`, a 1px `edge` and `radius-xl` |
+| Content | none | Text fields and content | Fields use `surface` and `control-edge`; content has no enclosing box |
 
-```css
-.mu-recessed { background-color: var(--mu-well); box-shadow: inset 0 0 0 1px var(--mu-edge), var(--mu-shadow-track); }
-.mu-raised   { background-color: var(--mu-key); background-image: linear-gradient(180deg, var(--mu-key-sheen), rgba(255,255,255,0) 60%); box-shadow: var(--mu-shadow-raised); }
-.mu-key      { background-color: var(--mu-key); background-image: linear-gradient(180deg, var(--mu-key-sheen), rgba(255,255,255,0) 60%); box-shadow: var(--mu-shadow-key); }
-.mu-popup    { background: var(--mu-surface); box-shadow: var(--mu-shadow-pop); border-radius: var(--mu-radius-xl); }
-```
+Use these classes before writing new surface styles. `mu-key` covers both a control and a selected choice; neither is raised. Dialogs use `radius-2xl`, and Drawers have an edge facing the page.
 
 ## Rules
 
-- Light always comes from the top.
-- Text entry is flat: an input is `surface` with an `edge`, never a gray well, so it never reads as disabled next to a key.
-- A checked box or radio holds a value, so it is a flat `primary` fill, not a raised key. Only things you press are raised.
-- **One rule for "selected".** A single choice among peers (tabs, a segmented filter) is a raised key sliding in a well. An on/off state (a toolbar toggle) is pressed into a well. Never mix the two in one row.
-- Content areas are flat. There is no card component: group content with spacing, a heading and a `Separator`.
-- No textures, no glass or blur behind text, and no neumorphism. Every fill and text pair keeps its contrast, and depth is added on top.
-
-## Shadow tokens
-
-| Token | Usage |
-| --- | --- |
-| `shadow-track` | Recessed parts: wells and the faint top shadow inside inputs. The border comes from `edge` |
-| `shadow-key` | Keys inside a well: the switch knob, the selected tab or segment |
-| `shadow-raised` | Free-standing keys on canvas or surface: buttons, select triggers, kbd |
-| `shadow-pressed` | A key while held |
-| `shadow-pop` | Menus, selects, popovers, dialogs, sheets and toasts: the floating layer |
-
-### Light
+- No `box-shadow`, `text-shadow`, sheen gradients, focus rings or visible `outline`. `outline: none` or `0` only suppresses a browser outline when another visible focus treatment exists.
+- Text entry keeps its `surface` fill on hover and focus. Enabled fields never use a gray well; disabled fields use `well` with `text-disabled` text.
+- A checked checkbox or radio uses `primary` with an `on-primary` mark. A switch also moves its knob.
+- Select triggers and switch tracks use a quiet `edge` at rest; focus still thickens to a strong contrasting border.
+- A single choice among peers uses a contrasting selected fill in a well. Neither the group nor its selected key has a visible border at rest; transparent borders reserve space, so geometry stays fixed. In forced colors the selected key gains a text-colored border. An independent on/off toggle uses `well` and an `edge` when on.
+- Floating surfaces have a border so they remain distinct over the same surface color. Modal backdrops still use `overlay`.
+- Content is grouped by spacing, headings and separators. The boxed exceptions are List, bordered Table and bordered Form.
+- Borders count toward the documented padding. Reserve their space and compensate inner padding so states never move text or change a control's size.
 
-```css
---mu-shadow-track: inset 0 1px 2px rgba(0,0,0,0.10);
---mu-shadow-key: 0 1px 2px rgba(0,0,0,0.16), 0 2px 6px rgba(0,0,0,0.08), inset 0 1px 0 rgba(255,255,255,0.9), inset 0 -1px 0 rgba(0,0,0,0.05);
---mu-shadow-raised: inset 0 1px 0 rgba(255,255,255,0.25), inset 0 -1px 0 rgba(0,0,0,0.10), 0 0 0 0.5px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.12);
---mu-shadow-pressed: inset 0 1px 3px rgba(0,0,0,0.22), 0 0 0 0.5px rgba(0,0,0,0.12);
---mu-shadow-pop: 0 8px 24px rgba(0,0,0,0.10), 0 1px 3px rgba(0,0,0,0.08), 0 0 0 0.5px rgba(0,0,0,0.08), inset 0 1px 0 rgba(255,255,255,0.8);
-```
-
-### Dark
+## Focus
 
-```css
---mu-shadow-track: inset 0 1px 2px rgba(0,0,0,0.55), inset 0 -0.5px 0 rgba(255,255,255,0.06);
---mu-shadow-key: 0 1px 2px rgba(0,0,0,0.6), 0 2px 6px rgba(0,0,0,0.3), inset 0 1px 0 rgba(255,255,255,0.10);
---mu-shadow-raised: inset 0 1px 0 rgba(255,255,255,0.10), inset 0 -1px 0 rgba(0,0,0,0.25), 0 0 0 0.5px rgba(0,0,0,0.6), 0 1px 2px rgba(0,0,0,0.5);
---mu-shadow-pressed: inset 0 1px 3px rgba(0,0,0,0.6), 0 0 0 0.5px rgba(0,0,0,0.6);
---mu-shadow-pop: 0 8px 24px rgba(0,0,0,0.6), 0 0 0 1px rgba(255,255,255,0.06), inset 0 1px 0 rgba(255,255,255,0.06);
-```
+- `mu-focus` thickens the existing border from 1px to `focus-edge-width` on `:focus-visible`. It provides the internal `--mu-control-border-width` variable. A custom control reads that variable for its border and subtracts it from its padding, so its text and size stay fixed. Text-only links use an underline instead.
+- The edge uses `focus` ink. On primary and checked fills it uses `on-primary`; danger buttons use `on-danger`, so the edge contrasts with the fill.
+- Fields darken and thicken their own border from 1px to `focus-edge-width` on any focus. Invalid fields keep `danger` and thicken the same way.
+- Text links use a double underline on keyboard focus, including links already underlined at rest.
+- Menu items and options use their highlighted fill. Opening a popup never draws a focus boundary around the popup.
+- In forced-colors mode, focused borders use the system `Highlight` color. Real borders remain visible without a shadow or outline fallback.
 
 <!-- docs/typography.md -->
 
@@ -266,14 +240,15 @@ Each depth class applies a whole role in one class. Use them for new parts befor
 
 ## Rules
 
-- Use few sizes and few weights. App text uses four sizes (13, 14, 16 and 20px) and two weights (400 and 500); 12px is only for the text of 20px parts (see `label-xs` and `caption-xs`). Hierarchy comes from text color, spacing and grouping first, then from weight, and from size last.
+- Font decisions follow Apple's [typography guidelines](https://developer.apple.com/design/human-interface-guidelines/typography): the system font, no weight lighter than Regular, hierarchy from color, weight and size, no text under its 11pt minimum for iPhone, and no added letter spacing. The package follows these rules; it does not copy Apple's size tables, which differ per platform (13pt text on Mac, 17pt on iPhone). One set of sizes serves every device, and text does not grow on touch screens, except typed text in fields (see the last rule).
+- Use few sizes and few weights. App text uses four sizes (13, 14, 16 and 20px) and two weights (400 and 500); 11px is only for the text of 20px parts (see `label-xs` and `caption-xs`). Hierarchy comes from text color, spacing and grouping first, then from weight, and from size last.
 - Weight 400 is for running text, values people typed or chose, and badge text (a badge's tone and fill carry its weight). Weight 500 is for labels, controls, titles and headings. The UI uses no 600 or 700. The one exception is [Prose](components/prose.md): bold text and headings that people wrote are 600, because 500 does not read as bold in system fonts.
 - 20px (`heading`) is for the page title only, once per page. 32px (`display`) is for the hero headline on a website only, once per page. Nothing else in the UI is larger than 16px, and 16px is only for `title` and Prose text. Headings that people write inside Prose have their own sizes (see [Prose](#prose)).
 - A section title inside a page or panel is `label` (14px, 500), set apart by space above it, not by a larger size. See [Page](patterns.md#page).
-- Secondary text (descriptions, helper text, metadata) is `caption` (13px) in `ink-muted`. No text is smaller than 13px, except `label-xs` and `caption-xs` inside 20px parts.
-- Control text scales with the control size: 12px at xs, 13px at sm, 14px at md.
+- Secondary text (descriptions, helper text, metadata) is `caption` (13px) in `text-secondary`. No text is smaller than 13px, except `label-xs` and `caption-xs` inside 20px parts.
+- Control text scales with the control size: 11px at xs, 13px at sm, 14px at md.
 - Reading text (`Prose`) is 16px on a 24px line. `sm` prose is 14px on a 22px line, for dense lists.
-- Letter spacing is 0, except −0.02em for `display`.
+- Letter spacing is 0 for every style, `display` included. The system fonts set their own letter spacing at each size, so adding more makes text tighter or looser than the platform intends.
 - Use `font-variant-numeric: tabular-nums` wherever numbers change or line up: counts, times, tables.
 - Selected and unselected states never change weight, so labels don't shift.
 - Adding a size, a weight or a style needs a written reason in this page and the maintainer's sign-off.
@@ -293,32 +268,32 @@ The package ships no font files and loads no remote font: text uses the system U
 
 ## Scale
 
-Nine styles over six sizes. 12, 13 and 14px each have a 400 style for text and a 500 style for labels; the three headings are 500. Body text on a website is `body`, or `Prose` for long-form copy.
+Nine styles over six sizes. 11, 13 and 14px each have a 400 style for text and a 500 style for labels; the three headings are 500. Body text on a website is `body`, or `Prose` for long-form copy.
 
 ### Text (`--mu-font-sans`)
 
 | Style | Size / line | Weight | Usage |
 | --- | --- | --- | --- |
-| `label-xs` | 12 / 16px | 500 | Labels inside xs controls and kbd: 20px parts you press. Never for running or secondary text. The reason for the size: xs controls must read as tiny, and at 13px they read as sm controls with less padding |
-| `caption-xs` | 12 / 16px | 400 | Text inside badges: 20px labels. Never for running or secondary text. The reason for the style: a badge is a label, not a heading, and at 500 every tag and status read heavier than the 13px `caption` metadata around it. Badges get their hierarchy from tone and fill |
-| `caption` | 13 / 18px | 400 | Secondary text: field descriptions and errors, metadata, timestamps, toast and popover descriptions, table captions, sm table cells. Usually in `ink-muted` |
+| `label-xs` | 11 / 16px | 500 | Labels inside xs controls and kbd: 20px parts you press. Never for running or secondary text. The reason for the size: xs parts must read as tiny. At 12px their text was 1px (8%) under the 13px `caption` beside it, a step people can't see, so an xs control read as an sm control with less padding. 11px is a visible step, and it matches the smallest sizes in platform guidelines (the 11pt minimum on iOS, the 11sp label in Material). Nothing is smaller |
+| `caption-xs` | 11 / 16px | 400 | Text inside badges: 20px labels. Never for running or secondary text. The reason for the style: a badge is a label, not a heading, and at 500 every tag and status read heavier than the 13px `caption` metadata around it. Badges get their hierarchy from tone and fill |
+| `caption` | 13 / 18px | 400 | Secondary text: field descriptions and errors, metadata, timestamps, toast and popover descriptions, table captions, sm table cells. Usually in `text-secondary` |
 | `label-sm` | 13 / 18px | 500 | Labels inside sm controls, tooltips, group labels in menus and lists, table heads |
 | `body` | 14 / 20px | 400 | Default running text in app UI; dialog descriptions; the names in rows people scan: Menu and Select items, settings row names, sidebar navigation rows |
 | `label` | 14 / 20px | 500 | Labels inside md controls, field labels, buttons, section titles, popover and toast titles. The default control text |
 
 ### Headings (`--mu-font-display`)
 
-| Style | Size / line | Weight | Letter spacing | Usage |
-| --- | --- | --- | --- | --- |
-| `title` | 16 / 24px | 500 | 0 | Dialog titles; empty-state titles |
-| `heading` | 20 / 28px | 500 | 0 | The page title in an app or on a website. One per page |
-| `display` | 32 / 40px | 500 | −0.02em | The hero headline on a website. Never in an app |
+| Style | Size / line | Weight | Usage |
+| --- | --- | --- | --- |
+| `title` | 16 / 24px | 500 | Dialog titles; empty-state titles |
+| `heading` | 20 / 28px | 500 | The page title in an app or on a website. One per page |
+| `display` | 32 / 40px | 500 | The hero headline on a website. Never in an app |
 
-Each style is also a class with the `mu-` prefix (`.mu-caption`, `.mu-heading`) in `@usememos/ui/styles.css`, which sets the family, size, line height, weight and, where listed, letter spacing.
+Each style is also a class with the `mu-` prefix (`.mu-caption`, `.mu-heading`) in `@usememos/ui/styles.css`, which sets the family, size, line height and weight.
 
 ### Removed styles
 
-The scale used to have 12 sizes and 3 weights. These styles were removed; use the replacement. (`label-xs` was 11px before it came back at 12px for the xs row.)
+The scale used to have 12 sizes and 3 weights. These styles were removed; use the replacement. (`label-xs` and `caption-xs` were 12px until November 2026; 12px is no longer in the scale.)
 
 | Removed | Was | Use |
 | --- | --- | --- |
@@ -343,7 +318,7 @@ Every control takes one `size` prop: `xs`, `sm` or `md` (the default). There is
 
 | Size | Height | Padding | Icon | Icon gap | Text | Radius | Check box |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| xs | `control-xs` 20px | 6px | 12px | 4px | 12 / 16px | `radius-sm` 4px | 14px |
+| xs | `control-xs` 20px | 6px | 12px | 4px | 11 / 16px | `radius-sm` 4px | 14px |
 | sm | `control-sm` 24px | 8px | 14px | 4px | 13 / 18px | `radius-sm` 4px | 16px |
 | md (default) | `control-md` 32px | 12px | 16px | 6px | 14 / 20px | `radius-md` 6px | 18px |
 
@@ -355,27 +330,70 @@ Every control takes one `size` prop: `xs`, `sm` or `md` (the default). There is
 
 ## Spacing
 
-Every spacing value comes from the 4px scale. The only exception is `inset` (2px), the gap between a well and the key inside it.
+Layout spacing comes from one ladder of nine steps, and each step has a job. Two rules decide every gap:
 
-- 0 inside a well.
-- 2px (`inset`) between items inside a cluster (a toolbar).
-- 8px between controls.
-- 16px between fields.
-- 24px between groups.
+- Closer means more related. A title is nearer to its own text than to the block before it.
+- A container's padding is never smaller than the gap between its blocks.
 
-| Token | Value | Usage |
-| --- | --- | --- |
-| `space-1` | 4px | Gap between sm controls; icon to text in sm; the label-to-control gap in a field |
-| `space-2` | 8px | Gap between md controls; sm horizontal padding |
-| `space-3` | 12px | md horizontal padding |
-| `space-4` | 16px | Padding inside popovers and toasts; gap between fields; page padding on phones |
-| `space-5` | 20px | Padding inside dialogs; space above Prose headings |
-| `space-6` | 24px | Gap between sections or entries inside a page; page padding on desktop |
-| `space-8` | 32px | Gap between page regions |
-| `space-12` | 48px | Section rhythm on a website |
-| `space-16` | 64px | Hero and footer padding on a website |
-
-`space-8`, `space-12` and `space-16` are for an app's page layout. No component uses them.
+| Token | Value | Job | Where |
+| --- | --- | --- | --- |
+| `space-1` | 4px | Parts of one thing | Label to control, title to description, control to hint; the gap between sm controls |
+| `space-2` | 8px | Controls side by side; a title to its list | Buttons in a row, tags, a section title to its List, a Fieldset legend to its options, the lines of an entry |
+| `space-3` | 12px | Rows in a set; blocks on a small surface | Options in a Fieldset or RadioGroup, blocks in a Popover or Toast |
+| `space-4` | 16px | Blocks in a container | Fields in a form, two blocks of one section; padding of popovers and boxed forms; page padding on phones |
+| `space-5` | 20px | Padding of big surfaces; above a Prose heading | Padding of dialogs and drawers; the space above a heading and around a rule in Prose. Nowhere else: between other things use 16 or 24 |
+| `space-6` | 24px | Groups | Sections and entries on a page, content to its footer; page padding on desktop |
+| `space-8` | 32px | Regions of a page | A page header band to the content, one column to the next; above and below an empty state |
+| `space-12` | 48px | Website sections | The rhythm between sections of a marketing page |
+| `space-16` | 64px | Website hero and footer | The padding of a hero or a footer |
+
+- `inset` (2px) is not a layout step. It is the gap between a well and the key inside it, and between items inside one cluster (a toolbar). Inside a well the gap is 0.
+- Inside a control the size row sets the spacing (see [Control sizes](#control-sizes)): 6px between an md icon and its text, 6px of padding at xs and in a menu, 2px less padding on a control's icon side. These are optical values of the control, not layout steps. Don't use 6px or 10px between things.
+- `space-8`, `space-12` and `space-16` are for an app's page layout. No component uses them.
+
+Every surface follows the same two tiers. Big surfaces pad `space-5` and stack `space-4`; small ones pad `space-4` and stack `space-3`.
+
+| Surface | Padding | Between blocks | Title to description | Content to footer |
+| --- | --- | --- | --- | --- |
+| Dialog, Drawer | 20px | 16px | 4px | 24px |
+| Form, `bordered` | 16px | 16px | 4px | 16px, then a footer bar |
+| Popover | 16px | 12px | 4px | |
+| Toast | 12px, 16px at the start | 12px | 0: one block of text | |
+| Fieldset | | 12px | 8px from the legend to its options | |
+| Field | | 4px between label, control and hint | | |
+
+The playground has three reference screens built only from these steps: a settings page, a timeline and an empty page (`#screen-settings`, `#screen-timeline` and `#screen-empty`, in `playground/screens.tsx`). The screenshot tests cover them, so a spacing change is judged on a whole screen, not only on one component. An app's pages copy their spacing.
+
+### Spacing in an app
+
+An app's own layout uses the same steps for the same jobs.
+
+- In CSS, read the token: `gap: var(--mu-space-4)`.
+- In Tailwind CSS, the class number is the token number, so `gap-4` is `space-4` (16px). The ladder is `1`, `2`, `3`, `4`, `5`, `6`, `8`, `12` and `16`. `0` and `px` are fine, and `gap-0.5` (2px) is `inset`, for the items of one cluster only.
+- `p-1.5`, `p-2.5`, `p-7`, `p-10` and lengths such as `gap-[6px]` are not steps.
+- Pick a step by its job, not by the nearest number. 6px between two buttons becomes `gap-2`, because they are controls side by side. 6px between a label and its field becomes `gap-1`, because they are parts of one thing.
+
+The package exports the ladder, and a check for an app's tests:
+
+- `spacingSteps` is the ladder in px: `[4, 8, 12, 16, 20, 24, 32, 48, 64]`.
+- `offLadderSpacing(source)` returns the Tailwind CSS padding, margin and gap classes in a text whose value is not a step, as written: `["gap-1.5", "px-[10px]"]`. It reads the `p`, `m`, `gap` and `space` classes that have a number or a px or rem length, with or without a variant or a minus sign. It does not check widths, heights or positions, and it skips a value it cannot measure (`auto`, a variable, a `calc()`).
+
+Run it over the app's source files:
+
+```ts
+import { offLadderSpacing } from "@usememos/ui";
+
+const sources = import.meta.glob<string>("/src/**/*.{ts,tsx,css}", { query: "?raw", import: "default", eager: true });
+
+it("uses only ladder steps for padding, margin and gap", () => {
+  const off = Object.entries(sources).flatMap(([file, text]) => offLadderSpacing(text).map((name) => `${file}: ${name}`));
+  expect(off).toEqual([]);
+});
+```
+
+- Vitest reads a stylesheet with `?raw` only when `test.css` is `true` in its config. Without it every `.css` file comes back empty, so its `@apply` classes are skipped without an error.
+- An app that is still moving to the ladder compares the count with a number, and lowers the number as it goes: `expect(off.length).toBeLessThanOrEqual(40)`.
+- A real exception, such as padding that makes room for a side panel of a fixed width, is filtered out by name in the app's test, with a comment that says why.
 
 ## Radius
 
@@ -403,9 +421,7 @@ Buttons and inputs are never pills; badges always are, so a label is never mista
 | `control-compact` | 28px | md height inside `mu-compact`, for an app's sidebar; sm row height in menus, select lists and combobox lists |
 | `inset` | 2px | Well-to-key inset at every size |
 | `hit-area` | 44px | Minimum touch target on `pointer: coarse`, added invisibly around a control |
-| `focus-width` | 2px | Width of the keyboard focus ring |
-| `focus-offset` | 1px | Gap between a control's edge and its focus ring, so the ring stays visible on ink fills |
-| `focus-edge-width` | 1.5px | Edge width of a focused field |
+| `focus-edge-width` | 2px | Edge width of a focused control or field |
 | `icon-xs` | 12px | Icons in xs controls and badges |
 | `icon-sm` | 14px | Icons in sm controls |
 | `icon-md` | 16px | Icons in md controls and rows |
@@ -457,17 +473,17 @@ Use these tokens for every `z-index`. Don't invent new layers in product code.
 
 # Motion
 
-Motion makes depth feel physical: keys sink when pressed, knobs and keys settle with a light spring, and popups fade in. It is quick and never decorative.
+Motion confirms interaction: buttons respond when pressed, knobs and selections settle with a light spring, and popups fade in. It is quick and never decorative.
 
 ## Rules
 
-- **Press.** Keys move down 0.5px and switch to `shadow-pressed` over `duration-press` (80ms). Switch knobs grow about 10%. Checkboxes and radios shrink 6%.
+- **Press.** Buttons move down 0.5px and change fill over `duration-press` (80ms). Switch knobs grow about 10%. Checkboxes and radios shrink 6%.
 - **Release and selection.** Knobs and the segment key slide over `duration-settle` (150ms) with `ease-settle`, which stops hard like a light spring. Content inside a control (a check mark, a value) fades in after the key stops.
 - **Popups.** Menus, popovers and collapsible content fade in and rise 4px over `duration-fade` (100ms). Dialogs do the same over `duration-settle`. Sheets slide up 24px.
 - **Tooltips** wait 400ms on hover before they open, and open at once on keyboard focus.
 - **Collapsible content** fades and rises in. There is no height animation, so long content never stutters.
 - **Spinners** turn once every 0.8s. **Skeletons** shimmer once every 1.4s.
-- **Reduced motion.** Under `prefers-reduced-motion`, keep color, opacity and shadow changes, and drop slides, scaling and shimmer.
+- **Reduced motion.** Under `prefers-reduced-motion`, keep color and opacity changes, and drop slides, scaling and shimmer.
 
 ## Tokens
 
@@ -489,28 +505,28 @@ Every interactive component handles these states the same way.
 
 | State | Looks like |
 | --- | --- |
-| Hover | Keys go to `key-hover`. Rows, ghost buttons and wells go to `hover`. An input's edge goes to `ink-muted`. Muted labels go to `ink`. Primary keys go to `primary-hover` |
-| Pressed (while held) | Keys move down 0.5px and use `shadow-pressed`. A ghost button sinks into a `well` with `shadow-track` |
-| Pressed toggle (on) | Sinks into a `well` with an `edge` and `ink` text |
-| Selected (one of several) | A raised key in a well that slides to the chosen item |
+| Hover | Keys go to `key-hover`. Rows, ghost buttons and wells go to `hover`. An input's edge goes to `text-secondary`. Muted labels go to `text`. Primary keys go to `primary-hover` |
+| Pressed (while held) | Buttons move down 0.5px and change fill; neutral and ghost buttons use `well`, primary uses `primary-hover`, danger darkens its fill |
+| Pressed toggle (on) | Uses `well` with an `edge` and the `text` color |
+| Selected (one of several) | A flat `key` fill in a well that slides to the chosen item; no visible group or selected-key border at rest |
 | Checked | A flat `primary` fill with an `on-primary` mark |
-| Loading | The control keeps its size, hides its label and shows a Spinner. It is inert while loading |
-| Disabled | 45% opacity, `cursor: not-allowed`, and no hover or press response |
+| Loading | The control becomes inert at once. After 300ms it hides its label and shows a Spinner without changing size; short waits keep the label |
+| Disabled | `text-disabled` text, quiet borders and `well` on filled controls; no whole-control opacity, hover or press response |
 | Invalid | A `danger` edge on the field, plus an error line with an icon under it |
-| Focus (field) | The edge darkens from 1px `edge` to 1.5px `focus-edge` (ink), on click and keyboard alike. No ring around it. An invalid field's `danger` edge thickens the same way |
-| Focus (everything else) | A 2px ink `focus` ring 1px outside the edge, on `:focus-visible` (keyboard) only |
+| Focus (field) | The edge darkens from 1px `control-edge` to 2px `focus-edge` (ink), on click and keyboard alike. No ring around it. An invalid field's `danger` edge thickens the same way |
+| Focus (everything else) | The existing border thickens to 2px `focus` on `:focus-visible`; primary/checked fills use `on-primary`, danger buttons use `on-danger`; text links get a double underline |
 | Focus (inside a widget) | Menu items and options take the `hover` fill. No ring |
 
 ## Rules
 
 - Hover never changes size, weight or layout.
 - An input never changes its background on hover or focus, so it never looks disabled.
-- Focus rings show for keyboard focus only (`:focus-visible`), never on mouse click. Fields are the exception: a clicked field is focused for typing, so its edge darkens, but it still gets no ring.
-- Focus is ink, never blue, and never a ring floating away from the control.
+- Control focus borders show for keyboard focus only (`:focus-visible`), never on mouse click. Fields are the exception: a clicked field is focused for typing, so its edge darkens, but it still gets no ring.
+- Focus changes the existing edge, never adds a ring or visible outline. Filled controls use their contrasting text color at the edge.
 - Popups, dialogs and panels never show a focus ring when they open and take focus.
-- Every focus style survives forced-colors mode: rings are outlines, and fields add a transparent outline that the system paints.
+- Focused borders use the system `Highlight` color in forced-colors mode. No shadow or outline fallback is needed.
 - Disabled controls stay in place. Prefer explaining why something is unavailable over hiding it.
-- Loading never shows a spinner for less than about 300ms; short waits pass silently.
+- Button waits 300ms before showing its spinner. It ignores presses and sets `aria-busy` immediately, cancels the delay when loading ends, and removes the spinner as soon as work finishes. Other loading indicators follow the same delay policy.
 
 <!-- docs/icons.md -->
 
@@ -530,7 +546,7 @@ import { Pin, Trash2 } from "lucide-react";
 - **Icons are elements, not names.** Components take `icon={<Pin />}`, never `icon="pin"`.
 - **Size comes from the control.** An icon inside a component is 12px at xs, 14px at sm and 16px at md (`icon-xs`, `icon-sm`, `icon-md`). Don't pass `size`.
 - **One stroke, fixed in screen pixels.** Every icon, at every size and in badges, draws the `icon-stroke` token: 1.25px. The check in a checkbox is the one exception, at 2px. Apps don't change the token. At 1.25px a 16px outline glyph (calendar, paperclip, search) reads no heavier than the 14px weight-400 text beside it: an icon puts more ink in its box than a letter does, so matching the letters' stem width would read heavier. CSS applies `vector-effect: non-scaling-stroke`, which matches Lucide's `absoluteStrokeWidth`, so no props are needed. Don't pass `strokeWidth`.
-- **Color is `currentColor`.** Icons follow the text color: `ink` in controls, `ink-muted` in menu rows, the tone color in toasts.
+- **Color is `currentColor`.** Icons follow the text color: `text` in controls, `text-secondary` in menu rows, the tone color in toasts.
 - **Icons sit in a fixed square.** In a menu row or a control, the icon square keeps labels aligned whether or not a row has an icon.
 - **Accessibility.** Icons are `aria-hidden`. Every icon-only Button or Toggle has an `aria-label`, and a Tooltip with the same text.
 - **Standalone icons.** Outside a component, give the icon a size class: `mu-icon-xs` (12px), `mu-icon-sm` (14px) or `mu-icon-md` (16px), all with the 1.25px stroke. Each sets the box and the stroke together, so a heading's icon or an empty state's icon matches the icons in controls. `mu-icon` alone takes the size of the nearest size row (`mu-s-*`), or 16px outside one. Don't size an icon with a utility such as `size-4`: it changes the box but not the stroke.
@@ -683,11 +699,11 @@ Wraps Base UI's [Button](https://base-ui.com/react/components/button): `disabled
 
 ## Style
 
-- A raised key: 20, 24 or 32px tall. `primary` is an ink key with `on-primary` text; `neutral` a `key` with a soft edge; `ghost` flat `ink-muted` with `hover` on hover; `danger` a `danger-key` with `on-danger` text.
+- A flat control: 20, 24 or 32px tall. `primary` is an ink key with `on-primary` text; `neutral` a `key` with a `control-edge` boundary; `ghost` flat `text-secondary` with `hover` on hover; `danger` a `danger-key` with `on-danger` text.
 - Only an icon: square. The side with an icon (`icon` at the start, `iconEnd` at the end) has 2px less padding.
-- Press moves the key down 0.5px and swaps its shadow for `shadow-pressed`; a ghost button sinks into a `well`. Under reduced motion the key doesn't move; the shadow still changes.
-- `loading` keeps the width, shows a Spinner over the label, sets `aria-busy` and `aria-disabled`, ignores presses and stays focusable.
-- Disabled: 45% opacity.
+- Press moves the control down 0.5px and changes its fill: `well` for neutral and ghost, `primary-hover` for primary, a darker fill for danger. Under reduced motion only the fill changes.
+- `loading` immediately sets `aria-busy` and `aria-disabled`, ignores presses and stays focusable. The label stays visible for 300ms; if still loading, a Spinner replaces it without changing width. Finishing cancels the delay and restores the label immediately.
+- Disabled: `text-disabled` text, a `well` fill and a quiet `edge`; ghost buttons keep their transparent fill and border. Opacity stays 1.
 
 <!-- docs/components/toggle.md -->
 
@@ -724,7 +740,7 @@ Wraps Base UI's [Toggle](https://base-ui.com/react/components/toggle): `pressed`
 
 ## Style
 
-- Off: flat `ink-muted`. On: sits in a `well` with `ink` text.
+- Off: flat `text-secondary`. On: sits in a `well` with the `text` color.
 - A label shrinks with an ellipsis when its row runs out of room, as Select's value does; an icon-only toggle never shrinks. A ToggleGroup is at most as wide as its container, so long translated labels truncate instead of overflowing.
 
 <!-- docs/components/toggle-group.md -->
@@ -775,7 +791,7 @@ Base UI's props pass through: `value`, `defaultValue`, `onValueChange`, `multipl
 ## Rules
 
 - Give the group an `aria-label`.
-- A single choice among peers is a raised key in a well; an on/off state is a pressed toggle. Never mix the two in one row.
+- A single choice among peers is a flat selected fill in a well; an on/off state is a pressed toggle. Never mix the two in one row.
 - Without `multiple`: filters and view switches that don't change the whole page. For sections of a page, use Tabs.
 - Base UI lets people press the chosen item to clear it. When one item must stay chosen, ignore an empty value, as in the example.
 - Arrow keys move focus between items; Space or Enter presses one.
@@ -785,7 +801,7 @@ Base UI's props pass through: `value`, `defaultValue`, `onValueChange`, `multipl
 
 - At most as wide as its container. With `fullWidth`, exactly as wide: labeled Toggles start at their natural width and share the extra space equally (`flex: 1 1 auto`), so equal labels give equal Toggles and a long label is never cut while there is room. Inside a popup that sizes to its content, the group is as wide as its labels need. When the container is narrower than the labels, they shrink with an ellipsis; icon-only items keep their size.
 - `multiple`: items 2px apart.
-- Without `multiple`: a segmented well; the key slides to the chosen item over `duration-settle` with `ease-settle` and re-measures when an item changes width. Under reduced motion it jumps.
+- Without `multiple`: a segmented well and contrasting selected fill, with no visible border around either at rest. Keyboard focus uses the strong item border; forced colors gives the selected key a text-colored border. The key slides to the chosen item over `duration-settle` with `ease-settle` and re-measures when an item changes width. Under reduced motion it jumps.
 
 <!-- docs/components/menu.md -->
 
@@ -845,7 +861,7 @@ interface Menu.PopupProps extends BaseMenu.Popup.Props {
 interface Menu.ItemProps extends BaseMenu.Item.Props {
   icon?: IconElement;
   shortcut?: React.ReactNode; // at the end of the row, "⌘ D"
-  description?: React.ReactNode; // a line of ink-muted text under the label; the row grows to two lines
+  description?: React.ReactNode; // a line of text-secondary text under the label; the row grows to two lines
   danger?: boolean;           // destructive: red text
 }
 // CheckboxItem and RadioItem take icon, shortcut and description too. SubmenuTrigger takes icon.
@@ -872,10 +888,10 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on
 ## Style
 
 - `mu-popup` with 6px padding (`radius-xl` − `radius-md`, so md highlights are concentric with the corners). As wide as its longest row, at least `menu-width` (160px) and at most `menu-max-width` (280px), both clamped to the space available; labels truncate and descriptions wrap at the maximum. Scrolls when taller than the space available.
-- Rows are 28px at sm (`control-compact`, with sm text and icons) and 32px at md, text weight 400; icons in `ink-muted`; the shortcut right-aligned in `ink-muted`. Text starts at the start edge.
-- A row with a description grows: the label, then the description in `caption` and `ink-muted`, with the row's vertical padding above and below. The icon and the check stay on the label's line.
+- Rows are 28px at sm (`control-compact`, with sm text and icons) and 32px at md, text weight 400; icons in `text-secondary`; the shortcut right-aligned in `text-secondary`. Text starts at the start edge.
+- A row with a description grows: the label, then the description in `caption` and `text-secondary`, with the row's vertical padding above and below. The icon and the check stay on the label's line.
 - A Separator has 6px above and below, the same as the popup padding, and runs edge to edge.
-- The highlighted row uses `hover` with the row's radius (`radius-sm` at sm, `radius-md` at md), and so does a row whose menu is open (a SubmenuTrigger, or a `menuClasses().item` row that is a `Menu.Trigger`). Disabled rows fade to 45%. `danger` rows use `danger`.
+- The highlighted row uses `hover` with the row's radius (`radius-sm` at sm, `radius-md` at md), and so does a row whose menu is open (a SubmenuTrigger, or a `menuClasses().item` row that is a `Menu.Trigger`). Disabled rows and their icons use `text-disabled` without fading the whole row. `danger` rows use `danger`.
 - A ghost trigger keeps its `hover` background while the menu is open.
 - Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
 - A menu below or above its trigger sits 4px from it. A submenu opens beside its trigger row, its own padding (6px) from the row. The row sits the same 6px inside the parent menu, so the submenu's edge touches the parent's edge.
@@ -918,7 +934,7 @@ Provide `href` and `children`.
 
 ## Style
 
-- `accent` text that underlines on hover: the one place the hue appears at rest. `muted` uses `ink-muted`.
+- `accent` text that underlines on hover: the one place the hue appears at rest. `muted` uses `text-secondary`.
 
 <!-- docs/components/form.md -->
 
@@ -982,7 +998,7 @@ Base UI's props pass through: `onFormSubmit`, `errors`, `validationMode` and `ac
 
 ## Style
 
-- Children stack `space-4` apart. Title: `label` (14px, 500); Description: `caption` in `ink-muted`, `space-1` under the title. Footer: buttons `space-2` apart at the end.
+- Children stack `space-4` apart. Title: `label` (14px, 500); Description: `caption` in `text-secondary`, `space-1` under the title. Footer: buttons `space-2` apart at the end.
 - `bordered`: `surface` fill, a 1px `line` edge, `radius-lg`, `space-4` padding, no shadow, as a List. The Footer runs to the edges as a `canvas` bar under a `line`, padded `space-3` × `space-4`, rounded with the box at the bottom.
 - The form is always md: controls inside it ignore the size of a parent Root.
 
@@ -1063,7 +1079,8 @@ Base UI's props pass through: `name`, `invalid`, `disabled`, `validate`, `valida
 
 - Label: `label` style (14px, 500), `space-1` above the control; weight 400 when it wraps a Checkbox, Switch or Radio.
 - Horizontal: a two-column grid. The label (weight 400, as every settings row name is; see [Page](../patterns.md#page)) and description fill the first column; the control sits at the end, centered on them, `space-4` from the text. The error spans the row under them.
-- Description and error: `caption` (13px), below the control. The error hides the description and turns the control's edge `danger`.
+- Description and error: `caption` (13px), `space-1` below the control. The error hides the description and turns the control's edge `danger`.
+- Fieldset: its options stack `space-3` apart. The legend (`label`) sits `space-2` above the first one, closer than the options are to each other, so it reads as their name.
 
 <!-- docs/components/input.md -->
 
@@ -1105,9 +1122,9 @@ Wraps Base UI's [Input](https://base-ui.com/react/components/input), so inside a
 
 ## Style
 
-- Flat `surface` with a 1px `edge` and a faint inner shadow from the top. Never a gray well, so it never reads as disabled.
-- Typed text weight 400; placeholder `ink-muted`. On touch screens typed text is 16px at every size, so iOS Safari does not zoom in on focus; the field keeps its height.
-- Hover darkens the edge to `ink-muted`; focus turns it into a 1.5px `focus-edge` (ink), on click and keyboard alike. There is no ring around the field. The background never changes.
+- Enabled fields use flat `surface` with a real 1px `control-edge` border. A gray well is reserved for the disabled state.
+- Typed text weight 400; placeholder `text-secondary`. On touch screens typed text is 16px at every size, so iOS Safari does not zoom in on focus; the field keeps its height.
+- Hover darkens the edge to `text-secondary`; focus turns it into a 2px `focus-edge` (ink), on click and keyboard alike. There is no ring around the field. The background stays fixed on hover and focus. Disabled fields use `well`, a quiet `edge` and `text-disabled` text.
 - The side with a prefix or suffix has 2px less padding.
 
 <!-- docs/components/textarea.md -->
@@ -1223,7 +1240,7 @@ Base UI's props pass through: `items`, `value`, `defaultValue`, `onValueChange`,
 
 ## Style
 
-- Trigger: a neutral key ([Button](button.md) `neutral`), value left-aligned, `ChevronsUpDown` in `ink-muted`. `ghost`: a ghost Button with `ink` text, `hover` on hover and while open. Placeholder in `ink-muted`, weight 400. Invalid: a `danger` edge.
+- Trigger: a neutral key ([Button](button.md) `neutral`), a quiet `edge` at rest, value left-aligned, `ChevronsUpDown` in `text-secondary`. `ghost`: a ghost Button with the `text` color, `hover` on hover and while open. Placeholder in `text-secondary`, weight 400. Invalid: a `danger` edge.
 - List: `mu-popup`, 6px padding, at least `menu-width` and the trigger's width, at most `menu-max-width` or the trigger's width when that is wider. Rows like [Menu](menu.md) items: 28px at sm, 32px at md, highlight in the row's radius; the highlighted row uses `hover`.
 - Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
 
@@ -1327,10 +1344,10 @@ Base UI's props pass through: `items`, `value`, `defaultValue`, `onValueChange`,
 
 ## Style
 
-- The box is an [Input](input.md): flat `surface`, `edge`, and the focused edge on the box. The search icon and chevron are `ink-muted`; the chevron turns `ink` on hover.
+- The box is an [Input](input.md): flat `surface`, `edge`, and the focused edge on the box. The search icon and chevron are `text-secondary`; the chevron turns `text` on hover.
 - List: `mu-popup`, 6px padding, as wide as the input and at least `menu-width`. Rows like [Menu](menu.md) items: 28px at sm, 32px at md, highlight in the row's radius. The list is at most `list-height` (240px) tall, then it scrolls.
 - Rows are text weight 400; the highlighted row uses `hover`; the chosen row has a check at the end.
-- Empty text: `body` in `ink-muted`, `space-3` by `space-4` padding.
+- Empty text: `body` in `text-secondary`, `space-3` by `space-4` padding.
 - Grid cells: square, a control height, `inset` apart, `row-radius`; the highlighted cell uses `hover`, the chosen cell sits in a `well` like a pressed Toggle. No check.
 - Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
 
@@ -1370,7 +1387,7 @@ Wraps Base UI's [Checkbox](https://base-ui.com/react/components/checkbox) root w
 
 ## Style
 
-- Unchecked: an empty well with an edge. Checked: a flat `primary` square (holds a value, so not raised).
+- Unchecked: an empty well with an edge. Checked: a flat `primary` square with a contrasting mark.
 - Lucide `Check` at a 2px stroke; `Minus` when indeterminate. It fades and scales in after the fill.
 - Shrinks 6% while pressed.
 
@@ -1409,9 +1426,9 @@ Wraps Base UI's [Switch](https://base-ui.com/react/components/switch) root with
 
 ## Style
 
-- A pill well with a round knob; the well fills with `primary` when on.
+- A pill well with a round knob and a quiet `edge` at rest; the well fills with `primary` when on. Keyboard focus uses the strong 2px focus boundary.
 - Height = checkbox box + 2px; width = height × 1.7.
-- The knob is a `key` with `shadow-key`, inset 2px; `on-primary` when on. It grows 10% on press and slides with `ease-settle`. Under reduced motion it doesn't slide or grow.
+- The knob is a flat `key`, inset 2px; `on-primary` when on. It grows 10% on press and slides with `ease-settle`. Under reduced motion it doesn't slide or grow.
 
 <!-- docs/components/radio-group.md -->
 
@@ -1467,7 +1484,7 @@ Base UI's props pass through: `value`, `defaultValue`, `onValueChange`, `disable
 ## Style
 
 - Each radio is a round well; the chosen one is a flat `primary` circle with an `on-primary` dot.
-- Vertical: `space-3` apart. Horizontal: `space-4` apart, with the legend on its own line above.
+- Vertical: `space-3` apart. Horizontal: `space-4` apart, with the legend on its own line above. The legend sits `space-2` above the radios.
 
 <!-- docs/components/tabs.md -->
 
@@ -1521,9 +1538,9 @@ Base UI's props pass through: `value`, `defaultValue`, `onValueChange` on the ro
 
 ## Style
 
-- Shares the segmented well and sliding key with a single-choice ToggleGroup.
+- Shares the segmented well and sliding key with a single-choice ToggleGroup. Grouping and selection use fills without visible borders at rest; keyboard focus retains the strong item border. In forced colors the selected key has a text-colored border.
 - Tabs are sized to their labels. The key re-measures when a label changes width.
-- Selected and hovered labels `ink`, others `ink-muted`. Weight never changes, so labels don't shift.
+- Selected and hovered labels `text`, others `text-secondary`. Weight never changes, so labels don't shift.
 
 <!-- docs/components/collapsible.md -->
 
@@ -1570,7 +1587,7 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `disabled`
 ## Style
 
 - The trigger is a ghost key that bleeds `px` to the left, so its label lines up with the content below.
-- The chevron is `ink-muted` and turns 180° over `duration-settle` with `ease-settle`.
+- The chevron is `text-secondary` and turns 180° over `duration-settle` with `ease-settle`.
 - The panel fades in and rises `space-1` over `duration-fade`. Its height never animates. No rise or turn under reduced motion.
 
 <!-- docs/components/dialog.md -->
@@ -1655,8 +1672,8 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal`, `d
 
 ## Style
 
-- `mu-popup` with `radius-2xl`, `space-5` padding, `dialog-width` wide; children stack `space-4` apart. The backdrop is `overlay`.
-- Title: `title`. Description: `body` in `ink-muted`, `space-2` under the title. The X is a small ghost Button at `space-4` from the corner.
+- `mu-popup` with `radius-2xl`, `space-5` padding, `dialog-width` wide; children stack `space-4` apart, and the Footer sits `space-6` under them. The backdrop is `overlay`.
+- Title: `title`. Description: `body` in `text-secondary`, `space-1` under the title, so the two read as one header. The X is a small ghost Button at `space-4` from the corner.
 - Fades in and rises `space-1` over `duration-settle`. A sheet slides up `space-6`, with square bottom corners and full-width buttons stacked with the action on top. No movement under reduced motion.
 - Long content scrolls the viewport around the panel.
 - `bare`: no padding, no gap and no X; the content is clipped to the radius. Set the width with `className` when it differs from `dialog-width`.
@@ -1720,8 +1737,8 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `onOpenChan
 
 ## Style
 
-- `surface` with `shadow-pop`, full height and `drawer-width` (320px) wide from the start or end edge, with a 1px `line` edge on its inner side (the side facing the page), as a fixed sidebar has, at most the screen width minus `space-12`. Square corners; from the bottom it is full width with `radius-2xl` top corners and at most the screen height minus `space-6`.
-- `panel`: content `space-5` in, stacked `space-4` apart; the X is a small ghost Button at `space-4` from the top end corner. Title: `title`. Description: `body` in `ink-muted`.
+- Flat `surface`, full height and `drawer-width` (320px) wide from the start or end edge, with a 1px `line` edge on its inner side (the side facing the page), as a fixed sidebar has, at most the screen width minus `space-12`. Square corners; from the bottom it has a 1px `edge` at the top and is full width with `radius-2xl` top corners and at most the screen height minus `space-6`.
+- `panel`: content `space-5` in, stacked `space-4` apart, as in a Dialog; the X is a small ghost Button at `space-4` from the top end corner. Title: `title`. Description: `body` in `text-secondary`, `space-1` under the title.
 - `bare`: no padding, gap or X. A visually hidden `Drawer.Close` named `closeLabel` follows the content, so screen readers on touch screens can close it.
 - The backdrop is `overlay`; it fades as the drawer is swiped away.
 - Slides in from its edge over `duration-settle` with `ease-settle` and follows the finger while swiped. Under reduced motion it fades instead.
@@ -1784,8 +1801,8 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on
 
 ## Style
 
-- `mu-popup` (`surface`, `shadow-pop`, `radius-xl`), `space-4` padding, `popover-width` wide. Children stack `space-3` apart.
-- Title: `label`. Description: `caption` in `ink-muted`, `space-1` under the title.
+- `mu-popup` (`surface`, a 1px `edge`, `radius-xl`), `space-4` padding, `popover-width` wide. Children stack `space-3` apart.
+- Title: `label`. Description: `caption` in `text-secondary`, `space-1` under the title.
 - `list`: 6px padding and no gap, like a Menu. A title and description inside line up with the rows' text, with `space-2` above the title and below the description.
 - Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
 
@@ -1903,7 +1920,7 @@ Base UI's props pass through: `timeout` (default 5000ms) and `limit` (default 3)
 ## Style
 
 - `mu-popup`, `toast-width` wide, top-right at `space-6` from the edges; below `breakpoint-sm`, full width across the top at `space-4`, below the status bar.
-- A tone icon (`Info`, `CircleCheck`, `TriangleAlert`, `CircleAlert`) in `ink-muted`, `success`, `warning` or `danger`; title in `label`; description in `caption` `ink-muted`; the action as a small neutral Button; the X as a small ghost Button.
+- A tone icon (`Info`, `CircleCheck`, `TriangleAlert`, `CircleAlert`) in `text-secondary`, `success`, `warning` or `danger`; title in `label`; description in `caption` `text-secondary`; the action as a small neutral Button; the X as a small ghost Button.
 - Newest in front; the ones behind peek out `space-2` below and shrink. A toast behind hides its text at once and gets a 1px `edge`, so its text never shows below a shorter front toast and the peeks stay visible in Dark. Hover or focus fans them out downward, `space-3` apart. Toasts slide in from above and can be swiped up or to the right. Under reduced motion they only fade.
 
 <!-- docs/components/avatar.md -->
@@ -1948,7 +1965,7 @@ interface Avatar.RootProps extends BaseAvatar.Root.Props {
 
 ## Style
 
-- A circle (one of three round shapes, with radios and switches). Initials in `ink-muted` on `well`.
+- A circle (one of three round shapes, with radios and switches). Initials in `text-secondary` on `well`.
 
 <!-- docs/components/badge.md -->
 
@@ -1986,8 +2003,8 @@ function badgeClasses(options?: { tone?: Tone | "outline" | "primary" }): string
 ## Rules
 
 - Tags: `neutral` with a `Hash` icon. Visibility: `outline` with its icon. Status: `success`, `warning` or `danger`, always with a word, never color alone. A label that should stand out, such as New on a feature: `primary`, in ink, the system's one emphasis. Use it for one badge in a view at most, and never for a status.
-- A tag in an entry's footer, or anywhere outside running text, is a `neutral` Badge with a `Hash` icon, in `ink`: it is the user's own word, not secondary text, so it is never muted. A tag inside text is a Prose tag (see [Prose](prose.md)).
-- When people can give a tag a color, pass it as `color`. The color tints the fill; the text and the icon stay `ink`, so every color the user can pick stays readable in both themes. Never set the text or the icon in the user's color: on its own tint it falls below 4.5:1 for most colors in one theme or the other. A tag without a color keeps `well`.
+- A tag in an entry's footer, or anywhere outside running text, is a `neutral` Badge with a `Hash` icon, in `text`: it is the user's own word, not secondary text, so it is never muted. A tag inside text is a Prose tag (see [Prose](prose.md)).
+- When people can give a tag a color, pass it as `color`. The color tints the fill; the text and the icon stay `text`, so every color the user can pick stays readable in both themes. Never set the text or the icon in the user's color: on its own tint it falls below 4.5:1 for most colors in one theme or the other. A tag without a color keeps `well`.
 - `color` is for colors people choose. The package's own meanings use tones: status is `success`, `warning` or `danger`, emphasis is `primary`.
 - A badge is not a button. A clickable tag filter is a [Toggle](toggle.md).
 - A badge is round and a control is square. Kbd and Toggle stay square.
@@ -1996,10 +2013,10 @@ function badgeClasses(options?: { tone?: Tone | "outline" | "primary" }): string
 
 ## Style
 
-- `control-xs` (20px) tall, `radius-full` (a pill: round marks a label, square marks a control), `caption-xs` text (12px, 400), optional `icon-xs` (12px) icon at a 1.25px stroke. It lines up with xs controls.
+- `control-xs` (20px) tall, `radius-full` (a pill: round marks a label, square marks a control), `caption-xs` text (11px, 400), optional `icon-xs` (12px) icon at a 1.25px stroke. It lines up with xs controls.
 - Inline padding is the xs row's `--mu-row-padding` plus 2px (half of `space-1`) on each side, so the text clears the round ends. The gap between icon and text is `space-1`.
-- Regular weight, because a badge is a label, not a heading: hierarchy among badges comes from tone and fill, not weight. `outline` text is `ink-muted`, 5.1:1 or more on `canvas`, `surface` and `well` in both themes.
-- `neutral`: `ink` on `well`. With `color`, the fill is an 18% tint of that color over the background, the same amount in both themes, and the text and icon stay `ink`. The color's lightness is first kept between 50% and 75% (OKLCH), so an ink-like color (black in Dark, white in Light) still gives a visible gray chip instead of vanishing into the background; hues in that range are unchanged. The prop sets `--mu-badge-color` on the badge; an app's own element with `badgeClasses()` sets that variable itself (see [Class functions](../custom-components.md#class-functions)). `primary`: `on-primary` on `primary`, the colors of a primary Button. Status tones: their `-soft` background with full-strength text.
+- Regular weight, because a badge is a label, not a heading: hierarchy among badges comes from tone and fill, not weight. `outline` text is `text-secondary`, 5.1:1 or more on `canvas`, `surface` and `well` in both themes.
+- `neutral`: `text` on `well`. With `color`, the fill is an 18% tint of that color over the background, the same amount in both themes, and the text and icon stay `text`. The color's lightness is first kept between 50% and 75% (OKLCH), so an ink-like color (black in Dark, white in Light) still gives a visible gray chip instead of vanishing into the background; hues in that range are unchanged. The prop sets `--mu-badge-color` on the badge; an app's own element with `badgeClasses()` sets that variable itself (see [Class functions](../custom-components.md#class-functions)). `primary`: `on-primary` on `primary`, the colors of a primary Button. Status tones: their `-soft` background with full-strength text.
 
 <!-- docs/components/kbd.md -->
 
@@ -2033,7 +2050,7 @@ Renders a `<kbd>`.
 
 ## Style
 
-- A tiny raised key, `control-xs` (20px) tall, `label-xs` text (12px) in `ink-muted`.
+- A tiny flat key with an `edge` border, `control-xs` (20px) tall, `label-xs` text (11px) in `text-secondary`.
 
 <!-- docs/components/separator.md -->
 
@@ -2210,7 +2227,7 @@ interface Table.HeadProps extends React.ComponentProps<"th"> {
 }
 interface Table.CellProps extends React.ComponentProps<"td"> {
   num?: boolean;   // right-aligned
-  muted?: boolean; // ink-muted, for secondary values such as dates
+  muted?: boolean; // text-secondary, for secondary values such as dates
 }
 ```
 
@@ -2239,9 +2256,9 @@ Every native attribute passes through.
 
 - No stripes: a `line` under the head row and between body rows. Body rows highlight with `hover`.
 - `bordered`: `surface` fill, a 1px `line` edge and `radius-lg` on the scrolling wrapper; the head row has a `canvas` fill, so it reads as the head inside the box; the Caption sits inside the edge, under a `line`. The outer columns pad `space-1` more, so the text lines up with a [List](list.md) row's.
-- Heads: `label-sm` (13px, 500) in `ink-muted`, a control height tall.
+- Heads: `label-sm` (13px, 500) in `text-secondary`, a control height tall.
 - Cells: `caption` at sm and `body` at md, with tabular numbers. Rows are 34 or 40px; a Button in a cell, or a `Table.Actions` group of them (`space-1` apart), overlaps the padding, so rows keep that height.
-- Cells pad `px` at the sides. Caption: `caption` in `ink-muted`, `space-2` above.
+- Cells pad `px` at the sides. Caption: `caption` in `text-secondary`, `space-2` above.
 
 <!-- docs/components/list.md -->
 
@@ -2318,8 +2335,8 @@ Every native attribute passes through.
 ## Style
 
 - `surface` fill, a 1px `line` edge, `radius-lg`. No shadow: it is flat, like a field.
-- Rows pad `space-3` × `space-4` at md and `space-2` × `space-3` at sm, divided by a 1px `line`. No hover on a plain row. An ItemButton fills its row, padded as the row is, lays out its children in a row `space-3` apart, highlights with `hover`, and rounds with the box at the first and last row; keyboard focus shows the ink ring.
-- Text is `body` in `ink`.
+- Rows pad `space-3` × `space-4` at md and `space-2` × `space-3` at sm, divided by a 1px `line`. No hover on a plain row. An ItemButton fills its row, padded as the row is, lays out its children in a row `space-3` apart, highlights with `hover`, and rounds with the box at the first and last row; keyboard focus darkens the row's reserved border.
+- Text is `body` in `text`.
 
 <!-- docs/components/prose.md -->
 
@@ -2362,15 +2379,15 @@ Every native attribute passes through.
 
 ## Style
 
-- Text: 16px on a 24px line (`sm`: 14 on 22), weight 400, `ink`. Paragraphs and list items use `text-wrap: pretty`, so a last line is rarely one word. Blocks are `space-3` apart.
+- Text: 16px on a 24px line (`sm`: 14 on 22), weight 400, `text`. Paragraphs and list items use `text-wrap: pretty`, so a last line is rarely one word. Blocks are `space-3` apart.
 - Headings: `h1` 24/32px, `h2` 20/28px, `h3`–`h6` 16/24px (`sm`: `h1` 16/24px, `h2`–`h6` 14/22px); all weight 600, balanced over their lines (`text-wrap: balance`), with `space-5` above and `space-2` below. Bold (`strong`, `b`) is 600 too. These are the only 600s in the system: people wrote them as bold, and 500 does not read as bold in system fonts.
 - Links: `accent`, underlined at rest, because color alone does not set them apart from the text.
 - Code: `--mu-font-mono` at 0.875em on `well`. Inline code has `radius-xs`; blocks have `radius-md`, `space-3` by `space-4` padding, and scroll sideways.
-- Quotes: a 2px `edge` bar, text in `ink-muted`. Rules: a 1px `line` with `space-5` around it.
-- Lists indent `space-6`; markers are `ink-muted`. Task checkboxes are 16px, drawn like [Checkbox](checkbox.md); done items go `ink-muted` with a strike-through.
+- Quotes: a 2px `edge` bar, text in `text-secondary`. Rules: a 1px `line` with `space-5` around it.
+- Lists indent `space-6`; markers are `text-secondary`. Task checkboxes are 16px, drawn like [Checkbox](checkbox.md); done items go `text-secondary` with a strike-through.
 - Images and video: never wider than the column, `radius-lg`.
-- Tables follow [Table](table.md): `line` between rows, 13px `ink-muted` heads (weight 500), tabular numbers; they scroll sideways when too wide.
-- Tags: `ink-muted` on `well`, `radius-xs`. They read as words, not badges.
+- Tables follow [Table](table.md): `line` between rows, 13px `text-secondary` heads (weight 500), tabular numbers; they scroll sideways when too wide.
+- Tags: `text-secondary` on `well`, `radius-xs`. They read as words, not badges.
 - Sizes are custom properties set on `.mu-prose` in the foundation (`--prose-fs`, `--prose-lh`, `--prose-h1`, `--prose-h2`, `--prose-h3` and their line heights).
 
 <!-- docs/usage.md -->
@@ -2384,7 +2401,7 @@ How to pick the right component for a screen and put components together. Read i
 1. Find the [pattern](patterns.md) the screen follows: page, form, entry, confirmation, loading, empty state, mobile. Follow it before choosing components.
 2. Pick each component with the guides below. When two seem to fit, the first row that matches wins.
 3. Import components from `@usememos/ui` and icons from `lucide-react`. Don't wrap a component to restyle it.
-4. Use `className` and `style` for layout only: width, margin, grid or flex placement. Don't change a component's color, height, padding, radius, shadow, font size or focus style. If the look is wrong, the component or its page is wrong; change the package, not the screen.
+4. Use `className` and `style` for layout only: width, margin, grid or flex placement. Don't change a component's color, height, padding, radius, border, font size or focus style. If the look is wrong, the component or its page is wrong; change the package, not the screen.
 5. A part the package doesn't ship is built with [Building your own component](custom-components.md), never by copying a component's CSS.
 
 ## Picking something that floats
@@ -2664,19 +2681,21 @@ The package ships no navigation component: the sidebar's rows are the app's link
   align-items: center;
   gap: var(--mu-row-gap);
   height: var(--mu-row-height); /* 28px inside mu-compact, 32px without */
-  padding: 0 var(--mu-row-padding-icon);
+  box-sizing: border-box;
+  padding: 0 calc(var(--mu-row-padding-icon) - var(--mu-control-border-width));
+  border: var(--mu-control-border-width) solid transparent;
   border-radius: var(--mu-row-radius);
-  color: var(--mu-ink-muted);
+  color: var(--mu-text-secondary);
   font-weight: 400; /* mu-base sets 500, for control labels */
   text-decoration: none;
 }
-.app-nav-row:hover, .app-nav-row[aria-current="page"] { color: var(--mu-ink); background-color: var(--mu-hover); }
+.app-nav-row:hover, .app-nav-row[aria-current="page"] { color: var(--mu-text); background-color: var(--mu-hover); }
 ```
 
 - `mu-compact` changes only md. sm (24px) and xs (20px) controls inside keep their heights, so an xs ghost Button for a row action still fits.
 - Popups opened from the sidebar (the Select's list, a Menu) mount outside it, at the normal 32px. To give a panel of rows the same 28px, put `mu-compact` on its popup: `<Popover.Popup variant="list" className="mu-compact">`.
 - `mu-s-md` gives the rows 14px text, 16px icons with a 1.25px stroke, and md padding and radius; `mu-base` sets the font. Never set the `--mu-row-*` variables or the size tokens yourself; `mu-compact` is the only way to change a row's height.
-- Rows are weight 400 (`body`), like Menu items, Select items and settings row names. A column of rows is content people scan; at 500 every row competes and the sidebar reads as bold. 500 is for what names a group: a section title in the sidebar and the "New" Button's label. The current row stands out by its fill and `ink` color, not by weight, so the text doesn't shift when the current page changes.
+- Rows are weight 400 (`body`), like Menu items, Select items and settings row names. A column of rows is content people scan; at 500 every row competes and the sidebar reads as bold. 500 is for what names a group: a section title in the sidebar and the "New" Button's label. The current row stands out by its fill and `text` color, not by weight, so the text doesn't shift when the current page changes.
 - Mark the current page with `aria-current="page"`, not with color alone; the fill shows it too.
 - Rows stack `inset` (2px) apart. Don't add `mu-hit` to stacked rows: their 44px touch areas would overlap. 28px is above the 24px minimum target size.
 - A row with a count or a menu at its end adds it after the label with `margin-inline-start: auto`.
@@ -2697,7 +2716,7 @@ Controls over an image or a video sit in a dark-theme scope, so they read on any
 ```
 
 - `data-theme="dark"` on any element sets the Dark tokens for everything inside it, so the Buttons are dark `neutral` keys with light icons. Don't use `ghost` there: it has no fill and disappears on a busy picture.
-- When the scope holds only Buttons, leave its own background transparent: the keys carry their own fill and shadow. Text in the scope, such as a counter or a file name, has no fill of its own and needs the pill in [Text over a photo](#text-over-a-photo).
+- When the scope holds only Buttons, leave its own background transparent: the keys carry their own fill and border. Text in the scope, such as a counter or a file name, has no fill of its own and needs the pill in [Text over a photo](#text-over-a-photo).
 - A full-screen viewer is a Dialog with `variant="bare" fullScreen`; put the scope inside its Popup.
 
 ### Text over a photo
@@ -2718,16 +2737,16 @@ Plain text over a picture, such as a viewer's "3 / 12" counter or its zoom level
   height: var(--mu-control-md);
   padding: 0 var(--mu-space-3);
   border-radius: var(--mu-radius-md);
-  color: var(--mu-ink);
+  color: var(--mu-text);
   background-color: var(--mu-surface);
-  box-shadow: var(--mu-shadow-pop);
+  border: 1px solid var(--mu-edge);
   font-variant-numeric: tabular-nums;
 }
 ```
 
-- The pill is opaque, as tall as the Buttons beside it, with their radius. Dark `surface` with `ink` text keeps 4.5:1 on any picture.
+- The pill is opaque, as tall as the Buttons beside it, with their radius. Dark `surface` with the `text` color keeps 4.5:1 on any picture.
 - No blur and no translucent fill: glass behind text is not in the system (see [Depth](depth.md)), and it fails contrast on bright pictures.
-- Several labels and Buttons in one row can share one pill instead: put the `surface`, radius, padding and shadow on the scope, and the Buttons become `ghost` inside it, since the pill is their fill.
+- Several labels and Buttons in one row can share one pill instead: put the `surface`, radius, padding and border on the scope, and the Buttons become `ghost` inside it, since the pill is their fill.
 
 ### Inside a shadow root or a host page
 
@@ -2813,6 +2832,7 @@ Run through it for every screen.
 | A tag in the user's color as text, or on a fill you mixed yourself | `<Badge color={tag.color}>`: a tint, with ink text |
 | Text over a photo on a translucent, blurred fill | An opaque `surface` pill in a `data-theme="dark"` scope |
 | Tailwind `size-4` on a standalone icon | `mu-icon-sm` or `mu-icon-md`, which set the stroke too |
+| `gap-1.5`, `px-2.5`, `py-7` or `gap-[6px]` between things | A step of the [spacing ladder](layout.md#spacing), picked by its job. `offLadderSpacing()` finds these in an app's tests |
 | A Spinner where a list will appear | Skeletons in the shape of the list |
 | `size="md"` or `"lg"` on a Button to emphasize it | `variant="primary"` at the row's size |
 | `size` on every part of a Menu or Select | `size` on its Root |
@@ -2869,16 +2889,16 @@ Names and parts from other libraries and where they go.
 
 # Patterns
 
-How the components go together. Each product builds its screens from these patterns. None of them is specific to one product.
+How the components go together. Each product builds its screens from these patterns. None of them is specific to one product. The gaps come from the [spacing ladder](layout.md#spacing), and the playground shows a settings page, a timeline and an empty page built this way (`playground/screens.tsx`).
 
 ## Page
 
 - From `breakpoint-md` (1024px) up: a fixed sidebar of `sidebar-width` (240px). Below it, the sidebar is a [Drawer](components/drawer.md) from the start edge (`side="start"`, `variant="bare"`) opened from a ghost button.
 - A sidebar may use 28px rows: put `mu-compact` on it and every md control and row inside is `control-compact` (28px) tall, the package's (a ghost Select switcher, the "New" Button) and the app's own navigation rows alike. See [A sidebar navigation row](usage.md#a-sidebar-navigation-row). Without it, sidebar rows are md (32px).
-- Sidebar navigation rows (pages, views, tags) are `body` text, weight 400, `ink-muted`, and the current row is `ink` on the `hover` fill. A sidebar section title ("Tags") is `label-sm` or `label`, 500, and the "New" Button keeps its 500 label. Rows are scanned content; weight is for the few things that name them.
+- Sidebar navigation rows (pages, views, tags) are `body` text, weight 400, `text-secondary`, and the current row is `text` on the `hover` fill. A sidebar section title ("Tags") is `label-sm` or `label`, 500, and the "New" Button keeps its 500 label. Rows are scanned content; weight is for the few things that name them.
 - Content sits in a column of at most `content-width` (720px), padded `space-4` on phones and `space-6` on desktop.
-- A page header is a `heading` with an optional `body` line under it, and the page's one primary action at the right. `heading` appears once per page.
-- Sections inside a page have a `label` title (14px, 500) with `space-6` above it and `space-2` below. Section titles are never larger than the text around them; space and grouping set them apart. A section's rows are horizontal Fields: the name at weight 400 (`body`) and the description in `caption`, `ink-muted`. The section title above is the only `label` (500); the row names stay 400 so the title stands out from them.
+- A page header is a `heading` with an optional `body` line `space-1` under it, and the page's one primary action at the right. `heading` appears once per page.
+- Sections inside a page have a `label` title (14px, 500) with `space-6` above it and `space-2` below. Section titles are never larger than the text around them; space and grouping set them apart. A section's rows are horizontal Fields: the name at weight 400 (`body`) and the description in `caption`, `text-secondary`. The section title above is the only `label` (500); the row names stay 400 so the title stands out from them. Two blocks of one section (a List and the Form that adds to it) are `space-4` apart.
 
 ## Form
 
@@ -2894,9 +2914,10 @@ How the components go together. Each product builds its screens from these patte
 
 A repeated unit of content in a list: a note, a comment, a changelog item.
 
-- **Header line** in `caption` (`ink-muted`): who or when, visibility as an outline Badge, and a ghost Menu trigger at the right that appears on hover. On touch screens the menu trigger is always visible.
+- **Header line** in `caption` (`text-secondary`): who or when, visibility as an outline Badge, and a ghost Menu trigger at the right that appears on hover. On touch screens the menu trigger is always visible.
 - **Body** in `Prose`.
-- **Footer line:** tags as `neutral` [Badge](components/badge.md)s with a `Hash` icon, in `ink` (a tag is the user's own word, not metadata); a tag's own color goes in the Badge's `color`. Then attachments and reactions. Prose tags are only for tags inside the body's text.
+- **Footer line:** tags as `neutral` [Badge](components/badge.md)s with a `Hash` icon, in `text` (a tag is the user's own word, not metadata); a tag's own color goes in the Badge's `color`. Then attachments and reactions. Prose tags are only for tags inside the body's text.
+- The three lines of an entry are `space-2` apart.
 - Entries are separated by `space-6` of whitespace or a `Separator`, never by boxes.
 
 ## Confirmation
@@ -2910,7 +2931,7 @@ A repeated unit of content in a list: a note, a comment, a changelog item.
 
 - A list or page that is loading shows Skeletons in the shape of what is coming. The layout must not jump when content arrives.
 - A control that is waiting uses its `loading` prop.
-- Nothing spins for less than about 300ms.
+- Delay a spinner for 300ms; if the work finishes before then, show no spinner.
 - Mark the loading region with `aria-busy`.
 
 ## Empty state
@@ -2918,8 +2939,10 @@ A repeated unit of content in a list: a note, a comment, a changelog item.
 Centered in the content column:
 
 - a `title` line that says what is missing ("No notes yet"),
-- a `body` line that says what to do,
-- one primary Button.
+- a `body` line in `text-secondary` that says what to do, `space-1` under the title,
+- one primary Button, `space-4` under the text.
+
+The block has `space-8` above and below it, so it reads as a region of its own under the page header. The Button is the page's one primary action: a page that shows an empty state has no second primary in its header.
 
 No illustration.
 
@@ -2986,14 +3009,14 @@ Inside another page (the web clipper, an embed), mount the UI under a `.mu-root`
 
 Set `data-theme="light" | "dark"` on the root element or on any `.mu-root`. Without the attribute the tokens are Light. The app, not the package, reads `prefers-color-scheme` and the user's saved choice. See [Color](color.md#themes). An app can add its own themes on top of these two; see [App themes](color.md#app-themes).
 
-An app changes only the color, shadow and font tokens. Every other token and every `mu-*` class rule is internal. See [What an app can change](color.md#what-an-app-can-change).
+An app changes only the color and font tokens. Every other token and every `mu-*` class rule is internal. See [What an app can change](color.md#what-an-app-can-change).
 
 ## Class names
 
 - Every class the package ships starts with `mu-`.
-- The [public classes](custom-components.md#public-classes) are for apps too: size rows (`mu-s-md`), depth roles (`mu-raised`), focus, touch targets, icons and the type scale. Apps apply them to their own parts and never override them.
+- The [public classes](custom-components.md#public-classes) are for apps too: size rows (`mu-s-md`), surface roles (`mu-key`), focus, touch targets, icons and the type scale. Apps apply them to their own parts and never override them.
 - `mu-positioner` puts a popup's positioner on `layer-popup`, and `mu-popup-motion` makes a popup fade in and rise `space-1` (no rise under reduced motion).
-- The depth classes `mu-recessed`, `mu-key`, `mu-raised` and `mu-popup` apply a whole depth role. Use them for new parts before writing new shadows. See [Depth](depth.md).
+- The surface classes `mu-well`, `mu-key` and `mu-popup` apply flat fills and borders. Use them for new parts. See [Surfaces and boundaries](depth.md).
 - `mu-prose` styles rendered content. See [Prose](components/prose.md).
 - `mu-icon` applies icon size and stroke rules outside a component, at the size of the nearest size row; `mu-icon-xs`, `mu-icon-sm` and `mu-icon-md` set a fixed size on their own. See [Icons](icons.md).
 - `mu-visually-hidden` hides text visually but keeps it for screen readers.
@@ -3076,7 +3099,7 @@ toast.add({ title: "Note archived", type: "success" });
 
 1. A reason: a screen in a product needs it, and no existing component or pattern covers it.
 2. A generic name and API that would make sense in any of our products.
-3. Tokens only: no raw colors, sizes or shadows.
+3. Tokens only: no raw colors or sizes; no shadows, sheen or visible outlines.
 4. Both sizes, all [states](states.md), both themes, and reduced motion.
 5. Keyboard and screen reader behavior from Base UI.
 6. A page in `docs/components/` and an entry in the [inventory](components/README.md).
@@ -3094,7 +3117,7 @@ An app always has parts the package doesn't ship and shouldn't: product parts (a
 1. **Use a component if one fits.** Check the [inventory](components/README.md). Compose components, swap a part's element with `render`, or adjust one instance with `className` before building anything.
 2. **Behavior from Base UI.** Build anything with focus, keyboard, an open state or a popup on [`@base-ui/react`](https://base-ui.com), as the package does. It is a peer dependency of the package at one exact version, so the app's components and the package's share one copy. Upgrade it only with the package.
 3. **Looks from a class function** when the part should look like a component: an anchor that looks like a Button, an editor that looks like a Textarea, a suggestion list that looks like a Menu. See [Class functions](#class-functions).
-4. **Otherwise, from the public classes and tokens.** Size the part with a size row class and read the [row variables](#row-variables); give it depth with a [depth class](depth.md); set text with a [type class](typography.md); color it with `var(--mu-<token>)` or the [Tailwind utilities](#tailwind-css).
+4. **Otherwise, from the public classes and tokens.** Size the part with a size row class and read the [row variables](#row-variables); give it a surface with a [surface class](depth.md); set text with a [type class](typography.md); color it with `var(--mu-<token>)` or the [Tailwind utilities](#tailwind-css).
 5. **Check it like a component.** It works in Light and Dark and under reduced motion; text keeps 4.5:1 contrast; focus shows on `:focus-visible` (`mu-focus`); touch targets reach 44px (`mu-hit`); icon-only controls have an `aria-label` and a [Tooltip](components/tooltip.md).
 
 ## Class functions
@@ -3148,22 +3171,21 @@ Apply these classes to an app's own elements. Don't override their rules: the pr
 | `mu-s-sm` | The sm size row: 24px | Dense toolbars, table rows, filters |
 | `mu-s-md` | The md size row: 32px | Everything else |
 | `mu-compact` | md controls and rows inside are `control-compact` (28px) tall; text, icons, padding and radius stay md | An app's sidebar with 28px rows, or a list Popover beside it |
-| `mu-base` | The system font, the row's text size and weight 500, `ink` text, and icon sizing for Lucide icons inside | The root of a control |
-| `mu-recessed` | `well`, a 1px `edge` and `shadow-track` | A part that holds a value |
-| `mu-key` | A `key` with the sheen and `shadow-key` | A key inside a well |
-| `mu-raised` | A `key` with the sheen and `shadow-raised` | A part you press |
-| `mu-popup` | `surface`, `shadow-pop` and `radius-xl` | A part that floats |
+| `mu-base` | The system font, the row's text size and weight 500, the `text` color, and icon sizing for Lucide icons inside | The root of a control |
+| `mu-well` | `well` and a 1px `control-edge` | A part that holds a value |
+| `mu-key` | `key` and a 1px `control-edge` | A control or a selected choice |
+| `mu-popup` | `surface`, a 1px `edge` and `radius-xl` | A part that floats |
 | `mu-popup-motion` | The popup fade and rise, none under reduced motion | A popup Base UI opens |
 | `mu-positioner` | The popup layer | A popup's positioner |
-| `mu-focus` | The ink focus ring on `:focus-visible`, 1px outside the edge | Anything focusable |
+| `mu-focus` | Thickens the existing border on `:focus-visible`; use its `--mu-control-border-width` for border and compensating padding | Anything focusable |
 | `mu-hit` | An invisible 44px touch target on `pointer: coarse` | Anything pressable smaller than 44px |
 | `mu-icon` | Icon size and stroke from the nearest size row, 16px outside one | A Lucide icon inside an app's own row |
-| `mu-icon-xs` | A 12px icon with a 1.25px stroke | A Lucide icon beside 12px or 13px text, outside a control |
+| `mu-icon-xs` | A 12px icon with a 1.25px stroke | A Lucide icon beside 11px or 13px text, outside a control |
 | `mu-icon-sm` | A 14px icon with a 1.25px stroke | A Lucide icon beside 13px or 14px text, outside a control |
 | `mu-icon-md` | A 16px icon with a 1.25px stroke | A Lucide icon beside 14px or 16px text, outside a control |
 | `mu-visually-hidden` | Hidden on screen, read by screen readers | Text for screen readers only |
-| `mu-label-xs` | 12 / 16px, 500 | Labels of 20px controls and kbd |
-| `mu-caption-xs` | 12 / 16px, 400 | Text of 20px labels (badges) |
+| `mu-label-xs` | 11 / 16px, 500 | Labels of 20px controls and kbd |
+| `mu-caption-xs` | 11 / 16px, 400 | Text of 20px labels (badges) |
 | `mu-caption` | 13 / 18px, 400 | Secondary text |
 | `mu-label-sm` | 13 / 18px, 500 | Small labels |
 | `mu-body` | 14 / 20px, 400 | Body text |
@@ -3181,9 +3203,9 @@ A size row class sets these variables on its element, and children inherit them.
 | `--mu-row-height` | 20px | 24px | 32px |
 | `--mu-row-padding` | 6px | 8px | 12px |
 | `--mu-row-padding-icon` | 4px | 6px | 10px |
-| `--mu-row-font-size` | 12px | 13px | 14px |
+| `--mu-row-font-size` | 11px | 13px | 14px |
 | `--mu-row-line-height` | 16px | 18px | 20px |
-| `--mu-row-field-font-size` | 12px | 13px | 14px |
+| `--mu-row-field-font-size` | 11px | 13px | 14px |
 | `--mu-row-field-line-height` | 16px | 18px | 20px |
 | `--mu-row-radius` | 4px | 4px | 6px |
 | `--mu-row-gap` | 4px | 4px | 6px |
@@ -3213,16 +3235,15 @@ An app on Tailwind CSS v4 loads `tailwind.css` after the package's other stylesh
 @import "@usememos/ui/tailwind.css";
 ```
 
-It maps the 27 color tokens, five shadow tokens, seven radius tokens and three font tokens to utilities with an `mu-` prefix, so they never clash with an app's own colors:
+It maps the 28 color tokens, seven radius tokens and three font tokens to utilities with an `mu-` prefix, so they never clash with an app's own colors:
 
 | Token | Utility |
 | --- | --- |
-| A color, such as `surface` | `bg-mu-surface`, `text-mu-ink-muted`, `border-mu-edge`, and every other color utility |
-| A shadow, such as `shadow-raised` | `shadow-mu-raised` |
+| A color, such as `surface` | `bg-mu-surface`, `text-mu-text-secondary`, `border-mu-edge`, and every other color utility |
 | A radius, such as `radius-md` | `rounded-mu-md` |
 | A font, such as `font-mono` | `font-mu-mono` |
 
 - Each utility reads the token where it is used, so a `.mu-root` with its own `data-theme` recolors the utilities inside it.
-- Spacing needs no mapping: Tailwind's step is 0.25rem, which is the 4px grid, so `p-3` is `space-3`. Don't use half steps such as `p-0.5`; the only 2px value is `inset`.
+- Spacing needs no mapping: Tailwind's step is 0.25rem (4px), so `p-3` is `space-3`. Use only the numbers of the [spacing ladder](layout.md#spacing): `1`, `2`, `3`, `4`, `5`, `6`, `8`, `12` and `16`. `gap-0.5` (2px) is `inset`, for the items of one cluster only; the other half steps (`p-1.5`, `p-2.5`) are not steps. `offLadderSpacing()` finds the classes that miss the ladder: see [Spacing in an app](layout.md#spacing-in-an-app).
 - Text uses the type classes (`mu-body`), not Tailwind's text sizes.
 - `tailwind-merge` doesn't know `mu-` classes and keeps them next to a utility. The utility still wins, because the package's styles sit in the `mu` [cascade layer](building.md#cascade-layer).