@usememos/ui 26.11.16 → 26.11.18

package/llms-full.txt

@@ -2,7 +2,7 @@
 
 # Memos UI design system
 
-Memos UI is one calm, dense and flat system for every product we build: memos (the app), the website, the web clipper and whatever comes next. Pure grays and ink emphasis keep attention on people's content. Hierarchy comes from type, spacing and fills. Components reuse a few shared state treatments; pointer events do not add decorative motion or effects.
+Memos UI is one calm, dense and flat system for every product we build: memos (the app), the website, the web clipper and whatever comes next. Quiet neutrals, a warm Light canvas and ink emphasis keep attention on people's content. Hierarchy comes from type, spacing and fills. Components reuse a few shared state treatments; pointer events do not add decorative motion or effects.
 
 These docs describe the target system. They are the source of truth for `@usememos/ui`. Where the code in `packages/` differs from them, the code is out of date and should move toward the docs.
 
@@ -17,12 +17,13 @@ It is not a general-purpose UI library for outside developers. Components are ge
 
 | Doc | What it covers |
 | --- | --- |
+| [Design reference: Linear](design-reference.md) | Official source evidence and how we apply it to Memos UI |
 | [Principles and voice](principles.md) | The taste in six rules, and how interface text is written |
 | [Color](color.md) | Color roles, every color token in Light and Dark, and how themes are chosen |
 | [Depth](depth.md) | Flat surface roles, borders and focus without shadows or outlines |
 | [Typography](typography.md) | The system font, the type scale and text rules |
 | [Size, spacing and layout](layout.md) | Control sizes, the 4px scale, radius, layout widths, breakpoints and layers |
-| [Motion](motion.md) | Press, settle and fade timing, and reduced motion |
+| [Motion](motion.md) | Immediate feedback, minimal opening and closing, and reduced motion |
 | [States](states.md) | Hover, pressed, loading, disabled, invalid and focus |
 | [Icons](icons.md) | Lucide, sizes, the fixed stroke and accessibility |
 | [Components](components/README.md) | The 31 components, what was left out, and one page per component |
@@ -36,26 +37,61 @@ It is not a general-purpose UI library for outside developers. Components are ge
 - **Behavior from Base UI.** Focus management, keyboard support, ARIA, portals and positioning come from [Base UI](https://base-ui.com). Styling, tokens and the component API are our own.
 - **No shadcn.** No shadcn dependency, no copied shadcn code, and no shadcn-compatible component or token names (`card`, `muted`, `destructive`, `foreground` and so on are not used).
 - **Flat and calm by default.** Fills identify controls and state. Reuse shared interaction treatments without press movement, scaling or brightness filters. Light is the default theme; Dark ships with it.
-- **Ink is the accent.** The primary action and every on state use `primary`: near-black in Light, near-white in Dark.
-- **One quiet hue.** `accent` is a quiet blue used only for links and text selection, never as a fill. Focus is ink.
+- **Ink is the accent.** The primary action and checked marks use `primary`: near-black in Light, near-white in Dark. Toggles and single choices use quiet saved-state fills.
+- **One quiet hue.** `accent` is a quiet blue used only for links and text selection, never as a fill. Non-text keyboard focus is ink; text-entry focus uses its caret or selection.
 - **Status colors only for status.** Green means success, amber means warning, red means danger or error. None of them is used for emphasis.
 - **Lucide icons** at one fixed screen-pixel stroke, 1.25px, at every size.
 - **The system UI font** for all text. The package ships no font files.
 - **Few sizes, two weights.** App UI uses 13, 14, 16 and 20px text at weights 400 and 500. 20px is for the page title only.
 - **Dense, on a 4px grid.** Controls are 32px tall by default.
 
+<!-- docs/design-reference.md -->
+
+# Design reference: Linear
+
+Linear's product interface is the reference for our hierarchy, restraint and interaction judgment. Our rules below turn that direction into a contract for Memos UI.
+
+## What the sources establish
+
+- The [March 2026 refresh](https://linear.app/now/behind-the-latest-design-refresh) reduces competing chrome, unnecessary icons and dividing lines. Its neutrals move toward a warmer, less saturated gray while content stays clear.
+- The [2024 redesign](https://linear.app/now/how-we-redesigned-the-linear-ui) treats alignment, density and hierarchy as one system, tested across views, platforms and themes.
+- The [August 2026 styling account](https://linear.app/now/styling-linear-for-the-future-stylex) describes explicit component contracts and shared interaction styling, including a highlight treatment for pointer hover and touch press. It also says Linear does not have a formal design system; these articles are not a complete public component specification.
+- The [contextual-menu account](https://linear.app/now/invisible-details) improves the pointer's path into a submenu. Craft includes reducing effort even when no visible effect is added.
+- Emil Kowalski's [animation guidance](https://emilkowal.ski/ui/you-dont-need-animations), with examples from his work at Linear, distinguishes purposeful motion from repeated effects that slow work. It supports short content transitions and immediate keyboard navigation; it does not prescribe one timing for every Linear component.
+
+## How we apply this
+
+These are Memos UI decisions informed by those sources and product review, not claims about Linear's private CSS, tokens or animation timings. A screenshot of a focused composer does not establish how all of Linear's inputs or keyboard paths behave.
+
+| Before | After | Why |
+| --- | --- | --- |
+| Every interaction event calls for a distinct appearance | Implement every behavioral state; add a visible change only when it conveys useful information | Events are not visual variants |
+| A text field emphasizes its entire boundary on focus | Keep border and surface stable; use its caret or text selection | Content and editing stay primary |
+| Holding an action adds a new fill or contrasting border | Reuse one immediate highlight for hover and press; keyboard focus stays independent | Fewer transient treatments |
+| Tabs and single-choice groups animate each selection | Update the selected key immediately | Frequent navigation does not wait for decoration |
+| Select has a separate opening treatment over its chosen value | Open an anchored list with the shared short fade and small offset; keep one chevron and one selected check | Content appears smoothly without extra choreography |
+| Simplifying event feedback also removes opening and closing animations | Retain minimal content transitions; keep hover, focus, press and row navigation immediate | Content visibility and repeated control feedback have different purposes |
+| A switch fades its track, border and knob colors | Update colors immediately; only the knob moves briefly | Motion explains a saved position |
+| Screens restyle controls to solve local taste problems | Fix shared roles and components, then test the contract | Products stay consistent |
+
+## Boundaries
+
+Keep Memos' warm Light canvas, bright surfaces, ink emphasis, text contrast, system fonts and existing size rows. Base UI owns behavior. These remain our tokens and APIs; adopting this reference does not require another styling framework or Linear's branding.
+
+State feedback is immediate. Motion is reserved for spatial changes, appearing or disappearing content, and progress. See [States](states.md), [Motion](motion.md) and [Surfaces and boundaries](depth.md) for the executable rules.
+
 <!-- docs/principles.md -->
 
 # Principles and voice
 
 ## Principles
 
-1. **Content first.** The interface uses quiet neutrals, with a pale warm-gray paper canvas in Light and brighter surfaces. People's words, tags and images carry the color on the page.
-2. **Ink is the emphasis.** The primary action, a checked box and a switch that is on use `primary` (near-black in Light, near-white in Dark). There is no brand hue in controls.
-3. **Flat surfaces, clear states.** Fills show controls and state; borders separate surfaces. No shadows, sheen, focus rings or visible outlines. Content stays unboxed. See [Surfaces and boundaries](depth.md).
-4. **Calm by default.** Hierarchy comes from text color, lightness steps and spacing, not from weight, size or extra color. Interaction uses a few shared treatments, not a separate effect for every event. Controls stay still while pressed; passive content does not highlight on hover. Few sizes and two weights: see [Typography](typography.md).
-5. **Dense, not cramped.** Controls are 32px tall by default, and every gap comes from the 4px scale. See [Size, spacing and layout](layout.md).
-6. **One system, many products.** Components are generic. A product's screens are built from them and from the [patterns](patterns.md); nothing in the package knows what a note or a memo is.
+1. **Work first.** Content and editing get attention; supporting navigation and controls recede. Light uses a pale warm-gray canvas with bright surfaces. A control should not become more prominent merely because the pointer crosses it.
+2. **Hierarchy before decoration.** Use alignment, spacing, text contrast and surface lightness before adding boundaries or icons. Ink emphasizes the primary action and saved on states. Brand hues do not fill controls.
+3. **One shared vocabulary.** Components and public classes carry the same roles across products. Solve visual problems in that contract instead of accumulating local overrides. Our [Linear reference](design-reference.md) explains the evidence and the choices we make from it.
+4. **Complete behavior, few visual treatments.** An interaction event is not a visual variant. Text entry stays stable through hover, focus and press; the caret or selection shows typing focus. Actions reuse one highlight, persistent choices retain a selected fill or mark, and errors, unavailable controls and waiting remain understandable.
+5. **Immediate feedback, minimal opening and closing.** Hover, press, focus and frequent selection update immediately. Tabs do not animate every navigation step. Keep short shared transitions when popups, dialogs and panels appear or disappear. Motion explains content visibility, useful position changes or progress. No press movement, scaling, brightness filters or decorative event fades. See [Motion](motion.md) for the shared timings and reduced-motion rules.
+6. **Dense and predictable.** Use the documented size rows, type scale, spacing ladder and icon system: controls default to 32px, on a 4px spacing scale. Components stay generic; products compose their screens from them and the shared patterns.
 
 ## Voice and interface text
 
@@ -65,14 +101,14 @@ It is not a general-purpose UI library for outside developers. Components are ge
 - Destructive confirmations name the object and the outcome: "Delete this note?" and "This can't be undone."
 - Name an action with its verb, never "OK".
 - Errors say how to fix the problem, not only what went wrong.
-- No emoji in the interface. Numbers use digits ("3 notes").
+- No decorative emoji in interface labels. User content and reaction choices may contain emoji; compose those as content, not Lucide icons. Numbers use digits ("3 notes").
 
 ## 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`. 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 or inputs.
+- Pills as the default for buttons or inputs. Use the opt-in Button/Toggle `shape="pill"` for compact reaction controls and similar content choices; ordinary actions keep the size-row corners.
 - Color as the only signal. Status colors always come with a word or an icon.
 - Illustrations in empty states.
 
@@ -89,10 +125,11 @@ Memos UI is ink on paper: a light warm-gray canvas, bright surfaces, `primary` i
 | Surfaces | `canvas`, `surface`, `overlay` | The page; then inputs, menus, dialogs and toasts one step up. `overlay` dims the page behind dialogs |
 | Wells | `well` | Switch tracks, segmented groups, unchecked boxes and radios, pressed toggles, inline code |
 | Hover | `hover` | Rows, ghost buttons, the highlighted menu row |
+| Saved choices | `selected` | Persistent fill on soft toggles, distinct from hover |
 | Keys | `key`, `key-hover` | Neutral buttons, select triggers, the selected tab, kbd |
 | Text | `text`, `text-secondary`, `text-disabled` | Primary, secondary and disabled text. Each keeps 4.5:1 on the backgrounds named in the token table below |
 | Emphasis | `primary`, `primary-hover`, `on-primary` | Primary button, checked checkbox and radio, switch when on, tooltip |
-| Meta | `accent`, `selection`, `focus`, `focus-edge` | Links and text selection (`accent`); the keyboard focus edge and the focused field edge (`focus`, `focus-edge`, both ink). Never a fill |
+| Meta | `accent`, `selection`, `focus`, `focus-edge` | Links and text selection (`accent`); the control keyboard focus edge and the forced-colors field focus edge (`focus`, `focus-edge`). Never a fill |
 | Status | `success`, `warning`, `danger` and their `-soft` pairs; `danger-key`, `on-danger` | Toasts, badges, field errors, danger buttons |
 | Lines | `edge`, `control-edge`, `line` | Quiet resting borders on fields, neutral buttons, switch tracks and surfaces; small checkbox/radio markers; separators and table rules |
 
@@ -100,7 +137,7 @@ Memos UI is ink on paper: a light warm-gray canvas, bright surfaces, `primary` i
 
 - Light uses near-neutral warm grays for its canvas, wells, hover fills and quiet boundaries: one OKLCH hue (95), with chroma at most 0.008. Surfaces and keys stay white. Text, ink emphasis and stronger control boundaries stay pure gray; Dark keeps its pure-gray neutrals.
 - `accent` is a quiet blue used only for links and selection. If a screen has blue on it at rest, apart from links, something is wrong.
-- Focus is ink, not blue. A focused field darkens its own edge to `focus-edge`; controls reuse the existing 1px focus border. On primary and checked fills, the border uses `on-primary`; danger buttons use `on-danger`. Only forced-colors mode uses a 2px system focus edge. See [States](states.md).
+- Text entry uses its visible caret or text selection to indicate focus. Hover, focus and press keep the same field edge and surface in normal colors. Other controls reuse the existing 1px ink `focus` border. On primary and checked fills, the border uses `on-primary`; danger buttons use `on-danger`. Only forced-colors mode uses a 2px system focus edge. See [States](states.md).
 - Status colors appear only when there is a status. Red is for destructive actions and errors, never for emphasis.
 - `danger` is tuned for text. `danger-key` is the danger button's fill; it is darker in Dark so the button is not the loudest thing on screen.
 - Always pair a status color with a word or an icon.
@@ -115,7 +152,7 @@ There are two themes: **Light** (the default) and **Dark**.
 - Each theme sets every color token explicitly. The package's tests check the values against the table on this page and check the contrast promised here.
 - Light starts with a pale warm-gray paper canvas. White surfaces and keys remain brighter; wells and hover fills are darker steps in the same warm-gray family. This is a flat color treatment, with no texture.
 - Dark keeps the same flat surface roles. Wells and keys are distinct gray fills, and `primary` flips to near-white with a dark `on-primary`.
-- `edge` separates bounded surfaces and stays quiet at rest, on hover and under selected/pressed attributes. Text fields keep it until typing focus; neutral buttons, Selects and off switch tracks do not strengthen it on hover. `control-edge` is reserved for small unchecked Checkbox, Radio and Prose task marks, at least 3:1 against `canvas` and `surface` in both themes. On toggles use a `well` fill with `text`, without a visible border; segmented choices use a contrasting `key` fill in a quiet well. Text tokens never become persistent borders. Focus and invalid states retain their explicit edge treatments. Forced colors adds system-colored selection boundaries when fills disappear; `line` separates content. The quiet resting field boundary remains below 3:1; see [boundary contrast](depth.md#rules).
+- `edge` separates bounded surfaces and stays quiet at rest, on hover and under selected/pressed attributes. Text fields keep it during typing focus too; neutral buttons, Selects and off switch tracks do not strengthen it on hover. `control-edge` is reserved for small unchecked Checkbox, Radio and Prose task marks, at least 3:1 against `canvas` and `surface` in both themes. On default toggles use a `well` fill with `text`, without a visible border; soft toggles use `hover` when off and `selected` with `text` when on; segmented choices use a contrasting `key` fill in a quiet well. Text tokens never become persistent borders. Non-text controls retain their focus treatment; invalid fields retain their error edge. Forced colors adds system-colored selection boundaries when fills disappear; `line` separates content. The quiet resting field boundary remains below 3:1; see [boundary contrast](depth.md#rules).
 
 ### Choosing a theme
 
@@ -127,7 +164,7 @@ The package does not read `prefers-color-scheme` itself. The app does, so that a
 
 An app sets only these tokens:
 
-- the 28 color tokens in the [table below](#color-tokens),
+- the 29 color tokens in the [table below](#color-tokens),
 - the three font tokens in [Typography](typography.md#fonts): `font-sans`, `font-display` and `font-mono`.
 
 Every other token (space, radius, sizes, layout widths, layers, motion) and every `mu-*` class rule is internal. Read those tokens in app CSS (`var(--mu-space-4)`), but don't override them, even though the cascade layer lets an app rule win: the products would drift apart, and the package's tests and screenshots cover only its own values. To change one element, pass `className` or `style` to that component (see [API conventions](building.md#api-conventions)).
@@ -148,7 +185,7 @@ An app can offer more themes than the two the package ships, such as a warm Pape
 ```
 
 - Set every color token in the table below. A token the theme leaves out keeps its Light value, so a partial theme mixes two palettes.
-- The package exports `themeTokens`, the custom property names of those 28 tokens (`--mu-canvas` to `--mu-on-danger`). Check in the app's tests that its theme sets each one (Vitest reads a stylesheet with `?raw` only when `test.css` is `true` in its config; without it the file comes back empty):
+- The package exports `themeTokens`, the custom property names of those 29 tokens (`--mu-canvas` to `--mu-on-danger`). Check in the app's tests that its theme sets each one (Vitest reads a stylesheet with `?raw` only when `test.css` is `true` in its config; without it the file comes back empty):
 
   ```ts
   import { themeTokens } from "@usememos/ui";
@@ -158,7 +195,7 @@ An app can offer more themes than the two the package ships, such as a warm Pape
     expect(themeTokens.filter((name) => !paper.includes(`${name}:`))).toEqual([]);
   });
   ```
-- Keep the rules on this page: `primary` stays ink, not a brand hue; `accent` is only for links and selection; focus is ink; status colors only for status.
+- Keep the rules on this page: `primary` stays ink, not a brand hue; `accent` is only for links and selection; control focus stays ink; text-entry focus does not change its normal border; status colors only for status.
 - The app owns the theme's contrast. Check in the app's own tests that every text and background pair named in the Usage column below keeps 4.5:1 or more. The package's tests and screenshots cover only Light and Dark.
 - The tokens sit in the `mu` [cascade layer](building.md#cascade-layer), so an unlayered app theme wins over them at any specificity.
 - An app theme is a choice the user makes. It is not a way to restyle the package per product: an app's default theme is Light or Dark.
@@ -171,22 +208,23 @@ An app can offer more themes than the two the package ships, such as a warm Pape
 | `surface` | `#ffffff` | `#1a1a1a` | One lightness step above canvas: inputs, menus, popovers, dialogs, toasts, table headers |
 | `well` | `oklch(0.934 0.008 95)` | `#252525` | Flat parts that hold a state: switch, tab, checkbox and radio wells, pressed toggles, inline code. A boundary is added only where the component needs one. Not for enabled text entry |
 | `hover` | `oklch(0.95 0.006 95)` | `#252525` | Hover on rows, ghost buttons and wells; the highlighted row in menus and selects |
+| `selected` | `oklch(0.919 0.004 95)` | `#343434` | Persistent soft-toggle fill, including while hovered; with `text` or `text-disabled`, never a selected border |
 | `key` | `#ffffff` | `#343434` | Controls and selected parts: neutral buttons, select triggers, the selected tab, kbd. Flat: neutral buttons and selects use `edge`; selected segments use fill without a visible border in normal colors |
 | `key-hover` | `oklch(0.982 0.004 95)` | `#3c3c3c` | Hover on a neutral key |
 | `edge` | `oklch(0.858 0.006 95)` | `#343434` | Quiet resting borders of fields, neutral buttons, switch tracks, well/key surfaces, popups, badges, selects and disabled controls |
 | `control-edge` | `#909090` | `#777777` | Small unchecked Checkbox, Radio and Prose task markers only; never a full-control hover or selected boundary; at least 3:1 on `canvas` and `surface` |
 | `line` | `oklch(0.919 0.004 95)` | `#252525` | Separators, table rules and menu dividers. About 1.2:1 against canvas in Light, so structural lines also need spacing or a heading |
 | `overlay` | `rgba(0,0,0,0.32)` | `rgba(0,0,0,0.6)` | Backdrop behind dialogs and sheets |
-| `text` | `#1a1a1a` | `#ededed` | Primary text and icons on canvas, surface, well and key (13:1 or more in both themes) |
+| `text` | `#1a1a1a` | `#ededed` | Primary text and icons on canvas, surface, well, key and selected (10:1 or more in both themes) |
 | `text-secondary` | `#5e5e5e` | `#adadad` | Secondary text: descriptions, placeholders, unselected tabs and toggles, shortcuts, timestamps (4.9:1 or more on every surface) |
-| `text-disabled` | `#666666` | `#9e9e9e` | Disabled text and icons, at least 4.5:1 on `canvas`, `surface`, `well` and `key`; never fade the whole control |
+| `text-disabled` | `#666666` | `#9e9e9e` | Disabled text and icons, at least 4.5:1 on `canvas`, `surface`, `well`, `key` and `selected`; never fade the whole control |
 | `primary` | `#1a1a1a` | `#e6e6e6` | The one emphasized action and every on state: primary buttons, checked boxes and radios, switches when on, tooltips. Ink, not a hue |
 | `primary-hover` | `#333333` | `#ffffff` | Hover on a primary key |
 | `on-primary` | `#ffffff` | `#0f0f0f` | Text, icons and the switch knob on `primary` (16:1 Light, 15:1 Dark) |
 | `accent` | `oklch(0.5 0.13 255)` | `oklch(0.78 0.11 255)` | The only hue at rest: links, the text cursor and selection. 5.7:1 on canvas in Light. Never a fill |
 | `selection` | `rgba(40,99,171,0.18)` | `rgba(135,186,253,0.28)` | Text selection and the selected range in an editor |
 | `focus` | `var(--mu-primary)` | `var(--mu-primary)` | 1px keyboard focus border, on `:focus-visible` only; contrasting text color on filled controls |
-| `focus-edge` | `var(--mu-text)` | `var(--mu-text)` | Edge of a focused field (Input, Textarea, Combobox): 1px on any focus, recoloring the quiet `edge` |
+| `focus-edge` | `var(--mu-edge)` | `var(--mu-edge)` | Field focus edge in forced colors, where it becomes system `Highlight`. Normal Input, Textarea and Combobox keep `edge` and show typing focus with the caret or selection |
 | `success` | `oklch(0.52 0.13 150)` | `oklch(0.78 0.14 150)` | Success text and icons on `surface` or `success-soft` (4.6:1 or more). Always with a word or icon |
 | `success-soft` | `#e9f4ec` | `#14261a` | Background of success badges and toasts |
 | `warning` | `oklch(0.5 0.11 70)` | `oklch(0.8 0.13 75)` | Warning text and icons on `surface` or `warning-soft` (5.5:1 or more) |
@@ -219,11 +257,11 @@ Use these classes before writing new surface styles. `mu-key` covers both a cont
 
 - No `box-shadow`, `text-shadow`, sheen gradients, focus rings or visible `outline`. `outline: none` or `0` only suppresses a browser outline when another visible focus treatment exists.
 - Text entry keeps its `surface` fill on hover and focus. Enabled fields never use a gray well; disabled fields use `well` with `text-disabled` text.
-- Boundary strength follows its job. Resting, hovered and persistently selected surfaces never borrow text or focus colors for their borders. Text entry keeps its quiet 1px `edge` on hover and takes a 1px ink edge on focus. A resting text field does not need the same visual weight as a checkbox or switch's state marker. The quiet field boundary is below 3:1 in the built-in themes; this treatment does not guarantee WCAG 1.4.11 for text entry.
+- Boundary strength follows its job. Resting, hovered and persistently selected surfaces never borrow text or focus colors for their borders. Text entry keeps its quiet 1px `edge` under hover, focus and press. A resting text field does not need the same visual weight as a checkbox or switch's state marker. The quiet field boundary is below 3:1 in the built-in themes; this treatment does not guarantee WCAG 1.4.11 for text entry.
 - A checked checkbox or radio uses `primary` with an `on-primary` mark. A switch also moves its knob.
 - Neutral buttons, Select triggers and switch tracks keep the quiet `edge` on hover. Button and Select fills provide hover feedback; fields and switches keep their fill. A switch keeps its contrasting `text` knob when off. Checkbox, Radio and Prose task checkboxes alone use `control-edge` around their small unchecked marks. Do not reuse that marker color around a toolbar item or a full control.
-- A single choice among peers uses a contrasting `key` fill in a quiet well, with `text` for the selected label and icon. The group and selected key have no visible border in normal colors. Hover only increases label and icon contrast; focus reuses `mu-focus`. Borders reserve space, so geometry stays fixed. In forced colors the selected key gains a text-colored border. An independent on/off toggle uses `well` and `text` when on, with a transparent reserved border. Disabled on toggles keep that fill and use `text-disabled`. In forced colors an on toggle gets a system-colored boundary because its fill may disappear.
-- Surface classes describe a surface, not an interaction state. `mu-key` keeps its `key` fill and quiet `edge` even with selected or pressed attributes. Use Toggle for a persistent on/off fill, or a key inside a well for one selected choice. Never turn a text token into a persistent border. Focus and invalid states are the explicit exceptions to quiet control boundaries.
+- A single choice among peers uses a contrasting `key` fill in a quiet well, with `text` for the selected label and icon. The group and selected key have no visible border in normal colors. Hover only increases label and icon contrast; focus reuses `mu-focus`. Borders reserve space, so geometry stays fixed. In forced colors the selected key gains a text-colored border. An independent on/off toggle uses `well` and `text` when on (`selected` and `text` for `variant="soft"`), with a transparent reserved border. Disabled on toggles keep that fill and use `text-disabled`. In forced colors an on toggle gets a system-colored boundary because its fill may disappear.
+- Surface classes describe a surface, not an interaction state. `mu-key` keeps its `key` fill and quiet `edge` even with selected or pressed attributes. Use Toggle for a persistent on/off fill, or a key inside a well for one selected choice. Never turn a text token into a persistent border. Non-text focus and invalid fields are the explicit exceptions to quiet control boundaries.
 - Floating surfaces have a border so they remain distinct over the same surface color. Modal backdrops still use `overlay`.
 - Content is grouped by spacing, headings and separators. The boxed exceptions are List, bordered Table and bordered Form.
 - Borders count toward the documented padding. Reserve their space and compensate inner padding so states never move text or change a control's size.
@@ -232,7 +270,7 @@ Use these classes before writing new surface styles. `mu-key` covers both a cont
 
 - `mu-focus` recolors the existing 1px border on `:focus-visible`. The fine edge keeps compact controls calm while contrasting with the fill. It provides the internal `--mu-control-border-width` variable. A custom control reads that variable for its border and subtracts it from its padding, so its text and size stay fixed. Text-only links use an underline instead.
 - The edge uses `focus` ink. On primary and checked fills it uses `on-primary`; danger buttons use `on-danger`, so the edge contrasts with the fill.
-- Fields darken their existing 1px `edge` to ink on any focus. Invalid text fields keep `danger` on hover and focus; their caret also identifies the typing focus.
+- Input, Textarea and Combobox input boxes keep their border, surface and geometry under hover, focus and press. The visible caret or text selection indicates typing focus; do not recolor the box or animate it. Invalid fields keep `danger`. In forced colors, focused fields use the shared 2px system `focus-edge`. The caret/selection approach follows the text-field examples in [WCAG Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html).
 - Invalid non-text controls reuse the shared 1px focus edge. Their error message continues to identify the error; do not add a thicker focus variant for validation.
 - Text links use a double underline on keyboard focus, including links already underlined at rest.
 - Menu items and options use their highlighted fill. Opening a popup never draws a focus boundary around the popup.
@@ -329,7 +367,7 @@ The table gives desktop sizes. Touch targets reserve additional space as describ
 - Use `sm` for dense toolbars, table rows and filters inside panels, and `md` everywhere else, including marketing pages, onboarding and sheets. A sidebar with 28px rows puts the `mu-compact` class on itself: md controls and rows inside are `control-compact` (28px) tall, with md text, icons, padding and radius (see [A sidebar navigation row](usage.md#a-sidebar-navigation-row)). It is the only height between sizes, and it is not a `size` value. Floating lists (Menu, Select and Combobox lists) use it for their sm rows too: an sm list has 28px rows with sm text and icons, because a 24px row is cramped inside a 12px-radius popup. Emphasis comes from the `primary` variant, not from a bigger control. On touch screens buttons, fields and option rows grow to at least 44px; checkboxes, radios and switches keep their small marks and reserve 44px of layout space around them.
 - 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.
+- The icon side of a control has 2px less padding, so text and icon look centered. Button and Toggle with `shape="pill"` instead keep equal size-row padding at both ends and use `radius-full`; an icon-only control is a circle. Heights, icon sizes and touch targets stay the same.
 - On touch screens (`pointer: coarse`), every control reserves at least `hit-area` (44px) in the layout. Buttons and option rows grow; checkboxes, radios and switches reserve margins around their visual marks. Adjacent hit areas must never overlap. A segmented group adds its 2px inset around 44px items.
 
 ## Spacing
@@ -477,52 +515,62 @@ Use these tokens for every `z-index`. Don't invent new layers in product code.
 
 # Motion
 
-Motion explains state and position: knobs and selections settle, and popups appear or disappear. Controls stay still under the pointer. Motion is quick and never added just to decorate an event.
+Keep opening and closing animations. They explain when content appears, where it belongs and when it leaves. Hover, press, focus and frequent selection feedback remain immediate. Controls stay still under the pointer.
+
+Our [Linear reference](design-reference.md) informs this restraint. The timings below are Memos UI decisions, not Linear's published animation specification.
 
 ## Rules
 
-- **Press.** Buttons use shared fill and border color changes over `duration-press` (80ms). No press translation, scaling or brightness filters. Switch knobs, checkboxes and radios do not resize while held.
-- **Selection.** Knobs and the segment key slide over `duration-settle` (150ms) with `ease-settle`. Checkbox and Radio marks appear immediately with their state, without a delayed fade or scale animation.
-- **Popups.** Menus, popovers and collapsible content fade in and rise 4px over `duration-fade` (100ms). Dialogs do the same over `duration-settle`. Sheets slide up 24px.
-- **Tooltips** wait 400ms on hover before they open, and open at once on keyboard focus.
-- **Collapsible content** fades and rises in. There is no height animation, so long content never stutters.
+- **Text entry.** Input, Textarea and Combobox input boxes have no hover, focus or press animation. Typing focus uses the caret or selection without a border change. Validation recolors the existing edge immediately; the surface and geometry stay fixed. Do not add a treatment just because an event occurs.
+
+- **Frequent feedback.** Hover, press, keyboard focus and label changes have no color or border animation. Actions reuse one highlight rather than adding a held-state edge. `duration-press` is 0ms for these shared treatments. No press translation, scaling or brightness filters.
+- **Selection.** Tabs and single-choice ToggleGroups update their selected key immediately, including its position and size. Checkbox and Radio marks also update immediately. Only the Switch knob uses a short positional slide over `duration-settle` (150ms); track, border and knob colors change immediately.
+- **One popup treatment.** Select, Menu, Combobox, Popover and Tooltip share a short fade and `space-1` (4px) vertical offset over `duration-fade` (100ms), using `ease-out`. Opening settles to full opacity and no offset; closing returns to the same hidden frame. No scale, bounce, blur, stagger or animated trigger chevron. Select opens below the trigger by default; it has no separate motion variant.
+- **Dialogs and drawers.** Dialogs use the same fade and `space-1` offset over `duration-settle` (150ms). A Dialog sheet uses `space-6` (24px) from the bottom. Drawers slide from their attached edge over `duration-settle`, using `ease-settle`, and follow the finger during a swipe. Their backdrops fade with the same duration; no delayed or staged entrance.
+- **Tooltips** wait 400ms on hover before opening; keyboard focus has no opening delay. This delay is separate from the short opening transition. Moving between tooltips in a group skips the delay and replayed entrance.
+- **Collapsible content** uses the shared 100ms fade and 4px offset for opening and closing. Its height never animates. A chevron may change orientation immediately to identify the open state; it does not rotate through a transition.
+- **Toasts** retain their short entrance, exit and stack behavior over `duration-settle`. Do not add bounce, stagger or an extra entrance for their content. See [Toast](components/toast.md) for stack and dismissal behavior.
+- **Keep behavior immediate.** Focus management, keyboard navigation, selection and dismissal do not wait for an animation. Opening by keyboard uses the same short content transition; moving focus or the highlighted row inside the open widget never animates. Rapid open/close changes retarget from the current frame instead of queuing or replaying an entrance. Opening and closing share the same short timing; never add a longer exit.
+- **Implementation.** Use the existing CSS transitions and Base UI lifecycle attributes. Animate only opacity and translation for opening and closing; keep size, padding, borders and colors fixed. Do not add an animation library or animate content that is already present on initial render.
 - **Spinners** turn once every 0.8s. **Skeletons** shimmer once every 1.4s.
-- **Reduced motion.** Under `prefers-reduced-motion`, keep color and opacity changes, and drop slides, scaling and shimmer.
+- **Reduced motion.** Under `prefers-reduced-motion: reduce`, opening, closing and Switch position changes are immediate: no translation or opacity transition, including backdrops. Remove shimmer and continuous decorative motion. Keep the visible loading state and all interaction behavior.
 
 ## Tokens
 
 | Token | Value | Usage |
 | --- | --- | --- |
-| `duration-press` | 80ms | Short control fill and border changes |
-| `duration-settle` | 150ms | Knobs and keys slide on release; dialogs open |
-| `duration-fade` | 100ms | Popups open; content inside a control fades in after the key stops |
+| `duration-press` | 0ms | Immediate shared hover, press and focus feedback |
+| `duration-settle` | 150ms | Switch knob position; Dialog and Drawer opening and closing |
+| `duration-fade` | 100ms | Shared popup and Collapsible opening and closing |
 | `duration-spin` | 800ms | One turn of a Spinner |
 | `duration-shimmer` | 1400ms | One pass of a Skeleton's shimmer |
-| `ease-settle` | `cubic-bezier(0.2, 0.9, 0.3, 1)` | Slides: hard deceleration at the end, like a light spring |
-| `ease-out` | `cubic-bezier(0.2, 0, 0, 1)` | Press and fades |
+| `ease-settle` | `cubic-bezier(0.2, 0.9, 0.3, 1)` | Switch and Drawer position changes; no bounce |
+| `ease-out` | `cubic-bezier(0.2, 0, 0, 1)` | Popup and Dialog opening and closing; backdrop fades |
 
 <!-- docs/states.md -->
 
 # States
 
-Every interactive component handles these states the same way.
+Behavioral states are complete, but they do not each require a different appearance. Reuse the smallest treatment that communicates the action or saved state. See the [Linear reference](design-reference.md) for the basis of this contract.
 
 | State | Looks like |
 | --- | --- |
 | Hover | Interactive keys go to `key-hover`; actionable rows and ghost buttons use `hover`. Passive content and ordinary table rows do not highlight. Bounded controls keep their quiet `edge`; fields and switches keep their fill. Invalid fields keep `danger`. Muted labels go to `text`. Primary keys go to `primary-hover`. |
-| Pressed (while held) | Buttons keep their geometry: neutral and ghost use `well`, primary uses `primary-hover`, danger retains `danger-key`. Filled primary and danger actions use their contrasting text color on the existing edge. Toggles do not imitate a selected state before activation |
-| Pressed toggle (on) | Uses `well` and the `text` color; the reserved border stays transparent |
-| Selected (one of several) | A flat `key` fill in a quiet well that slides to the chosen item, with `text` for its label and icon; no visible group or selected-key border in normal colors. Hover only changes label and icon contrast; focus reuses `mu-focus` |
+| Pressed (while held) | Actions reuse their hover highlight immediately: neutral uses `key-hover`, ghost and actionable rows use `hover`, primary uses `primary-hover`, danger retains `danger-key`. No extra border, movement, scale or filter. Toggles do not imitate a selected state before activation |
+| Pressed toggle (on) | Default: `well` and `text`. Soft: `selected` and `text`, retained on hover; the reserved border stays transparent |
+| Selected (one of several) | A flat `key` fill in a quiet well that updates immediately to the chosen item, with `text` for its label and icon; no visible group or selected-key border in normal colors. Hover only changes label and icon contrast; focus reuses `mu-focus` |
 | Checked | A flat `primary` fill with an `on-primary` mark |
 | Loading | The control becomes inert at once. After 300ms it hides its label and shows a Spinner without changing size; short waits keep the label |
 | Disabled | `text-disabled` text, quiet borders and `well` on all Button variants and other filled controls; no whole-control opacity, hover or press response |
 | Invalid | A `danger` edge on the field, plus an error line with an icon under it |
-| Focus (field) | The 1px edge darkens from `edge` to `focus-edge` (ink), on click and keyboard alike. No ring around it. Invalid text fields keep danger; the caret identifies typing focus |
+| Focus (field) | The caret or text selection identifies typing focus. Border and surface stay the same under mouse and keyboard focus, with no ring or animation. Invalid fields keep their danger edge; forced colors uses a 2px system edge |
 | Focus (everything else) | Reuse the shared 1px border on `:focus-visible`; primary/checked fills use `on-primary`, danger buttons use `on-danger`; text links get a double underline. Invalid non-text controls reuse the same focus edge; their error message keeps communicating the error |
 | Focus (inside a widget) | Menu items and options take the `hover` fill. No ring |
 
 ## Rules
 
+- An event does not need its own visual style. Text entry keeps its border, surface and geometry under hover, focus and press. Validation alone changes the ordinary field edge, immediately and without animation.
+- Hover, press and keyboard focus feedback are immediate. Actionable rows and actions reuse a highlight for pointer hover and touch press; do not invent a second held-state frame. Tabs and single-choice groups update their selected key without a slide.
 - Keep state styling minimal. Reuse the shared component and foundation treatments; add a separate treatment only when it communicates a distinct action or state. A component does not need a new fill, border, scale or animation for every pointer or focus event.
 - Persistent states and hover never strengthen a quiet boundary. Reserve `control-edge` for small checkbox/radio markers; text colors are not border colors. Focus and invalid states keep their explicit boundary treatments.
 - Keep selection persistent and independent of transient events. A selected fill is not a focus border. Reuse `mu-focus` for the shared focus behavior instead of defining component-specific focus variants.
@@ -530,9 +578,10 @@ Every interactive component handles these states the same way.
 - Press feedback does not move or resize a control, apply a brightness filter, or animate its mark. Checkbox and Radio marks change immediately. A Switch's knob still moves to show its saved state.
 - Hover never changes size, weight or layout.
 - An input never changes its background on hover or focus, so it never looks disabled.
-- Control focus borders show for keyboard focus only (`:focus-visible`), never on mouse click. Fields are the exception: a clicked field is focused for typing, so its edge darkens, but it still gets no ring.
-- Focus changes the existing edge, never adds a ring or visible outline. Filled controls use their contrasting text color at the edge.
+- Control focus borders show for keyboard focus only (`:focus-visible`), never on mouse click. Text fields use the visible caret or text selection for typing focus and keep their normal boundary.
+- Focus changes the existing edge, never adds a ring or visible outline. Filled controls use their contrasting text color at the edge for keyboard focus, not as a new pointer-held border.
 - Popups, dialogs and panels never show a focus ring when they open and take focus.
+- Opening and closing content retain the minimal shared [Motion](motion.md) transition. This does not animate focus, hover, press or navigation within the content; those respond immediately.
 - Focused borders use 2px in the system `Highlight` color in forced-colors mode. No shadow or outline fallback is needed.
 - In forced-colors mode, segmented selection keeps a system-colored key border and on toggles get a system-colored boundary, distinct from the shared focus treatment.
 - Disabled controls stay in place. Prefer explaining why something is unavailable over hiding it.
@@ -543,7 +592,7 @@ Every interactive component handles these states the same way.
 | Component family | Default feedback |
 | --- | --- |
 | Actions: Button and Link | Shared fill, edge or underline feedback, without movement or filters. All Button variants share the disabled well and edge |
-| Fields: Input, Textarea and Combobox input | Recolor the existing edge. Keep the surface and geometry fixed |
+| Fields: Input, Textarea and Combobox input | Keep the border, surface and geometry fixed through hover, focus and press. The caret or text selection indicates typing focus; validation alone recolors the ordinary edge |
 | Choices: Checkbox, Radio, Switch, Toggle, ToggleGroup and Tabs | Keep the saved state explicit through a mark, knob position or selected fill. Do not resize on press or imitate selection before activation |
 | Actionable rows: Menu, Select, Combobox options and List.ItemButton | Use the shared highlighted fill. Keep Base UI's interaction behavior |
 | Containers: Dialog, Drawer, Popover and Toast | Feedback belongs to their controls, not an extra container hover effect. Keep visibility, dismissal and Toast expansion behavior |
@@ -660,6 +709,7 @@ The short version. [Using the components](../usage.md) has the full decision gui
 | A small form (heading, a few fields, buttons) among Lists on a settings page | Form with `bordered` |
 | A status or tag label | Badge |
 | A clickable tag filter | Toggle |
+| Compact reactions and their picker | Soft pill Toggles, a ghost pill Button and Popover; see the [composition](popover.md#compact-reaction-picker) |
 | Content still loading | Skeleton |
 | A control waiting on a server | the control's `loading` prop |
 
@@ -667,6 +717,7 @@ The short version. [Using the components](../usage.md) has the full decision gui
 
 ```ts
 type Size = "xs" | "sm" | "md"; // xs only where a page says so; other components take "sm" | "md"
+type ControlShape = "default" | "pill"; // Button and Toggle; defaults keep size-row corners
 type Tone = "neutral" | "success" | "warning" | "danger";
 /** A Lucide icon element, such as <Pin /> from lucide-react. Size and stroke come from the component. */
 type IconElement = React.ReactElement;
@@ -695,13 +746,14 @@ import { Plus } from "lucide-react";
 interface ButtonProps extends BaseButton.Props {
   variant?: "primary" | "neutral" | "ghost" | "danger"; // default "neutral"
   size?: Size;
+  shape?: "default" | "pill"; // default "default"; icon-only pills are circular
   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"
 }
 
-function buttonClasses(options?: { variant?: ButtonVariant; size?: Size; iconOnly?: boolean }): string;
+function buttonClasses(options?: { variant?: ButtonVariant; size?: Size; shape?: ControlShape; iconOnly?: boolean }): string;
 ```
 
 Wraps Base UI's [Button](https://base-ui.com/react/components/button): `disabled`, `focusableWhenDisabled`, `render`, `nativeButton` and native button attributes pass through. Renders `<button type="button">`.
@@ -725,8 +777,9 @@ Wraps Base UI's [Button](https://base-ui.com/react/components/button): `disabled
 
 - A flat control: 20, 24 or 32px tall. `primary` is an ink key with `on-primary` text; `neutral` a `key` with a quiet `edge` boundary; `ghost` flat `text-secondary` with `hover` on hover; `danger` a `danger-key` with `on-danger` text.
 - A neutral button keeps its quiet `edge` on hover; its `key-hover` fill provides feedback. Keyboard focus changes the 1px edge to ink; filled actions retain their contrasting focus edge.
-- Only an icon: square. The side with an icon (`icon` at the start, `iconEnd` at the end) has 2px less padding.
-- Press uses `well` for neutral and ghost, and `primary-hover` for primary; danger retains `danger-key`. Filled primary and danger actions also recolor the existing edge to their contrasting text color. No translation, scale or brightness filter.
+- `shape="pill"` uses `radius-full` and equal size-row horizontal padding, even with an icon beside a label. Default shape and padding stay unchanged.
+- Only an icon: square (circular with `shape="pill"`). With the default shape, the side with an icon (`icon` at the start, `iconEnd` at the end) has 2px less padding.
+- Hover and press reuse one immediate highlight: `key-hover` for neutral, `hover` for ghost, `primary-hover` for primary; danger retains `danger-key`. Holding the pointer adds no new boundary. Keyboard focus owns the contrasting edge. No color fade, translation, scale or brightness filter.
 - `loading` immediately sets `aria-busy` and `aria-disabled`, ignores presses and stays focusable. The label stays visible for 300ms; if still loading, a Spinner replaces it without changing width. Finishing cancels the delay and restores the label immediately.
 - Disabled: every variant uses `text-disabled` text, a `well` fill and a quiet `edge`, including ghost buttons. This keeps disabled toolbar actions distinct from enabled ghost actions without dimming the text. Opacity stays 1.
 
@@ -750,6 +803,8 @@ import { Pin } from "lucide-react";
 ```ts
 interface ToggleProps extends BaseToggle.Props {
   size?: Size;
+  variant?: "ghost" | "soft"; // default "ghost", preserving the flat off state
+  shape?: "default" | "pill"; // default "default"; icon-only pills are circular
   icon?: IconElement; // before the label; alone, the toggle is square
 }
 ```
@@ -765,8 +820,12 @@ Wraps Base UI's [Toggle](https://base-ui.com/react/components/toggle): `pressed`
 
 ## Style
 
-- Off: flat `text-secondary`, with `hover` on hover. On: a `well` fill and the `text` color, with a transparent reserved border; hover keeps that selected fill. Hover never adds a boundary; keyboard focus reuses `mu-focus`.
-- Disabled: `text-disabled`; an on Toggle keeps its well and transparent border. In forced colors an on Toggle uses a system-colored boundary so selection survives when fills disappear.
+- Default (`variant="ghost"`): off: flat `text-secondary`, with `hover` on hover. On: a `well` fill and the `text` color, with a transparent reserved border; hover keeps that selected fill. Fill and text changes are immediate. Hover never adds a boundary; keyboard focus reuses `mu-focus`.
+- `variant="soft"`: off uses `hover` and `text-secondary`; hover uses `well` and `text`; on uses the distinct `selected` fill and `text`, retained on hover. The reserved border stays transparent; focus still uses `mu-focus`. No application `data-pressed` color rules are needed.
+- `shape="pill"` uses `radius-full` and equal size-row horizontal padding. An icon-only pill is circular. Heights, icon sizes and 44px touch targets stay unchanged.
+- Disabled soft toggles use `text-disabled` and `well` when off; an on toggle keeps `selected`. Neither responds to hover.
+- Disabled default toggles: `text-disabled`; an on Toggle keeps its well and transparent border. In forced colors an on Toggle uses a system-colored boundary so selection survives when fills disappear.
+- For emoji, keep the Lucide-only `icon` slot empty. Compose a span in `children`, hide the emoji from assistive technology when the control has an `aria-label`, and use the documented [compact reaction picker](popover.md#compact-reaction-picker) layout for a square emoji cell. This does not rely on the internal icon-only class.
 - A label wraps when its row runs out of room; an icon-only toggle never shrinks. A ToggleGroup is at most as wide as its container and grows in height to keep long translated labels readable. On touch screens each Toggle reserves at least 44px in each direction.
 
 <!-- docs/components/toggle-group.md -->
@@ -799,7 +858,7 @@ import { Bold, Code, Italic } from "lucide-react";
 
 | Part | Base UI part | Renders |
 | --- | --- | --- |
-| `ToggleGroup` | `ToggleGroup` | A `<div role="group">`. Takes `size`. Without `multiple`, adds the sliding key |
+| `ToggleGroup` | `ToggleGroup` | A `<div role="group">`. Takes `size`. Without `multiple`, adds the selected key |
 | `Toggle` | `Toggle` | One item, a `<button aria-pressed>` |
 | `Separator` | `Separator` | A line between clusters, `multiple` groups only |
 
@@ -832,7 +891,7 @@ Base UI's props pass through: `value`, `defaultValue`, `onValueChange`, `multipl
 - `multiple`: items 2px apart, using Toggle's `well` fill and `text` when on, with no visible border in normal colors. Keyboard focus stays separate from selection.
 - Inside a segmented key, the label's line box can tighten at xs and sm to leave room for the focus border without changing geometry; its font size stays in the size row. Long labels wrap and increase the group's height.
 - Use the existing `md` size for a labeled layout choice at the top of a settings popover: a 32px group, 28px selected face and 16px icons. Keep `sm` (24px) for dense contexts; do not invent a height between the size rows.
-- Without `multiple`: a quiet `well` and contrasting `key` fill, with no visible group or selected-key border in normal colors. The selected label and icon use `text`; hover only changes label and icon contrast, without adding a fill or moving the key. Focus reuses `mu-focus`; do not add a component-specific focus treatment. In forced colors the selected key retains its text-colored border. The key slides to the chosen item over `duration-settle` with `ease-settle` and re-measures when an item changes width. Under reduced motion it jumps. On touch screens every item reserves at least 44px in each direction, without overlapping its neighbor.
+- Without `multiple`: a quiet `well` and contrasting `key` fill, with no visible group or selected-key border in normal colors. The selected label and icon use `text`; hover only changes label and icon contrast, without adding a fill or moving the key. Focus reuses `mu-focus`; do not add a component-specific focus treatment. In forced colors the selected key retains its text-colored border. The key updates immediately and re-measures when an item changes width. Selection and label changes do not animate. On touch screens every item reserves at least 44px in each direction, without overlapping its neighbor.
 
 <!-- docs/components/menu.md -->
 
@@ -924,7 +983,7 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on
 - A Separator has 6px above and below, the same as the popup padding, and runs edge to edge.
 - On touch screens rows are at least 44px tall; menus remain anchored floating lists, including submenus. The highlighted or keyboard-focused row uses `hover` with the row's radius (`radius-sm` at sm, `radius-md` at md), and so does a row whose menu is open (a SubmenuTrigger, or a `menuClasses().item` row that is a `Menu.Trigger`). Disabled rows and their icons use `text-disabled` without fading the whole row. `danger` rows use `danger`.
 - A ghost trigger keeps its `hover` background while the menu is open.
-- Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
+- Opening and closing use the shared [Motion](../motion.md) fade and `space-1` offset over `duration-fade`. Both are immediate under reduced motion; item highlighting never animates.
 - A menu below or above its trigger sits 4px from it. A submenu opens beside its trigger row, its own padding (6px) from the row. The row sits the same 6px inside the parent menu, so the submenu's edge touches the parent's edge.
 - A menu that opens to the side of its trigger (`side` left, right, `inline-start` or `inline-end`; a submenu always does), aligned to `start` or `end`, moves along the trigger by its own top padding (6px, read when it is placed). Its first row lines up with the trigger. With no room below, it opens upward instead and its last row lines up with the trigger. A menu that opens above or below, or is centered, does not move.
 
@@ -1149,13 +1208,13 @@ Wraps Base UI's [Input](https://base-ui.com/react/components/input), so inside a
 - Provide a `Field.Label` or `aria-label`. Never a placeholder alone.
 - `prefix` and `suffix` hold an icon, a short word or a small ghost Button.
 - `sm` for filters inside panels, `md` everywhere else.
-- An app's own one-line field, such as a tag input around a native `<input>`, takes `inputClasses()` on its box: focus anywhere inside darkens the edge, and `aria-invalid="true"` or `aria-disabled="true"` on the box show those states. See [Class functions](../custom-components.md#class-functions).
+- An app's own one-line field, such as a tag input around a native `<input>`, takes `inputClasses()` on its box: typing focus keeps the edge unchanged, and `aria-invalid="true"` or `aria-disabled="true"` on the box show those states. See [Class functions](../custom-components.md#class-functions).
 
 ## Style
 
 - Enabled fields use flat `surface` with a quiet 1px `edge` border. A gray well is reserved for the disabled state.
 - Typed text weight 400; placeholder `text-secondary`. On touch screens typed text is 16px at every size, so iOS Safari does not zoom in on focus; the field keeps its height.
-- Hover keeps the quiet `edge`; focus recolors the 1px edge to `focus-edge` (ink), on click and keyboard alike. There is no ring around the field. The background stays fixed on hover and focus. Invalid fields keep their `danger` edge on hover and focus. Disabled fields use `well`, a quiet `edge` and `text-disabled` text. See [boundary contrast](../depth.md#rules) for the resting edge's contrast tradeoff.
+- Hover, focus and press keep the same `edge` border and `surface` fill. The caret or text selection indicates typing focus; there is no focus border change, ring or animation. Invalid fields retain their `danger` edge while focused. Disabled fields use `well`, a quiet `edge` and `text-disabled` text. Forced colors uses a 2px system focus edge. See [boundary contrast](../depth.md#rules) for the resting edge's contrast tradeoff.
 - The side with a prefix or suffix has 2px less padding.
 
 <!-- docs/components/textarea.md -->
@@ -1192,11 +1251,11 @@ Base UI has no textarea part, so this renders Base UI's `Field.Control` as a `<t
 
 - Provide a `Field.Label` or `aria-label`.
 - Rich content is not a textarea: use the editor (`@usememos/editor`) with [Prose](prose.md).
-- An app's own multi-line field, such as a content-editable editor, takes `textareaClasses()`: focus darkens the edge, and `aria-invalid="true"` or `aria-disabled="true"` show those states. See [Class functions](../custom-components.md#class-functions).
+- An app's own multi-line field, such as a content-editable editor, takes `textareaClasses()`: the caret or text selection indicates focus without changing the edge, and `aria-invalid="true"` or `aria-disabled="true"` show those states. See [Class functions](../custom-components.md#class-functions).
 
 ## Style
 
-- Looks like [Input](input.md). Resizes vertically only.
+- Looks like [Input](input.md), including an unchanged border and surface under mouse and keyboard focus. The caret or text selection identifies the active field; state changes have no animation. Resizes vertically only.
 - On touch screens typed text is 16px on a 20px line at every size, like Input, so iOS Safari does not zoom in on focus.
 
 <!-- docs/components/select.md -->
@@ -1250,7 +1309,7 @@ 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
+  alignItemWithTrigger?: boolean; // default false: open below the trigger
   side?: Side; align?: Align; // used when alignItemWithTrigger is false
   container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
 }
@@ -1271,9 +1330,9 @@ Base UI's props pass through: `items`, `value`, `defaultValue`, `onValueChange`,
 
 ## Style
 
-- Trigger: a neutral key ([Button](button.md) `neutral`), a quiet `edge` at rest and on hover, value left-aligned at weight 400, `ChevronsUpDown` in `text-secondary`. `ghost`: a ghost Button with the `text` color, `hover` on hover and while open. Placeholder in `text-secondary`, also weight 400. Invalid: a `danger` edge at rest and on hover; focus reuses the shared 1px edge while the error message stays visible.
+- Trigger: a neutral key ([Button](button.md) `neutral`), a quiet `edge` at rest and on hover, value left-aligned at weight 400, a single `ChevronDown` in `text-secondary`. `ghost`: a ghost Button with the `text` color, `hover` on hover and while open. Placeholder in `text-secondary`, also weight 400. Invalid: a `danger` edge at rest and on hover; focus reuses the shared 1px edge while the error message stays visible.
 - List: `mu-popup`, 6px padding, at least `menu-width` and the trigger's width, at most `menu-max-width` or the trigger's width when that is wider. Rows like [Menu](menu.md) items: 28px at sm, 32px at md, highlight in the row's radius; the highlighted row uses `hover`.
-- Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
+- Opens below the trigger, aligned to its start edge; collision handling can flip it when space is limited. `alignItemWithTrigger={true}` opts into value-aligned positioning. Opening and closing use the shared [Motion](../motion.md) treatment: a 100ms fade and `space-1` offset, with no scale or chevron rotation. Under reduced motion both are immediate. The chosen value uses one check; row highlighting identifies the current pointer or keyboard target and updates without animation.
 
 <!-- docs/components/combobox.md -->
 
@@ -1375,12 +1434,12 @@ Base UI's props pass through: `items`, `value`, `defaultValue`, `onValueChange`,
 
 ## Style
 
-- The box is an [Input](input.md): flat `surface`, `edge`, and the focused edge on the box. The search icon and chevron are `text-secondary`; the chevron turns `text` on hover. Disabled text and both icons use `text-disabled`. The chevron has a built-in Tooltip using `triggerLabel`.
+- The box is an [Input](input.md): flat `surface`, `edge`, with no border or surface change under hover, focus or press. The caret or text selection indicates typing focus, without animation. The search icon and chevron are `text-secondary`; the chevron turns `text` on hover. Disabled text and both icons use `text-disabled`. The chevron has a built-in Tooltip using `triggerLabel`.
 - List: `mu-popup`, 6px padding, as wide as the input and at least `menu-width`. Rows like [Menu](menu.md) items: 28px at sm, 32px at md, highlight in the row's radius. The list is at most `list-height` (240px) tall, then it scrolls.
 - Rows are text weight 400; the highlighted row uses `hover`; the chosen row has a check at the end.
 - Empty text: `body` in `text-secondary`, `space-3` by `space-4` padding.
 - Grid cells: square, a control height, `inset` apart, `row-radius`; the highlighted cell uses `hover`, the chosen cell sits in a `well` like a pressed Toggle. No check.
-- Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
+- Opening and closing use the shared [Motion](../motion.md) fade and `space-1` offset over `duration-fade`. Both are immediate under reduced motion; input feedback and option highlighting never animate.
 
 <!-- docs/components/checkbox.md -->
 
@@ -1458,7 +1517,7 @@ Wraps Base UI's [Switch](https://base-ui.com/react/components/switch) root with
 
 - A pill well with a round knob and a quiet `edge` at rest; the well fills with `primary` when on. The track keeps its quiet boundary and fill on hover. Keyboard focus uses a fine 1px contrasting boundary.
 - Height = checkbox box + 2px; width = height × 1.7.
-- The knob is flat `text`, inset 2px; `on-primary` when on. It slides with `ease-settle` when the state changes, without growing on press. Under reduced motion it doesn't slide. Disabled switches keep the knob position, but use a quiet `edge` and a `text-disabled` knob. On touch screens margins reserve a 44px target without enlarging the mark.
+- The knob is flat `text`, inset 2px; `on-primary` when on. Only its position slides with `ease-settle` when the state changes, without growing on press; all colors change immediately. Under reduced motion it has no transition. Disabled switches keep the knob position, but use a quiet `edge` and a `text-disabled` knob. On touch screens margins reserve a 44px target without enlarging the mark.
 
 <!-- docs/components/radio-group.md -->
 
@@ -1544,7 +1603,7 @@ import { Bell, User } from "lucide-react";
 | Part | Base UI part | Renders |
 | --- | --- | --- |
 | `Tabs.Root` | `Tabs.Root` | A `<div>` around the list and panels. Takes `size` |
-| `Tabs.List` | `Tabs.List` with `Tabs.Indicator` | The well, a `<div role="tablist">`, with the sliding key built in |
+| `Tabs.List` | `Tabs.List` with `Tabs.Indicator` | The well, a `<div role="tablist">`, with the selected key built in |
 | `Tabs.Tab` | `Tabs.Tab` | One tab, a `<button role="tab">`. Takes `icon` |
 | `Tabs.Panel` | `Tabs.Panel` | One tab's content, a `<div role="tabpanel">` |
 
@@ -1571,7 +1630,7 @@ Base UI's props pass through: `value`, `defaultValue`, `onValueChange` on the ro
 
 ## Style
 
-- Shares the quiet well and sliding key with a single-choice ToggleGroup. Normal selection uses a `key` fill without a visible border; hover only changes label and icon contrast. Focus reuses `mu-focus`, independently of selection. In forced colors the selected key retains its text-colored border. Use the standard sm and md size rows and the shared inset and radius tokens.
+- Shares the quiet well and selected key with a single-choice ToggleGroup. Selection and label changes update immediately, without a slide or color fade. Normal selection uses a `key` fill without a visible border; hover only changes label and icon contrast. Focus reuses `mu-focus`, independently of selection. In forced colors the selected key retains its text-colored border. Use the standard sm and md size rows and the shared inset and radius tokens.
 - Tabs are sized to their labels and wrap when space is narrow; the well and key grow to fit. On touch screens each tab is at least 44px tall and wide. The key re-measures when a label changes width.
 - Selected and hovered labels `text`, others `text-secondary`. Weight never changes, so labels don't shift.
 
@@ -1597,7 +1656,7 @@ import { Collapsible } from "@usememos/ui";
 | Part | Base UI part | Renders |
 | --- | --- | --- |
 | `Collapsible.Root` | `Collapsible.Root` | A `<div>` around the trigger and panel. Takes `size` |
-| `Collapsible.Trigger` | `Collapsible.Trigger` | A ghost [Button](button.md) with a chevron at the end that turns while open |
+| `Collapsible.Trigger` | `Collapsible.Trigger` | A ghost [Button](button.md) with a chevron at the end that points up while open |
 | `Collapsible.Panel` | `Collapsible.Panel` | The content, a `<div>`; unmounted while closed unless `keepMounted` |
 
 ## Props
@@ -1620,9 +1679,9 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `disabled`
 ## Style
 
 - The trigger is a ghost key that bleeds `px` to the left, so its label lines up with the content below.
-- The chevron is `text-secondary` and turns 180° over `duration-settle` with `ease-settle`.
+- The chevron is `text-secondary` and changes orientation by 180° immediately when open; no rotation transition.
 - Disabled labels and chevrons use `text-disabled`.
-- The panel fades in and rises `space-1` over `duration-fade`. Its height never animates. No rise or turn under reduced motion.
+- The panel opens and closes with the shared [Motion](../motion.md) fade and `space-1` offset over `duration-fade`. Its height never animates. Opening and closing are immediate under reduced motion.
 
 <!-- docs/components/dialog.md -->
 
@@ -1708,7 +1767,7 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal`, `d
 
 - `mu-popup` with `radius-2xl`, `space-5` padding, `dialog-width` wide; children stack `space-4` apart, and the Footer sits `space-6` under them. The backdrop is `overlay`.
 - Title: `title`. Description: `body` in `text-secondary`, `space-1` under the title, so the two read as one header. The X is a small ghost Button at `space-4` from the corner. On touch screens it reserves 44px, and the title leaves room for that target.
-- 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.
+- Opening and closing use the shared [Motion](../motion.md) fade and `space-1` offset over `duration-settle`; the backdrop fades with the same timing. A sheet uses `space-6` from the bottom, with square bottom corners and full-width buttons stacked with the action on top. Opening and closing are immediate under reduced motion, including the backdrop.
 - Long content scrolls the viewport around the panel.
 - `bare`: no padding, no gap and no X; the content is clipped to the radius. Set the width with `className` when it differs from `dialog-width`.
 - `fullScreen`: the viewport's padding goes, and the popup fills it with square corners.
@@ -1775,7 +1834,7 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `onOpenChan
 - `panel`: content `space-5` in, stacked `space-4` apart, as in a Dialog; the X is a small ghost Button at `space-4` from the top end corner. On touch screens it reserves 44px, and the title leaves room for that target. Title: `title`. Description: `body` in `text-secondary`, `space-1` under the title.
 - `bare`: no padding, gap or X. A visually hidden `Drawer.Close` named `closeLabel` follows the content, so screen readers on touch screens can close it.
 - The backdrop is `overlay`; it fades as the drawer is swiped away.
-- Slides in from its edge over `duration-settle` with `ease-settle` and follows the finger while swiped. Under reduced motion it fades instead.
+- Opens and closes from its attached edge over `duration-settle` with `ease-settle`, with a backdrop fade of the same duration. It follows the finger while swiped. Under reduced motion both panel and backdrop change immediately, without a slide or fade. See [Motion](../motion.md).
 
 <!-- docs/components/popover.md -->
 
@@ -1838,7 +1897,106 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on
 - `mu-popup` (`surface`, a 1px `edge`, `radius-xl`), `space-4` padding, `popover-width` wide. Children stack `space-3` apart.
 - Title: `label`. Description: `caption` in `text-secondary`, `space-1` under the title.
 - `list`: 6px padding and no gap, like a Menu. A title and description inside line up with the rows' text, with `space-2` above the title and below the description.
-- Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
+- Opening and closing use the shared [Motion](../motion.md) fade and `space-1` offset over `duration-fade`. Both are immediate under reduced motion.
+
+
+## Compact reaction picker
+
+Compose Popover, Toggle and Button; the library does not ship a ReactionPicker. The app owns counts, user identity, requests, pending/disabled state and whether a successful choice closes the popup. Both places read the same controlled `pressed` values; do not give the picker a separate selection state. This example keeps the popup open so several choices can be toggled.
+
+On desktop the strip is 24px high (`sm`): soft pills, 14px emoji, 13px counts and 4px between them. The ghost add button is circular and the same height. The picker uses `mu-compact` for 28px cells, 2px between cells and 8px total inset (including its border). It sizes to its contents and Base UI anchors it to the add button. The default eight choices form one row; narrow viewports and coarse pointers use four columns. On coarse pointers all controls actually reserve at least 44px in the layout, so adjacent hit areas never overlap. Text and emoji stay the same size.
+
+`icon` remains a Lucide slot. An emoji is content in `children`, with its own type class; the small layout class below makes an emoji-only Toggle square without depending on undocumented icon-slot behavior or internal `mu-*` classes. This is a CSS grid of ordinary toggles, not an ARIA grid or menu: Tab reaches each choice, Space/Enter toggles it, Escape dismisses an open Tooltip first, then the popup and restores trigger focus. Give each emoji a localized accessible name and a matching Tooltip. The popup is named with `aria-label` because this compact example has no visible title.
+
+```tsx
+import { Button, Popover, Toggle, Tooltip } from "@usememos/ui";
+import { SmilePlus } from "lucide-react";
+
+const choices = [
+  { emoji: "👍", label: "Thumbs up" },
+  { emoji: "❤️", label: "Heart" },
+  { emoji: "🎉", label: "Celebrate" },
+  { emoji: "😄", label: "Smile" },
+  { emoji: "🤔", label: "Thinking" },
+  { emoji: "👀", label: "Eyes" },
+  { emoji: "🚀", label: "Rocket" },
+  { emoji: "🙏", label: "Thanks" },
+];
+
+type Reaction = { emoji: string; label: string; count: number; pressed: boolean };
+
+// The parent supplies server counts and the current user's selected choices.
+function CompactReactions({ reactions, onPressedChange }: {
+  reactions: Reaction[];
+  onPressedChange: (emoji: string, pressed: boolean) => void;
+}) {
+  return (
+    <Tooltip.Provider>
+      <div className="reaction-strip" role="group" aria-label="Reactions">
+        {reactions.filter((reaction) => reaction.count > 0).map((reaction) => (
+          <Toggle
+            key={reaction.emoji}
+            variant="soft" shape="pill" size="sm"
+            aria-label={`${reaction.label}, ${reaction.count} reactions`}
+            pressed={reaction.pressed}
+            onPressedChange={(pressed) => onPressedChange(reaction.emoji, pressed)}
+          >
+            <span className="reaction-label">
+              <span className="mu-body" aria-hidden>{reaction.emoji}</span>
+              <span className="mu-caption reaction-count" aria-hidden>{reaction.count}</span>
+            </span>
+          </Toggle>
+        ))}
+        <Popover.Root>
+          <Tooltip.Root>
+            <Tooltip.Trigger render={
+              <Popover.Trigger render={
+                <Button variant="ghost" shape="pill" size="sm" icon={<SmilePlus />} aria-label="Add reaction" />
+              } />
+            } />
+            <Tooltip.Popup>Add reaction</Tooltip.Popup>
+          </Tooltip.Root>
+          <Popover.Popup align="start" aria-label="Choose reactions" className="mu-compact reaction-popup">
+            <div className="reaction-options">
+              {choices.map(({ emoji, label }) => (
+                <Tooltip.Root key={emoji}>
+                  <Tooltip.Trigger render={
+                    <Toggle
+                      variant="soft" className="reaction-option"
+                      aria-label={label}
+                      pressed={reactions.some((reaction) => reaction.emoji === emoji && reaction.pressed)}
+                      onPressedChange={(pressed) => onPressedChange(emoji, pressed)}
+                    >
+                      <span className="mu-body" aria-hidden>{emoji}</span>
+                    </Toggle>
+                  } />
+                  <Tooltip.Popup>{label}</Tooltip.Popup>
+                </Tooltip.Root>
+              ))}
+            </div>
+          </Popover.Popup>
+        </Popover.Root>
+      </div>
+    </Tooltip.Provider>
+  );
+}
+```
+
+The remaining CSS describes content and layout, not control colors, borders, focus or disabled states. Put it in the app's stylesheet, after the library (or in a later cascade layer). `Popover.Popup` supplies the surface and viewport collision constraints; keep its `max-width`. Its size context is md even if the trigger is sm. `mu-compact` must be on the popup itself because it is portaled.
+
+```css
+.reaction-strip { display: flex; flex-wrap: wrap; align-items: center; gap: var(--mu-space-1); }
+.reaction-label { display: inline-flex; align-items: center; gap: var(--mu-space-1); }
+.reaction-count { font-variant-numeric: tabular-nums; }
+.reaction-popup { width: max-content; padding: calc(var(--mu-space-2) - 1px); }
+.reaction-options { display: grid; grid-auto-flow: column; gap: var(--mu-inset); max-height: var(--mu-list-height); overflow-y: auto; }
+.reaction-option { width: var(--mu-row-height); padding: 0; }
+@media (max-width: 639px), (pointer: coarse) {
+  .reaction-options { grid-auto-flow: row; grid-template-columns: repeat(4, max-content); }
+}
+```
+
+A custom app theme now supplies `selected` alongside its other [color tokens](../color.md#app-themes); it must stay distinct from `hover`/`well` and keep at least 4.5:1 with `text` and `text-disabled`. Consumers do not need `data-pressed:bg-*`, `data-pressed:hover:bg-*`, forced-color rules, a custom focus treatment, control corner overrides or touch-size overrides.
 
 <!-- docs/components/tooltip.md -->
 
@@ -1896,7 +2054,7 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `disabled`
 ## Style
 
 - `primary` background, `on-primary` text, `label-sm`, `radius-md`, `space-1` by `space-2` padding, at most `tooltip-width` wide.
-- Opens after 400ms of hover, or at once on keyboard focus. Fades in and rises `space-1`; no rise under reduced motion.
+- Waits 400ms on hover before opening; keyboard focus has no opening delay. Opening and closing use the shared [Motion](../motion.md) fade and `space-1` offset over `duration-fade`. Both transitions are disabled under reduced motion. Moving between tooltips in a group skips the delay and replayed entrance.
 
 <!-- docs/components/toast.md -->
 
@@ -1956,7 +2114,7 @@ Base UI's props pass through: `timeout` (default 5000ms) and `limit` (default 3)
 
 - `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 `text-secondary`, `success`, `warning` or `danger`; title in `label`; description in `caption` `text-secondary`; the action as a small neutral Button; the X as a small ghost Button.
-- Newest in front; the ones behind peek out `space-2` below and shrink. A toast behind hides its text at once and gets a 1px `edge`, so its text never shows below a shorter front toast and the peeks stay visible in Dark. Hover or focus fans them out downward, `space-3` apart. Toasts slide in from above and can be swiped up or to the right. Under reduced motion they only fade.
+- Newest in front; the ones behind peek out `space-2` below and shrink. A toast behind hides its text at once and gets a 1px `edge`, so its text never shows below a shorter front toast and the peeks stay visible in Dark. Hover or focus fans them out downward, `space-3` apart. Toasts slide in from above and can be swiped up or to the right. Opening and closing remain short, using `duration-settle`; they add no bounce or staged entrance. Under reduced motion visibility and stack changes are immediate, without a slide, scale or fade. See [Motion](../motion.md).
 
 <!-- docs/components/avatar.md -->
 
@@ -2372,7 +2530,7 @@ Every native attribute passes through.
 ## Style
 
 - `surface` fill, a 1px `line` edge, `radius-lg`. No shadow: it is flat, like a field.
-- Rows pad `space-3` × `space-4` at md and `space-2` × `space-3` at sm, divided by a 1px `line`. No hover on a plain row. An ItemButton fills its row, padded as the row is, lays out its children in a row `space-3` apart, highlights with `hover`, and rounds with the box at the first and last row; keyboard focus darkens the row's reserved border.
+- Rows pad `space-3` × `space-4` at md and `space-2` × `space-3` at sm, divided by a 1px `line`. No hover on a plain row. An ItemButton fills its row, padded as the row is, lays out its children in a row `space-3` apart, highlights immediately with `hover` on pointer hover or touch press, and rounds with the box at the first and last row; keyboard focus darkens the row's reserved border.
 - Text is `body` in `text`.
 
 <!-- docs/components/prose.md -->
@@ -2799,6 +2957,10 @@ In an extension or an embed, pass the same `container` to every `Popup` and to `
 <Toast.Viewport container={shadowRoot} />
 ```
 
+## Compact reactions
+
+Use `Toggle variant="soft" shape="pill" size="sm"` for the display strip and a ghost pill Button for its add action. Compose the picker from Popover and controlled Toggles with `mu-compact`. See the [complete compact reaction picker recipe](components/popover.md#compact-reaction-picker) for emoji content, shared state, content-sized placement and the four-column touch layout. Counts and requests stay in the app.
+
 ## 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.
@@ -3057,7 +3219,7 @@ An app changes only the color and font tokens. Every other token and every `mu-*
 
 - Every class the package ships starts with `mu-`.
 - The [public classes](custom-components.md#public-classes) are for apps too: size rows (`mu-s-md`), surface roles (`mu-key`), focus, touch targets, icons and the type scale. Apps apply them to their own parts and never override them.
-- `mu-positioner` puts a popup's positioner on `layer-popup`, and `mu-popup-motion` makes a popup fade in and rise `space-1` (no rise under reduced motion).
+- `mu-positioner` puts a popup's positioner on `layer-popup`, and `mu-popup-motion` supplies the shared opening and closing fade and `space-1` offset over `duration-fade`. Under reduced motion it has no transition, including opacity. See [Motion](motion.md).
 - The surface classes `mu-well`, `mu-key` and `mu-popup` apply flat fills and borders. Use them for new parts. See [Surfaces and boundaries](depth.md).
 - `mu-prose` styles rendered content. See [Prose](components/prose.md).
 - `mu-icon` applies icon size and stroke rules outside a component, at the size of the nearest size row; `mu-icon-xs`, `mu-icon-sm` and `mu-icon-md` set a fixed size on their own. See [Icons](icons.md).
@@ -3115,7 +3277,7 @@ import { Ellipsis, Pin, Trash2 } from "lucide-react";
 - **`className` and `style`** pass through to the part's element, after our classes.
 - **Accessible names.** A control without a visible label takes `aria-label`. Icon-only controls always do.
 - **`tone`** describes a label or status treatment. The shared status tones are `"neutral" | "success" | "warning" | "danger"`. Badge also keeps `"outline"` for a quiet label and `"primary"` for emphasis; these are label treatments, not statuses. Badge's user-chosen `color` is allowed only with `"neutral"` (or an omitted tone). Toasts use the shared status tones through Base UI's `type` prop.
-- **`variant`** selects a component's predefined appearance or structure. Values belong to that component, not a global variant set: Button has `"primary" | "neutral" | "ghost" | "danger"`; Select.Trigger has `"neutral" | "ghost"`; Popover.Popup has `"panel" | "list"`; Dialog.Popup and Drawer.Popup have `"panel" | "bare"`. See each component's page for usage and defaults.
+- **`variant`** selects a component's predefined appearance or structure. Values belong to that component, not a global variant set: Button has `"primary" | "neutral" | "ghost" | "danger"`; Toggle has `"ghost" | "soft"`; Select.Trigger has `"neutral" | "ghost"`; Popover.Popup has `"panel" | "list"`; Dialog.Popup and Drawer.Popup have `"panel" | "bare"`. See each component's page for usage and defaults.
 - **Interaction states are not variants.** Hover, focus, pressed, selected, disabled, invalid and loading use the component's behavior props and state attributes, with the shared treatments in [States](states.md). Do not add variants or component-specific tokens for these states.
 - **Native props pass through** to the element a component or part renders.
 
@@ -3169,7 +3331,7 @@ A class function returns the classes that make any element look like a component
 
 | Function | Returns | For an app's own |
 | --- | --- | --- |
-| `buttonClasses({ variant, size, iconOnly })` | A string | Anchor that looks like an action |
+| `buttonClasses({ variant, size, shape, iconOnly })` | A string | Anchor that looks like an action |
 | `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 |
@@ -3178,7 +3340,7 @@ A class function returns the classes that make any element look like a component
 
 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 text field keeps its normal border and surface when it or its input has focus; use the caret or text selection to identify typing 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 directly focusable button or anchor also gets the row highlight on `:focus-visible`, even without `data-highlighted`. `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.
 - A tag with a user's color sets `--mu-badge-color` on the element: `style={{ "--mu-badge-color": tag.color } as React.CSSProperties}`. The fill becomes a tint of it; the text stays ink.
@@ -3213,7 +3375,7 @@ Apply these classes to an app's own elements. Don't override their rules: the pr
 | `mu-s-xs` | The xs size row: 20px | Secondary actions beside 13px text |
 | `mu-s-sm` | The sm size row: 24px | Dense toolbars, table rows, filters |
 | `mu-s-md` | The md size row: 32px | Everything else |
-| `mu-compact` | md controls and rows inside are `control-compact` (28px) tall; text, icons, padding and radius stay md | An app's sidebar with 28px rows, or a list Popover beside it |
+| `mu-compact` | md controls and rows inside are `control-compact` (28px) tall; text, icons, padding and radius stay md | An app's sidebar with 28px rows, a list Popover beside it, or a [compact picker](components/popover.md#compact-reaction-picker) |
 | `mu-base` | The system font, the row's text size and weight 500, the `text` color, and icon sizing for Lucide icons inside | The root of a control |
 | `mu-well` | `well` and a quiet 1px `edge` | A recessed surface; add a separate treatment for selection |
 | `mu-key` | `key` and a quiet 1px `edge`, including with selected or pressed attributes | A bounded control surface, or the bright selected face inside a well. It does not add interaction-state styling; use Toggle or ToggleGroup for choices |
@@ -3278,7 +3440,7 @@ An app on Tailwind CSS v4 loads `tailwind.css` after the package's other stylesh
 @import "@usememos/ui/tailwind.css";
 ```
 
-It maps the 28 color tokens, seven radius tokens and three font tokens to utilities with an `mu-` prefix, so they never clash with an app's own colors:
+It maps the 29 color tokens, seven radius tokens and three font tokens to utilities with an `mu-` prefix, so they never clash with an app's own colors:
 
 | Token | Utility |
 | --- | --- |