@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/glossary.en.md

@@ -0,0 +1,179 @@
+---
+sourceHash: 7b328de94ead
+---
+
+# Glossary of `@olddevs/ui`
+
+Kit terms. One concept, one word: a synonym from a neighboring system (plugin, service, node,
+library) introduces a second meaning, and the two drift apart silently. If a word has two
+meanings, both get compound names ("palette primitive", "overlay layer"), and the bare word stays
+with one of them.
+
+General terms are written in prose as ordinary words, lowercase: "consumer", "role", "showcase".
+Editor terms are capitalized ("Block", "Toolbar"): they are easy to confuse with an everyday word,
+and the capital letter shows that the word means exactly what the table says.
+
+A new term enters this glossary in the same change in which it appears. The glossary lives in the
+package, not in the documentation repository, because it changes together with the code; the
+documentation site shows it from the pinned kit version.
+
+Prop names are a separate vocabulary:
+[semantic prop vocabulary](conventions.md#семантический-словарь-пропсов).
+
+## Kit and consumer
+
+| Term                  | Meaning                                                                                                                                                                                                                                                                          | Not to be confused with                                                                                                                                         |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **kit**               | The `@olddevs/ui` design system: tokens, themes, accessible components and their documentation                                                                                                                                                                                   | The package: that is how the kit is delivered. A library: the kit is not called that, the word is taken by third-party dependencies (react-aria, Radix, Tiptap) |
+| **package**           | The `@olddevs/ui` npm artifact with entry points and `styles.css`; published to npm                                                                                                                                                                                              | The kit: one kit has one package, but the kit is also its decisions, the showcase and the design mockup                                                         |
+| **entry point**       | An import path that the package declares in `exports`: `@olddevs/ui`, `/icons`, `/color`, `/editor`, `/editor/schema`, `/editor/highlight`, `/locales/ru`, `/locales/en`. Anything that is not an entry point is not public API                                                  | A path in `src/`: it can change in any version                                                                                                                  |
+| **public contract**   | The exports of the entry points, their types, the documented behavior and `styles.css`                                                                                                                                                                                           | The sources: they prove behavior, but cannot be imported                                                                                                        |
+| **consumer**          | An application that installs the package and builds its screens from the kit                                                                                                                                                                                                     | A user: they work with a screen, not with the API                                                                                                               |
+| **screen**            | A page or form of the consumer's application. Domain texts, requests, status vocabularies and the screen layout belong to it, not to the kit                                                                                                                                     | A kit component                                                                                                                                                 |
+| **requesting screen** | A consumer screen that needs the component now. A component without one is not taken on, except where ADR-0048 allows it                                                                                                                                                         | The consumer: that is the whole application, while the requesting screen is one of its screens                                                                  |
+| **primitive**         | A kit component that other components and consumer screens are built from: `Toolbar` is the primitive of the Editor's Toolbar. Not replaced by hand-written markup                                                                                                               | A palette primitive: a color token of layer 1                                                                                                                   |
+| **component family**  | Components with one purpose and shared exports (`MobileTabBar` and `MobileTabBarItem`), described on one Reference page                                                                                                                                                          | A color family: a row of palette primitives of one hue                                                                                                          |
+| **category**          | A section of the Reference and a source folder: `actions`, `app-shell`, `content`, `date-time`, `inputs`, `navigation`, `overlays`, `table`. A component lives in the same category in `docs/components/` and in `src/components/`                                               | A component family: a category groups several families                                                                                                          |
+| **core**              | Components that require the full set of checks: behavioral tests, class coverage, axe, snapshots (ADR-0014)                                                                                                                                                                      | The periphery                                                                                                                                                   |
+| **periphery**         | Wrappers over the ready-made behavior of `react-aria-components`: a reduced set of checks is enough for them                                                                                                                                                                     | The core                                                                                                                                                        |
+| **message catalog**   | The kit's interface strings that `UiProvider` passes to components: the ready-made catalogs are the `locales/ru` and `locales/en` entry points; without the provider, an English fallback in code applies. A component prop overrides a string individually ([i18n.md](i18n.md)) | The component catalog. Screen texts: the kit does not translate them                                                                                            |
+| **component catalog** | An index of all public components by category — [components/index.md](components/index.md)                                                                                                                                                                                       | The message catalog                                                                                                                                             |
+
+## Documentation and checks
+
+| Term                  | Meaning                                                                                                                                                                     | Not to be confused with                                                                                                   |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **the Reference**     | Markdown in the package's `docs/`: component, API and convention pages — the source of truth about the public contract. Ships in the package and is shown on the site as is | The wiki: it retells the Reference for people and is wrong when they disagree. ADRs: they explain why a decision was made |
+| **showcase**          | The kit's Storybook: stories, snapshots and accessibility checks; published to GitHub Pages                                                                                 | The documentation site: the showcase is a workshop, not text for a reader                                                 |
+| **snapshot**          | A reference image of a showcase story in `tests-visual/`; taken and compared only locally (ADR-0013)                                                                        | A screenshot for documentation: it checks nothing                                                                         |
+| **gate**              | One automatic check that fails the run: the contrast gate (`npm run contrast`), the i18n gate, `format:check`                                                               | The release checklist: a gate is one check from its list                                                                  |
+| **release checklist** | The full list of checks before a merge and a release — the "Checks" section of `AGENTS.md`. Run locally: CI does not check pushes                                           | A GitHub Actions workflow: it publishes the showcase and the package, but checks nothing                                  |
+| **mirror**            | The Figma file `Olddevs UI DS`: mirrors the kit but is not the source of truth; when they differ, Figma is changed (ADR-0015)                                               | A mockup that code is written from: the only exception is a component that does not exist in code yet                     |
+| **wave**              | A set of changes that was planned and released together; ADRs and comments refer to the wave number                                                                         | A package version: the wave number is unrelated to the release number                                                     |
+
+## Tokens and themes
+
+| Term                  | Meaning                                                                                                                                                                                                         | Not to be confused with                                                    |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| **token layer**       | One of the four steps of the color chain: palette primitives → roles → component tokens → brand. A lower layer knows nothing about a higher one ([theming.md](theming.md#четыре-слоя))                          | An overlay layer: a z-index step                                           |
+| **palette primitive** | A layer 1 token `--od-<family>-<step>`: a color as a value, with no role and no theme. The consumer does not override it                                                                                        | A primitive: a kit component                                               |
+| **color family**      | A row of palette primitives of one hue: the neutrals `slate`, `cloud`, `navy` and seven tone families. Within a family the step number increases with lightness; 1 is the darkest                               | A component family                                                         |
+| **role**              | A layer 2 token: what is painted with what — `--surface-*`, `--text-*`, `--accent*`, tones. A theme changes only roles                                                                                          | A Tailwind class: it is built on a role, not the other way round           |
+| **component token**   | A layer 3 token — how one component family differs from the shared role (`--overlay-scrim`, `--topbar-bg`). The list is closed                                                                                  | A role                                                                     |
+| **theme**             | A set of role values on `<html data-theme>`: `dark` (default), `light`, `dim`                                                                                                                                   | An accent: it is an independent axis. The Editor's Paper                   |
+| **accent**            | The color of action and highlight on `<html data-accent>`: `blue` (default), `violet`                                                                                                                           | The `accent` tone: it takes the accent's value, but it is a component axis |
+| **brand**             | Layer 4: a brand block `[data-brand]` on top of roles and component tokens — the consumer's own palette as a single CSS block                                                                                   | A theme: a brand works in any theme                                        |
+| **surface**           | A background role: `--surface-app`, `--surface-panel`, `--surface-elevated` and the related roles; in components, the aliases `--bg-0…4`                                                                        | The Editor's `surface` prop: it chooses the Paper                          |
+| **inverse surface**   | A group of roles for a pill placed directly on a Document that differs from it by polarity, not by a single step: light in `dark` and `dim`, dark in `light` (`--surface-inverse`, `--text-on-inverse`)         | The `--surface-contrast` surface: it is a step of the same theme           |
+| **tone**              | A semantic color from the `Tone` vocabulary: `neutral`, `accent`, `success`, `warning`, `danger`. A tone has two roles: `--<tone>` is the fill under text, `--<tone>-strong` is text and border on a background | A variant (`variant`): it controls how prominent the tone is               |
+| **density**           | The default vertical rhythm of tables through `UiProvider`: `comfortable` or `compact`; a table prop overrides it                                                                                               | A size (`size`): it is the axis of one component                           |
+| **motion scale**      | Closed duration steps (`--duration-fast` … `--duration-slow`) and three curves (`--ease-standard`, `-enter`, `-exit`). Names by role, not by value (ADR-0047)                                                   | A step of a color family                                                   |
+
+## Prop axes
+
+| Term           | Meaning                                                                                                                                                              | Not to be confused with                                                         |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| **axis**       | An independent prop with a closed set of values shared across the whole kit: `size`, `tone`, `variant`. An axis is turned on by an explicit prop                     | A state (`selected`, `disabled`, `loading`): it is boolean and named positively |
+| **variant**    | The `variant` axis: how prominent the tone is — `solid`, `soft`, `outline`, `ghost`, one set across the kit                                                          | The appearance (`appearance`)                                                   |
+| **appearance** | The `appearance` prop, outside the axes: a different form of the same component — `appearance="card"` adds a border, an indicator and a description inside the label | The variant: it changes how prominent the tone is, not the form                 |
+
+The meaning of each axis and the props outside the axes (`appearance`, `active`, `level`) are in the
+[semantic prop vocabulary](conventions.md#семантический-словарь-пропсов).
+
+## Interaction
+
+The words pages use to describe how a component is operated with a mouse, a finger and the keyboard.
+
+| Term              | Meaning                                                                                                                                     | Not to be confused with                                                                     |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| **hit area**      | The area that accepts a press; it can be larger than the visible control. The lower bound is WCAG 2.5.8, 24 × 24 px                         | Size (`size`): it changes the look, while the hit area can stay the same                    |
+| **drag handle**   | A separate button on a row that moves the row with a mouse, a finger or the keyboard: `SortableList`, `EditableList`                        | The Editor's Block handle and the resize handle                                             |
+| **resize handle** | The strip along the bottom edge of a field with `resizable` that changes its height; from the keyboard it works like a slider               | The drag handle                                                                             |
+| **mask guide**    | The mask that an empty `MaskedInput` shows in full (`__.__.____`) and that input replaces character by character. Decorative: `aria-hidden` | The Editor's Skeleton: the look of the field before Readiness                               |
+| **item**          | One entry of `items` in a collection component: a menu item, a list row, a tree node                                                        | A DOM element: write "element" only for markup                                              |
+| **disabled**      | The `disabled` state: the action cannot be performed now, the control is dimmed and presses do nothing                                      | Read-only (`readOnly`): the value is visible and can be copied, but not changed             |
+| **result set**    | The records left after the filters; the consumer computes it                                                                                | The selection                                                                               |
+| **selection**     | The records the user has checked (`selectedKeys`)                                                                                           | The result set: a filter narrows the result set, the selection is what is checked inside it |
+
+## Layers on top
+
+| Term              | Meaning                                                                                                                                                                                                        | Not to be confused with                                                                          |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| **overlay**       | A kit element on top of the page: dialog, drawer, menu, popover, tooltip, suggestion list                                                                                                                      | A portal: an overlay can also sit in the owner's DOM, like the Editor's floating Toolbar         |
+| **overlay layer** | A named z-index step from `OVERLAY_LAYER`: `modal` — scrim and dialog, `alert` — a confirmation above a dialog, `popover` — menus, popovers, lists. Do not write z-index numbers outside this scale (ADR-0041) | A token layer                                                                                    |
+| **Escape stack**  | The stack of open kit overlays (`src/lib/overlay-layer.ts`), shared by Radix and react-aria overlays: only the top one handles Escape, nested ones close one at a time                                         | An overlay layer: the top of the stack is determined by position in the document, not by z-index |
+
+## Components in prose
+
+How a component is named in prose. Do not use the words listed after "Do not write:": readers
+search for a single word.
+
+| Term                  | Meaning                                                                                                                    | Not to be confused with                                                                                |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| **dialog**            | `Dialog`: a modal surface with a scrim                                                                                     | A drawer. A browser window, which is simply called a "browser window". Do not write: modal             |
+| **drawer**            | `Drawer`: a modal panel that slides in from an edge                                                                        | A dialog. Do not write: sheet, slide-out panel                                                         |
+| **popover**           | `Popover`: a non-modal panel next to the button that opened it                                                             | A tooltip: it has no interactivity. Do not write: popup                                                |
+| **tooltip**           | `Tooltip`: short text on hover and focus                                                                                   | A popover                                                                                              |
+| **hint**              | `hint` on `FormField` and neighboring fields: text under the field that helps to fill it in                                | A tooltip and a placeholder                                                                            |
+| **placeholder**       | `placeholder`: an example value shown in an empty field that disappears on input                                           | A hint and a tooltip                                                                                   |
+| **toast**             | A global notification `toast()` in `Toaster`                                                                               | The Editor's Field notice: it is tied to a field                                                       |
+| **checkbox**          | `Checkbox`: a yes/no choice within a set                                                                                   | The `Toggle` switch (`role="switch"`): one boolean property, not a choice within a set                 |
+| **table bar**         | The `toolbar` slot of `DataTable`, usually `TableToolbar`                                                                  | The Editor's Toolbar and the `Toolbar` primitive. Do not write: toolbar                                |
+| **menu trigger**      | The button that opens a menu: the right part of `SplitButton`, the `Menu` button                                           | A popover: that is the panel that opened. Do not write: disclosure                                     |
+| **segmented control** | `Segmented`: a row of buttons of which exactly one is selected                                                             | `Tabs` (they switch panels) and `ToggleGroup` (zero or more selected)                                  |
+| **tag**               | `Tag` in `TagGroup` and `TagInput`: a compact element with text and an optional remove button                              | The Editor's Mark and a field label                                                                    |
+| **close button**      | The button with an "×" that closes a dialog, drawer, popover or notification; in a search field it is the **clear button** | A "Cancel" button. Do not write: cross                                                                 |
+| **shortcut list**     | `ShortcutsHelp`: a dialog with a list of keyboard shortcuts                                                                | The Editor's Shortcuts reference: that one opens from the Toolbar and describes the Editor's shortcuts |
+
+## Editor
+
+Terms of `RichTextEditor` and `RichTextView` (the `@olddevs/ui/editor` entry point). Here it is
+especially easy to borrow a word from a neighboring editor (plugin, service, node) — and that
+introduces a second meaning.
+
+| Term                     | Meaning                                                                                                                                                                                                                                                                                                                                                        | Not to be confused with                                                                                                                                                       |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Editor**               | `RichTextEditor` — a rich text input field                                                                                                                                                                                                                                                                                                                     | A code editor: the kit has none, code is displayed with `CodeView`                                                                                                            |
+| **View**                 | `RichTextView` — read-only display of a saved Document                                                                                                                                                                                                                                                                                                         | The Editor's `readOnly` mode: that one carries the engine, the View does not                                                                                                  |
+| **Document**             | The Editor's value: an HTML string constrained by the Schema                                                                                                                                                                                                                                                                                                   | The ProseMirror JSON tree in the engine — it is internal; it comes out only as a JSON envelope                                                                                |
+| **JSON envelope**        | A Document as JSON for a file and a template: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), lossless and through the Schema                                                                                                                                                                                      | The Editor's value — the value stays HTML; the bare tree `editor.getJSON()` without an envelope                                                                               |
+| **Schema**               | An allowlist of Blocks, Marks and attributes that the Editor accepts and returns                                                                                                                                                                                                                                                                               | Server-side sanitization — the consumer does it (`sanitizeRichText`)                                                                                                          |
+| **Block**                | A structural element of a Document: paragraph, heading, list, table, image…                                                                                                                                                                                                                                                                                    | A Mark                                                                                                                                                                        |
+| **Mark**                 | Inline formatting inside a Block: bold, link, color…                                                                                                                                                                                                                                                                                                           | A Block                                                                                                                                                                       |
+| **Atom**                 | A Block or inline element that is selected, moved and deleted as a whole: an image (the caption inside it is editable), a divider, a soft break, a mention. Always makes the field non-empty                                                                                                                                                                   | An empty Block: a paragraph without text is not an Atom and does not count as content                                                                                         |
+| **Atom text**            | The string that represents an Atom in the Document's text: `getText` and `getSelectedText` return it, its length is the Atom's weight in `maxLength`, and it is how the Atom is exported to Markdown without rules of its own. For an image it is the caption text, for a divider an empty string                                                              | A Block attribute                                                                                                                                                             |
+| **Layout**               | A Block of columns (the `layout` Tool): six variants — from one to four equal columns, 60/40 and 40/60. Top level only, does not nest into itself; a column for its Blocks is the same as a Document                                                                                                                                                           | A table: it has data rows and cells, while the columns of a Layout are the Document's page structure. The kit's `Grid`: a screen grid, not a Block                            |
+| **Wrapper**              | A Block that gathers a group of Blocks (the `wrapper` Tool, a `div` with `data-block="wrapper"`): they are moved, duplicated and deleted as one Block. Without a Wrapper tone it has no look of its own — the dashed outline exists only in the Editor. Neither a Wrapper nor a Layout nests into a Wrapper                                                    | A quote: it has its own look and meaning in the Document, while a Wrapper without a tone is only grouping                                                                     |
+| **Wrapper tone**         | The styling of a Wrapper as a note (`data-tone`): a background and a stripe on the left in one of five tones of the `Tone` vocabulary — "Note", "Tip", "Important", "Warning", "Caution". Chosen in the "Tone ›" item of the Block handle, the same in the Editor and the View, exported to Markdown as a GitHub alert (what GitHub and Notion call a callout) | The tone of a Field notice (`status` or `error`). Meaning: the tone carries no roles or `aria-*`; the meaning of a note is written as a word in the text                      |
+| **Toolbar**              | A set of formatting buttons; its look is set by `toolbar`. **Fixed** (`fixed`, the default) — above the field, sticks on scroll; **floating** (`floating`) — the same buttons above a non-empty selection. With `bubble` there is no Toolbar — the Selection menu takes its place, with `none` there is neither. On a touch screen the Toolbar is always fixed | The kit's `Toolbar` — the primitive that the Toolbar is built from                                                                                                            |
+| **Insert menu**          | The "Insert" and "Turn into" list: opens on `/` in the text and on the "+" button                                                                                                                                                                                                                                                                              | The browser context menu                                                                                                                                                      |
+| **Selection menu**       | A compact pill on an inverse surface above a non-empty selection: "¶", lists, bold, italic, underline, color, "…", link, emoji; its contents are fixed by the kit. Appears in place of the Toolbar with `toolbar="bubble"` and on top of the fixed Toolbar — there `selectionMenu={false}` turns it off. Absent on a touch screen                              | The floating Toolbar: it has the full set of buttons                                                                                                                          |
+| **Block handle**         | The "⋮" on the Block that holds the caret, and its menu of actions on the whole Block: "Add ›", "Format ›", "Move up", "Move down", "Duplicate", "Delete"                                                                                                                                                                                                      | The Toolbar: it works with the selection, not with a Block                                                                                                                    |
+| **Insert item**          | A row of the Insert menu: inserts a Block or turns the current one into another. One item is visible on `/`, on "+" and in the Block handle                                                                                                                                                                                                                    | A Toolbar button                                                                                                                                                              |
+| **Block action**         | An item of the Block handle menu that works with the whole Block, for example "Duplicate"                                                                                                                                                                                                                                                                      | A button: it works with the selection                                                                                                                                         |
+| **Shortcuts reference**  | A read-only "command — shortcut" popover behind the last button of the fixed Toolbar. The rows are the commands of the enabled Tools, including custom ones; on a phone there is no button                                                                                                                                                                     | The kit's `CommandPalette`: the rows of the Shortcuts reference are not clickable. The kit's `ShortcutsHelp`: it lists screen shortcuts, not Editor ones                      |
+| **HTML mode**            | The mode of the `source` Tool: the "HTML" button on the fixed Toolbar replaces the Document with a field holding its HTML. The field text passes through the Schema and becomes the Document in a single edit — on leaving the mode, on `blur`, on form submit and on reading through the Handle                                                               | The HTML convention: that is the form of custom content in a Document, not a mode. `CodeView`: it displays code, while the HTML field is editable                             |
+| **Glass**                | A semi-transparent background that blurs what is behind it on everything the Editor shows above the Document: the floating Toolbar, the Selection menu, menus, popovers, the Text card. The color is the token of its own surface; with `prefers-reduced-transparency`, `prefers-contrast: more` and on iOS the background is solid                            | The kit's `Menu` and `Popover` outside the Editor: they stay solid                                                                                                            |
+| **UI contribution**      | A UI element of a custom Tool, described as data: a button, an Insert item, a Block action or a Text card. The kit renders it in a Slot; a disabled Tool removes its UI contributions as well                                                                                                                                                                  | A React node in the interface: arbitrary React is allowed only inside the content of a button popover and a Text card                                                         |
+| **Slot**                 | One place on a surface where the UI contributions of custom Tools appear, in `tools` order: the Toolbar group before "Undo", the end of an Insert menu section, the Block handle section before "Delete"                                                                                                                                                       | A position relative to a built-in button: the ids of built-ins are not public API                                                                                             |
+| **Preset**               | A ready-made set of built-in Tools: `full` or `basic` (`RICH_TEXT_PRESETS`). Not a frozen list: a new built-in arrives in it in a minor version                                                                                                                                                                                                                | An exact `tools` list: only the screen changes its composition                                                                                                                |
+| **Tool**                 | One capability of the Editor: its Blocks and Marks, their rules in the Schema and their place in the UI, for example `table`. A built-in one is set by name, a custom one by a description                                                                                                                                                                     | A button: disabling a Tool also removes its Block from the Schema. A Redactor plugin: that is a class of behavior over the DOM without a Schema                               |
+| **custom Tool**          | A Tool that the consumer describes (`CustomTool`): Schema rules as data, an Engine part and UI contributions. Passed in `tools` mixed in with the kit's names                                                                                                                                                                                                  | The kit's internal description: that is a superset of the public shape for built-ins and is not exported                                                                      |
+| **Consumer prefix**      | The start of the name of everything custom — a Tool, its Blocks, Marks and attributes — up to the underscore: `acme_mergeTag`, `data-acme_size`. Kit names have no underscore, so custom names and built-in ones never collide, either in a set or in a Document                                                                                               | A Preset: that is a set of built-in Tools, not a namespace                                                                                                                    |
+| **HTML convention**      | The form of custom content in a Document: a Block is a `div` or `span` with `data-block`, a Mark is a `span` with `data-mark`, attributes are `data-<prefix>_<name>`. Frozen: extended only by adding                                                                                                                                                          | The kit's Schema tags (`p`, `table`, `img`): a custom Block cannot take them                                                                                                  |
+| **Block trait**          | A Block property that only the kit understands, not the engine: "container" (children get their own handle), "can be turned into", "Atom without a formatting menu"                                                                                                                                                                                            | A Block attribute: that one is stored in the Document                                                                                                                         |
+| **Engine part**          | The part of a Tool description needed only by the live Editor: Tiptap extensions and the node view. Supplied immediately or through a Loader                                                                                                                                                                                                                   | Schema rules: those are data, read by the server and the View without an engine                                                                                               |
+| **Loader**               | A function with a dynamic import in place of the Engine part: `engine: () => import(…)`. The heavy built-ins outside `basic` load the same way — the code Block and the table                                                                                                                                                                                  | Preloading (`modulepreload`): the kit does not publish it, the consumer sets it up                                                                                            |
+| **Handle**               | Imperative access from screen code to the Editor through `ref`: insert at the caret, read, focus, history                                                                                                                                                                                                                                                      | Redactor services: those are engine internals, not screen API                                                                                                                 |
+| **Readiness**            | The moment when the engine is created and the Loaders of all enabled Tools, custom and built-in, have finished: from then on Handle methods take effect instead of doing nothing. Happens once per mount; `onReady` reports it                                                                                                                                 | Hydration: after it the engine may still be waiting for Loaders                                                                                                               |
+| **Field focus**          | Focus inside the Editor as a whole: the Document, the Toolbar, the kit's popovers, the HTML field. Moving between them does not lose Field focus; `onFocus` and `onBlur` are about it                                                                                                                                                                          | Document focus (the engine's `focus` and `blur`): a click in the Toolbar removes it                                                                                           |
+| **Author edit**          | A change to the Document equal to typing on a keyboard: a history step, `onChange` after a delay, the character limit applies. This also covers insert, undo and redo from the Handle                                                                                                                                                                          | An External replacement                                                                                                                                                       |
+| **External replacement** | Replacing the whole Document (`value`, `clear()`, `setMarkdown()`, `setJSON()`): the character limit does not truncate it; `onChange` fires immediately for `clear()`, `setMarkdown()` and `setJSON()`, but not for a new `value`                                                                                                                              | An Author edit                                                                                                                                                                |
+| **Skeleton**             | The Editor's look before Readiness: the field frame, a placeholder for the Toolbar and a Document: sanitized by the Schema, it is rendered as static HTML with the same class and rhythm as the engine's Document, without input. On the server — the frame without a Document. A Loader failure turns the Skeleton into a field error with "Retry"            | The View: that is a separate read-only component, while the Skeleton is a state of the Editor that the engine replaces. The kit's `Skeleton` component: a loading placeholder |
+| **Status line**          | A line inside the field frame under the Document: on the left the screen's content (`status`: word count, "Saved", co-author), on the right the kit's character counter                                                                                                                                                                                        | A Field notice: the line shows a lasting state of the screen, not an event                                                                                                    |
+| **Field notice**         | One event tied to the field (`showNotice`): tone `status` (only announced) or `error` (a visible line under the field until the next Author edit). A new one replaces the previous one                                                                                                                                                                         | The kit's toast: that one is global and not tied to a field                                                                                                                   |
+| **Text card**            | A non-modal card under a range of the Document, declared by a custom Tool (`textCards`): a comment, a hint from checking the text. Opens when the caret enters it or on click, focus stays in the text                                                                                                                                                         | A button popover: a button opens that one, while a Text card is opened by a place in the Document                                                                             |
+| **Trigger character**    | A character of a custom Tool (`trigger`) that opens a list of items at the caret when typed at the start of a Block or after a space, like `/`: `@` for mentions, `#` for tags. Picking an item replaces the typed `@query` with a custom node                                                                                                                 | The Insert menu on `/`: that one is built in, while a custom character is set by a Tool                                                                                       |
+| **Paper**                | A light area of the Document in any app theme (`surface="paper"`) — for text that leaves the app on a light background: an email, print, PDF. The Toolbar, menus and field frame stay in the app theme; the View with the same `surface` shows the same Paper                                                                                                  | The `light` theme: it changes the whole app, the Paper only the Document                                                                                                      |
+| **Island**               | A client-side piece of the View that, after mounting, brings a Block in already rendered HTML to life: the "Copy" button on a code Block, the `island` of a custom Block                                                                                                                                                                                       | A node view: it lives only in the Editor engine                                                                                                                               |
+| **Mount point**          | A place in already rendered HTML where an Island mounts a live element: the code Block header that receives the "Copy" button                                                                                                                                                                                                                                  | A Slot: that is a place in the Editor UI for the UI contributions of Tools                                                                                                    |

package/docs/glossary.md

@@ -0,0 +1,174 @@
+# Словарь `@olddevs/ui`
+
+Термины кита. Одно понятие — одно слово: синоним из соседней системы (плагин, сервис, нода,
+библиотека) заводит второй смысл, и разойдутся они молча. Если у слова два смысла, оба
+получают составное имя («примитив палитры», «слой оверлея»), а голое слово остаётся за одним
+из них.
+
+Общие термины в тексте пишутся как обычные слова, со строчной: «потребитель», «роль»,
+«витрина». Термины Редактора — с большой буквы («Блок», «Панель»): их легко спутать с
+обиходным словом, и заглавная показывает, что слово значит ровно то, что в таблице.
+
+Новый термин попадает сюда в том же изменении, где появился. Словарь лежит в пакете, а не в
+репозитории документации, потому что меняется вместе с кодом; сайт документации показывает
+его из закреплённой версии кита.
+
+Имена пропсов — отдельный словарь:
+[семантический словарь пропсов](conventions.md#семантический-словарь-пропсов).
+
+## Кит и потребитель
+
+| Термин                  | Значение                                                                                                                                                                                                                                    | Не путать с                                                                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Кит**                 | Дизайн-система `@olddevs/ui`: токены, темы, доступные компоненты и их документация                                                                                                                                                          | Пакетом: тот — то, как кит доставляется. Библиотекой: так кит не называется, слово занято сторонними зависимостями (react-aria, Radix, Tiptap) |
+| **Пакет**               | npm-артефакт `@olddevs/ui` со входами и `styles.css`; публикуется в npm                                                                                                                                                                     | Китом: у одного кита один пакет, но кит — ещё и решения, витрина и макет                                                                       |
+| **Вход**                | Путь импорта, который пакет объявляет в `exports`: `@olddevs/ui`, `/icons`, `/color`, `/editor`, `/editor/schema`, `/editor/highlight`, `/locales/ru`, `/locales/en`. Всё, что не вход, — не публичный API                                  | Путём в `src/`: он может смениться в любой версии                                                                                              |
+| **Публичный контракт**  | Экспорты входов, их типы, документированное поведение и `styles.css`                                                                                                                                                                        | Исходниками: они доказывают поведение, но импортировать их нельзя                                                                              |
+| **Потребитель**         | Приложение, которое ставит пакет и собирает из кита свои экраны                                                                                                                                                                             | Пользователем: тот работает с экраном, а не с API                                                                                              |
+| **Экран**               | Страница или форма приложения потребителя. Доменные тексты, запросы, словари статусов и раскладка экрана принадлежат ему, а не киту                                                                                                         | Компонентом кита                                                                                                                               |
+| **Экран-заказчик**      | Экран потребителя, которому компонент нужен сейчас. Компонент без него в работу не берут, кроме отступлений из ADR-0048; в тексте коротко — «заказчик»                                                                                      | Потребителем: тот — приложение целиком, а заказчик — один его экран                                                                            |
+| **Примитив**            | Компонент кита, из которого собраны другие и экраны потребителя: `Toolbar` — примитив Панели Редактора. Не заменяется ручной разметкой                                                                                                      | Примитивом палитры — цветовым токеном слоя 1                                                                                                   |
+| **Семья компонентов**   | Компоненты одного назначения с общими экспортами (`MobileTabBar` и `MobileTabBarItem`), описанные на одной странице справочника                                                                                                             | Семьёй цвета — рядом примитивов палитры одного оттенка                                                                                         |
+| **Категория**           | Раздел справочника и папка исходников: `actions`, `app-shell`, `content`, `date-time`, `inputs`, `navigation`, `overlays`, `table`. Компонент лежит в той же категории в `docs/components/` и в `src/components/`                           | Семьёй компонентов: категория собирает несколько семей                                                                                         |
+| **Ядро**                | Компоненты, для которых обязателен полный обряд проверки: поведенческие тесты, покрытие классов, axe, снимки (ADR-0014)                                                                                                                     | Периферией                                                                                                                                     |
+| **Периферия**           | Обёртки над готовым поведением `react-aria-components`: для них хватает сокращённого набора проверок                                                                                                                                        | Ядром                                                                                                                                          |
+| **Каталог сообщений**   | Строки интерфейса кита, которые `UiProvider` отдаёт компонентам: готовые каталоги — входы `locales/ru` и `locales/en`, без провайдера работает английский фолбэк в коде. Проп компонента переопределяет строку точечно ([i18n.md](i18n.md)) | Каталогом компонентов. Текстами экрана: их кит не переводит                                                                                    |
+| **Каталог компонентов** | Указатель всех публичных компонентов по категориям — [components/index.md](components/index.md)                                                                                                                                             | Каталогом сообщений                                                                                                                            |
+
+## Документация и проверка
+
+| Термин         | Значение                                                                                                                                                    | Не путать с                                                                                      |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| **Справочник** | Markdown в `docs/` пакета: страницы компонентов, API и соглашения — источник правды о публичном контракте. Едет в пакете и показывается на сайте без правок | Вики: та пересказывает для людей и при расхождении неправа. ADR: те объясняют, почему так решено |
+| **Витрина**    | Storybook кита: истории, снимки и проверки доступности; публикуется на GitHub Pages                                                                         | Сайтом документации: витрина — мастерская, а не текст для читателя                               |
+| **Снимок**     | Эталонная картинка истории витрины в `tests-visual/`; снимается и сверяется только локально (ADR-0013)                                                      | Скриншотом для документации: он ничего не проверяет                                              |
+| **Гейт**       | Одна автоматическая проверка, которая роняет прогон: гейт контраста (`npm run contrast`), гейт i18n, `format:check`                                         | Воротами: гейт — одна проверка из их списка                                                      |
+| **Ворота**     | Полный список проверок перед слиянием и релизом — раздел «Checks» в `AGENTS.md`. Запускаются локально: CI пуши не проверяет                                 | Воркфлоу GitHub Actions: те публикуют витрину и пакет, но не проверяет                           |
+| **Зеркало**    | Файл Figma `Olddevs UI DS`: повторяет кит, но источником правды не является; при расхождении меняется Figma (ADR-0015)                                      | Макетом, по которому пишут код: исключение — только компонент, которого в коде ещё нет           |
+| **Волна**      | Набор изменений, который планировался и выпускался вместе; ADR и комментарии ссылаются на номер волны                                                       | Версией пакета: номер волны с номером релиза не связан                                           |
+
+## Токены и темы
+
+| Термин                    | Значение                                                                                                                                                                          | Не путать с                                                       |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| **Слой токенов**          | Одна из четырёх ступеней цепочки цвета: примитивы палитры → роли → компонентные токены → бренд. Слой ниже не знает о слое выше ([theming.md](theming.md#четыре-слоя))             | Слоем оверлея — ступенью z-index                                  |
+| **Примитив палитры**      | Токен слоя 1 `--od-<семья>-<шаг>`: цвет как значение, без роли и без темы. Потребитель его не переопределяет                                                                      | Примитивом — компонентом кита                                     |
+| **Семья цвета**           | Ряд примитивов палитры одного оттенка: нейтрали `slate`, `cloud`, `navy` и семь тоновых. Шаг внутри семьи растёт по светлоте, 1 — самый тёмный                                    | Семьёй компонентов                                                |
+| **Роль**                  | Токен слоя 2: что чем красится — `--surface-*`, `--text-*`, `--accent*`, тона. Тема меняет только роли                                                                            | Классом Tailwind: тот стоит на роли, а не наоборот                |
+| **Компонентный токен**    | Токен слоя 3 — отличие одной семьи компонентов от общей роли (`--overlay-scrim`, `--topbar-bg`). Список закрытый                                                                  | Ролью                                                             |
+| **Тема**                  | Набор значений ролей на `<html data-theme>`: `dark` (по умолчанию), `light`, `dim`                                                                                                | Акцентом: это независимая ось. Листом Редактора                   |
+| **Акцент**                | Цвет действия и выделения на `<html data-accent>`: `blue` (по умолчанию), `violet`                                                                                                | Тоном `accent`: тот берёт значение акцента, но это ось компонента |
+| **Бренд**                 | Слой 4: блок бренда `[data-brand]` поверх ролей и компонентных токенов — своя палитра потребителя одним блоком CSS                                                                | Темой: бренд работает в любой теме                                |
+| **Поверхность**           | Роль фона: `--surface-app`, `--surface-panel`, `--surface-elevated` и соседние; в компонентах — алиасы `--bg-0…4`                                                                 | Пропом `surface` Редактора: тот выбирает Лист                     |
+| **Инверсная поверхность** | Группа ролей для плашки прямо на Документе, которая отличается от него знаком, а не шагом: светлая в `dark` и `dim`, тёмная в `light` (`--surface-inverse`, `--text-on-inverse`)  | Поверхностью `--surface-contrast`: та — шаг той же темы           |
+| **Тон**                   | Смысловой цвет из словаря `Tone`: `neutral`, `accent`, `success`, `warning`, `danger`. У тона две роли: `--<тон>` — заливка под текстом, `--<тон>-strong` — текст и рамка на фоне | Вариантом (`variant`): тот отвечает, насколько тон заметен        |
+| **Плотность**             | Умолчание вертикального ритма таблиц через `UiProvider`: `comfortable` или `compact`; проп таблицы его перекрывает                                                                | Размером (`size`): тот — ось одного компонента                    |
+| **Шкала движения**        | Закрытые ступени длительности (`--duration-fast` … `--duration-slow`) и три кривые (`--ease-standard`, `-enter`, `-exit`). Имена по роли, а не по значению (ADR-0047)             | Шагом семьи цвета                                                 |
+
+## Оси пропсов
+
+| Термин             | Значение                                                                                                                          | Не путать с                                                                          |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **Ось**            | Независимый проп с закрытым набором значений, общим на весь кит: `size`, `tone`, `variant`. Ось включается явным пропом           | Состоянием (`selected`, `disabled`, `loading`): оно булево и называется положительно |
+| **Подача**         | Ось `variant`: насколько заметен тон — `solid`, `soft`, `outline`, `ghost`, один набор на весь кит                                | Формой варианта (`appearance`)                                                       |
+| **Форма варианта** | Проп `appearance` вне осей: другая форма того же компонента — `appearance="card"` даёт рамку, индикатор и описание внутри подписи | Подачей: та меняет заметность тона, а не форму                                       |
+
+Смысл каждой оси и пропсы вне осей (`appearance`, `active`, `level`) — в
+[семантическом словаре пропсов](conventions.md#семантический-словарь-пропсов).
+
+## Взаимодействие
+
+Слова, которыми страницы описывают, как компонентом управляют мышью, пальцем и клавиатурой.
+
+| Термин                   | Значение                                                                                                                                        | Не путать с                                                                 |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| **Зона нажатия**         | Область, которая принимает нажатие; бывает больше видимого контрола. Нижний порог — WCAG 2.5.8, 24 × 24 px                                      | Размером (`size`): тот меняет вид, а зона может остаться прежней            |
+| **Ручка перетаскивания** | Отдельная кнопка строки, за которую строку переносят мышью, пальцем или с клавиатуры: `SortableList`, `EditableList`                            | Ручкой Блока Редактора и ручкой высоты                                      |
+| **Ручка высоты**         | Полоса у нижнего края поля с `resizable`, за которую меняют его высоту; с клавиатуры — как ползунок                                             | Ручкой перетаскивания                                                       |
+| **Трафарет маски**       | Маска, которую пустое поле `MaskedInput` показывает целиком (`__.__.____`) и которую ввод заменяет символ за символом. Украшение: `aria-hidden` | Скелетом Редактора — видом поля до Готовности                               |
+| **Элемент коллекции**    | Одна запись `items` у компонента-коллекции: пункт меню, строка списка, узел дерева                                                              | Элементом разметки (DOM): так и пишем — «элемент разметки»                  |
+| **Недоступный**          | Состояние `disabled`: действие сейчас выполнить нельзя, контрол приглушён и нажатие не срабатывает                                              | Только для чтения (`readOnly`): значение видно и копируется, но не меняется |
+| **Выборка**              | Записи, которые остались после фильтров; считает её потребитель                                                                                 | Выделением                                                                  |
+| **Выделение**            | Записи, которые отметил пользователь (`selectedKeys`)                                                                                           | Выборкой: фильтр сужает выборку, а выделение — то, что отмечено внутри неё  |
+
+## Слои поверх
+
+| Термин           | Значение                                                                                                                                                                                               | Не путать с                                                                      |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| **Оверлей**      | Элемент кита поверх страницы: окно, ящик, меню, поповер, подсказка, список подсказок                                                                                                                   | Порталом: оверлей может лежать и в DOM владельца, как плавающая Панель Редактора |
+| **Слой оверлея** | Именованная ступень z-index из `OVERLAY_LAYER`: `modal` — затемнение и окно, `alert` — подтверждение над окном, `popover` — меню, поповеры, списки. Числа z-index вне этой шкалы не пишутся (ADR-0041) | Слоем токенов                                                                    |
+| **Стек Escape**  | Стек открытых оверлеев кита (`src/lib/overlay-layer.ts`), общий для оверлеев на Radix и на react-aria: Escape обрабатывает только верхний, вложенные закрываются по одному                             | Слоем оверлея: верхний в стеке определяется положением в документе, а не z-index |
+
+## Компоненты в тексте
+
+Как компонент называется по-русски в прозе. Слова после «Не пишем:» в тексте не употребляются: читатель
+ищет по одному слову.
+
+| Термин                     | Значение                                                                                                        | Не путать с                                                                                             |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| **Окно**                   | `Dialog`: модальная поверхность с затемнением                                                                   | Ящиком. Окном браузера — его так и называем: «окно браузера». Не пишем: модалка                         |
+| **Ящик**                   | `Drawer`: модальная панель, которая выезжает от края                                                            | Окном. Не пишем: шторка, выдвижная панель                                                               |
+| **Поповер**                | `Popover`: немодальная панель у кнопки, которая её открыла                                                      | Подсказкой: в той нет интерактива. Не пишем: попап                                                      |
+| **Подсказка**              | `Tooltip`: короткий текст при наведении и фокусе                                                                | Поповером. Не пишем: тултип                                                                             |
+| **Пояснение**              | `hint` у `FormField` и соседних полей: текст под полем, который помогает его заполнить                          | Подсказкой (`Tooltip`) и плейсхолдером. Не пишем: подсказка поля                                        |
+| **Плейсхолдер**            | `placeholder`: пример значения, который виден в пустом поле и исчезает при вводе                                | Пояснением и подсказкой. Не пишем: подсказка в поле                                                     |
+| **Тост**                   | Глобальное уведомление `toast()` в `Toaster`                                                                    | Сообщением поля Редактора: то привязано к полю                                                          |
+| **Флажок**                 | `Checkbox`: выбор «да / нет» в наборе                                                                           | Переключателем `Toggle` (`role="switch"`): одно булево свойство, а не выбор в наборе. Не пишем: чекбокс |
+| **Полоса над таблицей**    | Слот `toolbar` у `DataTable`, обычно `TableToolbar`                                                             | Панелью Редактора и примитивом `Toolbar`. Не пишем: тулбар                                              |
+| **Раскрыватель**           | Кнопка, которая раскрывает меню: правая часть `SplitButton`, кнопка `Menu`                                      | Поповером: тот — сама раскрывшаяся панель. Не пишем: disclosure, стрелка-меню                           |
+| **Сегментированный выбор** | `Segmented`: ряд кнопок, из которых выбрана ровно одна                                                          | Вкладками `Tabs` (те переключают панели) и `ToggleGroup` (там выбрано ноль или несколько)               |
+| **Тег**                    | `Tag` в `TagGroup` и `TagInput`: компактный элемент с текстом и необязательной кнопкой удаления                 | Меткой Редактора (`Mark`) и подписью поля. Не пишем: таг                                                |
+| **Кнопка закрытия**        | Кнопка с иконкой «×», которая закрывает окно, ящик, поповер или уведомление; у поля поиска — **кнопка очистки** | Кнопкой «Отмена». Не пишем: крестик                                                                     |
+| **Свод сочетаний**         | `ShortcutsHelp`: окно со списком сочетаний клавиш                                                               | Справочником Редактора: тот открывается из Панели и описывает сочетания Редактора                       |
+
+## Редактор
+
+Термины `RichTextEditor` и `RichTextView` (вход `@olddevs/ui/editor`). Здесь особенно легко
+взять слово из соседнего редактора (плагин, сервис, нода) — оно заводит второй смысл.
+
+| Термин                   | Значение                                                                                                                                                                                                                                                                                                                                           | Не путать с                                                                                                                                                          |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Редактор**             | `RichTextEditor` — поле ввода форматированного текста                                                                                                                                                                                                                                                                                              | Редактором кода: его в ките нет, показ кода — `CodeView`                                                                                                             |
+| **Просмотр**             | `RichTextView` — только чтение сохранённого Документа                                                                                                                                                                                                                                                                                              | `readOnly`-режимом Редактора: тот держит движок, Просмотр — нет                                                                                                      |
+| **Документ**             | Значение Редактора: HTML-строка, ограниченная Схемой                                                                                                                                                                                                                                                                                               | JSON-деревом ProseMirror в движке — оно внутреннее; наружу оно выходит только JSON-конвертом                                                                         |
+| **JSON-конверт**         | Документ как JSON для файла и шаблона: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), без потерь и через Схему                                                                                                                                                                                        | Значением Редактора — значение остаётся HTML; голым деревом `editor.getJSON()` без конверта                                                                          |
+| **Схема**                | Белый список Блоков, Меток и атрибутов, которые Редактор принимает и отдаёт                                                                                                                                                                                                                                                                        | Санитизацией на сервере — её делает потребитель (`sanitizeRichText`)                                                                                                 |
+| **Блок**                 | Структурный элемент Документа: абзац, заголовок, список, таблица, картинка…                                                                                                                                                                                                                                                                        | Меткой                                                                                                                                                               |
+| **Метка**                | Строчное форматирование внутри Блока: жирный, ссылка, цвет…                                                                                                                                                                                                                                                                                        | Блоком                                                                                                                                                               |
+| **Атом**                 | Блок или строчный элемент, который выделяется, переносится и удаляется целиком: картинка (подпись внутри неё правится), разделитель, мягкий перенос, упоминание. Всегда делает поле непустым                                                                                                                                                       | Пустым Блоком: абзац без текста — не Атом и содержимым не считается                                                                                                  |
+| **Текст атома**          | Строка, которой Атом представлен в тексте Документа: её отдают `getText` и `getSelectedText`, её длина — вес Атома в `maxLength`, ею Атом выгружается в Markdown без своих правил. У картинки — текст подписи, у разделителя — пустая строка                                                                                                       | Атрибутом Блока                                                                                                                                                      |
+| **Раскладка**            | Блок из колонок (Инструмент `layout`): шесть вариантов — от одной до четырёх равных колонок, 60/40 и 40/60. Только верхнего уровня, в себя не вкладывается; колонка для своих Блоков — то же, что Документ                                                                                                                                         | Таблицей: у той строки и ячейки данных, а колонки Раскладки — вёрстка Документа. `Grid` кита — сеткой экрана, а не Блоком                                            |
+| **Обёртка**              | Блок, который собирает группу Блоков (Инструмент `wrapper`, `div` с `data-block="wrapper"`): их двигают, дублируют и удаляют одним Блоком. Без Тона Обёртки своего вида нет — пунктир только в Редакторе. Обёртка и Раскладка в Обёртку не вкладываются                                                                                            | Цитатой: у той свой вид и смысл в Документе, а Обёртка без тона — только группировка                                                                                 |
+| **Тон Обёртки**          | Оформление Обёртки заметкой (`data-tone`): фон и полоса слева одного из пяти тонов словаря `Tone` — «Заметка», «Совет», «Важно», «Внимание», «Осторожно». Выбирается в «Тон ›» Ручки Блока, одинаков в Редакторе и Просмотре, в Markdown выгружается GitHub alert (то, что GitHub и Notion называют callout)                                       | Тоном Сообщения поля (`status` или `error`). Смыслом: ролей и `aria-*` тон не несёт, смысл заметки пишется словом в тексте                                           |
+| **Панель**               | Набор кнопок форматирования; вид задаёт `toolbar`. **Фиксированная** (`fixed`, по умолчанию) — над полем, липнет при прокрутке; **плавающая** (`floating`) — те же кнопки над непустым выделением. При `bubble` Панели нет — её место занимает Меню выделения, при `none` нет ни того, ни другого. На сенсорном экране Панель всегда фиксированная | `Toolbar` кита — Примитивом, из которого Панель собрана                                                                                                              |
+| **Меню вставки**         | Список «Добавить» и «Превратить в»: открывается по `/` в тексте и по кнопке «+»                                                                                                                                                                                                                                                                    | Контекстным меню браузера                                                                                                                                            |
+| **Меню выделения**       | Компактная плашка на инверсной поверхности над непустым выделением: «¶», списки, жирный, курсив, подчёркнутый, цвет, «…», ссылка, эмодзи; состав задан китом. Стоит вместо Панели при `toolbar="bubble"` и поверх фиксированной Панели — там её выключает `selectionMenu={false}`. На сенсорном экране её нет                                      | Плавающей Панелью: у той полный набор кнопок                                                                                                                         |
+| **Ручка Блока**          | «⋮» у Блока с кареткой и её меню действий над Блоком целиком: «Добавить ›», «Формат ›», «Вверх», «Вниз», «Дублировать», «Удалить»                                                                                                                                                                                                                  | Панелью: та работает с выделением, а не с Блоком                                                                                                                     |
+| **Пункт вставки**        | Строка Меню вставки: вставляет Блок или превращает текущий. Один пункт виден и по `/`, и по «+», и в Ручке Блока                                                                                                                                                                                                                                   | Кнопкой Панели                                                                                                                                                       |
+| **Действие над Блоком**  | Пункт меню Ручки Блока, который работает с Блоком целиком, например «Дублировать»                                                                                                                                                                                                                                                                  | Кнопкой: та работает с выделением                                                                                                                                    |
+| **Справочник сочетаний** | Поповер «команда — сочетание» только для чтения за последней кнопкой фиксированной Панели. Строки — команды включённых Инструментов, своих тоже; на телефоне кнопки нет                                                                                                                                                                            | `CommandPalette` кита: строки Справочника сочетаний не нажимаются. `ShortcutsHelp` кита: тот — сочетания экрана, а не Редактора                                      |
+| **HTML-режим**           | Режим Инструмента `source`: кнопка «HTML» на фиксированной Панели заменяет Документ полем с его HTML. Текст поля проходит Схему и становится Документом одной правкой — при выходе из режима, `blur`, отправке формы и чтении через Хэндл                                                                                                          | HTML-соглашением: то — форма своего в Документе, а не режим. `CodeView`: тот показывает код, а поле HTML правится                                                    |
+| **Стекло**               | Полупрозрачная заливка с размытием фона у всего, что Редактор показывает поверх Документа: плавающая Панель, Меню выделения, меню, поповеры, Карточка у текста. Цвет — токен своей поверхности; при `prefers-reduced-transparency`, `prefers-contrast: more` и на iOS заливка сплошная                                                             | `Menu` и `Popover` кита вне Редактора: те остаются сплошными                                                                                                         |
+| **UI-запись**            | Элемент интерфейса своего Инструмента, описанный данными: кнопка, Пункт вставки, Действие над Блоком или Карточка у текста. Рисует её кит в Отведённом месте; выключенный Инструмент убирает и свои записи                                                                                                                                         | React-узлом в интерфейсе: произвольный React допускается только в содержимом поповера кнопки и Карточки у текста                                                     |
+| **Отведённое место**     | Одно место на поверхности, где стоят записи своих Инструментов, в порядке `tools`: группа Панели перед «Отменить», конец раздела Меню вставки, секция Ручки Блока перед «Удалить»                                                                                                                                                                  | Позицией относительно встроенной кнопки: id встроенных публичным API не являются                                                                                     |
+| **Пресет**               | Готовый набор встроенных Инструментов: `full` или `basic` (`RICH_TEXT_PRESETS`). Не замороженный список: новый встроенный приходит в него minor-версией                                                                                                                                                                                            | Точным списком `tools`: его состав меняет только экран                                                                                                               |
+| **Инструмент**           | Одна возможность Редактора: её Блоки и Метки, их правила в Схеме и место в интерфейсе, например `table`. Встроенный задаётся именем, свой — описанием                                                                                                                                                                                              | Кнопкой: выключенный Инструмент убирает и Блок из Схемы. Плагином Redactor: тот — класс поведения над DOM без Схемы                                                  |
+| **Свой Инструмент**      | Инструмент, который описывает потребитель (`CustomTool`): правила Схемы данными, Часть для движка и UI-записи. Передаётся в `tools` вперемешку с именами кита                                                                                                                                                                                      | Внутренним описанием кита: то — надмножество публичной формы для встроенных, наружу не экспортируется                                                                |
+| **Префикс потребителя**  | Начало имени всего своего — Инструмента, его Блоков, Меток и атрибутов — до подчёркивания: `acme_mergeTag`, `data-acme_size`. В именах кита подчёркивания нет, поэтому своё и встроенное не совпадают ни в наборе, ни в Документе                                                                                                                  | Пресетом: тот — набор встроенных Инструментов, а не пространство имён                                                                                                |
+| **HTML-соглашение**      | Форма своего в Документе: Блок — `div` или `span` с `data-block`, Метка — `span` с `data-mark`, атрибуты — `data-<префикс>_<имя>`. Заморожено: расширяется только добавлением                                                                                                                                                                      | Тегами Схемы кита (`p`, `table`, `img`): свой Блок их занять не может                                                                                                |
+| **Признак Блока**        | Свойство Блока, которое понимает только кит, а не движок: «контейнер» (детям своя Ручка), «можно превратить в», «Атом без меню форматирования»                                                                                                                                                                                                     | Атрибутом Блока: тот хранится в Документе                                                                                                                            |
+| **Часть для движка**     | То в описании Инструмента, что нужно только живому Редактору: расширения Tiptap и вид узла. Подаётся сразу или Загрузчиком                                                                                                                                                                                                                         | Правилами Схемы: те — данные, их читают сервер и Просмотр без движка                                                                                                 |
+| **Загрузчик**            | Функция с динамическим импортом вместо Части для движка: `engine: () => import(…)`. Так же грузятся тяжёлые встроенные вне `basic` — Блок кода и таблица                                                                                                                                                                                           | Предзагрузкой (`modulepreload`): её кит не публикует, ставит потребитель                                                                                             |
+| **Хэндл**                | Императивный доступ кода экрана к Редактору через `ref`: вставка у каретки, чтение, фокус, история                                                                                                                                                                                                                                                 | Сервисами Redactor: те — внутренности движка, а не API экрана                                                                                                        |
+| **Готовность**           | Момент, когда движок создан и Загрузчики всех включённых Инструментов, своих и встроенных, отработали: с него методы Хэндла действуют, а не молчат. Наступает один раз за монтаж, о нём сообщает `onReady`                                                                                                                                         | Гидратацией: после неё движок может ещё ждать Загрузчики                                                                                                             |
+| **Фокус поля**           | Фокус внутри Редактора целиком: Документ, Панель, поповеры кита, поле HTML. Переход между ними Фокус поля не теряет; `onFocus` и `onBlur` — о нём                                                                                                                                                                                                  | Фокусом Документа (`focus` и `blur` движка): клик в Панель его снимает                                                                                               |
+| **Правка автора**        | Изменение Документа, равное набору с клавиатуры: шаг истории, `onChange` после задержки, предел символов действует. Сюда же вставка, отмена и повтор из Хэндла                                                                                                                                                                                     | Заменой снаружи                                                                                                                                                      |
+| **Замена снаружи**       | Подмена Документа целиком (`value`, `clear()`, `setMarkdown()`, `setJSON()`): предел символов не режет; `onChange` сразу у `clear()`, `setMarkdown()` и `setJSON()`, на новый `value` не вызывается                                                                                                                                                | Правкой автора                                                                                                                                                       |
+| **Скелет**               | Вид Редактора до Готовности: рамка поля, место Панели и Документ: очищенный Схемой, он выведен статичным HTML с тем же классом и ритмом, что Документ движка, без ввода. На сервере — рамка без Документа. Сбой Загрузчика превращает Скелет в ошибку поля с «Повторить»                                                                           | Просмотром: тот — отдельный компонент только для чтения, а Скелет — состояние Редактора, которое сменяется движком. Компонентом `Skeleton` кита — заглушкой загрузки |
+| **Строка статуса**       | Строка внутри рамки поля под Документом: слева содержимое экрана (`status`: число слов, «Сохранено», соавтор), справа счётчик символов кита                                                                                                                                                                                                        | Сообщением поля: строка показывает длительное состояние экрана, а не событие                                                                                         |
+| **Сообщение поля**       | Одно событие, привязанное к полю (`showNotice`): тон `status` (только озвучивается) или `error` (видимая строка под полем до следующей Правки автора). Новое заменяет прежнее                                                                                                                                                                      | Тостом кита: тот глобален и к полю не привязан                                                                                                                       |
+| **Карточка у текста**    | Немодальная карточка под диапазоном Документа, который объявил свой Инструмент (`textCards`): комментарий, подсказка по результатам проверки текста. Открывается кареткой или щелчком, фокус остаётся в тексте                                                                                                                                     | Поповером кнопки: его открывает кнопка, а Карточку — место Документа                                                                                                 |
+| **Символ-триггер**       | Свой символ Инструмента (`trigger`), набор которого в начале Блока или после пробела открывает список пунктов у каретки, как `/`: `@` для упоминаний, `#` для тегов. Выбор заменяет набранное `@запрос` своим узлом                                                                                                                                | Меню вставки по `/`: то — встроенное, а свой символ задаёт Инструмент                                                                                                |
+| **Лист**                 | Светлая область Документа в любой теме приложения (`surface="paper"`) — для текста, который уйдёт из приложения светлым: письмо, печать, PDF. Панель, меню и рамка поля остаются в теме приложения; Просмотр с тем же `surface` показывает тот же Лист                                                                                             | Темой `light`: та меняет всё приложение, Лист — только Документ                                                                                                      |
+| **Остров**               | Клиентский кусок Просмотра, который после монтирования оживляет Блок в уже показанном HTML: кнопка «Копировать» у Блока кода, `island` своего Блока                                                                                                                                                                                                | Видом узла: тот живёт только в движке Редактора                                                                                                                      |
+| **Гнездо**               | Место в показанном HTML, куда Остров монтирует живой элемент: шапка Блока кода, в которую встаёт кнопка «Копировать»                                                                                                                                                                                                                               | Отведённым местом: то — место в интерфейсе Редактора для записей Инструментов                                                                                        |