@usememos/ui 26.10.0 → 26.10.2

package/llms-full.txt

@@ -0,0 +1,2181 @@
+<!-- docs/README.md -->
+
+# Memos UI design system
+
+Memos UI is one calm, dense and tactile system for every product we build: memos (the app), the website, the web clipper and whatever comes next. It reads like ink on paper: pure grays, black ink for the one thing that matters, and no brand color competing with what people write. Controls have a little physical depth, so you can tell at a glance what holds a value and what you can press.
+
+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.
+
+## Who it is for
+
+- **Product code** in memos, the website, the web clipper and future usememos projects. Each product builds its screens from these components and patterns, so the products look and feel like one family.
+- **People and coding agents** who build or change the package. Start with [`AGENTS.md`](../AGENTS.md).
+
+It is not a general-purpose UI library for outside developers. Components are generic: nothing in the package knows what a note, a memo or a clip is.
+
+## Contents
+
+| Doc | What it covers |
+| --- | --- |
+| [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, Dark and High contrast, and how themes are chosen |
+| [Depth](depth.md) | The tactile model: recessed, key, raised, popup and flat; shadow tokens |
+| [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 |
+| [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 |
+| [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 |
+
+## Decisions at a glance
+
+- **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).
+- **Light, tactile by default.** Restrained depth that shows behavior. Light is the default theme; Dark and High contrast ship 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 focus rings, links and text selection, never as a fill.
+- **Status colors only for status.** Green means success, amber means warning, red means danger or error. None of them is used for emphasis.
+- **Lucide icons** at a fixed screen-pixel stroke: 1.5px at md and lg, 1.25px at sm and in badges.
+- **The system UI font** for all text. The package ships no font files.
+- **Dense, on a 4px grid.** Controls are 32px tall by default.
+
+<!-- docs/principles.md -->
+
+# Principles and voice
+
+## Principles
+
+1. **Content first.** The interface stays gray, so people's words, tags and images are 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. **Depth means behavior.** Recessed parts hold a state (wells, tracks). Raised parts can be pressed (buttons, keys, knobs). Flat parts are content, including text fields. Never add depth for decoration. See [Depth](depth.md).
+4. **Calm by default.** Hierarchy comes from text color and lightness steps, not from weight, size or extra color.
+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.
+
+## Voice and interface text
+
+- Sentence case everywhere: "Save note", not "Save Note".
+- Control labels are one or two words. Buttons start with a verb.
+- Address the reader as "you". Say what happened: "Note archived", not "Success!".
+- 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").
+
+## 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`.
+- 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.
+- Illustrations in empty states.
+
+<!-- docs/color.md -->
+
+# Color
+
+Memos UI is ink on paper: pure-gray neutrals, `primary` ink for emphasis, one quiet blue for focus, links and selection, and status colors only when there is a status.
+
+## Roles
+
+| Role | Tokens | Used for |
+| --- | --- | --- |
+| Surfaces | `canvas`, `surface`, `overlay` | The page; then inputs, menus, dialogs and toasts one step up. `overlay` dims the page behind dialogs |
+| Wells | `well`, `edge` | Switch, tab, checkbox and radio wells, pressed toggles, inline code. `edge` is the 1px border of wells and inputs |
+| Hover | `hover` | Rows, ghost buttons, the highlighted menu row. About 4% ink over surface |
+| Keys | `key`, `key-hover`, `key-sheen` | Neutral buttons, select triggers, the selected tab, switch knobs, kbd |
+| Text | `ink`, `ink-muted` | Primary and secondary text. Both pass 4.5:1 on every surface, well and key in every theme |
+| Emphasis | `primary`, `primary-hover`, `on-primary` | Primary button, checked checkbox and radio, switch when on, tooltip |
+| Meta | `accent`, `selection`, `focus` | Links, focus ring, text selection. Never a fill |
+| Status | `success`, `warning`, `danger` and their `-soft` pairs; `danger-key`, `on-danger` | Toasts, badges, field errors, danger buttons |
+| Lines | `line` | Separators, table rules, menu dividers |
+
+## Rules
+
+- Neutrals are pure gray, never tinted.
+- `accent` is a quiet blue used only for links, focus and selection. If a screen has blue on it at rest, apart from links, something is wrong.
+- 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.
+- Use tokens through their CSS variables. Every token is a custom property with the `--mu-` prefix: the `well` token is `var(--mu-well)`. The prefix keeps the tokens apart from an app's own variables and from Tailwind's. Never copy raw values into component or product code.
+
+## Themes
+
+There are three themes: **Light** (the default), **Dark** and **High contrast**.
+
+- Colors are generated in OKLCH from a neutral base, the ink and a contrast level. A new theme means new inputs, not hand-picked values.
+- Dark keeps the same depth model. Wells go darker than `canvas`, keys go lighter, `key-sheen` drops to 8%, and `primary` flips to near-white with a dark `on-primary`.
+- Non-text contrast: `edge` is about 1.5:1 in Light and Dark. That is the soft border people expect from a calm interface, and it is below WCAG's 3:1 for control boundaries. High contrast raises `edge` to 5.3:1 and outlines every key. Offer High contrast wherever the theme is chosen.
+
+### Choosing a theme
+
+Set `data-theme="light" | "dark" | "contrast"` on the root element, or on any `.mu-root` element. Without the attribute the tokens are Light.
+
+The package does not read `prefers-color-scheme` itself. The app does, so that a saved preference wins over the system setting. Dark sets `color-scheme: dark`, so native scrollbars and form controls follow.
+
+### App themes
+
+An app can offer more themes than the three the package ships, such as a warm Paper theme in memos. An app theme is a rule that sets the tokens under its own `data-theme` value:
+
+```css
+[data-theme="paper"] {
+  color-scheme: light;
+  --mu-canvas: #f5ede4;
+  --mu-surface: #fbf6f0;
+  /* every other color token, and the five shadow tokens */
+}
+```
+
+- Set every color token in the table below and the five shadow tokens in [Depth](depth.md). A token the theme leaves out keeps its Light value, so a partial theme mixes two palettes.
+- Keep the rules on this page: `primary` stays ink, not a brand hue; `accent` is only for focus, links and selection; 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, Dark and High contrast.
+- 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.
+
+## Color tokens
+
+| Token | Light | Dark | High contrast | Usage |
+| --- | --- | --- | --- | --- |
+| `canvas` | `#f9f9f9` | `#0f0f0f` | `#ffffff` | Page background |
+| `surface` | `#ffffff` | `#1a1a1a` | `#ffffff` | One lightness step above canvas: inputs, menus, popovers, dialogs, toasts, table headers |
+| `well` | `#e4e4e4` | `#262626` | `#e6e6e6` | Recessed parts that hold a state: switch, tab, checkbox and radio wells, pressed toggles, inline code. Paired with `edge` and `shadow-track`. Not for text entry |
+| `hover` | `#ededed` | `#242424` | `#d9d9d9` | Hover on rows, ghost buttons and wells; the highlighted row in menus and selects |
+| `key` | `#ffffff` | `#343434` | `#ffffff` | Raised parts you press: neutral buttons, select triggers, the selected tab, switch knobs, kbd. Paired with `shadow-key` or `shadow-raised` |
+| `key-hover` | `#fbfbfb` | `#3c3c3c` | `#f2f2f2` | Hover on a neutral key |
+| `key-sheen` | `rgba(255,255,255,0.18)` | `rgba(255,255,255,0.08)` | `#ffffff00` | Top light on keys: a gradient from `key-sheen` at the top edge to clear at 60% of the height |
+| `edge` | `#d0d0d0` | `#353535` | `#6b6b6b` | 1px border of inputs and wells. About 1.5:1 on canvas in Light and Dark; 5.3:1 in High contrast, where it also outlines keys |
+| `line` | `#e0e0e0` | `#262626` | `#6b6b6b` | Separators, table rules and menu dividers. 1.25:1 in Light, so structural lines also need spacing or a heading |
+| `overlay` | `rgba(0,0,0,0.32)` | `rgba(0,0,0,0.6)` | `rgba(0,0,0,0.6)` | Backdrop behind dialogs and sheets |
+| `ink` | `#1a1a1a` | `#ededed` | `#000000` | Primary text and icons on canvas, surface, well and key (13:1 or more in every theme) |
+| `ink-muted` | `#5e5e5e` | `#adadad` | `#333333` | Secondary text: descriptions, placeholders, unselected tabs and toggles, shortcuts, timestamps (4.9:1 or more on every surface) |
+| `primary` | `#1f1f1f` | `#e6e6e6` | `#000000` | 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` | `#f5f5f5` | `#262626` | Hover on a primary key |
+| `on-primary` | `#ffffff` | `#111111` | `#ffffff` | 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)` | `oklch(0.42 0.14 255)` | The only hue at rest: focus rings, links, the text cursor and selection. 5.8:1 on canvas in Light. Never a fill |
+| `selection` | `rgba(40,99,171,0.18)` | `rgba(135,186,253,0.28)` | `rgba(0,75,151,0.25)` | Text selection and the selected range in an editor |
+| `focus` | `var(--mu-accent)` | `var(--mu-accent)` | `var(--mu-accent)` | Focus ring: 2px outline, 2px offset, on `:focus-visible` only |
+| `success` | `oklch(0.52 0.13 150)` | `oklch(0.78 0.14 150)` | `oklch(0.42 0.12 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` | `#e9f4ec` | Background of success badges and toasts |
+| `warning` | `oklch(0.5 0.11 70)` | `oklch(0.8 0.13 75)` | `oklch(0.45 0.11 70)` | Warning text and icons on `surface` or `warning-soft` (5.5:1 or more) |
+| `warning-soft` | `#fbf1df` | `#2a2112` | `#fbf1df` | Background of warning badges and toasts |
+| `danger` | `oklch(0.53 0.19 27)` | `oklch(0.72 0.16 25)` | `oklch(0.45 0.18 27)` | Danger text and icons: field errors, delete menu items, danger badges (5.0:1 or more on `surface` and `danger-soft`) |
+| `danger-key` | `oklch(0.53 0.19 27)` | `oklch(0.55 0.17 25)` | `oklch(0.45 0.18 27)` | Fill of a danger button. 5.3:1 or more with `on-danger` |
+| `danger-soft` | `#fbeaea` | `#2c1616` | `#fbeaea` | Background of danger badges and error toasts |
+| `on-danger` | `#ffffff` | `#ffffff` | `#ffffff` | Text on a danger key |
+
+Every text and background pair in this table keeps at least 4.5:1 in every theme. Depth (see [Depth](depth.md)) is added on top and never lowers contrast.
+
+<!-- docs/depth.md -->
+
+# Depth
+
+The default taste is "Light, tactile": restrained depth where depth shows behavior. Recessed parts hold a value. Raised parts can be pressed. Popups float. Everything else, including text fields and content, is flat.
+
+## Roles
+
+| Role | Class | Used for | Background | Shadow |
+| --- | --- | --- | --- | --- |
+| Recessed | `mu-recessed` | Switch, tab, checkbox and radio wells, pressed toggles | `well` with a 1px `edge` | `shadow-track`, a soft inner shadow from the top |
+| Key in a well | `mu-key` | The selected tab or segment, switch knobs | `key` with the `key-sheen` gradient | `shadow-key` |
+| Raised | `mu-raised` | Buttons, select triggers, kbd | `key` or `primary` with `key-sheen` | `shadow-raised`; `shadow-pressed` while held |
+| Popup | `mu-popup` | Menus, popovers, dialogs, sheets, toasts | `surface` | `shadow-pop` |
+| Flat | none | Inputs and textareas, checked boxes and radios, content | `surface` with `edge`, or `primary` | None |
+
+Each depth class applies a whole role in one class. Use them for new parts before writing new shadows.
+
+```css
+.mu-recessed { background-color: var(--mu-well); box-shadow: inset 0 0 0 1px var(--mu-edge), var(--mu-shadow-track); }
+.mu-raised   { background-color: var(--mu-key); background-image: linear-gradient(180deg, var(--mu-key-sheen), rgba(255,255,255,0) 60%); box-shadow: var(--mu-shadow-raised); }
+.mu-key      { background-color: var(--mu-key); background-image: linear-gradient(180deg, var(--mu-key-sheen), rgba(255,255,255,0) 60%); box-shadow: var(--mu-shadow-key); }
+.mu-popup    { background: var(--mu-surface); box-shadow: var(--mu-shadow-pop); border-radius: var(--mu-radius-xl); }
+```
+
+## Rules
+
+- Light always comes from the top.
+- Text entry is flat: an input is `surface` with an `edge`, never a gray well, so it never reads as disabled next to a key.
+- A checked box or radio holds a value, so it is a flat `primary` fill, not a raised key. Only things you press are raised.
+- **One rule for "selected".** A single choice among peers (tabs, a segmented filter) is a raised key sliding in a well. An on/off state (a toolbar toggle) is pressed into a well. Never mix the two in one row.
+- Content areas are flat. There is no card component: group content with spacing, a heading and a `Separator`.
+- No textures, no glass or blur behind text, and no neumorphism. Every fill and text pair keeps its contrast, and depth is added on top.
+- In High contrast, depth turns into outlines on every well and key, and `shadow-pressed` becomes an inner ring.
+
+## Shadow tokens
+
+| Token | Usage |
+| --- | --- |
+| `shadow-track` | Recessed parts: wells and the faint top shadow inside inputs. The border comes from `edge` |
+| `shadow-key` | Keys inside a well: the switch knob, the selected tab or segment |
+| `shadow-raised` | Free-standing keys on canvas or surface: buttons, select triggers, kbd |
+| `shadow-pressed` | A key while held |
+| `shadow-pop` | Menus, selects, popovers, dialogs, sheets and toasts: the floating layer |
+
+### Light
+
+```css
+--mu-shadow-track: inset 0 1px 2px rgba(0,0,0,0.10);
+--mu-shadow-key: 0 1px 2px rgba(0,0,0,0.16), 0 2px 6px rgba(0,0,0,0.08), inset 0 1px 0 rgba(255,255,255,0.9), inset 0 -1px 0 rgba(0,0,0,0.05);
+--mu-shadow-raised: inset 0 1px 0 rgba(255,255,255,0.25), inset 0 -1px 0 rgba(0,0,0,0.10), 0 0 0 0.5px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.12);
+--mu-shadow-pressed: inset 0 1px 3px rgba(0,0,0,0.22), 0 0 0 0.5px rgba(0,0,0,0.12);
+--mu-shadow-pop: 0 8px 24px rgba(0,0,0,0.10), 0 1px 3px rgba(0,0,0,0.08), 0 0 0 0.5px rgba(0,0,0,0.08), inset 0 1px 0 rgba(255,255,255,0.8);
+```
+
+### Dark
+
+```css
+--mu-shadow-track: inset 0 1px 2px rgba(0,0,0,0.55), inset 0 -0.5px 0 rgba(255,255,255,0.06);
+--mu-shadow-key: 0 1px 2px rgba(0,0,0,0.6), 0 2px 6px rgba(0,0,0,0.3), inset 0 1px 0 rgba(255,255,255,0.10);
+--mu-shadow-raised: inset 0 1px 0 rgba(255,255,255,0.10), inset 0 -1px 0 rgba(0,0,0,0.25), 0 0 0 0.5px rgba(0,0,0,0.6), 0 1px 2px rgba(0,0,0,0.5);
+--mu-shadow-pressed: inset 0 1px 3px rgba(0,0,0,0.6), 0 0 0 0.5px rgba(0,0,0,0.6);
+--mu-shadow-pop: 0 8px 24px rgba(0,0,0,0.6), 0 0 0 1px rgba(255,255,255,0.06), inset 0 1px 0 rgba(255,255,255,0.06);
+```
+
+### High contrast
+
+```css
+--mu-shadow-track: 0 0 0 0 rgba(0,0,0,0);
+--mu-shadow-key: 0 0 0 1px #6b6b6b;
+--mu-shadow-raised: 0 0 0 1px #000000;
+--mu-shadow-pressed: inset 0 0 0 2px #000000;
+--mu-shadow-pop: 0 0 0 1px #000000;
+```
+
+<!-- docs/typography.md -->
+
+# Typography
+
+## Rules
+
+- The platform's UI font for everything (San Francisco on Apple, Segoe UI on Windows, Roboto on Android), smoothed with antialiasing. The package ships no font files.
+- Controls and labels are weight 500. Running text is 400. Headings are 600.
+- Control text scales with the control size: 12px at sm, 14px at md, 16px at lg.
+- `body-sm` (13px) is for dense secondary text. `label-xs` (11px) is for kbd and counts inside badges only.
+- Reading text (`Prose`) is 15px on a 24px line. `sm` prose is 14px on a 22px line, for dense lists.
+- Letter spacing is 0 up to 20px, −0.01em for `heading-2` and `heading-1`, and −0.02em for `display`.
+- Use `font-variant-numeric: tabular-nums` wherever numbers change or line up: counts, times, tables.
+- Hierarchy comes from text color (`ink`, `ink-muted`) before size or weight. Selected and unselected states never change weight, so labels don't shift.
+
+## Fonts
+
+| Family | Stack |
+| --- | --- |
+| `--mu-font-sans` | `system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` |
+| `--mu-font-display` | `system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` |
+| `--mu-font-mono` | `ui-monospace, "SF Mono", Menlo, Consolas, monospace` |
+
+The package ships no font files and loads no remote font: text uses the system UI font, so it looks native on each platform and costs no download. An app that wants another font sets `--mu-font-sans` and `--mu-font-display` after loading `tokens.css`, and loads the font itself. Code in [Prose](components/prose.md) uses the platform's monospace font.
+
+## Scale
+
+### Text (`--mu-font-sans`)
+
+| Style | Size / line | Weight | Usage |
+| --- | --- | --- | --- |
+| `label-xs` | 11 / 16px | 500 | Kbd and counts inside badges only. Never running text |
+| `caption` | 12 / 16px | 400 | Metadata, timestamps, helper text. In `ink-muted` |
+| `label-sm` | 12 / 16px | 500 | Labels inside sm controls |
+| `body-sm` | 13 / 18px | 400 | Dense secondary text: toast descriptions, sm menu rows, dense table cells |
+| `body` | 14 / 20px | 400 | Default running text in app UI |
+| `label` | 14 / 20px | 500 | Labels inside md controls, nav rows, buttons. The default control text |
+| `body-lg` | 16 / 24px | 400 | Reading text on marketing pages and other long-form copy |
+| `label-lg` | 16 / 24px | 500 | Labels inside lg controls |
+
+### Headings (`--mu-font-display`)
+
+| Style | Size / line | Weight | Letter spacing | Usage |
+| --- | --- | --- | --- | --- |
+| `title` | 18 / 28px | 600 | 0 | Section titles inside panels; dialog titles; empty-state titles |
+| `heading-3` | 20 / 28px | 600 | 0 | Page sub-heads |
+| `heading-2` | 24 / 32px | 600 | −0.01em | Page titles in an app |
+| `heading-1` | 32 / 40px | 600 | −0.01em | Marketing and onboarding headings |
+| `display` | 40 / 48px | 600 | −0.02em | Hero headline on a website only |
+
+Each style is also a class with the `mu-` prefix (`.mu-caption`, `.mu-heading-2`) in `@usememos/ui/styles.css`, which sets the family, size, line height, weight and, where listed, letter spacing.
+
+## Prose
+
+Rendered content (notes, comments, changelogs, website pages) uses the `Prose` styles, not the scale above. See [Prose](components/prose.md).
+
+<!-- docs/layout.md -->
+
+# Size, spacing and layout
+
+## Control sizes
+
+Every control takes one `size` prop: `sm`, `md` (the default) or `lg`. The size sets every value in its row together. Never mix rows in one component.
+
+| Size | Height | Padding | Icon | Icon gap | Text | Radius | Check box |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| sm | `control-sm` 24px | 8px | 14px | 4px | 12 / 16px | `radius-sm` 4px | 16px |
+| md (default) | `control-md` 32px | 12px | 16px | 6px | 14 / 20px | `radius-md` 6px | 18px |
+| lg | `control-lg` 40px | 16px | 20px | 8px | 16 / 24px | `radius-lg` 8px | 20px |
+
+- Use `sm` for dense toolbars, table rows and filters inside panels; `md` everywhere else in an app; `lg` for marketing pages, onboarding and primary actions in sheets.
+- The icon side of a control has 2px less padding, so text and icon look centered.
+- On touch screens (`pointer: coarse`), every control gets an invisible hit area of at least `hit-area` (44px) without changing its visual size.
+
+## Spacing
+
+Every spacing value comes from the 4px scale. The only exception is `inset` (2px), the gap between a well and the key inside it.
+
+- 0 inside a well.
+- 2px between items inside a cluster (a toolbar).
+- 8px between controls.
+- 16px between fields.
+- 24px between groups.
+
+| Token | Value | Usage |
+| --- | --- | --- |
+| `space-0_5` | 2px | Only for insets: the gap between a well and the key inside it |
+| `space-1` | 4px | Gap between sm controls; icon to text in sm; the label-to-control gap in a field |
+| `space-2` | 8px | Gap between md and lg controls; sm horizontal padding |
+| `space-3` | 12px | md horizontal padding |
+| `space-4` | 16px | Padding inside popovers and toasts; lg horizontal padding; gap between fields; page padding on phones |
+| `space-5` | 20px | Padding inside dialogs; space above Prose headings |
+| `space-6` | 24px | Gap between sections or entries inside a page; page padding on desktop |
+| `space-8` | 32px | Gap between page regions |
+| `space-12` | 48px | Section rhythm on a website |
+| `space-16` | 64px | Hero and footer padding on a website |
+
+## Radius
+
+Inner radius = outer radius − `inset`, so nested corners stay concentric.
+
+| Token | Value | Usage |
+| --- | --- | --- |
+| `radius-xs` | 2px | Keys inside sm wells (`radius-sm` minus the 2px inset); inline code |
+| `radius-sm` | 4px | sm controls; badges |
+| `radius-md` | 6px | md controls, the default |
+| `radius-lg` | 8px | lg controls; images in Prose |
+| `radius-xl` | 12px | Menus, select lists, popovers and toasts |
+| `radius-2xl` | 16px | Dialogs and sheets |
+| `radius-full` | 9999px | Avatars, radios, switches and their knobs only |
+
+Buttons, inputs and badges are never pills.
+
+## Sizes
+
+| Token | Value | Usage |
+| --- | --- | --- |
+| `control-sm` | 24px | sm control height |
+| `control-md` | 32px | Default control height |
+| `control-lg` | 40px | lg control height |
+| `inset` | 2px | Well-to-key inset at every size |
+| `hit-area` | 44px | Minimum touch target on `pointer: coarse`, added invisibly around a control |
+| `focus-width` | 2px | Width and offset of the focus ring |
+| `icon-sm` | 14px | Icons in sm controls |
+| `icon-md` | 16px | Icons in md controls and nav rows |
+| `icon-lg` | 20px | Icons in lg controls |
+
+## Layout
+
+| Token | Value | Usage |
+| --- | --- | --- |
+| `content-width` | 720px | Maximum width of a reading column: a timeline, a settings form, an article |
+| `sidebar-width` | 240px | Width of a fixed navigation sidebar from `breakpoint-md` up |
+| `menu-width` | 200px | Minimum width of a menu or select list |
+| `list-height` | 240px | Maximum height of a combobox list before it scrolls |
+| `popover-width` | 280px | Default width of a popover |
+| `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 |
+| `breakpoint-sm` | 640px | Below this: one column, dialogs and menus become sheets, toasts sit bottom-center |
+| `breakpoint-md` | 1024px | From this: the sidebar is fixed and the content column is centered |
+
+CSS custom properties can't be used in media queries, so media queries use the values (`@media (min-width: 1024px)`) and name the token in a comment.
+
+## Layers
+
+| Token | Value | Usage |
+| --- | --- | --- |
+| `layer-popup` | 50 | Menus, select lists, popovers, tooltips. Equal to `layer-overlay` on purpose: the one opened last is on top, so a menu opened inside a dialog shows above it |
+| `layer-overlay` | 50 | Dialogs, sheets and their backdrops |
+| `layer-toast` | 60 | Toasts, above everything |
+
+Use these tokens for every `z-index`. Don't invent new layers in product code.
+
+<!-- docs/motion.md -->
+
+# Motion
+
+Motion makes depth feel physical: keys sink when pressed, knobs and keys settle with a light spring, and popups fade in. It is quick and never decorative.
+
+## Rules
+
+- **Press.** Keys move down 0.5px and switch to `shadow-pressed` over `duration-press` (80ms). Switch knobs grow about 10%. Checkboxes and radios shrink 6%.
+- **Release and selection.** Knobs and the segment key slide over `duration-settle` (150ms) with `ease-settle`, which stops hard like a light spring. Content inside a control (a check mark, a value) fades in after the key stops.
+- **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.
+- **Spinners** turn once every 0.8s. **Skeletons** shimmer once every 1.4s.
+- **Reduced motion.** Under `prefers-reduced-motion`, keep color, opacity and shadow changes, and drop slides, scaling and shimmer.
+
+## Tokens
+
+| Token | Value | Usage |
+| --- | --- | --- |
+| `duration-press` | 80ms | Pointer down: keys sink, knobs grow |
+| `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-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 |
+
+<!-- docs/states.md -->
+
+# States
+
+Every interactive component handles these states the same way.
+
+| State | Looks like |
+| --- | --- |
+| Hover | Keys go to `key-hover`. Rows, ghost buttons and wells go to `hover`. An input's edge goes to `ink-muted`. Muted labels go to `ink`. Primary keys go to `primary-hover` |
+| Pressed (while held) | Keys move down 0.5px and use `shadow-pressed`. A ghost button sinks into a `well` with `shadow-track` |
+| Pressed toggle (on) | Sinks into a `well` with an `edge` and `ink` text |
+| Selected (one of several) | A raised key in a well that slides to the chosen item |
+| Checked | A flat `primary` fill with an `on-primary` mark |
+| Loading | The control keeps its size, hides its label and shows a Spinner. It is inert while loading |
+| Disabled | 45% opacity, `cursor: not-allowed`, and no hover or press response |
+| Invalid | A `danger` edge on the field, plus an error line with an icon under it |
+| Focus | A 2px `focus` outline with a 2px offset, on `:focus-visible` only |
+
+## Rules
+
+- Hover never changes size, weight or layout.
+- An input never changes its background on hover or focus, so it never looks disabled.
+- Focus rings show for keyboard focus only (`:focus-visible`), never on mouse click.
+- Disabled controls stay in place. Prefer explaining why something is unavailable over hiding it.
+- Loading never shows a spinner for less than about 300ms; short waits pass silently.
+
+<!-- docs/icons.md -->
+
+# Icons
+
+Memos UI uses [Lucide](https://lucide.dev) (ISC license) for every icon. Apps import icons from `lucide-react` and pass them to components as elements. The design system does not wrap or re-export the set.
+
+```tsx
+import { Pin, Trash2 } from "lucide-react";
+
+<Button icon={<Pin />}>Pin</Button>
+<Menu items={[{ value: "delete", label: "Delete", icon: <Trash2 />, danger: true }]} />
+```
+
+## Rules
+
+- **Icons are elements, not names.** Components take `icon={<Pin />}`, never `icon="pin"`.
+- **Size comes from the control.** An icon inside a component is 14px at sm, 16px at md and 20px at lg (`icon-sm`, `icon-md`, `icon-lg`). Don't pass `size`.
+- **Stroke is fixed in screen pixels.** 1.25px at sm and in badges, 1.5px at md and lg, and 2px for the check in a checkbox. At 1.5px an icon matches the stem weight of the label text beside it. CSS applies `vector-effect: non-scaling-stroke`, which matches Lucide's `absoluteStrokeWidth`, so no props are needed. Don't pass `strokeWidth`.
+- **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.
+
+## Built-in glyphs
+
+These components bring their own Lucide icons, so the app doesn't pass them:
+
+| Component | Icons |
+| --- | --- |
+| Checkbox | `Check` |
+| Select | `ChevronDown`, `Check` |
+| Combobox | `Search`, `ChevronDown`, `Check` |
+| Menu | `Ellipsis` (default trigger), `Check` |
+| Collapsible | `ChevronRight` (turns 90° when open) |
+| Toast | `Info`, `CircleCheck`, `TriangleAlert`, `CircleAlert`, `X` |
+| Field | `CircleAlert` (errors) |
+| Link | `ArrowUpRight` (external links) |
+
+## Missing icons
+
+When Lucide doesn't have an icon, draw it on Lucide's 24px grid with 2px round strokes and round joins, then export it from the package under a Lucide-style name (`PascalCase`, describing the shape, not the feature).
+
+<!-- docs/components/README.md -->
+
+# 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.
+
+| 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) |
+
+## Page template
+
+Pages are reference for agents: short, imperative, no narrative. Every page has these sections, in this order:
+
+1. **Title and purpose.** `# Name`, then one line: what it is for.
+2. **Example.** One complete, copyable example of the common case.
+3. **Parts.** One row per part: name, the Base UI part it wraps, what it renders. Skip for single-element components.
+4. **Props.** A TypeScript block per part, only for props we add or change, then one line on which Base UI props pass through.
+5. **Rules.** Imperative bullets: when to use it, what to use instead, required labels, keyboard behavior.
+6. **Style.** Bullets for building the component: tokens, sizes, states and motion.
+
+Components follow the [API conventions](../building.md#api-conventions): parts with Base UI's names, no data props.
+
+## Left out on purpose
+
+- **Card.** Content is grouped by spacing, headings and separators, not boxes.
+- **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
+
+| Need | Use |
+| --- | --- |
+| Start an action | Button |
+| Go somewhere | Link, or an anchor with `buttonClasses()` when it should look like an action |
+| A setting that saves at once | Switch |
+| An option saved with a form | Checkbox |
+| One of 2 or 3 options, with room to show them | RadioGroup |
+| One of a short list | Select |
+| One of a long list, or typing to find | Combobox |
+| On/off in a toolbar, or stacking filters | Toggle, or ToggleGroup with `multiple` |
+| One of several views or filters on the same page | ToggleGroup without `multiple` |
+| Sections of a page | Tabs |
+| A list of actions for one thing | Menu |
+| A few controls that belong to one thing | Popover |
+| A decision that blocks the page | Dialog |
+| Name an icon-only control | Tooltip |
+| Confirm something happened | Toast |
+| A status or tag label | Badge |
+| A clickable tag filter | Toggle |
+| Content still loading | Skeleton |
+| A control waiting on a server | the control's `loading` prop |
+
+## Shared types
+
+```ts
+type Size = "sm" | "md" | "lg";
+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;
+```
+
+See [Building on it](../building.md#api-conventions) for the conventions every component follows.
+
+<!-- docs/components/button.md -->
+
+# Button
+
+Starts an action.
+
+## Example
+
+```tsx
+import { Button } from "@usememos/ui";
+import { Plus } from "lucide-react";
+
+<Button variant="primary" icon={<Plus />}>New note</Button>
+```
+
+## Props
+
+```ts
+interface ButtonProps extends BaseButton.Props {
+  variant?: "primary" | "neutral" | "ghost" | "danger"; // default "neutral"
+  size?: Size;
+  icon?: IconElement;
+  loading?: boolean;
+  loadingLabel?: string; // accessible name while loading, such as "Saving"
+}
+
+function buttonClasses(options?: { variant?: ButtonVariant; size?: Size; 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">`.
+
+## Rules
+
+- 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.
+- A link that should look like a button stays an `<a>` with `buttonClasses()`; Base UI doesn't render links through Button:
+
+  ```tsx
+  <a className={buttonClasses({ variant: "primary" })} href="/start">Get started</a>
+  ```
+
+- Prefer saying why an action is unavailable over disabling it.
+
+## Style
+
+- A raised key: 24, 32, 40px 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.
+- 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.
+
+<!-- docs/components/toggle.md -->
+
+# Toggle
+
+Turns one option on or off and stays pressed while on.
+
+## Example
+
+```tsx
+import { Toggle } from "@usememos/ui";
+import { Pin } from "lucide-react";
+
+<Toggle icon={<Pin />} pressed={pinnedOnly} onPressedChange={setPinnedOnly}>Pinned</Toggle>
+```
+
+## Props
+
+```ts
+interface ToggleProps extends BaseToggle.Props {
+  size?: Size;
+  icon?: IconElement; // before the label; alone, the toggle is square
+}
+```
+
+Wraps Base UI's [Toggle](https://base-ui.com/react/components/toggle): `pressed`, `defaultPressed`, `onPressedChange`, `disabled`, `value` pass through. Renders a `<button aria-pressed>`.
+
+## Rules
+
+- Provide `children`, or an `icon` with `aria-label` and a [Tooltip](tooltip.md) with the same text.
+- Use it for toolbar formatting and stacking filters ("Pinned", "Has tasks"). A clickable tag filter is a Toggle, not a Badge.
+- Inside a [ToggleGroup](toggle-group.md), `value` names the item in the group's value.
+- For a setting that saves at once, use [Switch](switch.md). For one choice among several, use a ToggleGroup without `multiple`.
+
+## Style
+
+- Off: flat `ink-muted`. On: sits in a `well` with `ink` text.
+
+<!-- docs/components/toggle-group.md -->
+
+# ToggleGroup
+
+A row of related [Toggles](toggle.md). With `multiple`: a toolbar of independent on/off toggles. Without: one choice among peers, the same control as [Tabs](tabs.md) without a panel.
+
+## Example
+
+```tsx
+import { Separator, Toggle, ToggleGroup } from "@usememos/ui";
+import { Bold, Code, Italic } from "lucide-react";
+
+<ToggleGroup value={[filter]} onValueChange={([next]) => next && setFilter(next)} aria-label="Show">
+  <Toggle value="all">All</Toggle>
+  <Toggle value="pinned">Pinned</Toggle>
+  <Toggle value="archived">Archived</Toggle>
+</ToggleGroup>
+
+<ToggleGroup multiple value={marks} onValueChange={setMarks} aria-label="Formatting">
+  <Toggle value="bold" icon={<Bold />} aria-label="Bold" />
+  <Toggle value="italic" icon={<Italic />} aria-label="Italic" />
+  <Separator orientation="vertical" />
+  <Toggle value="code" icon={<Code />} aria-label="Code" />
+</ToggleGroup>
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `ToggleGroup` | `ToggleGroup` | A `<div role="group">`. Takes `size`. Without `multiple`, adds the sliding key |
+| `Toggle` | `Toggle` | One item, a `<button aria-pressed>` |
+| `Separator` | `Separator` | A line between clusters, `multiple` groups only |
+
+## Props
+
+```ts
+interface ToggleGroupProps extends BaseToggleGroup.Props {
+  size?: Size; // passed to every Toggle inside
+}
+```
+
+Base UI's props pass through: `value`, `defaultValue`, `onValueChange`, `multiple`, `disabled`, `orientation`, `loopFocus`. The value is always an array of pressed `value`s, even without `multiple`.
+
+## Rules
+
+- Give the group an `aria-label`.
+- A single choice among peers is a raised key in a well; an on/off state is a pressed toggle. Never mix the two in one row.
+- Without `multiple`: filters and view switches that don't change the whole page. For sections of a page, use Tabs.
+- Base UI lets people press the chosen item to clear it. When one item must stay chosen, ignore an empty value, as in the example.
+- Arrow keys move focus between items; Space or Enter presses one.
+
+## Style
+
+- `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.
+
+<!-- docs/components/menu.md -->
+
+# Menu
+
+Lists actions for one thing, opened from a trigger.
+
+## Example
+
+```tsx
+import { Button, Menu } from "@usememos/ui";
+import { Ellipsis, FolderInput, Pin, Trash2 } from "lucide-react";
+
+<Menu.Root>
+  <Menu.Trigger render={<Button variant="ghost" icon={<Ellipsis />} aria-label="More actions" />} />
+  <Menu.Popup align="end">
+    <Menu.Item icon={<Pin />} shortcut="P" onClick={pin}>Pin</Menu.Item>
+    <Menu.SubmenuRoot>
+      <Menu.SubmenuTrigger icon={<FolderInput />}>Move to</Menu.SubmenuTrigger>
+      <Menu.Popup>
+        <Menu.Item onClick={() => move("inbox")}>Inbox</Menu.Item>
+      </Menu.Popup>
+    </Menu.SubmenuRoot>
+    <Menu.Separator />
+    <Menu.Item icon={<Trash2 />} danger onClick={confirmDelete}>Delete</Menu.Item>
+  </Menu.Popup>
+</Menu.Root>
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `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.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 |
+| `Menu.Group` | `Menu.Group` | A labeled set of items |
+| `Menu.GroupLabel` | `Menu.GroupLabel` | The name of a Group or RadioGroup |
+| `Menu.Separator` | `Menu.Separator` | A line between groups |
+| `Menu.SubmenuRoot` | `Menu.SubmenuRoot` | Nothing. Holds a SubmenuTrigger and a Popup |
+| `Menu.SubmenuTrigger` | `Menu.SubmenuTrigger` | The row that opens a submenu, with a chevron at the end. Takes `icon` |
+
+## Props
+
+```ts
+interface Menu.RootProps extends BaseMenu.Root.Props {
+  size?: Size; // row height: 24, 32, 40px
+}
+interface Menu.PopupProps extends BaseMenu.Popup.Props {
+  side?: Side; align?: Align; sideOffset?: number; alignOffset?: number; collisionPadding?: Padding; // Positioner props; default side "bottom", sideOffset 4
+  container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
+}
+interface Menu.ItemProps extends BaseMenu.Item.Props {
+  icon?: IconElement;
+  shortcut?: React.ReactNode; // at the end of the row, "⌘ D"
+  danger?: boolean;           // destructive: red text
+}
+// CheckboxItem and RadioItem take icon and shortcut too. SubmenuTrigger takes icon.
+```
+
+Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on the root; `onClick`, `closeOnClick`, `disabled`, `label` on items; `checked`, `defaultChecked`, `onCheckedChange` on CheckboxItem; `value`, `defaultValue`, `onValueChange` on RadioGroup; `value` on RadioItem.
+
+## Rules
+
+- 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).
+- Arrow keys move the highlight; typing jumps to an item; Escape and an outside click close it; focus returns to the trigger.
+
+## 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, 32, 40px), text weight 400; icons in `ink-muted`; the shortcut right-aligned in `ink-muted`.
+- 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.
+
+<!-- docs/components/link.md -->
+
+# Link
+
+Goes somewhere.
+
+## Example
+
+```tsx
+import { Link } from "@usememos/ui";
+
+<Link href="/notes">View all</Link>
+<p>Read the <Link href="/changelog" underline="always">release notes</Link> first.</p>
+<Link href="https://www.usememos.com" external>usememos.com</Link>
+```
+
+## Props
+
+```ts
+interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  muted?: boolean;                 // navigation that shouldn't draw the eye
+  external?: boolean;              // opens a new tab and shows an arrow
+  underline?: "hover" | "always";  // default "hover"
+  render?: React.ReactElement;     // a router's link: render={<RouterLink to="/notes" />}
+}
+```
+
+Provide `href` and `children`.
+
+## Rules
+
+- A link navigates; a button acts. A "Get started" that goes to a page is an anchor with [`buttonClasses()`](button.md#rules). "View all" is a link.
+- Inside running text, use `underline="always"`, so the link isn't told apart by color alone.
+- Inside [Prose](prose.md), plain anchors get this style without the component.
+
+## Style
+
+- `accent` text that underlines on hover: the one place the hue appears at rest. `muted` uses `ink-muted`.
+- High contrast underlines every link.
+
+<!-- docs/components/field.md -->
+
+# Field and Fieldset
+
+Field gives one control its label, description and error, wired for screen readers. Fieldset groups checkboxes, radios or switches under one legend.
+
+## Example
+
+```tsx
+import { Checkbox, Field, Fieldset, Input } from "@usememos/ui";
+
+<Field.Root invalid={!!error}>
+  <Field.Label>Email</Field.Label>
+  <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
+  <Field.Description>We only use it to sign you in.</Field.Description>
+  <Field.Error match>{error}</Field.Error>
+</Field.Root>
+
+<Fieldset.Root>
+  <Fieldset.Legend>Notifications</Fieldset.Legend>
+  <Field.Root>
+    <Field.Label><Checkbox defaultChecked /> Mentions</Field.Label>
+  </Field.Root>
+  <Field.Root>
+    <Field.Label><Checkbox /> Weekly digest</Field.Label>
+  </Field.Root>
+</Fieldset.Root>
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `Field.Root` | `Field.Root` | A `<div>` around one control. Takes `size` and passes it to the control |
+| `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 |
+| `Field.Error` | `Field.Error` | A `<div>` with a `CircleAlert` icon and the message, while the field is invalid |
+| `Fieldset.Root` | `Fieldset.Root` | A `<fieldset>`. Takes `size` |
+| `Fieldset.Legend` | `Fieldset.Legend` | The group's name |
+
+## Props
+
+```ts
+interface Field.RootProps extends BaseField.Root.Props {
+  size?: Size; // passed to the control inside
+}
+interface Fieldset.RootProps extends BaseFieldset.Root.Props {
+  size?: Size; // passed to every control inside
+}
+```
+
+Base UI's props pass through: `name`, `invalid`, `disabled`, `validate`, `validationMode` on `Field.Root`; `match` on `Field.Error` (`true` shows it whenever the field is invalid, or a `ValidityState` key such as `"valueMissing"`).
+
+## Rules
+
+- 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.
+- 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.
+- 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.
+- Description and error: 12px, below the control. The error hides the description and turns the control's edge `danger`.
+
+<!-- docs/components/input.md -->
+
+# Input
+
+Takes one line of text.
+
+## Example
+
+```tsx
+import { Input } from "@usememos/ui";
+import { Search } from "lucide-react";
+
+<Input prefix={<Search />} placeholder="Search notes" aria-label="Search notes" />
+```
+
+## Props
+
+```ts
+interface InputProps extends Omit<BaseInput.Props, "size" | "prefix"> {
+  size?: Size;
+  prefix?: React.ReactNode;        // says what the field is: a search or link icon
+  suffix?: React.ReactNode;        // one action on the value (copy, clear), or a unit
+  className?: string;              // on the visible box, not the <input>
+  style?: React.CSSProperties;     // on the visible box, not the <input>
+}
+```
+
+Wraps Base UI's [Input](https://base-ui.com/react/components/input), so inside a [Field](field.md) it gets its label, description and validity. The ref and every other prop (`value`, `onValueChange`, `type`, `disabled`, native attributes) go to the `<input>`. The visible box is a `<span>` around it that fills its container's width.
+
+## Rules
+
+- 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.
+
+## Style
+
+- Flat `surface` with a 1px `edge` and a faint inner shadow from the top. Never a gray well, so it never reads as disabled.
+- Typed text weight 400; placeholder `ink-muted`.
+- Hover darkens the edge to `ink-muted`; focus adds the ring. The background never changes.
+- The side with a prefix or suffix has 2px less padding.
+
+<!-- docs/components/textarea.md -->
+
+# Textarea
+
+Takes a few lines of plain text.
+
+## Example
+
+```tsx
+import { Field, Textarea } from "@usememos/ui";
+
+<Field.Root>
+  <Field.Label>About</Field.Label>
+  <Textarea placeholder="A line or two about you" />
+</Field.Root>
+```
+
+## Props
+
+```ts
+interface TextareaProps extends Omit<BaseField.Control.Props, "size" | "render"> {
+  size?: Size;
+  rows?: number; // visible lines, default 3
+}
+```
+
+Base UI has no textarea part, so this renders Base UI's `Field.Control` as a `<textarea>`. Inside a [Field](field.md) it gets its label, description and validity. Native textarea props (`value`, `onChange`, `maxLength`) pass through.
+
+## Rules
+
+- Provide a `Field.Label` or `aria-label`.
+- Rich content is not a textarea: use the editor (`@usememos/editor`) with [Prose](prose.md).
+
+## Style
+
+- Looks like [Input](input.md). Resizes vertically only.
+
+<!-- docs/components/select.md -->
+
+# Select
+
+Picks one value from a short list.
+
+## Example
+
+```tsx
+import { Field, Select } from "@usememos/ui";
+
+const visibility = { private: "Private", workspace: "Workspace", public: "Public" };
+
+<Field.Root>
+  <Field.Label>Visibility</Field.Label>
+  <Select.Root items={visibility} value={value} onValueChange={setValue}>
+    <Select.Trigger>
+      <Select.Value placeholder="Choose who can see it" />
+    </Select.Trigger>
+    <Select.Popup>
+      <Select.Item value="private">Private</Select.Item>
+      <Select.Item value="workspace">Workspace</Select.Item>
+      <Select.Item value="public">Public</Select.Item>
+    </Select.Popup>
+  </Select.Root>
+</Field.Root>
+```
+
+## Parts
+
+| 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.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` |
+| `Select.Group` | `Select.Group` | A labeled set of items |
+| `Select.GroupLabel` | `Select.GroupLabel` | The name of a Group |
+| `Select.Separator` | `Select.Separator` | A line between groups |
+
+## Props
+
+```ts
+type Select.RootProps<Value, Multiple> = BaseSelect.Root.Props<Value, Multiple> & {
+  size?: Size;
+};
+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; sideOffset?: number; alignOffset?: number; collisionPadding?: Padding; // used when alignItemWithTrigger is false
+  container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
+}
+interface Select.ItemProps extends BaseSelect.Item.Props {
+  icon?: IconElement;
+}
+```
+
+Base UI's props pass through: `items`, `value`, `defaultValue`, `onValueChange`, `name`, `disabled`, `required`, `multiple` on the root; `placeholder` on Value; `value`, `disabled`, `label` on Item.
+
+## Rules
+
+- Pass `items` (value to label) to the root, so `Select.Value` shows the label, not the raw value.
+- 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).
+
+## 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.
+- 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.
+
+<!-- docs/components/combobox.md -->
+
+# Combobox
+
+Picks one value from a long list by typing to filter it.
+
+## Example
+
+```tsx
+import { Combobox, Field } from "@usememos/ui";
+
+const tags = ["book", "design", "travel"];
+
+<Field.Root>
+  <Field.Label>Tag</Field.Label>
+  <Combobox.Root items={tags} value={tag} onValueChange={setTag}>
+    <Combobox.Input placeholder="Find a tag" />
+    <Combobox.Popup>
+      <Combobox.Empty>No tags found</Combobox.Empty>
+      <Combobox.List>
+        {(tag: string) => (
+          <Combobox.Item key={tag} value={tag}>{tag}</Combobox.Item>
+        )}
+      </Combobox.List>
+    </Combobox.Popup>
+  </Combobox.Root>
+</Field.Root>
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `Combobox.Root` | `Combobox.Root` | Nothing. Holds the value, the input text and a hidden input for forms. Takes `size` |
+| `Combobox.Input` | `Combobox.InputGroup`, `Input`, `Trigger` | An [Input](input.md) box: a search icon, the `<input role="combobox">` and a chevron button that opens the list. Takes `icon` |
+| `Combobox.Popup` | `Combobox.Portal`, `Positioner`, `Popup` | The panel under the input, as wide as the input, portaled to the body |
+| `Combobox.List` | `Combobox.List` | The items, a `<div role="listbox">`. A function child renders each filtered item |
+| `Combobox.Item` | `Combobox.Item` with `ItemIndicator` | One option, with a check at the end when chosen. Takes `icon` |
+| `Combobox.Empty` | `Combobox.Empty` | The text shown when nothing matches. Stays mounted, so screen readers announce it |
+| `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.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` |
+
+## Props
+
+```ts
+type Combobox.RootProps<Value, Multiple, Item> = BaseCombobox.Root.Props<Value, Multiple, Item> & {
+  size?: Size;
+};
+interface Combobox.InputProps extends BaseCombobox.Input.Props {
+  icon?: IconElement | null; // default <Search />; null drops it
+  triggerLabel?: string;     // the chevron's name outside a Field; default "Show options"
+  className?: string;        // on the box, not the <input>
+  style?: React.CSSProperties; // on the box
+}
+interface Combobox.PopupProps extends BaseCombobox.Popup.Props {
+  side?: Side; align?: Align; sideOffset?: number; alignOffset?: number; collisionPadding?: Padding; // Positioner props; default side "bottom", align "start", sideOffset 4
+  container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
+}
+interface Combobox.ItemProps extends BaseCombobox.Item.Props {
+  icon?: IconElement;
+}
+```
+
+Base UI's props pass through: `items`, `value`, `defaultValue`, `onValueChange`, `inputValue`, `onInputValueChange`, `filter`, `itemToStringLabel`, `isItemEqualToValue`, `open`, `onOpenChange`, `name`, `disabled`, `required` on the root; `placeholder`, `disabled` on Input; `value`, `disabled` on Item.
+
+## Rules
+
+- Pass `items` to the root and render them with a function child of `List`. The root filters them as people type; `Empty` needs `items` to know when nothing matches.
+- For object items, pass `itemToStringLabel` so the input shows the label, and give each Item the object as `value`.
+- Label it with a [Field](field.md); the label names the input and the chevron. Outside a Field, give Input an `aria-label`.
+- 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.
+
+## Style
+
+- The box is an [Input](input.md): flat `surface`, `edge`, focus ring on the box. The search icon and chevron are `ink-muted`; the chevron turns `ink` on hover.
+- 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.
+- Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
+
+<!-- docs/components/checkbox.md -->
+
+# Checkbox
+
+Includes or excludes one item, saved with a form.
+
+## Example
+
+```tsx
+import { Checkbox, Field } from "@usememos/ui";
+
+<Field.Root>
+  <Field.Label>
+    <Checkbox checked={digest} onCheckedChange={setDigest} /> Weekly digest
+  </Field.Label>
+</Field.Root>
+```
+
+## Props
+
+```ts
+interface CheckboxProps extends BaseCheckbox.Root.Props {
+  size?: Size; // box: 16, 18, 20px
+}
+```
+
+Wraps Base UI's [Checkbox](https://base-ui.com/react/components/checkbox) root with its indicator built in: `checked`, `defaultChecked`, `onCheckedChange`, `indeterminate`, `disabled`, `name`, `value` pass through. Renders a `<span role="checkbox">` and a hidden `<input>` for forms.
+
+## Rules
+
+- Name it with a `Field.Label` around it, or `aria-label`.
+- For a setting that applies at once, use [Switch](switch.md). For a labeled group, wrap the boxes in a [Fieldset](field.md).
+- Task lists in [Prose](prose.md) use this component at 16px.
+
+## Style
+
+- Unchecked: an empty well with an edge. Checked: a flat `primary` square (holds a value, so not raised).
+- Lucide `Check` at a 2px stroke; `Minus` when indeterminate. It fades and scales in after the fill.
+- Shrinks 6% while pressed.
+
+<!-- docs/components/switch.md -->
+
+# Switch
+
+Turns a setting on or off at once.
+
+## Example
+
+```tsx
+import { Field, Switch } from "@usememos/ui";
+
+<Field.Root>
+  <Field.Label>
+    <Switch checked={publicByDefault} onCheckedChange={save} /> Make new notes public
+  </Field.Label>
+</Field.Root>
+```
+
+## Props
+
+```ts
+interface SwitchProps extends BaseSwitch.Root.Props {
+  size?: Size; // 18, 20, 22px tall
+}
+```
+
+Wraps Base UI's [Switch](https://base-ui.com/react/components/switch) root with its thumb built in: `checked`, `defaultChecked`, `onCheckedChange`, `disabled`, `name` pass through.
+
+## Rules
+
+- Name it with a `Field.Label` around it, or `aria-label`.
+- Use it where each change saves at once (settings pages). In a form with a Save button, use [Checkbox](checkbox.md).
+
+## Style
+
+- A pill well with a round knob; the well fills with `primary` when on.
+- Height = checkbox box + 2px; width = height × 1.7.
+- The knob is a `key` with `shadow-key`, inset 2px; `on-primary` when on. It grows 10% on press and slides with `ease-settle`. Under reduced motion it doesn't slide or grow.
+
+<!-- docs/components/radio-group.md -->
+
+# RadioGroup
+
+Picks exactly one option from a short list that is always visible.
+
+## Example
+
+```tsx
+import { Field, Fieldset, Radio, RadioGroup } from "@usememos/ui";
+
+<Field.Root name="visibility">
+  <Fieldset.Root render={<RadioGroup value={visibility} onValueChange={setVisibility} />}>
+    <Fieldset.Legend>Visibility</Fieldset.Legend>
+    <Field.Item>
+      <Field.Label><Radio value="private" /> Private</Field.Label>
+    </Field.Item>
+    <Field.Item>
+      <Field.Label><Radio value="public" /> Public</Field.Label>
+    </Field.Item>
+  </Fieldset.Root>
+</Field.Root>
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `RadioGroup` | `RadioGroup` | A `<div role="radiogroup">`. Takes `size` and `orientation` |
+| `Radio` | `Radio.Root` with `Radio.Indicator` | One option, a `<span role="radio">` |
+
+## Props
+
+```ts
+interface RadioGroupProps extends BaseRadioGroup.Props {
+  size?: Size;
+  orientation?: "vertical" | "horizontal"; // default "vertical"
+}
+interface RadioProps extends BaseRadio.Root.Props {
+  size?: Size; // usually set by the group
+}
+```
+
+Base UI's props pass through: `value`, `defaultValue`, `onValueChange`, `disabled`, `name` on the group; `value`, `disabled` on each radio.
+
+## Rules
+
+- Use the pattern in the example: one field, a fieldset that names it, each radio labeled in a `Field.Item`.
+- Use it for two or three options, or options that need a description. Otherwise use [Select](select.md).
+- Arrow keys move the selection; only the selected radio is in the tab order.
+
+## Style
+
+- Each radio is a round well; the chosen one is a flat `primary` circle with an `on-primary` dot.
+- Vertical: `space-3` apart. Horizontal: `space-4` apart, with the legend on its own line above.
+
+<!-- docs/components/tabs.md -->
+
+# Tabs
+
+Switches between sections of the same page.
+
+## Example
+
+```tsx
+import { Tabs } from "@usememos/ui";
+import { Bell, User } from "lucide-react";
+
+<Tabs.Root defaultValue="account">
+  <Tabs.List aria-label="Settings sections">
+    <Tabs.Tab value="account" icon={<User />}>Account</Tabs.Tab>
+    <Tabs.Tab value="notifications" icon={<Bell />}>Notifications</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="account">…</Tabs.Panel>
+  <Tabs.Panel value="notifications">…</Tabs.Panel>
+</Tabs.Root>
+```
+
+## Parts
+
+| 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.Tab` | `Tabs.Tab` | One tab, a `<button role="tab">`. Takes `icon` |
+| `Tabs.Panel` | `Tabs.Panel` | One tab's content, a `<div role="tabpanel">` |
+
+## Props
+
+```ts
+interface Tabs.RootProps extends BaseTabs.Root.Props {
+  size?: Size;
+}
+interface Tabs.TabProps extends BaseTabs.Tab.Props {
+  icon?: IconElement; // before the label
+}
+```
+
+Base UI's props pass through: `value`, `defaultValue`, `onValueChange` on the root; `activateOnFocus`, `loopFocus` on the list; `value`, `disabled` on each tab; `keepMounted` on each panel.
+
+## Rules
+
+- Give the list an `aria-label`.
+- Use tabs for sections of a page, not for site navigation. For a filter or view switch, use a [ToggleGroup](toggle-group.md).
+- Left and Right arrow keys move between tabs.
+
+## Style
+
+- Shares the segmented well and sliding key with a single-choice ToggleGroup.
+- Tabs are sized to their labels. The key re-measures when a label changes width.
+- Selected and hovered labels `ink`, others `ink-muted`. Weight never changes, so labels don't shift.
+
+<!-- docs/components/collapsible.md -->
+
+# Collapsible
+
+Hides content behind one trigger until people ask for it.
+
+## Example
+
+```tsx
+import { Collapsible } from "@usememos/ui";
+
+<Collapsible.Root>
+  <Collapsible.Trigger>Advanced settings</Collapsible.Trigger>
+  <Collapsible.Panel>…</Collapsible.Panel>
+</Collapsible.Root>
+```
+
+## Parts
+
+| 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.Panel` | `Collapsible.Panel` | The content, a `<div>`; unmounted while closed unless `keepMounted` |
+
+## Props
+
+```ts
+interface Collapsible.RootProps extends BaseCollapsible.Root.Props {
+  size?: Size; // the trigger's size
+}
+```
+
+Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `disabled` on the root; `keepMounted`, `hiddenUntilFound` on the panel.
+
+## Rules
+
+- Use it for "Show more" on long content, advanced settings and secondary details.
+- The trigger label names what is hidden. To change it while open ("Show less"), control `open` and swap the label.
+- For several sections that open one at a time, stack Collapsibles and control them. There is no Accordion.
+- Enter and Space toggle it; the trigger has `aria-expanded`.
+
+## 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 `ink-muted` and turns 180° over `duration-settle` with `ease-settle`.
+- The panel fades in and rises `space-1` over `duration-fade`. Its height never animates. No rise or turn under reduced motion.
+
+<!-- docs/components/dialog.md -->
+
+# Dialog and AlertDialog
+
+Dialog asks for a short form or a decision on top of the page. AlertDialog asks to confirm an action and closes only through its buttons.
+
+## Example
+
+```tsx
+import { AlertDialog, Button, Dialog, Field, Input } from "@usememos/ui";
+
+<Dialog.Root>
+  <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>
+    <Field.Root>
+      <Field.Label>Description</Field.Label>
+      <Input />
+    </Field.Root>
+    <Dialog.Footer>
+      <Dialog.Close render={<Button variant="ghost">Cancel</Button>} />
+      <Button variant="primary" onClick={create}>Create</Button>
+    </Dialog.Footer>
+  </Dialog.Popup>
+</Dialog.Root>
+
+<AlertDialog.Root open={open} onOpenChange={setOpen}>
+  <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" onClick={remove}>Delete</Button>
+    </AlertDialog.Footer>
+  </AlertDialog.Popup>
+</AlertDialog.Root>
+```
+
+## Parts
+
+Dialog and AlertDialog have the same parts.
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `Root` | `Root` | Nothing. Holds the open state |
+| `Trigger` | `Trigger` | The control that opens it, usually a Button through `render` |
+| `Popup` | `Portal`, `Backdrop`, `Viewport`, `Popup` | The panel over a dimmed backdrop, portaled to the body. Dialog adds an X at the top right |
+| `Title` | `Title` | An `<h2>` that names the dialog |
+| `Description` | `Description` | A `<p>` under the title |
+| `Close` | `Close` | A button that closes it, usually a Button through `render` |
+| `Footer` | none (ours) | A `<div>` that right-aligns the buttons |
+
+## Props
+
+```ts
+interface Dialog.PopupProps extends BaseDialog.Popup.Props {
+  sheet?: boolean;      // below breakpoint-sm, a sheet from the bottom; default true
+  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.
+```
+
+Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal`, `disablePointerDismissal` on the root; `initialFocus`, `finalFocus` on the popup.
+
+## Rules
+
+- Title: a question or a task ("Delete this note?", "Create access token"). Description: what will happen.
+- Footer: Cancel as a `ghost` Button, then the action. Name the action with its verb, never "OK". Use `danger` only for destructive confirmations.
+- 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.
+
+## Style
+
+- `mu-popup` with `radius-2xl`, `space-5` padding, `dialog-width` wide; children stack `space-4` apart. The backdrop is `overlay`.
+- 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.
+
+<!-- docs/components/popover.md -->
+
+# Popover
+
+A small floating panel of controls next to its trigger, such as a share panel or a link editor.
+
+## Example
+
+```tsx
+import { Button, Input, Popover } from "@usememos/ui";
+
+<Popover.Root>
+  <Popover.Trigger render={<Button>Share</Button>} />
+  <Popover.Popup align="start">
+    <Popover.Title>Share this note</Popover.Title>
+    <Popover.Description>Anyone with the link can read it.</Popover.Description>
+    <Input readOnly value={link} aria-label="Link" />
+  </Popover.Popup>
+</Popover.Root>
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `Popover.Root` | `Popover.Root` | Nothing. Groups a trigger and its popup |
+| `Popover.Trigger` | `Popover.Trigger` | The control that opens it, usually a Button through `render` |
+| `Popover.Popup` | `Popover.Portal`, `Positioner`, `Popup` | The panel, a `<div>` portaled to the body |
+| `Popover.Title` | `Popover.Title` | An `<h2>` that names the popup |
+| `Popover.Description` | `Popover.Description` | A `<p>` under the title |
+| `Popover.Close` | `Popover.Close` | A button that closes it, usually a Button through `render` |
+
+## Props
+
+```ts
+interface Popover.PopupProps extends BasePopover.Popup.Props {
+  side?: Side; align?: Align; sideOffset?: number; alignOffset?: number; collisionPadding?: Padding; // Positioner props; default side "bottom", sideOffset 6
+  container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
+}
+```
+
+Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on the root; `openOnHover`, `delay` on the trigger; `initialFocus`, `finalFocus` on the popup.
+
+## Rules
+
+- 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.
+- It closes on Escape and on a click outside; focus returns to the trigger.
+
+## Style
+
+- `mu-popup` (`surface`, `shadow-pop`, `radius-xl`), `space-4` padding, `popover-width` wide. Children stack `space-3` apart.
+- Title: `label`. Description: `body-sm` in `ink-muted`, `space-1` under the title.
+- Fades in and rises `space-1` over `duration-fade`; no rise under reduced motion.
+
+<!-- docs/components/tooltip.md -->
+
+# Tooltip
+
+Names an icon-only control and shows its shortcut.
+
+## Example
+
+```tsx
+import { Button, Tooltip } from "@usememos/ui";
+import { Archive } from "lucide-react";
+
+<Tooltip.Provider>
+  <Tooltip.Root>
+    <Tooltip.Trigger render={<Button variant="ghost" icon={<Archive />} aria-label="Archive" />} />
+    <Tooltip.Popup shortcut="⌘ E">Archive</Tooltip.Popup>
+  </Tooltip.Root>
+</Tooltip.Provider>
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `Tooltip.Provider` | `Tooltip.Provider` | Nothing. Shares the hover delay, so the next tooltip in a toolbar opens at once |
+| `Tooltip.Root` | `Tooltip.Root` | Nothing. Groups a trigger and its popup |
+| `Tooltip.Trigger` | `Tooltip.Trigger` | The control, usually a Button through `render` |
+| `Tooltip.Popup` | `Tooltip.Portal`, `Positioner`, `Popup` | The label, a `<div>` portaled to the body |
+
+## Props
+
+```ts
+interface Tooltip.TriggerProps extends BaseTooltip.Trigger.Props {
+  delay?: number; // hover time before opening, ms; default 400
+}
+interface Tooltip.PopupProps extends BaseTooltip.Popup.Props {
+  shortcut?: React.ReactNode; // after the label, at 65% opacity
+  side?: Side; align?: Align; sideOffset?: number; alignOffset?: number; collisionPadding?: Padding; // Positioner props; default side "top", sideOffset 6
+  container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
+}
+```
+
+Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `disabled` on the root; `closeOnClick` on the trigger; `delay`, `closeDelay`, `timeout` on the provider.
+
+## Rules
+
+- Give every icon-only Button and Toggle a tooltip with the same text as its `aria-label`. Two or three words.
+- 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`.
+
+## 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.
+
+<!-- docs/components/toast.md -->
+
+# Toast
+
+Confirms that something happened, or that it failed, without blocking the page.
+
+## Example
+
+```tsx
+import { Toast } from "@usememos/ui";
+
+// Once, around the app:
+<Toast.Provider>
+  <App />
+  <Toast.Viewport />
+</Toast.Provider>
+
+// Anywhere inside:
+const toast = Toast.useToastManager();
+toast.add({ title: "Note archived", actionProps: { children: "Undo", onClick: unarchive } });
+toast.add({ title: "Settings saved", type: "success" });
+toast.add({ title: "Couldn't sync", description: "Check your connection.", type: "danger", timeout: 0 });
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `Toast.Provider` | `Toast.Provider` | Nothing. Holds the toasts |
+| `Toast.Viewport` | `Toast.Portal`, `Viewport`, and each toast's `Root`, `Content`, `Title`, `Description`, `Action`, `Close` | The stack of toasts, portaled to the body |
+| `Toast.useToastManager` | `Toast.useToastManager` | A hook: `add`, `update`, `close`, `promise`, `toasts` |
+| `Toast.createToastManager` | `Toast.createToastManager` | A manager for code outside React; pass it to the Provider as `toastManager` |
+
+## Props
+
+```ts
+interface Toast.ViewportProps extends BaseToast.Viewport.Props {
+  closeLabel?: string; // accessible name of each X; default "Close"
+  container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
+}
+// toast.add() options (Base UI): title, description, type, timeout, priority, actionProps, onClose, data.
+// type sets the tone: "success", "warning", "danger", or none for neutral.
+```
+
+Base UI's props pass through: `timeout` (default 5000ms) and `limit` (default 3) on the Provider.
+
+## Rules
+
+- Title: what happened, past tense ("Note archived"). Add a description only when it helps.
+- At most one action, such as "Undo", through `actionProps`.
+- Errors stay until dismissed: pass `timeout: 0` with `type: "danger"`, and `priority: "high"` when people must hear it at once.
+- Color only marks the icon; the words carry the meaning.
+- Render one Viewport per app. F6 moves focus into the toasts.
+
+## Style
+
+- `mu-popup`, `toast-width` wide, bottom-right at `space-6` from the edges; below `breakpoint-sm`, full width at `space-4`.
+- A tone icon (`Info`, `CircleCheck`, `TriangleAlert`, `CircleAlert`) in `ink-muted`, `success`, `warning` or `danger`; title in `label`; description in `body-sm` `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.
+
+<!-- docs/components/avatar.md -->
+
+# Avatar
+
+Shows a person.
+
+## Example
+
+```tsx
+import { Avatar } from "@usememos/ui";
+
+<Avatar.Root size="sm">
+  <Avatar.Image src={user.avatarUrl} alt={user.name} />
+  <Avatar.Fallback>{initials(user.name)}</Avatar.Fallback>
+</Avatar.Root>
+```
+
+## Parts
+
+| Part | Base UI part | Renders |
+| --- | --- | --- |
+| `Avatar.Root` | `Avatar.Root` | The circle, a `<span>`. Takes `size` |
+| `Avatar.Image` | `Avatar.Image` | The photo, an `<img>`, shown once loaded |
+| `Avatar.Fallback` | `Avatar.Fallback` | The initials, shown while there is no photo or it fails to load |
+
+## Props
+
+```ts
+interface Avatar.RootProps extends BaseAvatar.Root.Props {
+  size?: Size; // 24, 32, 40px
+}
+```
+
+`Avatar.Image` and `Avatar.Fallback` take Base UI's props (`src`, `alt`, `delay`, `render`).
+
+## Rules
+
+- Give the image an `alt` with the person's name. Initials are one or two letters, computed by the app.
+- `sm` in lists and comments, `md` in a sidebar, `lg` on profile pages.
+
+## Style
+
+- A circle (one of three round shapes, with radios and switches). Initials in `ink-muted` on `well`.
+
+<!-- docs/components/badge.md -->
+
+# Badge
+
+Labels a thing with a tag or a status.
+
+## Example
+
+```tsx
+import { Badge } from "@usememos/ui";
+import { Hash, Lock } from "lucide-react";
+
+<Badge icon={<Hash />}>reading</Badge>
+<Badge tone="outline" icon={<Lock />}>Private</Badge>
+<Badge tone="success">Synced</Badge>
+```
+
+## Props
+
+```ts
+interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+  tone?: Tone | "outline"; // default "neutral"
+  icon?: IconElement;
+  children: React.ReactNode; // one or two words
+  render?: React.ReactElement;
+}
+```
+
+## Rules
+
+- Tags: `neutral` with a `Hash` icon. Visibility: `outline` with its icon. Status: `success`, `warning` or `danger`, always with a word, never color alone.
+- A badge is not a button. A clickable tag filter is a [Toggle](toggle.md).
+
+## Style
+
+- 20px tall, `radius-sm` (never a pill), 12px medium text, optional 12px icon at a 1.25px stroke.
+- `neutral`: `ink` on `well`. Status tones: their `-soft` background with full-strength text.
+
+<!-- docs/components/kbd.md -->
+
+# Kbd
+
+Shows one keyboard key in help text, menus and empty states.
+
+## Example
+
+```tsx
+import { Kbd } from "@usememos/ui";
+
+<p>Press <Kbd>⌘</Kbd> <Kbd>K</Kbd> to search</p>
+```
+
+## Props
+
+```ts
+interface KbdProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode; // one key: "⌘", "Enter", "/"
+  render?: React.ReactElement;
+}
+```
+
+Renders a `<kbd>`.
+
+## Rules
+
+- One key per Kbd. Put a space between the keys of a shortcut.
+- Use symbols for modifiers on macOS (⌘ ⌥ ⇧) and words elsewhere (Ctrl, Alt, Shift).
+
+## Style
+
+- A tiny raised key, 20px tall, `label-xs` text in `ink-muted`.
+
+<!-- docs/components/separator.md -->
+
+# Separator
+
+A line between groups of content, horizontal or vertical.
+
+## Example
+
+```tsx
+import { Separator } from "@usememos/ui";
+
+<Separator />
+<Separator orientation="vertical" />
+```
+
+## Props
+
+```ts
+interface SeparatorProps extends BaseSeparator.Props {
+  orientation?: "horizontal" | "vertical"; // default "horizontal"
+}
+```
+
+Wraps Base UI's [Separator](https://base-ui.com/react/components/separator): a `<div role="separator">` with `aria-orientation`.
+
+## Rules
+
+- Prefer space over lines. Use a separator only where `space-6` alone doesn't make the groups clear.
+- In a [ToggleGroup](toggle-group.md), a vertical Separator splits clusters. Menus use `Menu.Separator`.
+
+## Style
+
+- 1px `line`. A vertical separator stretches to the height of its row.
+
+<!-- docs/components/spinner.md -->
+
+# Spinner
+
+Shows that something short is in progress.
+
+## Example
+
+```tsx
+import { Spinner } from "@usememos/ui";
+
+<Spinner label="Loading notes" />
+```
+
+## Props
+
+```ts
+interface SpinnerProps extends React.HTMLAttributes<HTMLSpanElement> {
+  size?: Size;    // 14, 16, 20px; default: the surrounding Root's size, else md
+  label?: string; // for screen readers, default "Loading"
+  render?: React.ReactElement;
+}
+```
+
+Renders a `<span role="status">` named by `label`.
+
+## Rules
+
+- For a wait inside a control, use the control's `loading` prop.
+- For content that is loading, use [Skeleton](skeleton.md), so the layout doesn't jump.
+- Don't show a spinner for waits under about 300ms.
+
+## Style
+
+- A ring in `currentColor` with one gap, at the icon stroke width of its size, turning once every `duration-spin`.
+
+<!-- docs/components/skeleton.md -->
+
+# Skeleton
+
+Holds the place of content that is still loading.
+
+## Example
+
+```tsx
+import { Skeleton } from "@usememos/ui";
+
+<Skeleton round />
+<Skeleton width="40%" />
+<Skeleton />
+```
+
+## Props
+
+```ts
+interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+  width?: number | string;  // default: full width (round: its height)
+  height?: number | string; // default: one line of text at `size` (round: the control height)
+  round?: boolean;          // for avatars
+  size?: Size;
+  render?: React.ReactElement;
+}
+```
+
+## Rules
+
+- Match the shape of what is coming: one bar per line of text, a circle for an avatar, a block for an image. The layout must not jump when content arrives.
+- Use skeletons for lists and pages, and [Spinner](spinner.md) for a control that is waiting.
+- Skeletons are hidden from screen readers. Set `aria-busy` on the loading region.
+
+## Style
+
+- A `well` block that shimmers once every `duration-shimmer`. The shimmer stops under reduced motion.
+
+<!-- docs/components/table.md -->
+
+# Table
+
+Lists things with the same attributes, such as tokens, users or webhooks.
+
+## Example
+
+```tsx
+import { Button, Menu, Table } from "@usememos/ui";
+import { Ellipsis } from "lucide-react";
+
+<Table.Root>
+  <Table.Caption>Access tokens</Table.Caption>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Name</Table.Head>
+      <Table.Head>Created</Table.Head>
+      <Table.Head num>Uses</Table.Head>
+      <Table.Head><span className="mu-visually-hidden">Actions</span></Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    {tokens.map((token) => (
+      <Table.Row key={token.id}>
+        <Table.Cell>{token.name}</Table.Cell>
+        <Table.Cell muted>{token.created}</Table.Cell>
+        <Table.Cell num>{token.uses}</Table.Cell>
+        <Table.Cell num>
+          <Menu.Root>
+            <Menu.Trigger render={<Button variant="ghost" icon={<Ellipsis />} aria-label={`Actions for ${token.name}`} />} />
+            <Menu.Popup align="end">…</Menu.Popup>
+          </Menu.Root>
+        </Table.Cell>
+      </Table.Row>
+    ))}
+  </Table.Body>
+</Table.Root>
+```
+
+## Parts
+
+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.Caption` | `<caption>`, under the table. Names it for screen readers |
+| `Table.Header` | `<thead>` |
+| `Table.Body` | `<tbody>` |
+| `Table.Row` | `<tr>` |
+| `Table.Head` | `<th scope="col">`. Takes `num` |
+| `Table.Cell` | `<td>`. Takes `num` and `muted` |
+
+## Props
+
+```ts
+interface Table.RootProps extends React.ComponentProps<"table"> {
+  size?: Size; // sm for dense admin lists
+}
+interface Table.HeadProps extends React.ComponentProps<"th"> {
+  num?: boolean; // right-aligned, for a column of numbers
+}
+interface Table.CellProps extends React.ComponentProps<"td"> {
+  num?: boolean;   // right-aligned
+  muted?: boolean; // ink-muted, for secondary values such as dates
+}
+```
+
+Every native attribute passes through.
+
+## Rules
+
+- Use it for data with columns. Lists of content (notes, comments) are [entries](../patterns.md#entry), not rows.
+- Set `num` on a numeric column's Head and on its Cells.
+- Put row actions in the last column as a ghost [Menu](menu.md) trigger, named for its row. Give that column's Head text in `mu-visually-hidden`.
+- 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.
+
+## Style
+
+- No boxes or stripes: a `line` under the head row and between body rows. Body rows highlight with `hover`.
+- Heads: `label-sm` (12px, 500) in `ink-muted`, a control height tall.
+- Cells: `body-sm`, `body` or `body-lg` at sm, md and lg, with tabular numbers. Rows are 34, 40 or 48px; 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/prose.md -->
+
+# Prose
+
+Styles rendered Markdown: the body of a note, a comment, a changelog, a page on the website.
+
+## Example
+
+```tsx
+import { Prose } from "@usememos/ui";
+
+<Prose dangerouslySetInnerHTML={{ __html: renderMarkdown(memo.content) }} />
+
+// or, with a React renderer
+<Prose>
+  <ReactMarkdown remarkPlugins={[remarkGfm]}>{memo.content}</ReactMarkdown>
+</Prose>
+```
+
+Without React: `<div class="mu-prose">…</div>`, and `mu-prose mu-prose-sm` for the small size.
+
+## Props
+
+```ts
+interface ProseProps extends React.ComponentProps<"div"> {
+  size?: "sm" | "md"; // md: 15/24px for reading; sm: 14/22px for dense lists
+}
+```
+
+Every native attribute passes through.
+
+## Rules
+
+- Put plain HTML from a Markdown renderer inside it. It styles elements (`h1`–`h6`, `p`, `ul`, `ol`, `li`, `a`, `code`, `pre`, `blockquote`, `table`, `img`, `video`, `hr`), so the renderer needs no classes.
+- Task lists are `<li>` elements that start with `<input type="checkbox">`, as GFM renders them. Give each checkbox a name, such as `aria-label` with the item text. Drop `disabled` when people can tick them.
+- Mark tags with `<span class="mu-prose-tag">#tag</span>`.
+- Do not put components that are not content (forms, menus) inside it.
+- The editor (`@usememos/editor`) uses the same stylesheet in edit mode, so content does not shift between editing and reading.
+
+## Style
+
+- Text: 15px on a 24px line (`sm`: 14 on 22), weight 400, `ink`. Blocks are `space-3` apart.
+- Headings: `h1` 20/28px, `h2` 17/24px, `h3`–`h6` the text size; all weight 600, with `space-5` above and `space-2` below.
+- Links: `accent`, underlined at rest, because color alone does not set them apart from the text.
+- Code: `--mu-font-mono` at 0.875em on `well`. Inline code has `radius-xs`; blocks have `radius-md`, `space-3` by `space-4` padding, and scroll sideways.
+- Quotes: a 2px `edge` bar, text in `ink-muted`. Rules: a 1px `line` with `space-5` around it.
+- Lists indent `space-6`; markers are `ink-muted`. Task checkboxes are 16px, drawn like [Checkbox](checkbox.md); done items go `ink-muted` with a strike-through.
+- Images and video: never wider than the column, `radius-lg`.
+- Tables follow [Table](table.md): `line` between rows, 12px `ink-muted` heads, tabular numbers; they scroll sideways when too wide.
+- Tags: `ink-muted` on `well`, `radius-xs`. They read as words, not badges.
+- Sizes are custom properties set on `.mu-prose` in the foundation (`--prose-fs`, `--prose-lh`, heading sizes).
+
+<!-- docs/patterns.md -->
+
+# Patterns
+
+How the components go together. Each product builds its screens from these patterns. None of them is specific to one product.
+
+## 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.
+- 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-2` with an optional `body` line under it, and the page's one primary action at the right.
+
+## Form
+
+- Fields stack `space-4` apart with the label above the control.
+- 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.
+- Errors appear under the field, in words that say how to fix it.
+
+## Entry
+
+A repeated unit of content in a list: a note, a comment, a changelog item.
+
+- **Header line** in `caption` (`ink-muted`): who or when, visibility as an outline Badge, and a ghost Menu trigger at the right that appears on hover. On touch screens the menu trigger is always visible.
+- **Body** in `Prose`.
+- **Footer line:** tags as Prose tags, attachments, reactions.
+- Entries are separated by `space-6` of whitespace or a `Separator`, never by boxes.
+
+## Confirmation
+
+- A destructive action opens an alert Dialog that names the object and the outcome.
+- It has a ghost Cancel and a danger Button that repeats the verb ("Delete note").
+- On phones it is a sheet with stacked, full-width buttons.
+- After the action runs, a neutral Toast confirms it, with Undo where undo is possible.
+
+## Loading
+
+- A list or page that is loading shows Skeletons in the shape of what is coming. The layout must not jump when content arrives.
+- A control that is waiting uses its `loading` prop.
+- Nothing spins for less than about 300ms.
+- Mark the loading region with `aria-busy`.
+
+## Empty state
+
+Centered in the content column:
+
+- a `title` line that says what is missing ("No notes yet"),
+- a `body` line that says what to do,
+- one primary Button.
+
+No illustration.
+
+## Mobile
+
+Under `breakpoint-sm` (640px):
+
+- One column.
+- Dialogs and menus become sheets.
+- Toasts sit bottom-center.
+- Every control keeps its 44px hit area.
+- Controls stay `md`. `lg` is for marketing pages and primary actions in sheets.
+
+<!-- docs/building.md -->
+
+# Building on it
+
+How the package is put together and how products use it.
+
+## Stack
+
+- **React components on [Base UI](https://base-ui.com).** Base UI provides behavior: focus management, keyboard support, ARIA, portals and positioning. Memos UI provides the styling, the tokens and the component API.
+- **No shadcn.** Don't depend on shadcn, don't copy its code, and don't use shadcn-compatible names for components or tokens. Following a similar layering (unstyled behavior below, styled components above) is fine.
+- **One npm package**, `@usememos/ui`, used by every product. ESM only, React 18 and 19, one JS entry point and two stylesheets.
+- **Plain CSS on tokens.** Components are styled with CSS that reads token variables. Product code uses tokens through their CSS variables (`var(--mu-well)`) and never copies raw values.
+- **Lucide icons** from `lucide-react`. See [Icons](icons.md).
+- **No fonts.** Text uses the system UI font; nothing is downloaded.
+
+## Loading the CSS
+
+Load the tokens first, then the styles:
+
+```ts
+import "@usememos/ui/tokens.css";
+import "@usememos/ui/styles.css";
+```
+
+`tokens.css` defines every token on `:root`, on a shadow root's `:host`, and on any element with the `mu-root` class. `styles.css` holds the foundation classes and every component's styles.
+
+Every token is a custom property named `--mu-<token>`, so the `surface` token is `var(--mu-surface)`. The prefix keeps the tokens apart from an app's own variables and from those of a CSS framework.
+
+### Cascade layer
+
+Both stylesheets sit in one [cascade layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) named `mu`. Unlayered CSS always wins over layered CSS, so an app's own rules override a component without a specificity fight: a `className` on a `Button` that sets `width` wins over the button's own rule.
+
+When the app also puts its CSS in layers, declare the order once, before any import, so that `mu` comes after resets and before the app's components and utilities. For an app on Tailwind CSS v4:
+
+```css
+@layer theme, base, mu, components, utilities;
+@import "tailwindcss";
+@import "@usememos/ui/tokens.css";
+@import "@usememos/ui/styles.css";
+```
+
+Without that line, the layer seen first is the weakest. A reset loaded after `styles.css` would then override the components.
+
+## Scoping inside a host page
+
+Inside another page (the web clipper, an embed), mount the UI under a `.mu-root` element or inside a shadow root, so neither side's styles leak into the other. The package has no global selectors beyond `:root`, `:host` and `.mu-root`.
+
+## Choosing a theme
+
+Set `data-theme="light" | "dark" | "contrast"` on the root element or on any `.mu-root`. Without the attribute the tokens are Light. The app, not the package, reads `prefers-color-scheme` and the user's saved choice. See [Color](color.md#themes). An app can add its own themes on top of these three; see [App themes](color.md#app-themes).
+
+## Class names
+
+- Every class the package ships starts with `mu-`.
+- `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-visually-hidden` hides text visually but keeps it for screen readers.
+
+## API conventions
+
+Components follow the conventions of established React libraries (Base UI, Radix, React Aria), not the needs of one product. Each [component page](components/README.md) lists its parts and their props.
+
+### Parts
+
+A component made of more than one element is a namespace of styled parts. Part names are Base UI's, so anyone who knows Base UI knows the anatomy:
+
+```tsx
+import { Menu, Button } from "@usememos/ui";
+import { Ellipsis, Pin, Trash2 } from "lucide-react";
+
+<Menu.Root>
+  <Menu.Trigger render={<Button variant="ghost" icon={<Ellipsis />} aria-label="More actions" />} />
+  <Menu.Popup align="end">
+    <Menu.Item icon={<Pin />}>Pin</Menu.Item>
+    <Menu.Separator />
+    <Menu.Item icon={<Trash2 />} danger>Delete</Menu.Item>
+  </Menu.Popup>
+</Menu.Root>
+```
+
+- **Base UI's names.** `Root`, `Trigger`, `Popup`, `Item`, `Title`, `Description`, `Close`, `Panel` and so on. No shadcn names (`DropdownMenuContent`, `CardHeader`).
+- **One `Popup` per overlay.** Base UI's `Portal`, `Positioner` and `Backdrop` are folded into our `Popup`. It takes the positioning props (`side`, `align`, `sideOffset`, `alignOffset`, `collisionPadding`) and Base UI's portal `container`, and draws the backdrop where the component has one (Dialog).
+- **Indicators are built in.** The check in a menu or select item, the chevron in a select trigger and the knob in a switch render by themselves. See [built-in glyphs](icons.md#built-in-glyphs).
+- **One element, one component.** Button, Input, Textarea, Badge, Kbd, Separator, Spinner, Skeleton, Link, Checkbox, Switch and Toggle are single components, not namespaces.
+- **No data props.** Collections are built from parts (`Menu.Item`, `Select.Item`, `Tabs.Tab`), not passed as `items` or `options` arrays.
+
+### Props
+
+- **`size`**: `"sm" | "md" | "lg"`, default `"md"`. One prop sets height, padding, text, icon size and radius together. On a namespace, set it on `Root`; every part reads it from context.
+- **Controlled or uncontrolled**, with Base UI's prop names:
+  - `value` + `onValueChange`, or `defaultValue` (Select, Combobox, Tabs, ToggleGroup, RadioGroup)
+  - `checked` + `onCheckedChange`, or `defaultChecked` (Checkbox, Switch, Menu.CheckboxItem)
+  - `pressed` + `onPressedChange`, or `defaultPressed` (Toggle)
+  - `open` + `onOpenChange`, or `defaultOpen` (Menu, Dialog, AlertDialog, Popover, Tooltip, Collapsible, Select, Combobox)
+- **`icon`** takes a Lucide element (`icon={<Pin />}`), never a string name.
+- **`render`** on every component and part swaps the rendered element, as in Base UI: a router's link in `Link`, a Button as a `Menu.Trigger`. Base UI doesn't render links through Button; a link that looks like a button is an anchor with `buttonClasses()` (see [Button](components/button.md#rules)).
+- **`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`**: `"neutral" | "success" | "warning" | "danger"` on status components (Badge, toasts).
+- **`variant`** is for Button only: `"primary" | "neutral" | "ghost" | "danger"`.
+- **Native props pass through** to the element a component or part renders.
+
+### Styling hooks
+
+- Every part has a class `mu-<component>-<part>` (`mu-menu-popup`, `mu-menu-item`), plus `mu-<component>` on single components. Variants are classes too (`mu-button-primary`, `mu-badge-success`), so `buttonClasses()` can style any element.
+- State is styled through Base UI's data attributes (`data-highlighted`, `data-checked`, `data-pressed`, `data-disabled`, `data-open`, `data-starting-style`, `data-ending-style`), never through extra classes.
+
+### Toasts
+
+Wrap the app in `Toast.Provider`, render `Toast.Viewport` once, and create toasts with Base UI's manager:
+
+```tsx
+const toast = Toast.useToastManager();
+toast.add({ title: "Note archived", type: "success" });
+```
+
+## Shared styles for content
+
+`Prose` is one stylesheet shared by every place content is rendered or edited, including the editor (`@usememos/editor`). Content never shifts between editing and reading.
+
+## What every new component needs
+
+1. A reason: a screen in a product needs it, and no existing component or pattern covers it.
+2. A generic name and API that would make sense in any of our products.
+3. Tokens only: no raw colors, sizes or shadows.
+4. All three sizes, all [states](states.md), all three themes, and reduced motion.
+5. Keyboard and screen reader behavior from Base UI.
+6. A page in `docs/components/` and an entry in the [inventory](components/README.md).