@usememos/ui 26.11.0 → 26.11.2

package/llms-full.txt

@@ -25,7 +25,8 @@ 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 |
 | [Building your own component](custom-components.md) | How an app builds a part the package doesn't ship: Base UI, class functions, public classes, row variables and Tailwind CSS |
@@ -69,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.
@@ -342,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.
@@ -416,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.
@@ -426,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
@@ -524,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
 
@@ -539,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
@@ -549,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
 
@@ -574,13 +581,15 @@ 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.
 
 ## Choosing between similar components
 
+The short version. [Using the components](../usage.md) has the full decision guides, recipes and common mistakes.
+
 | Need | Use |
 | --- | --- |
 | Start an action | Button |
@@ -596,8 +605,11 @@ Components follow the [API conventions](../building.md#api-conventions): parts w
 | 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 |
@@ -635,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"
 }
@@ -650,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
@@ -657,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.
@@ -702,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 -->
 
@@ -757,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.
 
@@ -795,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 |
@@ -818,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;
 };
 ```
@@ -834,15 +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.
-- For picking a value saved with a form, use [Select](select.md).
+- 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.
@@ -919,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 |
@@ -932,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
@@ -945,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 -->
@@ -1072,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` |
@@ -1086,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
@@ -1104,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.
 
@@ -1153,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` |
 
@@ -1187,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
 
@@ -1194,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 -->
@@ -1493,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.
@@ -1508,6 +1567,8 @@ 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
 
@@ -1515,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 -->
 
@@ -1554,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.
@@ -1565,6 +1691,8 @@ 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).
 
@@ -1572,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 -->
@@ -1624,6 +1753,7 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `disabled`
 - Never put essential information only in a tooltip: it doesn't open on touch screens.
 - For text that explains something, use a [Popover](popover.md) instead.
 - Wrap a toolbar, or the whole app, in one `Tooltip.Provider`.
+- On a trigger that also opens a Menu, Popover or Dialog, stack the triggers: `<Tooltip.Trigger render={<Menu.Trigger render={<Button … />} />} />`. See [the recipe](../usage.md#an-icon-only-button-with-a-tooltip-and-a-menu).
 
 ## Style
 
@@ -1686,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 -->
 
@@ -1963,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>` |
@@ -1975,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
@@ -1995,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
@@ -2055,6 +2251,410 @@ Every native attribute passes through.
 - 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).
 
+<!-- docs/usage.md -->
+
+# Using the components
+
+How to pick the right component for a screen and put components together. Read it before building or migrating a screen in an app. Each component's own page has its props and rules; this page decides between them.
+
+## Before you build a screen
+
+1. Find the [pattern](patterns.md) the screen follows: page, form, entry, confirmation, loading, empty state, mobile. Follow it before choosing components.
+2. Pick each component with the guides below. When two seem to fit, the first row that matches wins.
+3. Import components from `@usememos/ui` and icons from `lucide-react`. Don't wrap a component to restyle it.
+4. Use `className` and `style` for layout only: width, margin, grid or flex placement. Don't change a component's color, height, padding, radius, shadow, font size or focus style. If the look is wrong, the component or its page is wrong; change the package, not the screen.
+5. A part the package doesn't ship is built with [Building your own component](custom-components.md), never by copying a component's CSS.
+
+## Picking something that floats
+
+The most common mistake is reaching for the wrong overlay. Decide by what the floating thing holds and how it closes.
+
+| Component | Holds | Opens on | Closes when | Blocks the page | Use it for |
+| --- | --- | --- | --- | --- | --- |
+| [Tooltip](components/tooltip.md) | Two or three words of text, and a shortcut | Hover or keyboard focus | The pointer or focus leaves | No | Naming an icon-only control |
+| [Menu](components/menu.md) | A list of commands | Click on its trigger | One command is picked, Escape, a click outside | No | Actions on one thing: "Pin", "Copy link", "Delete" |
+| [Select](components/select.md), [Combobox](components/combobox.md) | A list of values | Click or typing | One value is picked | No | Choosing a value that a form or setting keeps |
+| [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
+
+- **Menu: picking an item runs a command and closes the menu.** Items are verbs. Arrow keys move between items; typing jumps to one. Nothing inside a Menu takes text or holds focus.
+- **Popover: the content stays open while people use it.** It can hold text, inputs, buttons, a list of toggles. People tab through it like a small page.
+- An input, a checkbox list with an Apply button, or explanatory text inside a Menu means it should be a Popover.
+- A Popover whose content is only a list of actions should be a Menu.
+- A Menu may hold `Menu.CheckboxItem`s and `Menu.RadioItem`s for view options ("Show archived", "Sort by"). They stay open on click. Use them only for options of the view the menu belongs to, not for form values.
+
+### Menu or Select
+
+- **Menu runs commands; Select keeps a value.** A Select's trigger shows the chosen value, it sits in a [Field](components/field.md) with a label, and its value is submitted with a form.
+- A "Sort by" control in a toolbar that changes a view is a Menu with a `Menu.RadioGroup`, or a [ToggleGroup](components/toggle-group.md) when the options fit in a row.
+- A "Visibility" field in a form is a Select.
+
+### Popover, Dialog or a page
+
+- **Popover**: one to three controls about the thing next to it, changes that apply as they are made or are trivial to undo.
+- **Dialog**: more than three controls, a Save or Create button, or a decision that must be made before going on.
+- **A page**: more than about six fields, sections, or content people need to link to.
+- Don't open a Dialog from a Dialog. Replace the content, or close the first one. The one exception is an AlertDialog that confirms discarding the first one's input.
+
+### Tooltip or Popover
+
+- **Tooltip**: a label for a control. It has no interactive content and never opens on touch screens, so it must never be the only place a fact appears.
+- **Popover**: anything people need to read, anything with a link or a button, or anything that must work on touch. For a hover card ("show the person on hover"), use a Popover with `openOnHover` on its trigger, and make sure a click shows the same thing.
+
+### Dialog or AlertDialog
+
+- **AlertDialog** for "Are you sure?": deleting, discarding unsaved input, revoking a token. It has no X and ignores the backdrop, so people must answer.
+- **Dialog** for everything else. A Dialog with a form keeps itself open while it has unsaved input (see [Recipes](#form-in-a-dialog)).
+- Don't confirm actions that can be undone. Run them and show a Toast with Undo instead.
+
+### Toast or an inline message
+
+- **Toast**: the result of an action people just took, when the screen doesn't already show it. "Note archived" (the note disappeared), "Link copied" (nothing else changed).
+- **Inline**: anything tied to a place on the screen. A field's error goes in `Field.Error` under the field. A page that fails to load says so in the page, with a Retry button.
+- Don't toast what the screen already shows. A saved setting whose Switch moved needs no toast.
+- A toast never asks a question. A decision is an AlertDialog.
+
+## Picking a control
+
+### Starting an action or going somewhere
+
+| Need | Use | Not |
+| --- | --- | --- |
+| Run an action | [Button](components/button.md) | A Link with an `onClick` |
+| Go to another page | [Link](components/link.md) | A Button with `navigate()` in `onClick` |
+| Go to another page, styled as an action ("Get started") | An `<a>` (or router link) with `buttonClasses()` | `Button` with `render={<a />}` |
+| Several actions on one thing | A ghost Button that opens a [Menu](components/menu.md) | A row of icon buttons for rare actions |
+| Turn one option on or off in a toolbar | [Toggle](components/toggle.md) | A Button that changes its own label |
+
+### Choosing a value
+
+Answer in order; the first yes decides.
+
+1. **Does it save the moment it changes (a settings page)?** On or off: [Switch](components/switch.md). One of a few: [Select](components/select.md) that saves in `onValueChange`.
+2. **Is it on or off, saved with a form?** [Checkbox](components/checkbox.md).
+3. **Is it one of 2 or 3 options, with room to show them or each needing a description?** [RadioGroup](components/radio-group.md).
+4. **Is it one of up to about 10 options?** [Select](components/select.md).
+5. **Is it one of a long list, or do people know what they're looking for and type it?** [Combobox](components/combobox.md).
+6. **Is it several of a few options?** Checkboxes in a [Fieldset](components/field.md).
+7. **Is it a view or filter on the current page, not a stored value?** One choice: [ToggleGroup](components/toggle-group.md) without `multiple`. Stacking filters: [Toggle](components/toggle.md)s, or a ToggleGroup with `multiple`.
+8. **Is it text?** One line: [Input](components/input.md). A few plain lines: [Textarea](components/textarea.md). Formatted content: the editor (`@usememos/editor`) with [Prose](components/prose.md).
+9. **Is it a number?** An Input with `type="number"` and `inputMode="numeric"`, or a Select of the sensible values. There is no Slider or Stepper.
+
+### Grouping and moving between sections
+
+| Need | Use | Not |
+| --- | --- | --- |
+| Sections of one page (Account, Notifications) | [Tabs](components/tabs.md) | ToggleGroup |
+| A view or filter of the same content (All, Pinned, Archived) | [ToggleGroup](components/toggle-group.md) without `multiple` | Tabs |
+| Navigation between pages | [Link](components/link.md)s in the app's sidebar | Tabs |
+| 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), `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
+
+| Situation | Use |
+| --- | --- |
+| A button's action is waiting on a server | The Button's `loading`, with `loadingLabel` ("Saving") |
+| A list or page is loading | [Skeleton](components/skeleton.md)s in the shape of the content, and `aria-busy` on the region |
+| Something short is running with no control to put it in | [Spinner](components/spinner.md) with a `label` |
+| An action finished and the screen doesn't show it | [Toast](components/toast.md), neutral or `success` |
+| An action failed | Toast with `type: "danger"` and `timeout: 0`; a field's own error in `Field.Error` instead |
+| A field's value is wrong | `invalid` on `Field.Root` and a `Field.Error` that says how to fix it |
+| A thing has a status (Synced, Expired) | [Badge](components/badge.md) with a tone and a word |
+| A list is empty | The [empty state](patterns.md#empty-state) pattern |
+| An action is about to destroy something | [AlertDialog](components/dialog.md), then a Toast after it runs |
+
+Waits under about 300ms show nothing. Status colors (`success`, `warning`, `danger`) appear only with words or an icon, never as the only signal.
+
+## Recipes
+
+### Trigger through `render`
+
+Every `Trigger` and `Close` renders the element given in `render`. Pass the Button there; don't put it inside.
+
+```tsx
+// Do: one <button>
+<Menu.Trigger render={<Button variant="ghost" icon={<Ellipsis />} aria-label="More actions" />} />
+
+// Don't: a <button> inside a <button>
+<Menu.Trigger><Button variant="ghost" icon={<Ellipsis />} aria-label="More actions" /></Menu.Trigger>
+```
+
+### An icon-only button with a tooltip and a menu
+
+Stack the triggers with `render`. One `<button>` gets both behaviors.
+
+```tsx
+<Menu.Root>
+  <Tooltip.Root>
+    <Tooltip.Trigger
+      render={<Menu.Trigger render={<Button variant="ghost" icon={<Ellipsis />} aria-label="More actions" />} />}
+    />
+    <Tooltip.Popup>More actions</Tooltip.Popup>
+  </Tooltip.Root>
+  <Menu.Popup align="end">…</Menu.Popup>
+</Menu.Root>
+```
+
+The same works for a Dialog or Popover trigger: `<Tooltip.Trigger render={<Popover.Trigger render={<Button … />} />} />`.
+
+### A menu item that opens a dialog
+
+Keep the Dialog outside the Menu and control it with `open`. The Menu closes when the item is picked, so a Dialog inside `Menu.Popup` would unmount with it.
+
+```tsx
+const [confirming, setConfirming] = useState(false);
+
+<Menu.Root>
+  <Menu.Trigger render={<Button variant="ghost" icon={<Ellipsis />} aria-label="More actions" />} />
+  <Menu.Popup align="end">
+    <Menu.Item icon={<Pin />} onClick={pin}>Pin</Menu.Item>
+    <Menu.Separator />
+    <Menu.Item icon={<Trash2 />} danger onClick={() => setConfirming(true)}>Delete</Menu.Item>
+  </Menu.Popup>
+</Menu.Root>
+
+<AlertDialog.Root open={confirming} onOpenChange={setConfirming}>
+  <AlertDialog.Popup>
+    <AlertDialog.Title>Delete this note?</AlertDialog.Title>
+    <AlertDialog.Description>It moves to the trash for 30 days.</AlertDialog.Description>
+    <AlertDialog.Footer>
+      <AlertDialog.Close render={<Button variant="ghost">Cancel</Button>} />
+      <Button variant="danger" loading={deleting} loadingLabel="Deleting" onClick={remove}>Delete note</Button>
+    </AlertDialog.Footer>
+  </AlertDialog.Popup>
+</AlertDialog.Root>
+```
+
+`remove` closes the dialog with `setConfirming(false)` once the server answers, then shows a Toast. Use `AlertDialog.Close render={<Button variant="danger" />}` only when the action can't fail.
+
+### Form in a dialog
+
+```tsx
+<Dialog.Root
+  open={open}
+  onOpenChange={(next) => {
+    if (!next && dirty) return; // keep unsaved input; Cancel resets and closes
+    setOpen(next);
+  }}
+>
+  <Dialog.Trigger render={<Button>Create access token</Button>} />
+  <Dialog.Popup>
+    <Dialog.Title>Create access token</Dialog.Title>
+    <Dialog.Description>Use it to call the API from scripts.</Dialog.Description>
+    <form id="create-token" onSubmit={create}>
+      <Field.Root invalid={!!error}>
+        <Field.Label>Description</Field.Label>
+        <Input value={description} onValueChange={setDescription} />
+        <Field.Error match>{error}</Field.Error>
+      </Field.Root>
+    </form>
+    <Dialog.Footer>
+      <Button variant="ghost" onClick={cancel}>Cancel</Button>
+      <Button variant="primary" type="submit" form="create-token" loading={saving} loadingLabel="Creating">Create</Button>
+    </Dialog.Footer>
+  </Dialog.Popup>
+</Dialog.Root>
+```
+
+- One Field per control. The submit button is `primary`, named with its verb, and shows `loading`.
+- On a server error, keep the dialog open and show the error on the field it belongs to. Close it only on success.
+- On phones the dialog becomes a sheet by itself. Don't build a separate mobile layout.
+
+### Settings that save at once
+
+```tsx
+<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
+
+```tsx
+<Tooltip.Provider>
+  <ToggleGroup multiple size="sm" value={marks} onValueChange={setMarks} aria-label="Formatting">
+    <Tooltip.Root>
+      <Tooltip.Trigger render={<Toggle value="bold" icon={<Bold />} aria-label="Bold" />} />
+      <Tooltip.Popup shortcut="⌘ B">Bold</Tooltip.Popup>
+    </Tooltip.Root>
+    …
+    <Separator orientation="vertical" />
+    …
+  </ToggleGroup>
+</Tooltip.Provider>
+```
+
+One `Tooltip.Provider` around the toolbar (or the app) so moving along it opens the next tooltip at once.
+
+### Row and entry actions
+
+- Put rare actions in a ghost "More actions" Menu trigger at the end of the row. Name it for the row: `aria-label={`Actions for ${token.name}`}`.
+- 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).
+
+```tsx
+<Menu.Popup container={shadowRoot}>…</Menu.Popup>
+<Toast.Viewport container={shadowRoot} />
+```
+
+## Size
+
+- **Set `size` once, on the outermost part that takes it.** `Menu.Root`, `Select.Root`, `Combobox.Root`, `Tabs.Root`, `Collapsible.Root`, `Table.Root`, `Field.Root`, `Fieldset.Root`, `RadioGroup` and `ToggleGroup` pass their size to every part and every Button, Toggle, Checkbox or Input inside them. Don't repeat it on the parts.
+- **Pick by place, not by importance.** `md` everywhere by default, including dialogs, forms, onboarding, marketing pages and the app's sidebar (its navigation rows and its main button). `sm` for dense toolbars, table rows and filters inside panels. `xs` for secondary actions beside 13px text (entry footers, row actions). See [Control sizes](layout.md#control-sizes).
+- **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.
+- **Menus follow their surroundings.** A Menu, Select or Combobox without its own `size` takes the size of the Root around it, so a menu opened from a sm toolbar has sm rows.
+- Text entry, menus, tabs and tables have no `xs`; an inherited `xs` renders them at `sm`.
+
+## Emphasis and color
+
+- **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.
+- **Links are the only blue.** Don't color text, icons or backgrounds with `accent`.
+
+## Accessibility checklist
+
+Run through it for every screen.
+
+- [ ] Every control has a name: a `Field.Label`, a visible label, or `aria-label`. Placeholders are never names.
+- [ ] Every icon-only Button and Toggle has an `aria-label` and a Tooltip with the same text.
+- [ ] Every group has a name: `aria-label` on a ToggleGroup and a `Tabs.List`; a `Fieldset.Legend`; a `Table.Caption` or `aria-label` on a Table; a `Popover.Title` or `aria-label`; a `Dialog.Title`.
+- [ ] Checkboxes, Switches and Radios sit inside their `Field.Label`, so the text is clickable.
+- [ ] Repeated triggers are named for their row ("Actions for Backup token"), not just "More actions".
+- [ ] No fact appears only in a Tooltip, only in color, or only in a placeholder.
+- [ ] Loading regions have `aria-busy`; loading Buttons have a `loadingLabel`.
+- [ ] Errors are in `Field.Error` or a danger Toast with `timeout: 0`, worded as how to fix them.
+- [ ] No `outline: none`, custom focus ring or `tabIndex` on a component. Focus, keyboard and ARIA come from Base UI; don't add key handlers that fight them.
+- [ ] Nothing pressable is built from a `<div>`. If the package has no component for it, build it on Base UI ([Building your own component](custom-components.md)).
+
+## Common mistakes
+
+| Don't | Do |
+| --- | --- |
+| An Input or checkbox list inside a Menu | A Popover |
+| A Popover holding only a list of actions | A Menu |
+| A Menu to choose a form value | A Select in a Field |
+| A Dialog for one or two quick controls | A Popover |
+| A Dialog for "Are you sure?" | An AlertDialog |
+| A confirmation for an action that can be undone | Run it, then a Toast with Undo |
+| A Tooltip with a link, a button or a paragraph | A Popover |
+| A Tooltip on text that isn't a control | Visible text, or a Popover |
+| A Toast for a field's error | `Field.Error` under the field |
+| A success Toast after every Switch | Nothing; the Switch shows it |
+| A Button that navigates | A Link, or an anchor with `buttonClasses()` |
+| `<Button render={<a href="…" />}>` | `<a className={buttonClasses()} href="…">` |
+| A Button nested inside a `Trigger` | `render={<Button … />}` on the Trigger |
+| A clickable Badge | A Toggle (filters) or a Link with `badgeClasses()` (tag pages) |
+| Tabs to filter a list | A ToggleGroup without `multiple` |
+| A ToggleGroup to switch page sections | Tabs |
+| A Switch in a form with a Save button | A Checkbox |
+| A Checkbox that saves at once | A Switch |
+| A Select with 30 options | A Combobox |
+| A Select with two options and room to spare | A RadioGroup |
+| A boxed card around each item | Whitespace, a section title, or a Separator. Rows of settings or records go in one [List](components/list.md) |
+| 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 |
+| Two `primary` Buttons in one view | One `primary`, the rest `neutral` |
+| `danger` Button as the first click | A `danger` Menu item, then an AlertDialog |
+| A placeholder as the only label | `Field.Label`, or `aria-label` |
+| Color as the only signal of status | A Badge or Toast with a word and an icon |
+| `className` that changes a component's color, height or radius | Use the component as it is, or change the package |
+| Copying a component's CSS to make a lookalike | Base UI with a class function or public classes |
+| A `<div onClick>` as a control | A component, or Base UI's part with a class function |
+
+## Migrating from another UI kit
+
+Names and parts from other libraries and where they go.
+
+| Other kits | Memos UI |
+| --- | --- |
+| Modal, Dialog | [Dialog](components/dialog.md); `sheet` covers phones |
+| ConfirmDialog, AlertDialog, `window.confirm` | [AlertDialog](components/dialog.md) |
+| 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). 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` |
+| Accordion | [Collapsible](components/collapsible.md)s |
+| Slider, NumberInput, Stepper | Input `type="number"` or a Select |
+| Autocomplete, SearchSelect | [Combobox](components/combobox.md) |
+| NativeSelect, `<select>` | [Select](components/select.md) |
+| Label, FormLabel | `Field.Label` |
+| FormMessage, HelperText | `Field.Error`, `Field.Description` |
+| FormItem, FormControl | `Field.Root` |
+| Loader, CircularProgress | [Spinner](components/spinner.md), or a control's `loading` |
+| Progress bar | Not built. Use Skeletons for loading, or text ("3 of 10") |
+| Typography, Text, Heading | The type classes (`mu-body`, `mu-caption`, `mu-heading`) from [Typography](typography.md) |
+| Markdown or rich-text body | [Prose](components/prose.md) |
+| `variant="secondary"`, `"outline"` on a button | `neutral`; `ghost` in toolbars |
+| `variant="destructive"` on a button | `danger`, only inside a confirmation |
+| `size="lg"` | `md`; emphasis comes from `primary` |
+| `options={[…]}`, `items={[…]}` data props | Parts: `Select.Item`, `Menu.Item`, `Tabs.Tab`. Select and Combobox still take `items` on the Root for labels and filtering |
+| `asChild` | `render={<… />}` |
+
 <!-- docs/patterns.md -->
 
 # Patterns
@@ -2063,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.
@@ -2074,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
@@ -2115,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`.
 
@@ -2181,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).
@@ -2293,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
@@ -2340,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 |