@usememos/ui 26.11.1 → 26.11.3

package/llms-full.txt

@@ -25,7 +25,7 @@ It is not a general-purpose UI library for outside developers. Components are ge
 | [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 28 components, what was left out, and one page per component |
+| [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 |
@@ -70,7 +70,7 @@ It is not a general-purpose UI library for outside developers. Components are ge
 ## What to avoid
 
 - A brand hue on controls, or blue anywhere at rest except links.
-- Cards and boxes around content. Group with spacing, a heading and a `Separator`.
+- Cards and boxes around content. Group with spacing, a heading and a `Separator`. The exceptions are rows of settings or records: a [List](components/list.md), or a [Table](components/table.md) with `bordered`.
 - Textures, glass or blur behind text, and neumorphism.
 - Pills for buttons, inputs or badges.
 - Color as the only signal. Status colors always come with a word or an icon.
@@ -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 and sheets. 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 |
@@ -417,6 +420,7 @@ Buttons, inputs and badges are never pills.
 | `tooltip-width` | 240px | Maximum width of a tooltip |
 | `toast-width` | 360px | Width of a toast from `breakpoint-sm` up |
 | `dialog-width` | 440px | Default width of a dialog |
+| `drawer-width` | 320px | Default width of a drawer from the start or end edge |
 
 - `content-width` and `sidebar-width` are suggested values for an app's page layout. No component uses them. An app that needs another width uses its own value instead of overriding the token.
 - The other widths are component defaults. To change one instance, pass `className` or `style` to it.
@@ -427,7 +431,7 @@ Two breakpoints. They are values, not tokens: CSS custom properties can't be use
 
 | Breakpoint | Value | Usage |
 | --- | --- | --- |
-| breakpoint-sm | 640px | Below this: one column, dialogs and menus become sheets, toasts sit bottom-center |
+| breakpoint-sm | 640px | Below this: one column, dialogs and menus become sheets, toasts span the top |
 | breakpoint-md | 1024px | From this: the sidebar is fixed and the content column is centered |
 
 ```css
@@ -525,7 +529,11 @@ import { Pin, Trash2 } from "lucide-react";
 - **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, add `className="mu-icon"` to get the same size and stroke rules.
+- **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.
+
+  ```tsx
+  <h2 className="mu-title"><Inbox className="mu-icon-sm" aria-hidden /> Inbox</h2>
+  ```
 
 ## Built-in glyphs
 
@@ -540,6 +548,7 @@ These components bring their own Lucide icons, so the app doesn't pass them:
 | Collapsible | `ChevronRight` (turns 90° when open) |
 | Toast | `Info`, `CircleCheck`, `TriangleAlert`, `CircleAlert`, `X` |
 | Field | `CircleAlert` (errors) |
+| Dialog, Drawer | `X` |
 | Link | `ArrowUpRight` (external links) |
 
 ## Missing icons
@@ -550,15 +559,15 @@ When Lucide doesn't have an icon, draw it on Lucide's 24px grid with 2px round s
 
 # Components
 
-28 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), [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), [Prose](prose.md), plus [Lucide icons](../icons.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) |
 
 ## Page template
 
@@ -575,7 +584,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, not boxes.
+- **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.
@@ -599,8 +608,12 @@ The short version. [Using the components](../usage.md) has the full decision gui
 | A list of actions for one thing | Menu |
 | A few controls that belong to one thing | Popover |
 | A decision that blocks the page | Dialog |
+| Navigation or details that slide in from an edge | Drawer |
 | Name an icon-only control | Tooltip |
 | 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 |
@@ -638,7 +651,8 @@ import { Plus } from "lucide-react";
 interface ButtonProps extends BaseButton.Props {
   variant?: "primary" | "neutral" | "ghost" | "danger"; // default "neutral"
   size?: Size;
-  icon?: IconElement;
+  icon?: IconElement;    // before the label
+  iconEnd?: IconElement; // after the label: "Show more" with a chevron, "Next" with an arrow
   loading?: boolean;
   loadingLabel?: string; // accessible name while loading, such as "Saving"
 }
@@ -653,6 +667,7 @@ Wraps Base UI's [Button](https://base-ui.com/react/components/button): `disabled
 - Label with a verb in sentence case ("Save", "Copy link"). With only an `icon`, pass `aria-label` and add a [Tooltip](tooltip.md) with the same text.
 - `primary`: the one action a view exists for, at most one per view. `neutral`: every other action. `ghost`: toolbars, dense rows, the "More actions" trigger. `danger`: confirming a destructive action inside a dialog, never as a first click.
 - Use `loading` for any action that waits on a server.
+- `iconEnd` says where the action leads or that it opens something (a chevron, an arrow). Don't put an icon in `children`: the label is one text span, so it would wrap. Use `icon` for what the action is.
 - A link that should look like a button stays an `<a>` with `buttonClasses()`; Base UI doesn't render links through Button:
 
   ```tsx
@@ -660,11 +675,12 @@ Wraps Base UI's [Button](https://base-ui.com/react/components/button): `disabled
   ```
 
 - Prefer saying why an action is unavailable over disabling it.
+- Over a photo or video (an image viewer's close and arrows, a cover's edit button), use `neutral` Buttons inside an element with `data-theme="dark"`, so they are dark keys whatever the app's theme. There is no media variant. See [the recipe](../usage.md#buttons-over-a-photo).
 
 ## 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.
-- Only an icon: square. The icon side has 2px less padding.
+- 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.
@@ -705,6 +721,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.
+- 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 -->
 
@@ -744,7 +761,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
 }
 ```
 
@@ -757,9 +775,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. 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.
 
@@ -798,7 +818,7 @@ import { Ellipsis, FolderInput, Pin, Trash2 } from "lucide-react";
 | `Menu.Root` | `Menu.Root` | Nothing. Groups a trigger and its popup. Takes `size` |
 | `Menu.Trigger` | `Menu.Trigger` | The control that opens it, usually a Button through `render` |
 | `Menu.Popup` | `Menu.Portal`, `Positioner`, `Popup` | The list, a `<div role="menu">` portaled to the body. Also a submenu's list |
-| `Menu.Item` | `Menu.Item` | One action. Takes `icon`, `shortcut`, `danger` |
+| `Menu.Item` | `Menu.Item` | One action. Takes `icon`, `shortcut`, `description`, `danger` |
 | `Menu.CheckboxItem` | `Menu.CheckboxItem` with its indicator | An option that turns on or off, with a check at the end |
 | `Menu.RadioGroup` | `Menu.RadioGroup` | Groups RadioItems; holds the value |
 | `Menu.RadioItem` | `Menu.RadioItem` with its indicator | One choice, with a check at the end when chosen |
@@ -821,12 +841,13 @@ 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
   danger?: boolean;           // destructive: red text
 }
-// CheckboxItem and RadioItem take icon and shortcut too. SubmenuTrigger takes icon.
+// CheckboxItem and RadioItem take icon, shortcut and description too. SubmenuTrigger takes icon.
 
 function menuClasses(options?: { size?: "sm" | "md" }): {
-  popup: string; item: string; dangerItem: string; label: string;
+  popup: string; item: string; dangerItem: string; label: string; text: string; description: string;
   shortcut: string; separator: string; groupLabel: string;
 };
 ```
@@ -837,16 +858,18 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on
 
 - Act in `onClick`. Labels are verbs in sentence case.
 - Put destructive items last, after a Separator, with `danger`. Confirm them with an [AlertDialog](dialog.md).
-- CheckboxItems and RadioItems stay open on click, so people can change several.
+- CheckboxItems and RadioItems stay open on click, so people can change several. A RadioItem that picks one setting and is done (a visibility picker) takes `closeOnClick`.
+- `description` explains a choice in a few words ("Only you can see it"). The item is named by its label and described by the description. Keep descriptions to one short line; they wrap when longer.
 - For picking a value saved with a form, use [Select](select.md). For content that stays open while people use it (inputs, text, several controls), use [Popover](popover.md). See [Menu or Popover](../usage.md#menu-or-popover).
 - To open a Dialog from an item, keep the Dialog outside the Menu and control its `open`. See [the recipe](../usage.md#a-menu-item-that-opens-a-dialog).
 - Arrow keys move the highlight; typing jumps to an item; Escape and an outside click close it; focus returns to the trigger.
-- An app's own floating list, such as an editor's suggestion list, takes `menuClasses()`: `popup` on the list, `item` on each row, and `data-highlighted` on the active row. See [Class functions](../custom-components.md#class-functions).
+- An app's own floating list, such as an editor's suggestion list, takes `menuClasses()`: `popup` on the list, `item` on each row, and `data-highlighted` on the active row. `item` works on a `<div>`, a `<button>` or an `<a>`: it resets their width, border, fill, font and centered text. See [Class functions](../custom-components.md#class-functions).
 
 ## Style
 
 - `mu-popup` with `space-1` padding, at least `menu-width` wide, scrolls when taller than the space available.
-- Rows are a control height (24 or 32px), text weight 400; icons in `ink-muted`; the shortcut right-aligned in `ink-muted`.
+- Rows are a control height (24 or 32px), 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.
 - The highlighted row uses `hover`. Disabled rows fade to 45%. `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.
@@ -890,6 +913,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
@@ -923,7 +1012,7 @@ import { Checkbox, Field, Fieldset, Input } from "@usememos/ui";
 
 | Part | Base UI part | Renders |
 | --- | --- | --- |
-| `Field.Root` | `Field.Root` | A `<div>` around one control. Takes `size` and passes it to the control |
+| `Field.Root` | `Field.Root` | A `<div>` around one control. Takes `size` and passes it to the control, and `orientation` |
 | `Field.Label` | `Field.Label` | A `<label>`: above a text control, or around a Checkbox, Switch or Radio |
 | `Field.Item` | `Field.Item` | A `<div>` around one option of a radio or checkbox group in one field |
 | `Field.Description` | `Field.Description` | A `<p>` of help under the control |
@@ -936,6 +1025,7 @@ import { Checkbox, Field, Fieldset, Input } from "@usememos/ui";
 ```ts
 interface Field.RootProps extends BaseField.Root.Props {
   size?: "sm" | "md"; // passed to the control inside
+  orientation?: "vertical" | "horizontal"; // default "vertical"; horizontal: label first, control at the end of the row
 }
 interface Fieldset.RootProps extends BaseFieldset.Root.Props {
   size?: "sm" | "md"; // passed to every control inside
@@ -949,13 +1039,23 @@ Base UI's props pass through: `name`, `invalid`, `disabled`, `validate`, `valida
 - Set `invalid` from the app when the server rejects a value; use `validate` for client checks.
 - Write the error as how to fix the problem.
 - Put a Checkbox, Switch or Radio inside its `Field.Label`, so clicking the text toggles it.
+- For a settings row (a name, an optional description, and a Switch or Select at the end), use `orientation="horizontal"` and put the control after `Field.Label` and `Field.Description`, not inside the label:
+
+  ```tsx
+  <Field.Root orientation="horizontal">
+    <Field.Label>Compact mode</Field.Label>
+    <Field.Description>Show more notes on one screen.</Field.Description>
+    <Switch checked={compact} onCheckedChange={setCompact} />
+  </Field.Root>
+  ```
 - A radio group is one field: `Field.Root` holds `Fieldset.Root render={<RadioGroup />}`, and each radio sits in a `Field.Item`. See [RadioGroup](radio-group.md).
-- Stack fields `space-4` apart. Group them with a heading or a Fieldset, not boxes.
+- Stack fields `space-4` apart. Group them with a heading or a Fieldset. On a settings page, put horizontal Fields in a [List](list.md), one per Item.
 - Never use a placeholder as the only label.
 
 ## 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, 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 -->
@@ -999,7 +1099,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.
 
@@ -1042,6 +1142,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 -->
 
@@ -1076,7 +1177,7 @@ const visibility = { private: "Private", workspace: "Workspace", public: "Public
 | Part | Base UI part | Renders |
 | --- | --- | --- |
 | `Select.Root` | `Select.Root` | Nothing. Holds the value and a hidden input for forms. Takes `size` |
-| `Select.Trigger` | `Select.Trigger` with `Select.Icon` | A neutral key with a chevron at the end, a `<button role="combobox">` |
+| `Select.Trigger` | `Select.Trigger` with `Select.Icon` | A neutral key with a chevron at the end, a `<button role="combobox">`. Takes `variant` |
 | `Select.Value` | `Select.Value` | The chosen item's label, or the placeholder |
 | `Select.Popup` | `Select.Portal`, `Positioner`, `Popup`, `List`, scroll arrows | The list, portaled to the body |
 | `Select.Item` | `Select.Item` with `ItemText` and `ItemIndicator` | One option, with a check at the end when chosen. Takes `icon` |
@@ -1090,6 +1191,9 @@ const visibility = { private: "Private", workspace: "Workspace", public: "Public
 type Select.RootProps<Value, Multiple> = BaseSelect.Root.Props<Value, Multiple> & {
   size?: "sm" | "md";
 };
+interface Select.TriggerProps extends BaseSelect.Trigger.Props {
+  variant?: "neutral" | "ghost"; // default "neutral"; ghost: a flat row, for a switcher in a sidebar or toolbar
+}
 interface Select.PopupProps extends BaseSelect.Popup.Props {
   alignItemWithTrigger?: boolean; // default true: the list opens over the trigger with the chosen item on the value
   side?: Side; align?: Align; // used when alignItemWithTrigger is false
@@ -1108,10 +1212,11 @@ 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. 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
 
-- Trigger: a neutral key ([Button](button.md) `neutral`), value left-aligned, `ChevronsUpDown` in `ink-muted`. Placeholder in `ink-muted`, weight 400. Invalid: a `danger` edge.
+- 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.
 - List: `mu-popup`, `space-1` padding, at least `menu-width` and the trigger's width. Rows like [Menu](menu.md) items; the highlighted row uses `hover`.
 - Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
 
@@ -1157,6 +1262,7 @@ const tags = ["book", "design", "travel"];
 | `Combobox.Group` | `Combobox.Group` | A labeled set of items |
 | `Combobox.GroupLabel` | `Combobox.GroupLabel` | The name of a Group |
 | `Combobox.Separator` | `Combobox.Separator` | A line between groups |
+| `Combobox.Row` | `Combobox.Row` | One row of a grid, with `grid` on the root: square cells for icons or emoji |
 | `Combobox.Collection` | `Combobox.Collection` | Base UI's part, unstyled: renders one group's items from grouped `items` |
 | `Combobox.useFilter` | `Combobox.useFilter` | Base UI's hook: locale-aware `contains`, `startsWith`, `endsWith` for `filter` |
 
@@ -1191,6 +1297,26 @@ Base UI's props pass through: `items`, `value`, `defaultValue`, `onValueChange`,
 - Use it for more than about 10 options, or when people type to find one. For fewer, use [Select](select.md).
 - Typing opens the list. Up and Down move the highlight, Enter picks, Escape closes; focus stays in the input.
 - Multi-select (chips) is not built.
+- With `inline` on the root, the list sits in the page instead of a popup: put `Input`, `Empty` and `List` directly inside the root, with no `Popup`. The root is then open unless you pass `open`, and the Input drops its chevron. Use it for a picker inside a Popover or a Dialog.
+- With `grid` on the root, split the filtered items into rows of a fixed count and wrap each in `Combobox.Row`. Arrow keys then move across rows and columns, and Enter picks. Give each cell an `aria-label`. This is the icon and emoji picker:
+
+  ```tsx
+  <Combobox.Root items={icons} inline grid value={icon} onValueChange={pick} inputValue={query} onInputValueChange={setQuery} itemToStringLabel={(item) => item.label}>
+    <Combobox.Input placeholder="Find an icon" aria-label="Find an icon" />
+    <Combobox.Empty>No icons found</Combobox.Empty>
+    <Combobox.List aria-label="Icons">
+      {rows(icons.filter((item) => contains(item.label, query)), 8).map((row, index) => (
+        <Combobox.Row key={index}>
+          {row.map((item) => (
+            <Combobox.Item key={item.value} value={item} aria-label={item.label}>{item.icon}</Combobox.Item>
+          ))}
+        </Combobox.Row>
+      ))}
+    </Combobox.List>
+  </Combobox.Root>
+  ```
+
+  The rows are rendered by the app, so filter them with the same query: keep it in `inputValue` and `onInputValueChange`, and match with `useFilter().contains`.
 
 ## Style
 
@@ -1198,6 +1324,7 @@ Base UI's props pass through: `items`, `value`, `defaultValue`, `onValueChange`,
 - List: `mu-popup`, `space-1` padding, as wide as the input and at least `menu-width`, at most `list-height` (240px) tall, then it scrolls.
 - Rows are a control height, 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.
+- 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.
 
 <!-- docs/components/checkbox.md -->
@@ -1497,10 +1624,12 @@ Dialog and AlertDialog have the same parts.
 ```ts
 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.
+// 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.
@@ -1512,6 +1641,9 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal`, `d
 - Use AlertDialog for confirmations; see the [confirmation pattern](../patterns.md#confirmation). Open it from a Menu item with `open` and `onOpenChange`.
 - 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
@@ -1520,6 +1652,72 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal`, `d
 - 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.
 - 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 -->
+
+# Drawer
+
+A panel that slides in from one edge of the screen over a dimmed backdrop, such as a navigation sidebar on a phone or the details of one item.
+
+## Example
+
+```tsx
+import { Button, Drawer } from "@usememos/ui";
+import { Menu } from "lucide-react";
+
+<Drawer.Root side="start" open={open} onOpenChange={setOpen}>
+  <Drawer.Trigger render={<Button variant="ghost" icon={<Menu />} aria-label="Open navigation" />} />
+  <Drawer.Popup variant="bare">
+    <Drawer.Title className="mu-visually-hidden">Navigation</Drawer.Title>
+    <AppSidebar />
+  </Drawer.Popup>
+</Drawer.Root>
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `Drawer.Root` | `Drawer.Root` | Nothing. Holds the open state. Takes `side` |
+| `Drawer.Trigger` | `Drawer.Trigger` | The control that opens it, usually a Button through `render` |
+| `Drawer.Popup` | `Drawer.Portal`, `Backdrop`, `Viewport`, `Popup`, `Content` | The panel against the edge, over a dimmed backdrop, portaled to the body. Adds an X unless `variant="bare"` |
+| `Drawer.Title` | `Drawer.Title` | An `<h2>` that names the drawer |
+| `Drawer.Description` | `Drawer.Description` | A `<p>` under the title |
+| `Drawer.Close` | `Drawer.Close` | A control that closes it, such as each link of a navigation drawer |
+
+## Props
+
+```ts
+interface Drawer.RootProps extends BaseDrawer.Root.Props {
+  side?: "start" | "end" | "bottom"; // the edge it slides from and swipes back to; default "end". start and end follow the text direction
+}
+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, or of bare's screen-reader Close; default "Close"
+  container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
+}
+```
+
+Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `onOpenChangeComplete`, `modal`, `disablePointerDismissal` on the root; `initialFocus`, `finalFocus` on the popup. `side` replaces Base UI's `swipeDirection`; snap points are not supported.
+
+## Rules
+
+- 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`. 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, 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.
 
 <!-- docs/components/popover.md -->
 
@@ -1559,9 +1757,10 @@ import { Button, Input, Popover } from "@usememos/ui";
 interface Popover.PopupProps extends BasePopover.Popup.Props {
   side?: Side; align?: Align; // Positioner props; default side "bottom"
   container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
+  variant?: "panel" | "list"; // default "panel"; list: a Menu's padding and no gap, for rows
 }
 
-function popoverClasses(): { popup: string; title: string; description: string };
+function popoverClasses(options?: { variant?: "panel" | "list" }): { popup: string; title: string; description: string };
 ```
 
 Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on the root; `openOnHover`, `delay` on the trigger; `initialFocus`, `finalFocus` on the popup.
@@ -1570,6 +1769,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. 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).
@@ -1578,6 +1778,7 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on
 
 - `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.
+- `list`: `space-1` 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.
 
 <!-- docs/components/tooltip.md -->
@@ -1693,9 +1894,9 @@ Base UI's props pass through: `timeout` (default 5000ms) and `limit` (default 3)
 
 ## Style
 
-- `mu-popup`, `toast-width` wide, bottom-right at `space-6` from the edges; below `breakpoint-sm`, full width at `space-4`.
+- `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.
-- Newest in front; the ones behind peek out `space-2` above and shrink. Hover or focus fans them out `space-3` apart. Toasts slide in from below and can be swiped away. Under reduced motion they only fade.
+- Newest in front; the ones behind peek out `space-2` below and shrink. 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 -->
 
@@ -1756,31 +1957,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 -->
 
@@ -1970,19 +2172,21 @@ No Base UI part: these are styled native table elements.
 
 | Part | Renders |
 | --- | --- |
-| `Table.Root` | A `<table>` inside a `<div>` that scrolls sideways when the table is too wide. Takes `size`. The ref and props go to the `<table>` |
+| `Table.Root` | A `<table>` inside a `<div>` that scrolls sideways when the table is too wide. Takes `size` and `bordered`. The ref and props go to the `<table>` |
 | `Table.Caption` | `<caption>`, under the table. Names it for screen readers |
 | `Table.Header` | `<thead>` |
 | `Table.Body` | `<tbody>` |
 | `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
 
 ```ts
 interface Table.RootProps extends React.ComponentProps<"table"> {
-  size?: "sm" | "md"; // sm for dense admin lists
+  size?: "sm" | "md";  // sm for dense admin lists
+  bordered?: boolean;  // a line edge and rounded corners around the table, for a table that sits among other sections
 }
 interface Table.HeadProps extends React.ComponentProps<"th"> {
   num?: boolean; // right-aligned, for a column of numbers
@@ -2000,16 +2204,106 @@ 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.
 
 ## Style
 
-- No boxes or stripes: a `line` under the head row and between body rows. Body rows highlight with `hover`.
+- 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.
-- 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 -->
+
+# List
+
+A boxed list of rows: settings, or records such as webhooks, sessions or linked accounts.
+
+## Example
+
+```tsx
+import { Field, List, Switch } from "@usememos/ui";
+
+<h2 className="mu-label" id="preferences">Preferences</h2>
+<List.Root aria-labelledby="preferences">
+  <List.Item>
+    <Field.Root orientation="horizontal">
+      <Field.Label>Compact mode</Field.Label>
+      <Field.Description>Show more notes on one screen.</Field.Description>
+      <Switch checked={compact} onCheckedChange={saveCompact} />
+    </Field.Root>
+  </List.Item>
+  <List.Item>
+    <Field.Root orientation="horizontal">
+      <Field.Label>Show pinned first</Field.Label>
+      <Switch checked={pinnedFirst} onCheckedChange={savePinnedFirst} />
+    </Field.Root>
+  </List.Item>
+</List.Root>
+```
+
+## Parts
+
+No Base UI part: these are styled native list elements.
+
+| Part | Renders |
+| --- | --- |
+| `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
+
+```ts
+interface List.RootProps extends React.ComponentProps<"ul"> {
+  size?: "sm" | "md"; // sm for dense lists; also the size of the controls inside
+}
+```
+
+Every native attribute passes through.
+
+## Rules
+
+- Use it for settings rows and for short lists of records with an action or two each. Data with several columns goes in a [Table](table.md); content people read (notes, comments) goes in [entries](../patterns.md#entry), never in a List.
+- 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.
+- 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 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 -->
 
 # Prose
@@ -2051,8 +2345,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.
@@ -2060,7 +2354,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 -->
 
@@ -2088,6 +2382,7 @@ The most common mistake is reaching for the wrong overlay. Decide by what the fl
 | [Popover](components/popover.md) | Any small content: text, a few controls | Click on its trigger | Escape, a click outside, or its own Close | No | A share panel, a link editor, a filter panel, an explanation |
 | [Dialog](components/dialog.md) | A short form or a decision | An action | Its buttons, Escape, a backdrop click | Yes | Creating something, editing settings of one thing |
 | [AlertDialog](components/dialog.md) | A question and two buttons | An action | Only its buttons | Yes | Confirming a destructive or irreversible action |
+| [Drawer](components/drawer.md) | Navigation, or the details of one thing | A ghost button | Escape, a backdrop click, a swipe toward its edge, or a link inside | Yes | The sidebar on a phone; details beside a list |
 | [Toast](components/toast.md) | A sentence about what happened, at most one action | The app, after something happened | A timeout, its X, or its action | No | "Note archived" with Undo; "Couldn't sync" |
 
 ### Menu or Popover
@@ -2165,7 +2460,8 @@ Answer in order; the first yes decides.
 | Details or advanced settings people rarely need | [Collapsible](components/collapsible.md) | A Dialog |
 | Several sections, one open at a time | Collapsibles, controlled together | A third-party accordion |
 | Separating groups of content | `space-6` of whitespace, then a section title, then a [Separator](components/separator.md) if still unclear | A box, border or card |
-| Data with columns (tokens, users, webhooks) | [Table](components/table.md) | A list of boxes |
+| Data with columns (tokens, users, webhooks) | [Table](components/table.md), `bordered` when it is one section among others | A List with columns faked in each row |
+| Settings rows, or a few records with an action each | [List](components/list.md) | Separate boxes for each row |
 | A list of content (notes, comments) | [Entries](patterns.md#entry) | A Table |
 
 ## Picking feedback
@@ -2282,17 +2578,21 @@ const [confirming, setConfirming] = useState(false);
 ### Settings that save at once
 
 ```tsx
-<Fieldset.Root>
-  <Fieldset.Legend>Notifications</Fieldset.Legend>
-  <Field.Root>
-    <Field.Label>
-      <Switch checked={mentions} onCheckedChange={saveMentions} /> Email me when I'm mentioned
-    </Field.Label>
-    <Field.Description>Sent at most once an hour.</Field.Description>
-  </Field.Root>
-</Fieldset.Root>
+<h2 className="mu-label" id="notifications">Notifications</h2>
+<List.Root aria-labelledby="notifications">
+  <List.Item>
+    <Field.Root orientation="horizontal">
+      <Field.Label>Email me when I'm mentioned</Field.Label>
+      <Field.Description>Sent at most once an hour.</Field.Description>
+      <Switch checked={mentions} onCheckedChange={saveMentions} />
+    </Field.Root>
+  </List.Item>
+  <List.Item>…</List.Item>
+</List.Root>
 ```
 
+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.
 
 ### A toolbar
@@ -2319,6 +2619,97 @@ 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.5px 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:
+
+```tsx
+<figure className="app-viewer">
+  <img src={src} alt={alt} />
+  <div className="app-viewer-controls" data-theme="dark">
+    <Button icon={<X />} aria-label="Close" onClick={close} />
+    <Button icon={<ChevronLeft />} aria-label="Previous image" onClick={previous} />
+    <Button icon={<ChevronRight />} aria-label="Next image" onClick={next} />
+  </div>
+</figure>
+```
+
+- `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.
+- 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
 
 In an extension or an embed, pass the same `container` to every `Popup` and to `Toast.Viewport`, so popups mount inside the shadow root and pick up its styles. See [Scoping inside a host page](building.md#scoping-inside-a-host-page).
@@ -2331,7 +2722,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 and marketing pages. `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.
@@ -2343,7 +2734,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
@@ -2385,7 +2776,21 @@ 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 |
+| 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 |
 | `size` on every part of a Menu or Select | `size` on its Root |
@@ -2405,14 +2810,19 @@ Names and parts from other libraries and where they go.
 | --- | --- |
 | Modal, Dialog | [Dialog](components/dialog.md); `sheet` covers phones |
 | ConfirmDialog, AlertDialog, `window.confirm` | [AlertDialog](components/dialog.md) |
-| Drawer, Sheet | Dialog (a bottom sheet below 640px). There is no side drawer; a narrow sidebar below `breakpoint-md` is the [page pattern](patterns.md#page) |
+| Drawer, Sheet | [Drawer](components/drawer.md) from an edge; a Dialog already becomes a bottom sheet below 640px |
+| Command palette, Spotlight | Dialog with `variant="bare"` around an inline [Combobox](components/combobox.md) |
+| Lightbox, image viewer | Dialog with `variant="bare"`, its controls as neutral Buttons in a `data-theme="dark"` scope ([recipe](#buttons-over-a-photo)) |
+| List group, settings card, DataList | [List](components/list.md) |
+| Emoji or icon picker | Combobox with `inline` and `grid` |
 | DropdownMenu, ActionMenu | [Menu](components/menu.md) |
 | ContextMenu | Not built. Put the same actions in a Menu on a visible trigger |
 | HoverCard | [Popover](components/popover.md) with `openOnHover` on the trigger |
 | 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) |
+| 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` |
@@ -2441,10 +2851,11 @@ 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 sheet opened from a ghost button.
+- 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).
 - 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
 
@@ -2452,7 +2863,9 @@ How the components go together. Each product builds its screens from these patte
 - Related checkboxes or switches sit in a `Fieldset`.
 - Actions go at the end, right-aligned: a ghost Cancel, then the primary.
 - 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
 
@@ -2493,7 +2906,7 @@ Under `breakpoint-sm` (640px):
 
 - One column.
 - Dialogs and menus become sheets.
-- Toasts sit bottom-center.
+- Toasts span the top of the screen.
 - Every control keeps its 44px hit area.
 - Controls stay `md`.
 
@@ -2559,7 +2972,7 @@ An app changes only the color, shadow and font tokens. Every other token and eve
 - `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).
 - `mu-prose` styles rendered content. See [Prose](components/prose.md).
-- `mu-icon` applies icon size and stroke rules outside a component.
+- `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.
 - A size row class sets the `--mu-row-*` variables (height, padding, text, radius, gap, icon) that every part inside reads. See [Row variables](custom-components.md#row-variables).
 - Component part classes (`mu-menu-item`) are internal. An app reaches a component's look through its class function (`menuClasses()`). See [Class functions](custom-components.md#class-functions).
@@ -2671,13 +3084,13 @@ A class function returns the classes that make any element look like a component
 | `inputClasses({ size })` | A string | One-line field, such as a tag input around a native `<input>` |
 | `textareaClasses({ size })` | A string | Multi-line field, such as a content-editable editor |
 | `badgeClasses({ tone })` | A string | Label, such as a tag that is also a link |
-| `menuClasses({ size })` | `popup`, `item`, `dangerItem`, `label`, `shortcut`, `separator`, `groupLabel` | Floating list, such as an editor's suggestion list |
-| `popoverClasses()` | `popup`, `title`, `description` | Floating panel, such as an emoji picker |
+| `menuClasses({ size })` | `popup`, `item`, `dangerItem`, `label`, `text`, `description`, `shortcut`, `separator`, `groupLabel` | Floating list, such as an editor's suggestion list, or rows inside a Popover with `variant="list"` |
+| `popoverClasses({ variant })` | `popup`, `title`, `description` | Floating panel, such as an emoji picker |
 
 State is set with attributes, never with extra classes:
 
 - A field darkens its edge to `focus-edge` when it or anything inside it has focus. `aria-invalid="true"` shows the error edge, and `aria-disabled="true"` dims it.
-- A menu row is highlighted while it has `data-highlighted`, and dimmed with `data-disabled`. Base UI sets both; a list the app drives itself sets them on the active row.
+- A menu row is highlighted while it has `data-highlighted`, and dimmed with `data-disabled`. Base UI sets both; a list the app drives itself sets them on the active row. `item` works on a `<div>`, `<button>` or `<a>`. For a two-line row, wrap `label` and `description` in a `text` span.
 - A popup fades in with `data-starting-style` and out with `data-ending-style`, which Base UI's popups set.
 
 ```tsx
@@ -2709,6 +3122,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 |
@@ -2718,7 +3132,10 @@ Apply these classes to an app's own elements. Don't override their rules: the pr
 | `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-hit` | An invisible 44px touch target on `pointer: coarse` | Anything pressable smaller than 44px |
-| `mu-icon` | Icon size and stroke | A Lucide icon outside a control |
+| `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-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 |
@@ -2740,13 +3157,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-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 {