@usememos/ui 26.10.3 → 26.10.5

package/llms-full.txt

@@ -8,7 +8,7 @@ These docs describe the target system. They are the source of truth for `@usemem
 
 ## 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.
+- **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. Parts a product needs beyond them follow [Building your own component](custom-components.md).
 - **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.
@@ -28,6 +28,7 @@ It is not a general-purpose UI library for outside developers. Components are ge
 | [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 |
+| [Building your own component](custom-components.md) | How an app builds a part the package doesn't ship: Base UI, class functions, public classes, row variables and Tailwind CSS |
 
 ## Decisions at a glance
 
@@ -37,8 +38,9 @@ It is not a general-purpose UI library for outside developers. Components are ge
 - **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.
+- **Lucide icons** at a fixed screen-pixel stroke: 1.5px at md, 1.25px at xs, sm and in badges.
 - **The system UI font** for all text. The package ships no font files.
+- **Few sizes, two weights.** App UI uses 13, 14, 16 and 20px text at weights 400 and 500. 20px is for the page title only.
 - **Dense, on a 4px grid.** Controls are 32px tall by default.
 
 <!-- docs/principles.md -->
@@ -50,7 +52,7 @@ It is not a general-purpose UI library for outside developers. Components are ge
 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.
+4. **Calm by default.** Hierarchy comes from text color, lightness steps and spacing, not from weight, size or extra color. Few sizes and two weights: see [Typography](typography.md).
 5. **Dense, not cramped.** Controls are 32px tall by default, and every gap comes from the 4px scale. See [Size, spacing and layout](layout.md).
 6. **One system, many products.** Components are generic. A product's screens are built from them and from the [patterns](patterns.md); nothing in the package knows what a note or a memo is.
 
@@ -106,7 +108,7 @@ Memos UI is ink on paper: pure-gray neutrals, `primary` ink for emphasis, one qu
 
 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.
+- Each theme sets every color token and every shadow token to an explicit value. Nothing is derived at runtime. The package's tests check the values against the tables on this page and in [Depth](depth.md), and check the contrast promised here.
 - 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.
 
@@ -116,9 +118,21 @@ Set `data-theme="light" | "dark" | "contrast"` on the root element, or on any `.
 
 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.
 
+### What an app can change
+
+An app sets only these tokens:
+
+- the 26 color tokens in the [table below](#color-tokens),
+- the five shadow tokens in [Depth](depth.md#shadow-tokens),
+- the three font tokens in [Typography](typography.md#fonts): `font-sans`, `font-display` and `font-mono`.
+
+Every other token (space, radius, sizes, layout widths, layers, motion) and every `mu-*` class rule is internal. Read those tokens in app CSS (`var(--mu-space-4)`), but don't override them, even though the cascade layer lets an app rule win: the products would drift apart, and the package's tests and screenshots cover only its own values. To change one element, pass `className` or `style` to that component (see [API conventions](building.md#api-conventions)).
+
+Internal rules are not private classes. An app applies the [public classes](custom-components.md#public-classes) and the class functions to its own elements; it only never changes what they do.
+
 ### 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:
+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 color and shadow tokens under its own `data-theme` value:
 
 ```css
 [data-theme="paper"] {
@@ -130,6 +144,16 @@ An app can offer more themes than the three the package ships, such as a warm Pa
 ```
 
 - 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.
+- The package exports `themeTokens`, the custom property names of those 31 tokens (`--mu-canvas` to `--mu-shadow-pop`). Check in the app's tests that its theme sets each one:
+
+  ```ts
+  import { themeTokens } from "@usememos/ui";
+  import paper from "./themes/paper.css?raw";
+
+  it("sets every theme token", () => {
+    expect(themeTokens.filter((name) => !paper.includes(`${name}:`))).toEqual([]);
+  });
+  ```
 - Keep the rules on this page: `primary` stays ink, not a brand hue; `accent` is only for 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.
@@ -249,14 +273,18 @@ Each depth class applies a whole role in one class. Use them for new parts befor
 
 ## 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 few sizes and few weights. App text uses four sizes (13, 14, 16 and 20px) and two weights (400 and 500); 12px is only for the labels of 20px parts (see `label-xs`). Hierarchy comes from text color, spacing and grouping first, then from weight, and from size last.
+- Weight 400 is for running text and values people typed or chose. Weight 500 is for labels, controls, titles and headings. The UI uses no 600 or 700. The one exception is [Prose](components/prose.md): bold text and headings that people wrote are 600, because 500 does not read as bold in system fonts.
+- 20px (`heading`) is for the page title only, once per page. 32px (`display`) is for the hero headline on a website only, once per page. Nothing else is larger than 16px, and 16px is only for `title` and Prose text.
+- A section title inside a page or panel is `label` (14px, 500), set apart by space above it, not by a larger size. See [Page](patterns.md#page).
+- Secondary text (descriptions, helper text, metadata) is `caption` (13px) in `ink-muted`. No text is smaller than 13px, except `label-xs` inside 20px parts.
+- Control text scales with the control size: 12px at xs, 13px at sm, 14px at md.
+- Reading text (`Prose`) is 16px on a 24px line. `sm` prose is 14px on a 22px line, for dense lists.
+- Letter spacing is 0, except −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.
+- Selected and unselected states never change weight, so labels don't shift.
+- Adding a size, a weight or a style needs a written reason in this page and the maintainer's sign-off.
+- The platform's UI font for everything (San Francisco on Apple, Segoe UI on Windows, Roboto on Android), smoothed with antialiasing. The package ships no font files.
 
 ## Fonts
 
@@ -266,38 +294,48 @@ Each depth class applies a whole role in one class. Use them for new parts befor
 | `--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.
+The package ships no font files and loads no remote font: text uses the system UI font, so it looks native on each platform and costs no download. An app that wants another font sets `--mu-font-sans`, `--mu-font-display` or `--mu-font-mono` after loading `tokens.css`, and loads the font itself. These are the only type tokens an app may set: sizes, line heights, weights and letter spacing are fixed (see [What an app can change](color.md#what-an-app-can-change)). Code in [Prose](components/prose.md) uses `font-mono`, the platform's monospace font by default.
 
 ## Scale
 
+Eight styles over six sizes. 13 and 14px each have a 400 style for text and a 500 style for labels; 12px has only a label style; the three headings are 500. Body text on a website is `body`, or `Prose` for long-form copy.
+
 ### 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 |
+| `label-xs` | 12 / 16px | 500 | Labels inside xs controls, badges and kbd: the parts that are 20px tall. Never for running or secondary text. The reason for the size: xs controls must read as tiny, and at 13px they read as sm controls with less padding |
+| `caption` | 13 / 18px | 400 | Secondary text: field descriptions and errors, metadata, timestamps, toast and popover descriptions, table captions, sm table cells. Usually in `ink-muted` |
+| `label-sm` | 13 / 18px | 500 | Labels inside sm controls, tooltips, group labels in menus and lists, table heads |
+| `body` | 14 / 20px | 400 | Default running text in app UI; dialog descriptions |
+| `label` | 14 / 20px | 500 | Labels inside md controls, field labels, nav rows, buttons, section titles, popover and toast titles. The default control text |
 
 ### 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 |
+| `title` | 16 / 24px | 500 | 0 | Dialog titles; empty-state titles |
+| `heading` | 20 / 28px | 500 | 0 | The page title in an app or on a website. One per page |
+| `display` | 32 / 40px | 500 | −0.02em | The hero headline on a website. Never in an app |
 
-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.
+Each style is also a class with the `mu-` prefix (`.mu-caption`, `.mu-heading`) in `@usememos/ui/styles.css`, which sets the family, size, line height, weight and, where listed, letter spacing.
+
+### Removed styles
+
+The scale used to have 12 sizes and 3 weights. These styles were removed; use the replacement. (`label-xs` was 11px before it came back at 12px for the xs row.)
+
+| Removed | Was | Use |
+| --- | --- | --- |
+| `body-sm` | 13 / 18px, 400 | `caption` |
+| `heading-3` | 20 / 28px, 600 | `heading`, or `label` for a section title |
+| `heading-2` | 24 / 32px, 600 | `heading` |
+| `heading-1` | 32 / 40px, 600 | `display` on a website; `heading` in an app |
+| `body-lg` | 16 / 24px, 400 | `body`, or `Prose` for long-form copy |
+| `label-lg` | 16 / 24px, 500 | `label` (there is no `lg` control size) |
 
 ## Prose
 
-Rendered content (notes, comments, changelogs, website pages) uses the `Prose` styles, not the scale above. See [Prose](components/prose.md).
+Rendered content (notes, comments, changelogs, website pages) uses the `Prose` styles, not the scale above. It uses the same sizes: 16px text (14px at `sm`), 20px `h1`, 16px `h2`–`h6`, and 13px table heads. See [Prose](components/prose.md).
 
 <!-- docs/layout.md -->
 
@@ -305,15 +343,17 @@ Rendered content (notes, comments, changelogs, website pages) uses the `Prose` s
 
 ## 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.
+Every control takes one `size` prop: `xs`, `sm` or `md` (the default). There is no `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 |
+| xs | `control-xs` 20px | 6px | 12px | 4px | 12 / 16px | `radius-sm` 4px | 14px |
+| sm | `control-sm` 24px | 8px | 14px | 4px | 13 / 18px | `radius-sm` 4px | 16px |
 | md (default) | `control-md` 32px | 12px | 16px | 6px | 14 / 20px | `radius-md` 6px | 18px |
-| 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.
+- Use `sm` for dense toolbars, table rows and filters inside panels, and `md` everywhere else, including marketing pages, onboarding and sheets. Emphasis comes from the `primary` variant, not from a bigger control. On touch screens the hit area, not the visual size, grows.
+- Use `xs` for secondary actions beside 13px text: actions on a row or an entry, inline formatting, filters in a tight header, checkboxes in a dense list. It is the height of a Badge or a Kbd, so they line up. Don't use `xs` for forms, for navigation, or for the main action of a screen.
+- Only Button, Toggle, ToggleGroup, Checkbox, RadioGroup and Radio, Switch, Avatar, Spinner and Skeleton take `xs`. Text entry, menus, tabs and tables are too cramped at 20px, so their `size` is `sm | md`, and an `xs` inherited from a parent renders them at `sm`.
 - The icon side of a control has 2px less padding, so text and icon look centered.
 - On touch screens (`pointer: coarse`), every control gets an invisible hit area of at least `hit-area` (44px) without changing its visual size.
 
@@ -322,24 +362,25 @@ Every control takes one `size` prop: `sm`, `md` (the default) or `lg`. The size
 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).
+- 2px (`inset`) 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-2` | 8px | Gap between md 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-4` | 16px | Padding inside popovers and toasts; 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 |
 
+`space-8`, `space-12` and `space-16` are for an app's page layout. No component uses them.
+
 ## Radius
 
 Inner radius = outer radius − `inset`, so nested corners stay concentric.
@@ -349,7 +390,7 @@ Inner radius = outer radius − `inset`, so nested corners stay concentric.
 | `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-lg` | 8px | 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 |
@@ -360,15 +401,15 @@ Buttons, inputs and badges are never pills.
 
 | Token | Value | Usage |
 | --- | --- | --- |
+| `control-xs` | 20px | xs control height; Badge and Kbd |
 | `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-xs` | 12px | Icons in xs controls and badges |
 | `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
 
@@ -382,10 +423,23 @@ Buttons, inputs and badges are never pills.
 | `tooltip-width` | 240px | Maximum width of a tooltip |
 | `toast-width` | 360px | Width of a toast from `breakpoint-sm` up |
 | `dialog-width` | 440px | Default width of a dialog |
-| `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.
+- `content-width` and `sidebar-width` are suggested values for an app's page layout. No component uses them. An app that needs another width uses its own value instead of overriding the token.
+- The other widths are component defaults. To change one instance, pass `className` or `style` to it.
+
+## Breakpoints
+
+Two breakpoints. They are values, not tokens: CSS custom properties can't be used in media queries, so there is no `--mu-breakpoint-*` variable and nothing to override. Write the value in the query and name the breakpoint in a comment.
+
+| Breakpoint | Value | Usage |
+| --- | --- | --- |
+| 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
+/* Below breakpoint-sm */
+@media (max-width: 639.98px) { … }
+```
 
 ## Layers
 
@@ -461,14 +515,14 @@ Memos UI uses [Lucide](https://lucide.dev) (ISC license) for every icon. Apps im
 import { Pin, Trash2 } from "lucide-react";
 
 <Button icon={<Pin />}>Pin</Button>
-<Menu items={[{ value: "delete", label: "Delete", icon: <Trash2 />, danger: true }]} />
+<Menu.Item icon={<Trash2 />} danger>Delete</Menu.Item>
 ```
 
 ## 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`.
+- **Size comes from the control.** An icon inside a component is 12px at xs, 14px at sm and 16px at md (`icon-xs`, `icon-sm`, `icon-md`). Don't pass `size`.
+- **Stroke is fixed in screen pixels.** 1.25px at xs, at sm and in badges, 1.5px at md, 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.
@@ -554,7 +608,7 @@ Components follow the [API conventions](../building.md#api-conventions): parts w
 ## Shared types
 
 ```ts
-type Size = "sm" | "md" | "lg";
+type Size = "xs" | "sm" | "md"; // xs only where a page says so; other components take "sm" | "md"
 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;
@@ -608,7 +662,7 @@ Wraps Base UI's [Button](https://base-ui.com/react/components/button): `disabled
 
 ## 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.
+- A raised key: 20, 24 or 32px tall. `primary` is an ink key with `on-primary` text; `neutral` a `key` with a soft edge; `ghost` flat `ink-muted` with `hover` on hover; `danger` a `danger-key` with `on-danger` text.
 - Only an icon: square. The icon side has 2px less padding.
 - 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.
@@ -757,10 +811,10 @@ import { Ellipsis, FolderInput, Pin, Trash2 } from "lucide-react";
 
 ```ts
 interface Menu.RootProps extends BaseMenu.Root.Props {
-  size?: Size; // row height: 24, 32, 40px
+  size?: "sm" | "md"; // row height: 24, 32px. An xs trigger still opens sm rows
 }
 interface Menu.PopupProps extends BaseMenu.Popup.Props {
-  side?: Side; align?: Align; sideOffset?: number; alignOffset?: number; collisionPadding?: Padding; // Positioner props; default side "bottom", sideOffset 4
+  side?: Side; align?: Align; // Positioner props; default side "bottom"
   container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
 }
 interface Menu.ItemProps extends BaseMenu.Item.Props {
@@ -769,6 +823,11 @@ interface Menu.ItemProps extends BaseMenu.Item.Props {
   danger?: boolean;           // destructive: red text
 }
 // CheckboxItem and RadioItem take icon and shortcut too. SubmenuTrigger takes icon.
+
+function menuClasses(options?: { size?: "sm" | "md" }): {
+  popup: string; item: string; dangerItem: string; label: string;
+  shortcut: string; separator: string; groupLabel: string;
+};
 ```
 
 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.
@@ -780,11 +839,12 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on
 - 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.
+- An app's own floating list, such as an editor's suggestion list, takes `menuClasses()`: `popup` on the list, `item` on each row, and `data-highlighted` on the active row. See [Class functions](../custom-components.md#class-functions).
 
 ## 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`.
+- Rows are a control height (24 or 32px), 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.
@@ -874,10 +934,10 @@ import { Checkbox, Field, Fieldset, Input } from "@usememos/ui";
 
 ```ts
 interface Field.RootProps extends BaseField.Root.Props {
-  size?: Size; // passed to the control inside
+  size?: "sm" | "md"; // passed to the control inside
 }
 interface Fieldset.RootProps extends BaseFieldset.Root.Props {
-  size?: Size; // passed to every control inside
+  size?: "sm" | "md"; // passed to every control inside
 }
 ```
 
@@ -895,7 +955,7 @@ Base UI's props pass through: `name`, `invalid`, `disabled`, `validate`, `valida
 ## 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`.
+- Description and error: `caption` (13px), below the control. The error hides the description and turns the control's edge `danger`.
 
 <!-- docs/components/input.md -->
 
@@ -916,12 +976,14 @@ import { Search } from "lucide-react";
 
 ```ts
 interface InputProps extends Omit<BaseInput.Props, "size" | "prefix"> {
-  size?: Size;
+  size?: "sm" | "md";
   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>
 }
+
+function inputClasses(options?: { size?: "sm" | "md" }): string; // the visible box
 ```
 
 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.
@@ -931,6 +993,7 @@ Wraps Base UI's [Input](https://base-ui.com/react/components/input), so inside a
 - Provide a `Field.Label` or `aria-label`. Never a placeholder alone.
 - `prefix` and `suffix` hold an icon, a short word or a small ghost Button.
 - `sm` for filters inside panels, `md` everywhere else.
+- An app's own one-line field, such as a tag input around a native `<input>`, takes `inputClasses()` on its box: focus anywhere inside shows the ring, and `aria-invalid="true"` or `aria-disabled="true"` on the box show those states. See [Class functions](../custom-components.md#class-functions).
 
 ## Style
 
@@ -960,9 +1023,11 @@ import { Field, Textarea } from "@usememos/ui";
 
 ```ts
 interface TextareaProps extends Omit<BaseField.Control.Props, "size" | "render"> {
-  size?: Size;
+  size?: "sm" | "md";
   rows?: number; // visible lines, default 3
 }
+
+function textareaClasses(options?: { size?: "sm" | "md" }): string;
 ```
 
 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.
@@ -971,6 +1036,7 @@ Base UI has no textarea part, so this renders Base UI's `Field.Control` as a `<t
 
 - Provide a `Field.Label` or `aria-label`.
 - Rich content is not a textarea: use the editor (`@usememos/editor`) with [Prose](prose.md).
+- An app's own multi-line field, such as a content-editable editor, takes `textareaClasses()`: focus shows the ring, and `aria-invalid="true"` or `aria-disabled="true"` show those states. See [Class functions](../custom-components.md#class-functions).
 
 ## Style
 
@@ -1021,11 +1087,11 @@ const visibility = { private: "Private", workspace: "Workspace", public: "Public
 
 ```ts
 type Select.RootProps<Value, Multiple> = BaseSelect.Root.Props<Value, Multiple> & {
-  size?: Size;
+  size?: "sm" | "md";
 };
 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
+  side?: Side; align?: Align; // used when alignItemWithTrigger is false
   container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
 }
 interface Select.ItemProps extends BaseSelect.Item.Props {
@@ -1097,7 +1163,7 @@ const tags = ["book", "design", "travel"];
 
 ```ts
 type Combobox.RootProps<Value, Multiple, Item> = BaseCombobox.Root.Props<Value, Multiple, Item> & {
-  size?: Size;
+  size?: "sm" | "md";
 };
 interface Combobox.InputProps extends BaseCombobox.Input.Props {
   icon?: IconElement | null; // default <Search />; null drops it
@@ -1106,7 +1172,7 @@ interface Combobox.InputProps extends BaseCombobox.Input.Props {
   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
+  side?: Side; align?: Align; // Positioner props; default side "bottom", align "start"
   container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
 }
 interface Combobox.ItemProps extends BaseCombobox.Item.Props {
@@ -1155,7 +1221,7 @@ import { Checkbox, Field } from "@usememos/ui";
 
 ```ts
 interface CheckboxProps extends BaseCheckbox.Root.Props {
-  size?: Size; // box: 16, 18, 20px
+  size?: Size; // box: 14, 16, 18px
 }
 ```
 
@@ -1195,7 +1261,7 @@ import { Field, Switch } from "@usememos/ui";
 
 ```ts
 interface SwitchProps extends BaseSwitch.Root.Props {
-  size?: Size; // 18, 20, 22px tall
+  size?: Size; // 16, 18, 20px tall
 }
 ```
 
@@ -1303,7 +1369,7 @@ import { Bell, User } from "lucide-react";
 
 ```ts
 interface Tabs.RootProps extends BaseTabs.Root.Props {
-  size?: Size;
+  size?: "sm" | "md";
 }
 interface Tabs.TabProps extends BaseTabs.Tab.Props {
   icon?: IconElement; // before the label
@@ -1353,7 +1419,7 @@ import { Collapsible } from "@usememos/ui";
 
 ```ts
 interface Collapsible.RootProps extends BaseCollapsible.Root.Props {
-  size?: Size; // the trigger's size
+  size?: "sm" | "md"; // the trigger's size
 }
 ```
 
@@ -1489,9 +1555,11 @@ import { Button, Input, Popover } from "@usememos/ui";
 
 ```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
+  side?: Side; align?: Align; // Positioner props; default side "bottom"
   container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
 }
+
+function popoverClasses(): { popup: string; title: string; description: string };
 ```
 
 Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on the root; `openOnHover`, `delay` on the trigger; `initialFocus`, `finalFocus` on the popup.
@@ -1501,11 +1569,12 @@ Base UI's props pass through: `open`, `defaultOpen`, `onOpenChange`, `modal` on
 - Use it for a few controls that belong to one thing. For a list of actions, use [Menu](menu.md). For a decision that blocks the page, use [Dialog](dialog.md).
 - Give it a `Popover.Title`, or `aria-label` on the popup.
 - It closes on Escape and on a click outside; focus returns to the trigger.
+- An app's own floating panel, such as an emoji picker, takes `popoverClasses()`. See [Class functions](../custom-components.md#class-functions).
 
 ## 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.
+- Title: `label`. Description: `caption` 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 -->
@@ -1545,7 +1614,7 @@ interface Tooltip.TriggerProps extends BaseTooltip.Trigger.Props {
 }
 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
+  side?: Side; align?: Align; // Positioner props; default side "top"
   container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
 }
 ```
@@ -1621,7 +1690,7 @@ Base UI's props pass through: `timeout` (default 5000ms) and `limit` (default 3)
 ## Style
 
 - `mu-popup`, `toast-width` wide, bottom-right at `space-6` from the edges; below `breakpoint-sm`, full width at `space-4`.
-- 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.
+- A tone icon (`Info`, `CircleCheck`, `TriangleAlert`, `CircleAlert`) in `ink-muted`, `success`, `warning` or `danger`; title in `label`; description in `caption` `ink-muted`; the action as a small neutral Button; the X as a small ghost Button.
 - Newest in front; the ones behind peek out `space-2` above and shrink. Hover or focus fans them out `space-3` apart. Toasts slide in from below and can be swiped away. Under reduced motion they only fade.
 
 <!-- docs/components/avatar.md -->
@@ -1653,7 +1722,7 @@ import { Avatar } from "@usememos/ui";
 
 ```ts
 interface Avatar.RootProps extends BaseAvatar.Root.Props {
-  size?: Size; // 24, 32, 40px
+  size?: Size; // 20, 24, 32px
 }
 ```
 
@@ -1662,7 +1731,7 @@ interface Avatar.RootProps extends BaseAvatar.Root.Props {
 ## 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.
+- `xs` inline with a name in 13px text, `sm` in lists and comments, `md` in a sidebar and on profile pages.
 
 ## Style
 
@@ -1694,16 +1763,19 @@ interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
   children: React.ReactNode; // one or two words
   render?: React.ReactElement;
 }
+
+function badgeClasses(options?: { tone?: Tone | "outline" }): string;
 ```
 
 ## Rules
 
 - Tags: `neutral` with a `Hash` icon. Visibility: `outline` with its icon. Status: `success`, `warning` or `danger`, always with a word, never color alone.
 - A badge is not a button. A clickable tag filter is a [Toggle](toggle.md).
+- An app's own element that should look like a badge, such as a tag that is also a link, takes `badgeClasses()`. See [Class functions](../custom-components.md#class-functions).
 
 ## Style
 
-- 20px tall, `radius-sm` (never a pill), 12px medium text, optional 12px icon at a 1.25px stroke.
+- `control-xs` (20px) tall, `radius-sm` (never a pill), `label-xs` text (12px, 500), optional `icon-xs` (12px) icon at a 1.25px stroke. It lines up with xs controls.
 - `neutral`: `ink` on `well`. Status tones: their `-soft` background with full-strength text.
 
 <!-- docs/components/kbd.md -->
@@ -1738,7 +1810,7 @@ Renders a `<kbd>`.
 
 ## Style
 
-- A tiny raised key, 20px tall, `label-xs` text in `ink-muted`.
+- A tiny raised key, `control-xs` (20px) tall, `label-xs` text (12px) in `ink-muted`.
 
 <!-- docs/components/separator.md -->
 
@@ -1792,7 +1864,7 @@ import { Spinner } from "@usememos/ui";
 
 ```ts
 interface SpinnerProps extends React.HTMLAttributes<HTMLSpanElement> {
-  size?: Size;    // 14, 16, 20px; default: the surrounding Root's size, else md
+  size?: Size;    // 12, 14, 16px; default: the surrounding Root's size, else md
   label?: string; // for screen readers, default "Loading"
   render?: React.ReactElement;
 }
@@ -1906,7 +1978,7 @@ No Base UI part: these are styled native table elements.
 
 ```ts
 interface Table.RootProps extends React.ComponentProps<"table"> {
-  size?: Size; // sm for dense admin lists
+  size?: "sm" | "md"; // sm for dense admin lists
 }
 interface Table.HeadProps extends React.ComponentProps<"th"> {
   num?: boolean; // right-aligned, for a column of numbers
@@ -1930,8 +2002,8 @@ Every native attribute passes through.
 ## 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.
+- Heads: `label-sm` (13px, 500) in `ink-muted`, a control height tall.
+- Cells: `caption` at sm and `body` at md, with tabular numbers. Rows are 34 or 40px; a Button in a cell overlaps the padding, so rows keep that height.
 - Cells pad `px` at the sides. Caption: `caption` in `ink-muted`, `space-2` above.
 
 <!-- docs/components/prose.md -->
@@ -1959,7 +2031,7 @@ Without React: `<div class="mu-prose">…</div>`, and `mu-prose mu-prose-sm` for
 
 ```ts
 interface ProseProps extends React.ComponentProps<"div"> {
-  size?: "sm" | "md"; // md: 15/24px for reading; sm: 14/22px for dense lists
+  size?: "sm" | "md"; // md: 16/24px for reading; sm: 14/22px for dense lists
 }
 ```
 
@@ -1975,14 +2047,14 @@ Every native attribute passes through.
 
 ## 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.
+- Text: 16px on a 24px line (`sm`: 14 on 22), weight 400, `ink`. Blocks are `space-3` apart.
+- Headings: `h1` 20/28px, `h2`–`h6` 16/24px; all weight 600, with `space-5` above and `space-2` below. Bold (`strong`, `b`) is 600 too. These are the only 600s in the system: people wrote them as bold, and 500 does not read as bold in system fonts.
 - 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.
+- Tables follow [Table](table.md): `line` between rows, 13px `ink-muted` heads (weight 500), tabular numbers; they scroll sideways when too wide.
 - Tags: `ink-muted` on `well`, `radius-xs`. They read as words, not badges.
 - Sizes are custom properties set on `.mu-prose` in the foundation (`--prose-fs`, `--prose-lh`, heading sizes).
 
@@ -1996,7 +2068,8 @@ How the components go together. Each product builds its screens from these patte
 
 - 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.
+- A page header is a `heading` with an optional `body` line under it, and the page's one primary action at the right. `heading` appears once per page.
+- Sections inside a page have a `label` title (14px, 500) with `space-6` above it and `space-2` below. Section titles are never larger than the text around them; space and grouping set them apart. A section's rows use `label` for the name and `caption` in `ink-muted` for the description.
 
 ## Form
 
@@ -2047,7 +2120,7 @@ Under `breakpoint-sm` (640px):
 - 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.
+- Controls stay `md`.
 
 <!-- docs/building.md -->
 
@@ -2057,9 +2130,9 @@ 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.
+- **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. `@base-ui/react` is a peer dependency at one exact version, so an app's own Base UI components share the package's copy.
 - **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.
+- **One npm package**, `@usememos/ui`, used by every product. ESM only, React 18 and 19, one JS entry point, two stylesheets and a Tailwind CSS theme file.
 - **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.
@@ -2073,6 +2146,8 @@ import "@usememos/ui/tokens.css";
 import "@usememos/ui/styles.css";
 ```
 
+An app on Tailwind CSS v4 also loads `@usememos/ui/tailwind.css`, which maps the tokens to `mu-` utilities (`bg-mu-surface`). See [Tailwind CSS](custom-components.md#tailwind-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.
@@ -2100,14 +2175,28 @@ Inside another page (the web clipper, an embed), mount the UI under a `.mu-root`
 
 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).
 
+An app changes only the color, shadow and font tokens. Every other token and every `mu-*` class rule is internal. See [What an app can change](color.md#what-an-app-can-change).
+
 ## Class names
 
 - Every class the package ships starts with `mu-`.
+- The [public classes](custom-components.md#public-classes) are for apps too: size rows (`mu-s-md`), depth roles (`mu-raised`), focus, touch targets, icons and the type scale. Apps apply them to their own parts and never override them.
 - `mu-positioner` puts a popup's positioner on `layer-popup`, and `mu-popup-motion` makes a popup fade in and rise `space-1` (no rise under reduced motion).
 - 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.
+- A size row class sets the `--mu-row-*` variables (height, padding, text, radius, gap, icon) that every part inside reads. See [Row variables](custom-components.md#row-variables).
+- Component part classes (`mu-menu-item`) are internal. An app reaches a component's look through its class function (`menuClasses()`). See [Class functions](custom-components.md#class-functions).
+
+## Writing component CSS
+
+Inside the package, source order decides which rule wins: a rule later in `styles.css` overrides an earlier one on the same element. Selector weight must not get in the way.
+
+- Put every `:has()` inside `:where()`: write `.mu-button:where(:has(> svg:first-child))`, not `.mu-button:has(> svg:first-child)`. A `:has()` takes the specificity of its argument, so the bare form scores (0,2,1) and beats a later `.mu-button.mu-button-icon` (0,2,0), whatever the order.
+- A modifier rule (a variant, an `-icon` class, a context like `.mu-segmented > .mu-toggle`) comes after the base rule it changes, and its selector weighs at least as much.
+
+`packages/ui/test/cascade.test.ts` fails when a `:has()` adds specificity, and when an earlier rule outranks a later rule that adds a class to the same element and sets the same property. `e2e/icons.spec.ts` checks the result in the browser: icon-only buttons and toggles are squares with the icon centered, in every size.
 
 ## API conventions
 
@@ -2132,14 +2221,14 @@ import { Ellipsis, Pin, Trash2 } from "lucide-react";
 ```
 
 - **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).
+- **One `Popup` per overlay.** Base UI's `Portal`, `Positioner` and `Backdrop` are folded into our `Popup`. It takes `side`, `align`, Base UI's other placement behavior (`anchor`, `sticky`, `collisionAvoidance`, `collisionBoundary`, `positionMethod`, `disableAnchorTracking`) and its portal `container`, and draws the backdrop where the component has one (Dialog). The gap to the trigger and the distance kept from the viewport edge are fixed by the system (4px for menus and lists, 6px for popovers and tooltips; Base UI's default edge distance), so `sideOffset`, `alignOffset` and `collisionPadding` are not props.
 - **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.
+- **`size`**: `"xs" | "sm" | "md"`, default `"md"`. `xs` only on the components listed in [Control sizes](layout.md#control-sizes); the rest take `"sm" | "md"`. There is no `lg`: a bigger control is not a stronger one, and apps hardly need it. 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)
@@ -2155,7 +2244,8 @@ import { Ellipsis, Pin, Trash2 } from "lucide-react";
 
 ### 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.
+- 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 a class function can style any element.
+- **Class functions.** A component whose look apps put on their own elements exports `<component>Classes()`: `buttonClasses`, `inputClasses`, `textareaClasses`, `badgeClasses`, `menuClasses` and `popoverClasses`. It returns a string for a single component and one string per part for a namespace. The component builds its own classes with it, so the two can't drift. See [Class functions](custom-components.md#class-functions).
 - 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
@@ -2176,6 +2266,143 @@ toast.add({ title: "Note archived", type: "success" });
 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.
+4. Both 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).
+
+<!-- docs/custom-components.md -->
+
+# Building your own component
+
+How an app builds a component the package doesn't ship, so that it looks and behaves like the package's own: Base UI for behavior, the package's class functions and public classes for looks, and tokens for everything else.
+
+An app always has parts the package doesn't ship and shouldn't: product parts (an entry card, a tag pill, an editor's suggestion list) and wrappers around third-party widgets (a date picker, a code editor, a chart). Build them with the steps on this page. Never copy a value out of the package's CSS: copied values don't follow the themes.
+
+## Steps
+
+1. **Use a component if one fits.** Check the [inventory](components/README.md). Compose components, swap a part's element with `render`, or adjust one instance with `className` before building anything.
+2. **Behavior from Base UI.** Build anything with focus, keyboard, an open state or a popup on [`@base-ui/react`](https://base-ui.com), as the package does. It is a peer dependency of the package at one exact version, so the app's components and the package's share one copy. Upgrade it only with the package.
+3. **Looks from a class function** when the part should look like a component: an anchor that looks like a Button, an editor that looks like a Textarea, a suggestion list that looks like a Menu. See [Class functions](#class-functions).
+4. **Otherwise, from the public classes and tokens.** Size the part with a size row class and read the [row variables](#row-variables); give it depth with a [depth class](depth.md); set text with a [type class](typography.md); color it with `var(--mu-<token>)` or the [Tailwind utilities](#tailwind-css).
+5. **Check it like a component.** It works in Light, Dark and High contrast and under reduced motion; text keeps 4.5:1 contrast; focus shows on `:focus-visible` (`mu-focus`); touch targets reach 44px (`mu-hit`); icon-only controls have an `aria-label` and a [Tooltip](components/tooltip.md).
+
+## Class functions
+
+A class function returns the classes that make any element look like a component, the same classes the component uses, so the two can't drift apart. Functions for single components return a string; functions for components made of parts return one string per part. Add the app's own classes after them.
+
+| Function | Returns | For an app's own |
+| --- | --- | --- |
+| `buttonClasses({ variant, size, iconOnly })` | A string | Anchor that looks like an action |
+| `inputClasses({ size })` | A string | One-line field, such as a tag input around a native `<input>` |
+| `textareaClasses({ size })` | A string | Multi-line field, such as a content-editable editor |
+| `badgeClasses({ tone })` | A string | Label, such as a tag that is also a link |
+| `menuClasses({ size })` | `popup`, `item`, `dangerItem`, `label`, `shortcut`, `separator`, `groupLabel` | Floating list, such as an editor's suggestion list |
+| `popoverClasses()` | `popup`, `title`, `description` | Floating panel, such as an emoji picker |
+
+State is set with attributes, never with extra classes:
+
+- A field shows the focus ring when it or anything inside it has focus. `aria-invalid="true"` shows the error edge, and `aria-disabled="true"` dims it.
+- A menu row is highlighted while it has `data-highlighted`, and dimmed with `data-disabled`. Base UI sets both; a list the app drives itself sets them on the active row.
+- A popup fades in with `data-starting-style` and out with `data-ending-style`, which Base UI's popups set.
+
+```tsx
+import { badgeClasses, menuClasses, textareaClasses } from "@usememos/ui";
+
+<a className={badgeClasses()} href="/tags/work">work</a>
+
+<div className={textareaClasses()} contentEditable role="textbox" aria-multiline="true" aria-label="Note" />
+
+const menu = menuClasses({ size: "sm" });
+
+<div className={menu.popup} role="listbox">
+  {matches.map((tag, index) => (
+    <div key={tag} className={menu.item} role="option" aria-selected={index === active} data-highlighted={index === active ? "" : undefined}>
+      <span className={menu.label}>{tag}</span>
+    </div>
+  ))}
+</div>
+```
+
+A popup built this way still needs its behavior from Base UI or the editor it belongs to: positioning, dismissal and focus. Put the positioner on the popup layer with `mu-positioner`. Inside a host page or a shadow root, render it inside the `.mu-root` element or the shadow root, or it loses the tokens (see [Scoping inside a host page](building.md#scoping-inside-a-host-page)).
+
+## Public classes
+
+Apply these classes to an app's own elements. Don't override their rules: the products would drift apart, and the package's tests cover only its own values. Every other `mu-*` class, such as a component part's `mu-menu-item`, is internal; reach it through a class function.
+
+| Class | What it applies | Use it for |
+| --- | --- | --- |
+| `mu-s-xs` | The xs size row: 20px | Secondary actions beside 13px text |
+| `mu-s-sm` | The sm size row: 24px | Dense toolbars, table rows, filters |
+| `mu-s-md` | The md size row: 32px | Everything else |
+| `mu-base` | The system font, the row's text size and weight 500, `ink` text, and icon sizing for Lucide icons inside | The root of a control |
+| `mu-recessed` | `well`, a 1px `edge` and `shadow-track` | A part that holds a value |
+| `mu-key` | A `key` with the sheen and `shadow-key` | A key inside a well |
+| `mu-raised` | A `key` with the sheen and `shadow-raised` | A part you press |
+| `mu-popup` | `surface`, `shadow-pop` and `radius-xl` | A part that floats |
+| `mu-popup-motion` | The popup fade and rise, none under reduced motion | A popup Base UI opens |
+| `mu-positioner` | The popup layer | A popup's positioner |
+| `mu-focus` | The focus ring on `:focus-visible` | Anything focusable |
+| `mu-hit` | An invisible 44px touch target on `pointer: coarse` | Anything pressable smaller than 44px |
+| `mu-icon` | Icon size and stroke | A Lucide icon outside a control |
+| `mu-visually-hidden` | Hidden on screen, read by screen readers | Text for screen readers only |
+| `mu-label-xs` | 12 / 16px, 500 | Labels of 20px parts |
+| `mu-caption` | 13 / 18px, 400 | Secondary text |
+| `mu-label-sm` | 13 / 18px, 500 | Small labels |
+| `mu-body` | 14 / 20px, 400 | Body text |
+| `mu-label` | 14 / 20px, 500 | Labels and buttons |
+| `mu-title` | 16 / 24px, 500 | Section titles |
+| `mu-heading` | 20 / 28px, 500 | The page title |
+| `mu-display` | 32 / 40px, 500 | A website hero only |
+
+## Row variables
+
+A size row class sets these variables on its element, and children inherit them. Read them in the app's CSS to match the package's rows; never set them. The values are those in [Control sizes](layout.md#control-sizes).
+
+| Variable | xs | sm | md |
+| --- | --- | --- | --- |
+| `--mu-row-height` | 20px | 24px | 32px |
+| `--mu-row-padding` | 6px | 8px | 12px |
+| `--mu-row-padding-icon` | 4px | 6px | 10px |
+| `--mu-row-font-size` | 12px | 13px | 14px |
+| `--mu-row-line-height` | 16px | 18px | 20px |
+| `--mu-row-radius` | 4px | 4px | 6px |
+| `--mu-row-gap` | 4px | 4px | 6px |
+| `--mu-row-icon` | 12px | 14px | 16px |
+| `--mu-row-icon-stroke` | 1.25px | 1.25px | 1.5px |
+| `--mu-row-check-box` | 14px | 16px | 18px |
+
+`--mu-row-padding-icon` is the padding on the side of a control that starts or ends with an icon.
+
+```css
+.app-tag-input-chip {
+  height: calc(var(--mu-row-height) - 2 * var(--mu-inset));
+  padding: 0 var(--mu-row-padding-icon);
+  border-radius: var(--mu-row-radius);
+}
+```
+
+## Tailwind CSS
+
+An app on Tailwind CSS v4 loads `tailwind.css` after the package's other stylesheets:
+
+```css
+@layer theme, base, mu, components, utilities;
+@import "tailwindcss";
+@import "@usememos/ui/tokens.css";
+@import "@usememos/ui/styles.css";
+@import "@usememos/ui/tailwind.css";
+```
+
+It maps the 26 color tokens, five shadow tokens, seven radius tokens and three font tokens to utilities with an `mu-` prefix, so they never clash with an app's own colors:
+
+| Token | Utility |
+| --- | --- |
+| A color, such as `surface` | `bg-mu-surface`, `text-mu-ink-muted`, `border-mu-edge`, and every other color utility |
+| A shadow, such as `shadow-raised` | `shadow-mu-raised` |
+| A radius, such as `radius-md` | `rounded-mu-md` |
+| A font, such as `font-mono` | `font-mu-mono` |
+
+- Each utility reads the token where it is used, so a `.mu-root` with its own `data-theme` recolors the utilities inside it.
+- Spacing needs no mapping: Tailwind's step is 0.25rem, which is the 4px grid, so `p-3` is `space-3`. Don't use half steps such as `p-0.5`; the only 2px value is `inset`.
+- Text uses the type classes (`mu-body`), not Tailwind's text sizes.
+- `tailwind-merge` doesn't know `mu-` classes and keeps them next to a utility. The utility still wins, because the package's styles sit in the `mu` [cascade layer](building.md#cascade-layer).