@usememos/ui 26.11.2 → 26.11.4

package/llms-full.txt

@@ -24,8 +24,8 @@ It is not a general-purpose UI library for outside developers. Components are ge
 | [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 |
 | [States](states.md) | Hover, pressed, loading, disabled, invalid and focus |
-| [Icons](icons.md) | Lucide, sizes, fixed stroke widths and accessibility |
-| [Components](components/README.md) | The 30 components, what was left out, and one page per component |
+| [Icons](icons.md) | Lucide, sizes, the fixed stroke and accessibility |
+| [Components](components/README.md) | The 31 components, what was left out, and one page per component |
 | [Using the components](usage.md) | Which component to pick (overlays, controls, feedback), recipes for combining them, size, emphasis, an accessibility checklist, common mistakes and a map from other UI kits |
 | [Patterns](patterns.md) | Page, form, entry, confirmation, loading, empty state and mobile |
 | [Building on it](building.md) | Base UI, loading the CSS, scoping inside a host page, theme selection and API conventions |
@@ -39,7 +39,7 @@ It is not a general-purpose UI library for outside developers. Components are ge
 - **Ink is the accent.** The primary action and every on state use `primary`: near-black in Light, near-white in Dark.
 - **One quiet hue.** `accent` is a quiet blue used only for links and text selection, never as a fill. Focus is ink.
 - **Status colors only for status.** Green means success, amber means warning, red means danger or error. None of them is used for emphasis.
-- **Lucide icons** at a fixed screen-pixel stroke: 1.5px at md, 1.25px at xs, sm and in badges.
+- **Lucide icons** at one fixed screen-pixel stroke, 1.25px, at every size.
 - **The system UI font** for all text. The package ships no font files.
 - **Few sizes, two weights.** App UI uses 13, 14, 16 and 20px text at weights 400 and 500. 20px is for the page title only.
 - **Dense, on a 4px grid.** Controls are 32px tall by default.
@@ -267,7 +267,7 @@ Each depth class applies a whole role in one class. Use them for new parts befor
 
 - 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 labels of 20px parts (see `label-xs`). Hierarchy comes from text color, spacing and grouping first, then from weight, and from size last.
 - Weight 400 is for running text and values people typed or chose. 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 is larger than 16px, and 16px is only for `title` and Prose text.
+- 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` inside 20px parts.
 - Control text scales with the control size: 12px at xs, 13px at sm, 14px at md.
@@ -277,16 +277,18 @@ Each depth class applies a whole role in one class. Use them for new parts befor
 - 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.
 - The platform's UI font for everything (San Francisco on Apple, Segoe UI on Windows, Roboto on Android), smoothed with antialiasing. The package ships no font files.
+- Titles and headings (`title`, `heading`, `display`, and headings in Prose) use `text-wrap: balance`, so a heading that wraps does not leave one word on its last line. Prose paragraphs and list items use `text-wrap: pretty`. Browsers without these wrap as usual.
+- Typed text in fields is 16px on touch screens (`pointer: coarse`), whatever the field's size: below 16px, iOS Safari zooms the page in when a field takes focus. The field keeps its height; its label and placeholder layout do not change.
 
 ## Fonts
 
 | Family | Stack |
 | --- | --- |
-| `--mu-font-sans` | `system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` |
-| `--mu-font-display` | `system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` |
+| `--mu-font-sans` | `-apple-system, BlinkMacSystemFont, "Segoe UI (mu)", system-ui, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` |
+| `--mu-font-display` | `-apple-system, BlinkMacSystemFont, "Segoe UI (mu)", system-ui, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` |
 | `--mu-font-mono` | `ui-monospace, "SF Mono", Menlo, Consolas, monospace` |
 
-The package ships no font files and loads no remote font: text uses the system UI font, so it looks native on each platform and costs no download. An app that wants another font sets `--mu-font-sans`, `--mu-font-display` or `--mu-font-mono` after loading `tokens.css`, and loads the font itself. These are the only type tokens an app may set: sizes, line heights, weights and letter spacing are fixed (see [What an app can change](color.md#what-an-app-can-change)). Code in [Prose](components/prose.md) uses `font-mono`, the platform's monospace font by default.
+The package ships no font files and loads no remote font: text uses the system UI font, so it looks native on each platform and costs no download. Do not import or define another font family. The one exception is `"Segoe UI (mu)"`, an alias of the installed Windows UI font that the stylesheet defines with `local()` sources only, so it loads no file. Segoe UI has Regular, Semibold and Bold faces but no Medium, so with a plain stack the browser draws weight 500 at 400 and every label on Windows loses its weight. The alias draws 500 and 600 with the installed Semibold face. It comes after `-apple-system` and `BlinkMacSystemFont`, so Apple platforms still get San Francisco, and before `system-ui`, which is plain Segoe UI on Windows. An app that wants another font sets `--mu-font-sans`, `--mu-font-display` or `--mu-font-mono` after loading `tokens.css`, and loads the font itself. These are the only type tokens an app may set: sizes, line heights, weights and letter spacing are fixed (see [What an app can change](color.md#what-an-app-can-change)). Code in [Prose](components/prose.md) uses `font-mono`, the platform's monospace font by default.
 
 ## Scale
 
@@ -327,7 +329,7 @@ The scale used to have 12 sizes and 3 weights. These styles were removed; use th
 
 ## Prose
 
-Rendered content (notes, comments, changelogs, website pages) uses the `Prose` styles, not the scale above. It uses the same sizes: 16px text (14px at `sm`), 20px `h1`, 16px `h2`–`h6`, and 13px table heads. See [Prose](components/prose.md).
+Rendered content (notes, comments, changelogs, website pages) uses the `Prose` styles, not the scale above. It uses 16px text (14px at `sm`) and 13px table heads, and has three heading sizes: 24px `h1`, 20px `h2`, and 16px `h3`–`h6`. 24px appears nowhere else. The reason: notes have sections and subsections, and when `h2` and `h3` were both the size of the text they read as one level, and as bold sentences. At `sm`, `h1` is 16px and `h2`–`h6` are 14px. See [Prose](components/prose.md).
 
 <!-- docs/layout.md -->
 
@@ -343,7 +345,7 @@ Every control takes one `size` prop: `xs`, `sm` or `md` (the default). There is
 | 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 |
 
-- Use `sm` for dense toolbars, table rows and filters inside panels, and `md` everywhere else, including marketing pages, onboarding, sheets and an app's sidebar navigation. Emphasis comes from the `primary` variant, not from a bigger control. On touch screens the hit area, not the visual size, grows.
+- Use `sm` for dense toolbars, table rows and filters inside panels, and `md` everywhere else, including marketing pages, onboarding and sheets. A sidebar with 28px rows puts the `mu-compact` class on itself: md controls and rows inside are `control-compact` (28px) tall, with md text, icons, padding and radius (see [A sidebar navigation row](usage.md#a-sidebar-navigation-row)). It is the only height between sizes, and it is not a `size` value. Emphasis comes from the `primary` variant, not from a bigger control. On touch screens the hit area, not the visual size, grows.
 - Use `xs` for secondary actions beside 13px text: actions on a row or an entry, inline formatting, filters in a tight header, checkboxes in a dense list. It is the height of a Badge or a Kbd, so they line up. Don't use `xs` for forms, for navigation, or for the main action of a screen.
 - Only Button, Toggle, ToggleGroup, Checkbox, RadioGroup and Radio, Switch, Avatar, Spinner and Skeleton take `xs`. Text entry, menus, tabs and tables are too cramped at 20px, so their `size` is `sm | md`, and an `xs` inherited from a parent renders them at `sm`.
 - The icon side of a control has 2px less padding, so text and icon look centered.
@@ -396,6 +398,7 @@ Buttons, inputs and badges are never pills.
 | `control-xs` | 20px | xs control height; Badge and Kbd |
 | `control-sm` | 24px | sm control height |
 | `control-md` | 32px | Default control height |
+| `control-compact` | 28px | md height inside `mu-compact`, for an app's sidebar |
 | `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 |
@@ -404,6 +407,7 @@ Buttons, inputs and badges are never pills.
 | `icon-xs` | 12px | Icons in xs controls and badges |
 | `icon-sm` | 14px | Icons in sm controls |
 | `icon-md` | 16px | Icons in md controls and nav rows |
+| `icon-stroke` | 1.25px | Stroke of every icon, in screen pixels, at every size. Only the checkbox check differs (2px) |
 
 ## Layout
 
@@ -522,11 +526,11 @@ 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`.
-- **Stroke is fixed in screen pixels.** 1.25px at xs, at sm and in badges, 1.5px at md, and 2px for the check in a checkbox. At 1.5px an icon matches the stem weight of the label text beside it. CSS applies `vector-effect: non-scaling-stroke`, which matches Lucide's `absoluteStrokeWidth`, so no props are needed. Don't pass `strokeWidth`.
+- **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.
 - **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, 1.25px stroke), `mu-icon-sm` (14px, 1.25px) or `mu-icon-md` (16px, 1.5px). 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.
+- **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.
 
   ```tsx
   <h2 className="mu-title"><Inbox className="mu-icon-sm" aria-hidden /> Inbox</h2>
@@ -556,12 +560,12 @@ When Lucide doesn't have an icon, draw it on Lucide's 24px grid with 2px round s
 
 # Components
 
-30 components in five groups, chosen from what Base UI and other popular libraries provide and what our products need today. Every component is generic: it works the same in memos, the website, the web clipper and any future product.
+31 components in five groups, chosen from what Base UI and other popular libraries provide and what our products need today. Every component is generic: it works the same in memos, the website, the web clipper and any future product.
 
 | Group | Components |
 | --- | --- |
 | Actions | [Button](button.md), [Toggle](toggle.md), [ToggleGroup](toggle-group.md), [Menu](menu.md), [Link](link.md) |
-| Forms | [Field and Fieldset](field.md), [Input](input.md), [Textarea](textarea.md), [Select](select.md), [Combobox](combobox.md), [Checkbox](checkbox.md), [Switch](switch.md), [RadioGroup](radio-group.md) |
+| Forms | [Form](form.md), [Field and Fieldset](field.md), [Input](input.md), [Textarea](textarea.md), [Select](select.md), [Combobox](combobox.md), [Checkbox](checkbox.md), [Switch](switch.md), [RadioGroup](radio-group.md) |
 | Navigation | [Tabs](tabs.md), [Collapsible](collapsible.md) |
 | Overlays | [Dialog](dialog.md) (and its sheet form), [Drawer](drawer.md), [Popover](popover.md), [Tooltip](tooltip.md), [Toast](toast.md) |
 | Display | [Avatar](avatar.md), [Badge](badge.md), [Kbd](kbd.md), [Separator](separator.md), [Spinner](spinner.md), [Skeleton](skeleton.md), [Table](table.md), [List](list.md), [Prose](prose.md), plus [Lucide icons](../icons.md) |
@@ -581,7 +585,7 @@ Components follow the [API conventions](../building.md#api-conventions): parts w
 
 ## Left out on purpose
 
-- **Card.** Content is grouped by spacing, headings and separators. The only boxes are a [List](list.md) of settings or records and a `bordered` [Table](table.md).
+- **Card.** Content is grouped by spacing, headings and separators. The only boxes are a [List](list.md) of settings or records, a `bordered` [Table](table.md) and a `bordered` [Form](form.md) for a small form among them.
 - **Slider, Stepper.** No setting in our products needs a continuous range. Use an Input with `type="number"` or a Select.
 - **Chip, SegmentedControl, Accordion.** A Toggle covers filter chips, a single-choice ToggleGroup covers segmented choices, and stacked Collapsibles cover an accordion.
 - **Later, when a screen needs them:** multi-select Combobox, ContextMenu, ScrollArea, Progress, Calendar.
@@ -610,6 +614,7 @@ The short version. [Using the components](../usage.md) has the full decision gui
 | Confirm something happened | Toast |
 | Settings rows, or a short list of records with actions | List |
 | Data with columns | Table |
+| A small form (heading, a few fields, buttons) among Lists on a settings page | Form with `bordered` |
 | A status or tag label | Badge |
 | A clickable tag filter | Toggle |
 | Content still loading | Skeleton |
@@ -757,7 +762,8 @@ import { Bold, Code, Italic } from "lucide-react";
 
 ```ts
 interface ToggleGroupProps extends BaseToggleGroup.Props {
-  size?: Size; // passed to every Toggle inside
+  size?: Size;         // passed to every Toggle inside
+  fullWidth?: boolean; // fills the container; labeled Toggles share the width equally
 }
 ```
 
@@ -770,10 +776,11 @@ Base UI's props pass through: `value`, `defaultValue`, `onValueChange`, `multipl
 - 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.
+- Set `fullWidth` when the group is the only control on its row and should line up with the edges, such as a view switch across a popover. Don't set `className="w-full"` and `flex-1` on the Toggles yourself.
 
 ## Style
 
-- At most as wide as its container. When the labels don't fit, they shrink with an ellipsis; icon-only items keep their size.
+- At most as wide as its container. With `fullWidth`, exactly as wide, and labeled Toggles take equal shares (icon-only ones keep their size). When the labels don't fit, 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.
 
@@ -907,6 +914,72 @@ Provide `href` and `children`.
 
 - `accent` text that underlines on hover: the one place the hue appears at rest. `muted` uses `ink-muted`.
 
+<!-- docs/components/form.md -->
+
+# Form
+
+A `<form>` with a title, its fields and its buttons. `bordered` boxes a small form among the [Lists](list.md) of a settings page.
+
+## Example
+
+```tsx
+import { Button, Field, Form, Input, Switch } from "@usememos/ui";
+
+<Form.Root bordered onSubmit={addRule}>
+  <Form.Title>Add a tag rule</Form.Title>
+  <Form.Description>Tag new notes that match a word.</Form.Description>
+  <Field.Root name="tag">
+    <Field.Label>Tag</Field.Label>
+    <Input required />
+  </Field.Root>
+  <Field.Root orientation="horizontal">
+    <Field.Label>Apply to existing notes</Field.Label>
+    <Switch name="existing" />
+  </Field.Root>
+  <Form.Footer>
+    <Button variant="ghost" onClick={cancel}>Cancel</Button>
+    <Button variant="primary" type="submit">Add rule</Button>
+  </Form.Footer>
+</Form.Root>
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `Form.Root` | `Form` | A `<form>`. Takes `bordered`. Named by its Title |
+| `Form.Title` | none (ours) | An `<h2>` in `label` style. Takes `render` for another heading level |
+| `Form.Description` | none (ours) | A `<p>` under the title |
+| `Form.Footer` | none (ours) | A `<div>` that right-aligns the buttons |
+
+## Props
+
+```ts
+interface Form.RootProps extends BaseForm.Props {
+  bordered?: boolean; // a List's edge around the form, and the Footer as a canvas bar
+}
+interface Form.TitleProps extends React.ComponentProps<"h2"> {
+  render?: React.ReactElement; // such as <h3 /> under a page section
+}
+```
+
+Base UI's props pass through: `onFormSubmit`, `errors`, `validationMode` and `actionsRef`, as do the native `<form>` attributes (`onSubmit`, `action`).
+
+## Rules
+
+- Set `bordered` for a small form (a heading, two to four fields and its buttons) on a settings page, next to [Lists](list.md) or a `bordered` [Table](table.md), such as "Add a tag rule" under the rules it adds to. Leave it off for a form that is the page's main content.
+- Never put a bordered Form inside a Dialog, Popover or Drawer: those are boxes already. A form in a Dialog uses the Dialog's own Title and Footer; see [Form in a dialog](../usage.md#form-in-a-dialog).
+- Don't box single settings: a setting that saves at once is a horizontal [Field](field.md) in a List.
+- Footer: a ghost Cancel, then one `primary` Button with `type="submit"` named with its verb ("Add rule", never "OK" or "Submit").
+- Give each Field a `name`; errors from the server go in `errors`, keyed by name, and appear under their fields.
+- Name it with a Title, or `aria-label` on the root when there is no visible heading.
+
+## 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.
+- `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.
+
 <!-- docs/components/field.md -->
 
 # Field and Fieldset
@@ -983,7 +1056,7 @@ Base UI's props pass through: `name`, `invalid`, `disabled`, `validate`, `valida
 ## Style
 
 - 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) 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.
+- 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`.
 
 <!-- docs/components/input.md -->
@@ -1027,7 +1100,7 @@ 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`.
+- 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.
 - The side with a prefix or suffix has 2px less padding.
 
@@ -1070,6 +1143,7 @@ Base UI has no textarea part, so this renders Base UI's `Field.Control` as a `<t
 ## Style
 
 - Looks like [Input](input.md). Resizes vertically only.
+- On touch screens typed text is 16px on a 20px line at every size, like Input, so iOS Safari does not zoom in on focus.
 
 <!-- docs/components/select.md -->
 
@@ -1139,7 +1213,7 @@ Base UI's props pass through: `items`, `value`, `defaultValue`, `onValueChange`,
 - Label it with a [Field](field.md), or `aria-label` on the trigger.
 - Use [RadioGroup](radio-group.md) for two or three options with room to show them, and [Combobox](combobox.md) for more than about 10 or when people type to find.
 - For actions, use [Menu](menu.md).
-- `variant="ghost"` draws the trigger as a row instead of a key, for a value people switch in place, such as the current space in a sidebar. Put an icon or Avatar before `Select.Value`. In a form, keep `neutral`.
+- `variant="ghost"` draws the trigger as a row instead of a key, for a value people switch in place, such as the current space in a sidebar. In a sidebar with `mu-compact` it is 28px tall, like the rows around it. Put an icon or Avatar before `Select.Value`. In a form, keep `neutral`.
 
 ## Style
 
@@ -1552,10 +1626,11 @@ Dialog and AlertDialog have the same parts.
 interface Dialog.PopupProps extends BaseDialog.Popup.Props {
   sheet?: boolean;      // below breakpoint-sm, a sheet from the bottom; default true
   variant?: "panel" | "bare"; // default "panel"; bare: no padding, gap or X (Dialog only)
+  fullScreen?: boolean;  // covers the whole screen with square corners, at every width (Dialog only)
   closeLabel?: string;  // accessible name of the X; default "Close"
   container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
 }
-// AlertDialog.Popup takes sheet and container; it has no X and no variant.
+// AlertDialog.Popup takes sheet and container; it has no X, no variant and no fullScreen.
 ```
 
 Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal`, `disablePointerDismissal` on the root; `initialFocus`, `finalFocus` on the popup.
@@ -1568,6 +1643,8 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal`, `d
 - Escape and a backdrop click close a Dialog. While a form has unsaved input, keep it open from `onOpenChange`.
 - Focus moves into the dialog and returns to the trigger on close.
 - `variant="bare"` is for content that runs edge to edge: a search palette, a picker with its own header, an image. The content sets its own padding. Name the dialog with a `Dialog.Title` (hidden with `mu-visually-hidden` if needed) or `aria-label` on the popup; Escape and a backdrop click still close it.
+- Every Dialog has the same backdrop, `overlay`, including a search palette. There is no prop to lighten or remove it.
+- `fullScreen` is for content that needs the whole screen, such as an image viewer (`variant="bare" fullScreen`). It replaces the sheet on phones. The content handles the safe-area insets. Don't add `fixed inset-0` or `rounded-none` yourself.
 - The panel is always md: controls inside it ignore the size of a Root the Dialog is declared in (a sm Table). Pass `size` to a control inside only when it should differ.
 
 ## Style
@@ -1577,6 +1654,7 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal`, `d
 - 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`.
+- `fullScreen`: the viewport's padding goes, and the popup fills it with square corners.
 
 <!-- docs/components/drawer.md -->
 
@@ -1618,7 +1696,7 @@ interface Drawer.RootProps extends BaseDrawer.Root.Props {
 }
 interface Drawer.PopupProps extends BaseDrawer.Popup.Props {
   variant?: "panel" | "bare"; // default "panel"; bare: no padding, gap or X
-  closeLabel?: string;        // accessible name of the X; default "Close"
+  closeLabel?: string;        // accessible name of the X, or of bare's screen-reader Close; default "Close"
   container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
 }
 ```
@@ -1629,15 +1707,16 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `onOpenChan
 
 - Use it for content that belongs beside the page rather than on top of it: the navigation sidebar below `breakpoint-md`, or the details of one item. For a decision or a short form, use [Dialog](dialog.md), which already becomes a sheet from the bottom on phones.
 - Name it: a `Drawer.Title`, hidden with `mu-visually-hidden` when the content names itself, or `aria-label` on the popup.
-- `variant="bare"` is for content that lays itself out, such as an app's sidebar. Set its width with `className` when the content has its own, such as `sidebar-width`.
+- `variant="bare"` is for content that lays itself out, such as an app's sidebar. Set its width with `className` when the content has its own, such as `sidebar-width`. From the start or end, its content is exactly the drawer's height: give the app's sidebar `height: 100%` and let a region inside it scroll (`flex: 1; min-height: 0; overflow-y: auto`). Don't set `100dvh` or add a Close or an edge yourself: bare has a Close for screen readers (out of the tab order; keyboards use Escape) and the drawer draws its own edge.
 - Close it when people pick a destination: wrap each link in `Drawer.Close render={<a … />}`, or close it from the router.
 - Escape, a backdrop click and a swipe toward its edge close it. Focus moves in and returns to the trigger.
 - The panel is always md, as a Dialog is.
 
 ## Style
 
-- `surface` with `shadow-pop`, full height and `drawer-width` (320px) wide from the start or end edge, 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`.
+- `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`.
+- `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.
 
@@ -1691,7 +1770,7 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on
 
 - Use it for a few controls that belong to one thing. For a list of actions, use [Menu](menu.md). For a decision that blocks the page, use [Dialog](dialog.md).
 - Give it a `Popover.Title`, or `aria-label` on the popup.
-- `variant="list"` is for a panel made of rows, such as an account panel (a name, then links) or a scope picker with a header. Draw the rows with `menuClasses().item` and the lines between them with `menuClasses().separator`. When the rows are only actions, use a [Menu](menu.md) instead.
+- `variant="list"` is for a panel made of rows, such as an account panel (a name, then links) or a scope picker with a header. Draw the rows with `menuClasses().item` and the lines between them with `menuClasses().separator`. When the rows are only actions, use a [Menu](menu.md) instead. For 28px rows beside a sidebar with `mu-compact`, put `mu-compact` on the popup too: `className="mu-compact"`.
 - The panel is always md: controls inside it ignore the size of the Root around the Popover (a sm toolbar). Pass `size` to a control inside only when it should differ.
 - It closes on Escape and on a click outside; focus returns to the trigger.
 - An app's own floating panel, such as an emoji picker, takes `popoverClasses()`. See [Class functions](../custom-components.md#class-functions).
@@ -1879,31 +1958,32 @@ import { Hash, Lock } from "lucide-react";
 <Badge icon={<Hash />}>reading</Badge>
 <Badge tone="outline" icon={<Lock />}>Private</Badge>
 <Badge tone="success">Synced</Badge>
+<Badge tone="primary">New</Badge>
 ```
 
 ## Props
 
 ```ts
 interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
-  tone?: Tone | "outline"; // default "neutral"
+  tone?: Tone | "outline" | "primary"; // default "neutral"
   icon?: IconElement;
   children: React.ReactNode; // one or two words
   render?: React.ReactElement;
 }
 
-function badgeClasses(options?: { tone?: Tone | "outline" }): string;
+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.
+- 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 badge is not a button. A clickable tag filter is a [Toggle](toggle.md).
 - An app's own element that should look like a badge, such as a tag that is also a link, takes `badgeClasses()`. See [Class functions](../custom-components.md#class-functions).
 
 ## Style
 
 - `control-xs` (20px) tall, `radius-sm` (never a pill), `label-xs` text (12px, 500), optional `icon-xs` (12px) icon at a 1.25px stroke. It lines up with xs controls.
-- `neutral`: `ink` on `well`. Status tones: their `-soft` background with full-strength text.
+- `neutral`: `ink` on `well`. `primary`: `on-primary` on `primary`, the colors of a primary Button. Status tones: their `-soft` background with full-strength text.
 
 <!-- docs/components/kbd.md -->
 
@@ -2100,6 +2180,7 @@ No Base UI part: these are styled native table elements.
 | `Table.Row` | `<tr>` |
 | `Table.Head` | `<th scope="col">`. Takes `num` |
 | `Table.Cell` | `<td>`. Takes `num` and `muted` |
+| `Table.Actions` | A `<div>` that lays two or more row actions side by side in one Cell |
 
 ## Props
 
@@ -2124,6 +2205,16 @@ Every native attribute passes through.
 - Use it for data with columns. Lists of content (notes, comments) are [entries](../patterns.md#entry), not rows.
 - Set `num` on a numeric column's Head and on its Cells.
 - Put row actions in the last column as a ghost [Menu](menu.md) trigger, named for its row. Give that column's Head text in `mu-visually-hidden`.
+- Two or three frequent actions, such as Edit and Delete, go in a `Table.Actions` inside that Cell, as ghost Buttons. Put a single Button straight in the Cell:
+
+  ```tsx
+  <Table.Cell num>
+    <Table.Actions>
+      <Button variant="ghost" size="sm" icon={<Pencil />} aria-label={`Edit ${hook.name}`} />
+      <Button variant="ghost" size="sm" icon={<Trash2 />} aria-label={`Delete ${hook.name}`} />
+    </Table.Actions>
+  </Table.Cell>
+  ```
 - Name the table with a Caption, or `aria-label` on the root.
 - Sort, select and paginate in the app. The table has no data props.
 - Set `bordered` when the table is one section of a settings or admin page, next to other sections or a [List](list.md), so it reads as one block. Leave it off when the table is the page's main content. Never put a bordered table inside a Dialog or Popover.
@@ -2131,9 +2222,9 @@ Every native attribute passes through.
 ## Style
 
 - 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 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.
+- `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.
-- Cells: `caption` at sm and `body` at md, with tabular numbers. Rows are 34 or 40px; a Button in a cell overlaps the padding, so rows keep that height.
+- 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.
 
 <!-- docs/components/list.md -->
@@ -2173,6 +2264,7 @@ No Base UI part: these are styled native list elements.
 | --- | --- |
 | `List.Root` | A `<ul>` with a `line` edge and rounded corners. Takes `size` |
 | `List.Item` | An `<li>`: one row, divided from the next by a `line` |
+| `List.ItemButton` | A `<button>` that fills its Item, for a row that acts as a whole. Takes `render` for a link |
 
 ## Props
 
@@ -2190,13 +2282,27 @@ Every native attribute passes through.
 - A settings row is a horizontal [Field](field.md) inside the Item. A record row lays out its own content: the record's text first, its actions at the end (a ghost [Menu](menu.md) trigger named for the row, or one or two Buttons).
 - Name the list: `aria-labelledby` pointing at the section title above it, or `aria-label`.
 - Don't nest Lists, and don't put a List inside a Dialog or Popover: those are boxes already. Use horizontal Fields stacked `space-4` apart there.
-- Rows are not links or buttons. To open a record, put a Link or a Button in the row.
+- When the whole row opens something (a space, a record's page), put one `List.ItemButton` in the Item and the row's content inside it. For a link, `render={<a href="…" />}` or the router's link. Don't give a button negative margins to fill the row yourself.
+- A row with an ItemButton has no other controls: buttons don't nest. A row with its own actions (a Menu trigger, a Switch) keeps them in the Item and opens the record from a Link in its text.
+
+  ```tsx
+  <List.Root aria-label="Spaces">
+    {spaces.map((space) => (
+      <List.Item key={space.id}>
+        <List.ItemButton render={<a href={`/s/${space.id}`} />}>
+          <Avatar.Root size="sm">…</Avatar.Root>
+          {space.name}
+        </List.ItemButton>
+      </List.Item>
+    ))}
+  </List.Root>
+  ```
 - An empty list shows the [empty state](../patterns.md#empty-state) in place of the List.
 
 ## 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: rows don't act on click.
+- 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`.
 
 <!-- docs/components/prose.md -->
@@ -2240,8 +2346,8 @@ Every native attribute passes through.
 
 ## Style
 
-- Text: 16px on a 24px line (`sm`: 14 on 22), weight 400, `ink`. Blocks are `space-3` apart.
-- Headings: `h1` 20/28px, `h2`–`h6` 16/24px; all weight 600, 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.
+- 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.
+- 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.
@@ -2249,7 +2355,7 @@ Every native attribute passes 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.
-- Sizes are custom properties set on `.mu-prose` in the foundation (`--prose-fs`, `--prose-lh`, heading sizes).
+- 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 -->
 
@@ -2486,7 +2592,7 @@ const [confirming, setConfirming] = useState(false);
 </List.Root>
 ```
 
-A horizontal Field puts the setting's name first and the Switch or Select at the end of the row. A [List](components/list.md) boxes the rows of one section and divides them with lines. Inside a Dialog, leave out the List and stack the Fields. For a short list of options under one heading (notification types), a Switch or Checkbox inside its `Field.Label` also works.
+A horizontal Field puts the setting's name first, at weight 400, and the Switch or Select at the end of the row. The section title above it is the `label` (500). A [List](components/list.md) boxes the rows of one section and divides them with lines. Inside a Dialog, leave out the List and stack the Fields. For a short list of options under one heading (notification types), a Switch or Checkbox inside its `Field.Label` also works.
 
 No Save button and no toast: the Switch shows the result. If saving fails, move the Switch back and show a danger Toast.
 
@@ -2514,6 +2620,49 @@ One `Tooltip.Provider` around the toolbar (or the app) so moving along it opens
 - Show one or two frequent actions as xs or sm ghost Buttons beside it, each with a Tooltip.
 - On an entry the trigger appears on hover; on touch screens it is always visible (see [Entry](patterns.md#entry)).
 
+### A sidebar navigation row
+
+The package ships no navigation component: the sidebar's rows are the app's links. For 28px rows, put `mu-compact` on the sidebar: every md control and row inside it is `control-compact` (28px) tall instead of 32px, with md text, icons, padding and radius. The app's own rows read the row variables, so they match the package's controls beside them:
+
+```tsx
+<aside className="app-sidebar mu-compact">
+  <Select.Root value={space} onValueChange={setSpace}>
+    <Select.Trigger variant="ghost">…</Select.Trigger>
+    …
+  </Select.Root>
+  <Button variant="primary" icon={<Plus />}>New note</Button>
+  <nav className="app-nav mu-s-md mu-base" aria-label="Main">
+    <a className="app-nav-row mu-focus" href="/" aria-current={path === "/" ? "page" : undefined}>
+      <House className="mu-icon" aria-hidden />
+      Home
+    </a>
+    …
+  </nav>
+</aside>
+```
+
+```css
+.app-nav { display: grid; gap: var(--mu-inset); }
+.app-nav-row {
+  display: flex;
+  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);
+  border-radius: var(--mu-row-radius);
+  color: var(--mu-ink-muted);
+  text-decoration: none;
+}
+.app-nav-row:hover, .app-nav-row[aria-current="page"] { color: var(--mu-ink); 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 and weight 500. Never set the `--mu-row-*` variables or the size tokens yourself; `mu-compact` is the only way to change a row's height.
+- 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`.
+
 ### Buttons over a photo
 
 Controls over an image or a video sit in a dark-theme scope, so they read on any picture in both app themes:
@@ -2530,8 +2679,37 @@ 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.
-- Leave the scope's own background transparent; the keys carry their own fill and shadow.
-- A full-screen viewer is a Dialog with `variant="bare"`; put the scope inside its Popup.
+- When the scope holds only Buttons, leave its own background transparent: the keys carry their own fill and shadow.
+- A full-screen viewer is a Dialog with `variant="bare" fullScreen`; put the scope inside its Popup.
+
+### Text over a photo
+
+Plain text over a picture, such as a viewer's "3 / 12" counter or its zoom level, has no fill of its own, so it needs one. Put it in the same dark-theme scope and give the text a `surface` pill:
+
+```tsx
+<div className="app-viewer-controls" data-theme="dark">
+  <span className="app-viewer-label mu-label-sm" aria-live="polite">{index + 1} / {count}</span>
+  <Button icon={<ZoomIn />} aria-label="Zoom in" onClick={zoomIn} />
+</div>
+```
+
+```css
+.app-viewer-label {
+  display: inline-flex;
+  align-items: center;
+  height: var(--mu-control-md);
+  padding: 0 var(--mu-space-3);
+  border-radius: var(--mu-radius-md);
+  color: var(--mu-ink);
+  background-color: var(--mu-surface);
+  box-shadow: var(--mu-shadow-pop);
+  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.
+- 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.
 
 ### Inside a shadow root or a host page
 
@@ -2545,7 +2723,7 @@ In an extension or an embed, pass the same `container` to every `Popup` and to `
 ## Size
 
 - **Set `size` once, on the outermost part that takes it.** `Menu.Root`, `Select.Root`, `Combobox.Root`, `Tabs.Root`, `Collapsible.Root`, `Table.Root`, `Field.Root`, `Fieldset.Root`, `RadioGroup` and `ToggleGroup` pass their size to every part and every Button, Toggle, Checkbox or Input inside them. Don't repeat it on the parts.
-- **Pick by place, not by importance.** `md` everywhere by default, including dialogs, forms, onboarding, marketing pages and the app's sidebar (its navigation rows and its main button). `sm` for dense toolbars, table rows and filters inside panels. `xs` for secondary actions beside 13px text (entry footers, row actions). See [Control sizes](layout.md#control-sizes).
+- **Pick by place, not by importance.** `md` everywhere by default, including dialogs, forms, onboarding, marketing pages and an app's sidebar. A sidebar with 28px rows puts `mu-compact` on itself, which makes md 28px inside it; see [A sidebar navigation row](#a-sidebar-navigation-row). `sm` for dense toolbars, table rows and filters inside panels. `xs` for secondary actions beside 13px text (entry footers, row actions). See [Control sizes](layout.md#control-sizes).
 - **Never make a control bigger to make it stronger.** Emphasis is the `primary` variant.
 - **Don't mix sizes in one row.** A Button beside an Input has the Input's size.
 - **Dialogs and Popovers start at md.** Their panels are md wherever they are declared, so a Dialog inside a `Table.Root size="sm"` still has md Buttons and fields. Set `size` inside the panel only for a part that should differ.
@@ -2557,7 +2735,7 @@ In an extension or an embed, pass the same `container` to every `Popup` and to `
 - **One `primary` Button per view.** A view is a page, a dialog or a popover. Everything else is `neutral`, or `ghost` in toolbars and rows.
 - **`danger` confirms; it never starts.** The first click on "Delete" is a Menu item with `danger` or a neutral Button; the `danger` Button lives in the AlertDialog that follows.
 - **Dialog footers** are a ghost Cancel, then the action, named with its verb ("Delete note", "Create"), never "OK" or "Yes".
-- **Tone is status only.** Badge and Toast tones say success, warning or danger. Don't use them to highlight, decorate or color-code categories.
+- **Tone is status only.** Badge and Toast tones say success, warning or danger. Don't use them to highlight, decorate or color-code categories. The one exception is Badge `tone="primary"`: ink, for the single label in a view that should stand out, such as New.
 - **Links are the only blue.** Don't color text, icons or backgrounds with `accent`.
 
 ## Accessibility checklist
@@ -2599,10 +2777,20 @@ Run through it for every screen.
 | A Checkbox that saves at once | A Switch |
 | A Select with 30 options | A Combobox |
 | A Select with two options and room to spare | A RadioGroup |
-| A boxed card around each item | Whitespace, a section title, or a Separator. Rows of settings or records go in one [List](components/list.md) |
+| A boxed card around each item | Whitespace, a section title, or a Separator. Rows of settings or records go in one [List](components/list.md); a small form among them in a `bordered` [Form](components/form.md) |
 | An icon after a Button's label inside `children` | `iconEnd` |
 | A `<button>` with its own classes as a row in a Popover | `menuClasses().item`, in a Popover with `variant="list"` |
 | A Dialog with `className` that removes its padding and X | `variant="bare"` |
+| A local box (a "settings panel") around a small form on a settings page | `Form.Root bordered` with `Form.Footer` |
+| A Dialog with `fixed inset-0 rounded-none` | `variant="bare" fullScreen` |
+| A lighter or clear backdrop for one Dialog, such as a search palette | The standard backdrop: every Dialog dims the page the same way |
+| A blue or custom-colored New badge | `tone="primary"` |
+| A wrapper with negative margins around two Buttons in a table cell | `Table.Actions` |
+| A button with negative margins to make a List row clickable | `List.ItemButton` |
+| `w-full` on a ToggleGroup and `flex-1` on its Toggles | `fullWidth` |
+| `h-dvh`, a `border-e` or your own Close on a bare Drawer's content | Nothing: bare does these; give your content `height: 100%` |
+| A 28px row class, or `--mu-row-height` set by hand | `mu-compact` on the sidebar or popup |
+| 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 |
 | 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 |
@@ -2634,7 +2822,8 @@ Names and parts from other libraries and where they go.
 | Tooltip with a `title` or `content` prop | [Tooltip](components/tooltip.md) parts: Root, Trigger, Popup |
 | Snackbar, Toaster, sonner's `toast()` | [Toast](components/toast.md) and `Toast.useToastManager().add()` |
 | Toast `variant="destructive"` | `type: "danger"` |
-| Card, Paper, Panel | No component: spacing, a section title and [Separator](components/separator.md). For a boxed group of rows, [List](components/list.md) |
+| Card, Paper, Panel | No component: spacing, a section title and [Separator](components/separator.md). For a boxed group of rows, [List](components/list.md); for a boxed small form, a `bordered` [Form](components/form.md) |
+| Form (Base UI, React Hook Form wrappers) | [Form](components/form.md), with [Field](components/field.md)s inside |
 | Divider | [Separator](components/separator.md) |
 | Chip, Tag | [Badge](components/badge.md) to show, [Toggle](components/toggle.md) to filter |
 | SegmentedControl, RadioButtons in a row | [ToggleGroup](components/toggle-group.md) without `multiple` |
@@ -2664,10 +2853,10 @@ How the components go together. Each product builds its screens from these patte
 ## 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.
-- Sidebar rows (navigation links, a space switcher, the main "New" button) are md: 32px tall, `label` text, md icons. There is no 28px row; don't build one with custom padding.
+- 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).
 - 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 use `label` for the name and `caption` in `ink-muted` for the description.
+- 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.
 
 ## Form
 
@@ -2677,6 +2866,7 @@ How the components go together. Each product builds its screens from these patte
 - A form that saves at once (settings) uses switches and has no Save button. A form with a Save button uses checkboxes.
 - On a settings page, each section is a title and a [List](components/list.md) of horizontal Fields: the setting's name at the start, its Switch or Select at the end. A section of records (tokens, webhooks) is a List, or a `bordered` [Table](components/table.md) when the records have columns.
 - Errors appear under the field, in words that say how to fix it.
+- A small form on a settings page, among Lists ("Add a tag rule", a reactions picker), is a `bordered` [Form](components/form.md): a title, its fields, and the buttons in a footer bar.
 
 ## Entry
 
@@ -2933,6 +3123,7 @@ Apply these classes to an app's own elements. Don't override their rules: the pr
 | `mu-s-xs` | The xs size row: 20px | Secondary actions beside 13px text |
 | `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 |
@@ -2945,7 +3136,7 @@ Apply these classes to an app's own elements. Don't override their rules: the pr
 | `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-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.5px stroke | A Lucide icon beside 14px or 16px 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 parts |
 | `mu-caption` | 13 / 18px, 400 | Secondary text |
@@ -2967,13 +3158,15 @@ A size row class sets these variables on its element, and children inherit them.
 | `--mu-row-padding-icon` | 4px | 6px | 10px |
 | `--mu-row-font-size` | 12px | 13px | 14px |
 | `--mu-row-line-height` | 16px | 18px | 20px |
+| `--mu-row-field-font-size` | 12px | 13px | 14px |
+| `--mu-row-field-line-height` | 16px | 18px | 20px |
 | `--mu-row-radius` | 4px | 4px | 6px |
 | `--mu-row-gap` | 4px | 4px | 6px |
 | `--mu-row-icon` | 12px | 14px | 16px |
-| `--mu-row-icon-stroke` | 1.25px | 1.25px | 1.5px |
+| `--mu-row-icon-stroke` | 1.25px | 1.25px | 1.25px |
 | `--mu-row-check-box` | 14px | 16px | 18px |
 
-`--mu-row-padding-icon` is the padding on the side of a control that starts or ends with an icon.
+`--mu-row-padding-icon` is the padding on the side of a control that starts or ends with an icon. Inside `mu-compact`, the md `--mu-row-height` is 28px. `--mu-row-field-font-size` and `--mu-row-field-line-height` are for text people type; on touch screens they are 16px and 20px at every size, so iOS Safari does not zoom in when a field takes focus.
 
 ```css
 .app-tag-input-chip {