@usememos/ui 26.11.1 → 26.11.2

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 30 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.
@@ -343,7 +343,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, 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 `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.
@@ -417,6 +417,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 +428,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 +526,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 +545,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 +556,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.
+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.
 
 | 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) |
 | 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 +581,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 and a `bordered` [Table](table.md).
 - **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 +605,11 @@ 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 status or tag label | Badge |
 | A clickable tag filter | Toggle |
 | Content still loading | Skeleton |
@@ -638,7 +647,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 +663,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 +671,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 +717,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 -->
 
@@ -760,6 +773,7 @@ Base UI's props pass through: `value`, `defaultValue`, `onValueChange`, `multipl
 
 ## 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.
 - `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 +812,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 +835,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 +852,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.
@@ -923,7 +940,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 +953,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 +967,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) 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 -->
@@ -1076,7 +1104,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 +1118,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 +1139,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. 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 +1189,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 +1224,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 +1251,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 +1551,11 @@ 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)
   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 and no variant.
 ```
 
 Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal`, `disablePointerDismissal` on the root; `initialFocus`, `finalFocus` on the popup.
@@ -1512,6 +1567,7 @@ 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.
 - 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 +1576,70 @@ 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`.
+
+<!-- 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; 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`.
+- 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`.
+- `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`.
+- 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 +1679,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 +1691,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.
 - 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 +1700,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 +1816,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 -->
 
@@ -1970,7 +2093,7 @@ 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>` |
@@ -1982,7 +2105,8 @@ No Base UI part: these are styled native table elements.
 
 ```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
@@ -2002,14 +2126,79 @@ Every native attribute passes through.
 - 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`.
 - 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 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 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` |
+
+## 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.
+- Rows are not links or buttons. To open a record, put a Link or a Button in the row.
+- 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.
+- Text is `body` in `ink`.
+
 <!-- docs/components/prose.md -->
 
 # Prose
@@ -2088,6 +2277,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 +2355,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 +2473,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 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.
+
 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 +2514,25 @@ 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)).
 
+### 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.
+- 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.
+
 ### 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 +2545,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 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).
 - **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.
@@ -2385,7 +2599,11 @@ 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) |
+| 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"` |
+| 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 +2623,18 @@ 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) |
 | 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,7 +2663,8 @@ 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.
+- 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.
 - 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.
@@ -2452,6 +2675,7 @@ 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.
 
 ## Entry
@@ -2493,7 +2717,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 +2783,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 +2895,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
@@ -2718,7 +2942,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 |