@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/index.en.md

@@ -0,0 +1,155 @@
+---
+sourceHash: 27c68d4dc26c
+---
+
+# Component catalog
+
+The catalog lists the kit's components by group: each has a link to its page, its
+exports and a note on what the component is and what it is for. Related
+components (for example, the different kinds of switches) are described on one
+page.
+
+## Actions and feedback
+
+- [Button](actions/button.md): `Button` — a button that runs an action: save, submit, open a dialog
+- [Chip](actions/chip.md): `Chip` — a compact filter button that can be switched on and off
+- [SplitButton](actions/split-button.md): `SplitButton` — a button with a primary action and, next to it, a dropdown of other options
+- [Toolbar](actions/toolbar.md): `Toolbar` — a bar of buttons and switches, for example above a canvas or an input field; you move through it with the arrow keys
+- [Toggles](actions/toggles.md): `Toggle`, `Segmented`, `ToggleGroup`, `ButtonGroup` —
+  switches: turn one setting on or off, pick one mode out of several, mark several
+  independent options, put ordinary buttons into a row
+- [Feedback](actions/feedback.md): `Alert`, `Banner`, `Progress`, `Spinner`, `Toaster`,
+  `toast`, `StatusBadge` — messages and indicators: an inline notice or an app-wide
+  one, a toast, a progress bar, a loading indicator, a colored
+  status label
+- [CopyButton and Truncate](actions/copy-and-truncate.md): `CopyButton`, `Truncate` —
+  a "Copy" button with confirmation and truncation of long text with a tooltip
+  showing the full value
+
+## Input fields
+
+- [TextControl](inputs/text-control.md): `TextControl` — the base text field: a single line or multi-line text, with an icon and a placeholder inside; the other input fields are built on it
+- [RichTextEditor](inputs/rich-text-editor.md): `RichTextEditor`, the `useRichTextEditorState` hook, the `RICH_TEXT_PRESETS` Presets, a custom Tool (`CustomTool`) — a rich text editor: headings, lists, links, inline formatting (bold, italic, color). Suitable for long articles and descriptions, and the value is stored as HTML. A separate entry point `@olddevs/ui/editor`; the consumer installs the Tiptap engine with the command from that page
+- [Editor extension API](../api/editor-extension.md) — a reference for those who extend the Editor with custom Tools, buttons and Loaders: what can be plugged in and what will not change between versions
+- [NumberInput](inputs/number-input.md): `NumberInput` — a number field with "increase" and "decrease" buttons, bounds and formatting; an empty field yields `null`, not zero
+- [Choice controls](inputs/choice-controls.md): `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup` — checkboxes and radio buttons: mark several independent options or choose exactly one from a set
+- [Select](inputs/select.md): `Select` — a dropdown list: choose a value only from a predefined set; a new one cannot be created
+- [Combobox](inputs/combobox.md): `Combobox` — a field with a list of options as you type: you can pick from the list or enter your own value that is not in the list
+- [TagInput](inputs/tag-input.md): `TagInput` — a field where the user types several short tag values, separating them with Enter or a comma
+- [Transfer](inputs/transfer.md): `Transfer` — two columns, "available" and "selected", with items moved between them; for choosing many values from a large list
+- [TreeSelect](inputs/tree-select.md): `TreeSelect` — a dropdown field for choosing a node from a hierarchy: a department in an org chart, a category in a catalog
+- [ColorPicker](inputs/color-picker.md): `ColorPicker` — choose any color: a palette, a hue strip and a color code input; a separate entry point `@olddevs/ui/color`
+- [SwatchGroup](inputs/swatch-group.md): `SwatchGroup` — choose one option from a set of color swatches, for example tags or categories; only shades from the kit's palette can be chosen, not any color
+- [Rating](inputs/rating.md): `Rating` — a star rating: the user assigns a score to a review, a product or a piece of content
+- [Slider](inputs/slider.md): `Slider`, `RangeSlider` — a scale with a draggable thumb: `Slider` picks one number, `RangeSlider` sets the lower and upper bounds of a range
+- [SearchControl](inputs/search-control.md): `SearchControl` — a search field with a magnifier and a clear button; it does not run the query; it only collects the string for your search
+- [FileDropzone](inputs/file-dropzone.md): `FileDropzone` — an area where users drag files or pick them with a button; it checks type and size and explains a rejection, but uploads nothing itself
+- [UploadQueue](inputs/upload-queue.md): `UploadQueue` — a list of files being uploaded, with the state of each (waiting, uploading, ready, error) and actions: retry, cancel, remove
+- [PasswordInput](inputs/password-input.md): `PasswordInput` — a password field with a "show" button and a warning that Caps Lock is on
+- [MaskedInput](inputs/masked-input.md): `MaskedInput`, `formatMask`, `unmask`, `maskCapacity` — a field that inserts separators according to a pattern as you type: a date, a document number, an account number
+- [PhoneInput](inputs/phone-input.md): `PhoneInput`, `RU_PHONE_MASK` — a phone field with a ready-made Russian mask; for another format, use `MaskedInput`
+- [PinInput](inputs/pin-input.md): `PinInput` — a confirmation code input, one digit per cell; a code pasted from an SMS is split across the cells automatically
+- [InlineEdit](inputs/inline-edit.md): `InlineEdit` — a value that is changed right in place: a click turns it into a field, Enter confirms, Escape cancels
+- [Form](inputs/form.md): `Form`, `FormField` — a form with a shared submit action: it is locked while the request runs; `FormField` ties a field to its label, hint and error
+- [FormLayout](inputs/form-layout.md): `FormLayout`, `FieldRow` — a layout for form fields: one or two columns, labels on top or on the left; it neither validates nor submits anything
+
+## Date and time
+
+- [Calendar](date-time/calendar.md): `Calendar`, `NAV_BUTTON_CLASS`,
+  `WEEKDAY_CELL_CLASS` — a month grid for picking one date, without a field or a dropdown: for your own layout, it is usually simpler to use `DatePicker`
+- [RangeCalendar](date-time/range-calendar.md): `RangeCalendar` — a grid of one or two months for picking a date range, without a field or presets: for your own layout, it is usually simpler to use `DateRangePicker`
+- [DatePicker](date-time/date-picker.md): `DatePicker`, `formatDate` — a single-date picker field: a click opens a calendar, the value is stored as a `YYYY-MM-DD` string
+- [DateRangePicker](date-time/date-range-picker.md): `DateRangePicker` — a date range picker field with quick options like "7 days" and a clear button, for example for a filter or a report
+- [DateTimePicker](date-time/date-time-picker.md): `DateTimePicker`,
+  `maskTime`, `normalizeTime` — a pair of fields for a date and a time together, for example a publication deadline or an event start; the date and the time are stored separately
+- [TimePicker](date-time/time-picker.md): `TimePicker`, `upcomingSlots` — an `HH:MM` time field: you can type an exact time or pick from a list of the nearest slots
+
+## Overlays
+
+- [Dialog](overlays/dialog.md): `Dialog`, `ModalHeader`, `ModalOverlay` —
+  a modal dialog over the page for a form or a preview: while it is open, the
+  rest of the screen cannot be used
+- [ConfirmDialog](overlays/confirm-dialog.md): `ConfirmDialog` — a short dialog with an "are you sure?" question before a deletion or another irreversible action; for forms, use `Dialog`
+- [ShortcutsHelp](overlays/shortcuts-help.md): `ShortcutsHelp` — a dialog with a list of the
+  app's keyboard shortcuts, arranged by section
+- [Drawer](overlays/drawer.md): `Drawer` — a panel that slides in from the side or the bottom over the page: in it
+  you can view or edit a record without leaving the screen
+- [Popover](overlays/popover.md): `Popover`, `PopoverAnchor`, `PopoverClose`,
+  `PopoverContent`, `PopoverTrigger` — a small panel with any content that
+  opens next to a button on click; the foundation for dropdown panels and calendars
+- [HoverCard](overlays/hover-card.md): `HoverCard`, `HoverCardContent`,
+  `HoverCardTrigger` — a card with details that appears when you hover over a name
+  or a link: an avatar, a job title, the start of a document
+- [Tooltip](overlays/tooltip.md): `Tooltip`, `TooltipContent`,
+  `TooltipProvider`, `TooltipRoot`, `TooltipTrigger`, `HelpTooltip` — a short
+  short text that appears on hover or focus, for example a label for an icon button;
+  `HelpTooltip` is a ready-made "?" icon with an explanation for a field
+- [Menu](overlays/menu.md): `Menu`, `MenuButton`, `MenuItem`, `MenuSection`,
+  `MenuSeparator`, `MenuTrigger`, `SubmenuTrigger` — a dropdown list of commands that opens when you click
+  a button, for example "Rename" and "Delete"; to choose a value in a field, use `Select`
+- [Context menu](overlays/context-menu.md): `ContextMenu`,
+  `ContextMenuCheckboxItem`, `ContextMenuContent`, `ContextMenuItem`,
+  `ContextMenuLabel`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`,
+  `ContextMenuSeparator`, `ContextMenuSub`,
+  `ContextMenuSubContent`, `ContextMenuSubTrigger`, `ContextMenuTrigger` — a command menu that opens
+  on a right click over a file, a table row or a card
+- [Command palette](overlays/command-palette.md): `CommandPalette` — a quick search dialog
+  over the app's commands: the user types a few letters and immediately runs the action they need
+
+## Table
+
+Ready-made components for entity lists, built on top of the low-level `Table`.
+
+- [DataTable](table/data-table.md): `DataTable` — a ready-made table for a list of entities: column and density settings, loading and error states, a bar with filters and actions above the table
+- [Table toolbar](table/toolbar.md): `TableToolbar`, `TablePreferences` — a bar above a table with a title, a counter and actions, plus a settings menu: which columns to show, in what order and how densely
+- [FilterBar](table/filter-bar.md): `FilterBar`, `FilterBarAdd` — a row of applied filters, each of which can be removed, and a button to add a new one; for lists where there are several filters and the set changes
+- [SavedViews](table/saved-views.md): `SavedViews` — a switcher of saved filter sets such as "Mine" or "Drafts", which the user creates and returns to with one click
+
+## App shell
+
+Components built from primitives: the page frame, its navigation and header.
+
+- [AppShell](app-shell/app-shell.md): `AppShell`, `useAppShell` — the frame of an app page: side navigation on the left, a header on top, content in the middle; it handles the mobile mode, focus on screen change and the "skip to content" link on its own
+- [SideNav](app-shell/side-nav.md): `SideNav`, `NavGroup`, `NavItem` — the app's side menu: sections with link items, the current item highlighted; the menu can be collapsed to icons
+- [MobileTabBar](app-shell/mobile-tab-bar.md): `MobileTabBar`, `MobileTabBarItem` — a bottom bar with the main sections for a phone (up to five items): navigation in one tap; on a wide screen it is replaced by `SideNav`
+- [TopBar](app-shell/top-bar.md): `TopBar` — the app header with a logo, search and actions (notifications, profile); different from `PageHeader`, which sets the title of the page itself
+- [SplitPanel](app-shell/split-panel.md): `SplitPanel`, `useMediaQuery` — two areas side by side or one above the other with a divider the user drags: for example, a list and the details of the selected row
+
+## Navigation
+
+- [Tabs](navigation/tabs.md): `Tabs` — a tab list for switching between peer views of one screen; you render the content panel yourself
+- [Accordion](navigation/accordion.md): `Accordion`, `AccordionItem` — a list of sections that expand and collapse on a click: an FAQ, settings, a long page of self-contained sections
+- [Breadcrumbs](navigation/breadcrumbs.md): `Breadcrumbs` — a chain of links "Section / Subsection / Page" that shows where the user is and lets them go back up a level
+- [Pagination](navigation/pagination.md): `Pagination`, `pageRange` — a page switcher for long results: numbers, adjacent pages, jumping to the first and last; `pageRange` calculates which numbers to show
+- [Stepper](navigation/stepper.md): `Stepper` — a step indicator for a wizard, an import or a checkout: shows the current step and lets you go back to a completed one
+- [TreeView](navigation/tree-view.md): `TreeView` — a tree with expandable branches for categories, folders and sections; nodes can be selected, including with checkboxes
+- [Selection bar](navigation/selection-bar.md): `SelectionBar`, `useStickyOffset` — a bar above a list or a grid where several objects are selected: shows "12 selected", bulk action buttons and a clear-selection button
+- [Contextual save bar](navigation/contextual-save-bar.md): `ContextualSaveBar` — a bar at the bottom of the viewport that appears after the first edit of a form and offers to save or discard unsaved changes
+- [Page header](navigation/page-header.md): `PageHeader` — the page header: the main title, an explanation under it and primary actions like "Create" or "Upload"; one per page
+- [Section header](navigation/section-header.md): `SectionHeader` — a title for a block inside a page or a card, with a counter, a link or a small button on the right; for the title of the page itself there is `PageHeader`
+
+## Content
+
+- [Typography](content/typography.md): `Text`, `Heading`, `Link` — page text: headings of the right level, paragraphs and captions, links that navigate to a URL
+- [Card](content/card.md): `Card` — a panel with a background, a border and padding that sets a self-contained block apart from the page background; you put the content into it yourself
+- [Image](content/image.md): `Image` — a picture that shows a loading state, and a placeholder if the URL is empty or the file fails to load
+- [Timeline](content/timeline.md): `Timeline` — a sequence of process steps where each step has its own outcome and any of them can fail: a task pipeline, a publication history
+- [CodeView](content/code-view.md): `CodeView` — a read-only block of code or data that can be copied whole: an API response, a config, a webhook body; highlighting comes from the `highlightCodeNodes` helper in `@olddevs/ui/editor/highlight`
+- [Notifications](content/notifications.md): `NotificationItem`, `NotificationList`, `NotificationCenter` — a notification feed in a popover or on a page: what happened, when, whether it has been read; unlike `toast`, it stays on screen
+- [MediaCard](content/media-card.md): `MediaCard` — a tile with a preview, with badges and buttons overlaid on it; the tile can be selected among other tiles: frames, documents, covers
+- [SortableList](content/sortable-list.md): `SortableList` — a short list the user reorders by dragging: menu sections, scenario steps, priorities; lists sharing a `group` can exchange rows, which is how a kanban board is built
+- [EditableList](content/editable-list.md): `EditableList` — a list whose rows can be edited in place and reordered by dragging, and which can be added to at the bottom: a checklist, tasks; if you only need the order, `SortableList` is enough
+- [RichTextView](content/rich-text-view.md): `RichTextView` — displays ready-made rich text from the Editor without the Editor itself; a separate entry point `@olddevs/ui/editor`, suitable for a server component
+- [VirtualGrid](content/virtual-grid.md): `VirtualGrid` — a grid of hundreds or thousands of previews that renders only the visible cells and lets you select them; for a dozen cards `Grid` is enough
+- [Avatar](content/avatar.md): `Avatar`, `AvatarGroup` — a round image of a person: a photo or, if there is none, initials; `AvatarGroup` shows several participants with a "+N" overflow count
+- [Data display](content/data-display.md): `Badge`, `Stat`, `DescriptionList`, `Table` — four ways to show data: a counter or a label, a key metric with an explanation, "property and value" pairs, a table of records of the same kind
+- [Empty and loading](content/empty-and-loading.md): `EmptyState`, `ErrorState`, `Skeleton` — three states of a screen without data: a placeholder for an empty result, a failure message with a retry, a gray placeholder layout while the data loads
+- [Layout primitives](content/layout-primitives.md): `Separator`, `ScrollArea`, `AspectRatio`, `Kbd` — small layout elements: a divider, a scrollable block, an area with fixed proportions, a marker for a keyboard key in text
+- [Grid](content/grid.md): `Grid` — a grid of equal columns whose count changes with the screen width: pricing cards, metric tiles; for hundreds of items you need `VirtualGrid`
+- [TagGroup](content/tag-group.md): `TagGroup`, `Tag` — a set of tags shown next to a record: categories, projects, statuses; a tag can be colored, removable or a link, but not selectable
+- [Carousel](content/carousel.md): `Carousel` — a horizontal row of slides that you flip through with buttons, swipes and arrow keys, so that a selection takes one row: a gallery, recommendations
+- [Keyboard and hidden text](content/keyboard.md): `Keyboard`, `VisuallyHidden` — an on-screen keyboard for entering into an existing field by touch or mouse, and text that is hidden on screen but available to a screen reader
+
+`@olddevs/ui/icons` and exports from `lib/`/`hooks/` are not components. Their
+description is in [icons.md](../icons.md) and
+[`api/utilities.md`](../api/utilities.md).

package/docs/components/index.md

@@ -0,0 +1,150 @@
+# Каталог компонентов
+
+Каталог перечисляет компоненты кита по группам: у каждого есть ссылка на
+страницу, экспорты и пояснение, что это за компонент и для чего он нужен. Близкие
+компоненты (например, разные виды переключателей) описаны на одной странице.
+
+## Действия и обратная связь
+
+- [Button](actions/button.md): `Button` — кнопка, которая запускает действие: сохранить, отправить, открыть окно
+- [Chip](actions/chip.md): `Chip` — компактная кнопка-фильтр, которую можно включить и выключить
+- [SplitButton](actions/split-button.md): `SplitButton` — кнопка с главным действием и выпадающим списком других вариантов рядом
+- [Toolbar](actions/toolbar.md): `Toolbar` — панель из кнопок и переключателей, например над полотном или полем ввода; по ней двигаются стрелками
+- [Toggles](actions/toggles.md): `Toggle`, `Segmented`, `ToggleGroup`, `ButtonGroup` —
+  переключатели: включить или выключить одну настройку, выбрать один режим из
+  нескольких, отметить несколько независимых вариантов, собрать обычные кнопки в ряд
+- [Feedback](actions/feedback.md): `Alert`, `Banner`, `Progress`, `Spinner`, `Toaster`,
+  `toast`, `StatusBadge` — сообщения и индикаторы: уведомление на месте или на всё
+  приложение, тост, полоса прогресса, индикатор ожидания, цветная
+  метка статуса
+- [CopyButton и Truncate](actions/copy-and-truncate.md): `CopyButton`, `Truncate` —
+  кнопка «Скопировать» с подтверждением и обрезка длинного текста с подсказкой
+  полного значения
+
+## Поля ввода
+
+- [TextControl](inputs/text-control.md): `TextControl` — базовое текстовое поле: одна строка или многострочный текст, с иконкой и плейсхолдером внутри; на нём построены остальные поля ввода
+- [RichTextEditor](inputs/rich-text-editor.md): `RichTextEditor`, хук `useRichTextEditorState`, Пресеты `RICH_TEXT_PRESETS`, свой Инструмент (`CustomTool`) — редактор форматированного текста: заголовки, списки, ссылки, выделение слов (жирный, курсив, цвет). Подходит для длинных статей и описаний, значение хранится как HTML. Отдельный вход `@olddevs/ui/editor`; движок Tiptap потребитель ставит сам — командой со страницы
+- [API расширения Редактора](../api/editor-extension.md) — справочник для тех, кто дописывает Редактор своими Инструментами, кнопками и Загрузчиками: что можно подключить и что не изменится между версиями
+- [NumberInput](inputs/number-input.md): `NumberInput` — поле для числа с кнопками «больше» и «меньше», границами и форматированием; пустое поле даёт `null`, а не ноль
+- [Choice controls](inputs/choice-controls.md): `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup` — флажки и радиокнопки: отметить несколько независимых вариантов или выбрать ровно один из набора
+- [Select](inputs/select.md): `Select` — выпадающий список: выбрать значение только из заранее заданного набора, нового создать нельзя
+- [Combobox](inputs/combobox.md): `Combobox` — поле со списком вариантов при вводе: можно выбрать из списка, а можно ввести своё значение, которого в списке нет
+- [TagInput](inputs/tag-input.md): `TagInput` — поле, в котором пользователь сам набирает несколько коротких значений-тегов, разделяя их Enter или запятой
+- [Transfer](inputs/transfer.md): `Transfer` — две колонки «доступно» и «выбрано» с переносом элементов между ними; для выбора многих значений из большого списка
+- [TreeSelect](inputs/tree-select.md): `TreeSelect` — выпадающее поле для выбора узла из иерархии: отдел в оргструктуре, категория в каталоге
+- [ColorPicker](inputs/color-picker.md): `ColorPicker` — выбор любого цвета: палитра, полоса тона и ввод кода цвета; отдельный вход `@olddevs/ui/color`
+- [SwatchGroup](inputs/swatch-group.md): `SwatchGroup` — выбор одного варианта из набора цветных образцов, например теги или категории; можно выбрать только оттенки из палитры кита, а не любой цвет
+- [Rating](inputs/rating.md): `Rating` — оценка звёздами: пользователь ставит число баллов отзыву, товару или материалу
+- [Slider](inputs/slider.md): `Slider`, `RangeSlider` — шкала с ползунком: `Slider` выбирает одно число, `RangeSlider` задаёт нижнюю и верхнюю границы диапазона
+- [SearchControl](inputs/search-control.md): `SearchControl` — поле поиска с лупой и кнопкой очистки; запрос не выполняет, только собирает строку для вашего поиска
+- [FileDropzone](inputs/file-dropzone.md): `FileDropzone` — область, в которую перетаскивают файлы или выбирают их кнопкой; проверяет тип и размер и объясняет отказ, но сама ничего не загружает
+- [UploadQueue](inputs/upload-queue.md): `UploadQueue` — список загружаемых файлов с состоянием каждого (ожидает, грузится, готов, ошибка) и действиями: повторить, отменить, убрать
+- [PasswordInput](inputs/password-input.md): `PasswordInput` — поле пароля с кнопкой «показать» и предупреждением о включённом Caps Lock
+- [MaskedInput](inputs/masked-input.md): `MaskedInput`, `formatMask`, `unmask`, `maskCapacity` — поле, которое подставляет разделители по шаблону при вводе: дата, номер документа, номер счёта
+- [PhoneInput](inputs/phone-input.md): `PhoneInput`, `RU_PHONE_MASK` — поле телефона с готовой российской маской; для другого формата берите `MaskedInput`
+- [PinInput](inputs/pin-input.md): `PinInput` — ввод кода подтверждения по одной цифре в отдельной ячейке; код, вставленный из SMS, раскладывается по ячейкам сам
+- [InlineEdit](inputs/inline-edit.md): `InlineEdit` — значение, которое меняют прямо на месте: клик превращает его в поле, Enter подтверждает, Escape отменяет
+- [Form](inputs/form.md): `Form`, `FormField` — форма с общей отправкой: на время запроса она блокируется; `FormField` связывает поле с подписью, пояснением и ошибкой
+- [FormLayout](inputs/form-layout.md): `FormLayout`, `FieldRow` — раскладка полей формы: одна или две колонки, подписи сверху или слева; ничего не проверяет и не отправляет
+
+## Дата и время
+
+- [Calendar](date-time/calendar.md): `Calendar`, `NAV_BUTTON_CLASS`,
+  `WEEKDAY_CELL_CLASS` — сетка месяца для выбора одной даты, без поля и выпадающего окна: для собственной раскладки, обычно проще взять `DatePicker`
+- [RangeCalendar](date-time/range-calendar.md): `RangeCalendar` — сетка из одного или двух месяцев для выбора периода от даты до даты, без поля и пресетов: для собственной раскладки, обычно проще взять `DateRangePicker`
+- [DatePicker](date-time/date-picker.md): `DatePicker`, `formatDate` — поле выбора одной даты: по клику открывается календарь, значение хранится строкой `YYYY-MM-DD`
+- [DateRangePicker](date-time/date-range-picker.md): `DateRangePicker` — поле выбора периода «с — по» с быстрыми вариантами вроде «7 дней» и кнопкой очистки, например для фильтра или отчёта
+- [DateTimePicker](date-time/date-time-picker.md): `DateTimePicker`,
+  `maskTime`, `normalizeTime` — пара полей для даты и времени вместе, например срок публикации или начало события; дата и время хранятся отдельно
+- [TimePicker](date-time/time-picker.md): `TimePicker`, `upcomingSlots` — поле времени `ЧЧ:ММ`: можно напечатать точное время или выбрать из списка ближайших слотов
+
+## Оверлеи
+
+- [Dialog](overlays/dialog.md): `Dialog`, `ModalHeader`, `ModalOverlay` —
+  модальное окно поверх страницы для формы или просмотра: пока оно открыто,
+  работать с остальным экраном нельзя
+- [ConfirmDialog](overlays/confirm-dialog.md): `ConfirmDialog` — короткое окно с вопросом «точно
+  сделать?» перед удалением или другим необратимым действием; для форм берите `Dialog`
+- [ShortcutsHelp](overlays/shortcuts-help.md): `ShortcutsHelp` — окно со списком
+  сочетаний клавиш приложения, разложенных по разделам
+- [Drawer](overlays/drawer.md): `Drawer` — панель, выезжающая сбоку или снизу поверх страницы: в ней
+  можно просмотреть или отредактировать запись, не уходя с экрана
+- [Popover](overlays/popover.md): `Popover`, `PopoverAnchor`, `PopoverClose`,
+  `PopoverContent`, `PopoverTrigger` — небольшая панель с любым содержимым, которая
+  открывается по клику рядом с кнопкой; основа для выпадающих блоков и календарей
+- [HoverCard](overlays/hover-card.md): `HoverCard`, `HoverCardContent`,
+  `HoverCardTrigger` — карточка с подробностями, которая появляется при наведении на имя
+  или ссылку: аватар, должность, начало документа
+- [Tooltip](overlays/tooltip.md): `Tooltip`, `TooltipContent`,
+  `TooltipProvider`, `TooltipRoot`, `TooltipTrigger`, `HelpTooltip` — короткая
+  текстовая подсказка при наведении или фокусе, например подпись к кнопке с иконкой;
+  `HelpTooltip` — готовая иконка «?» с пояснением к полю
+- [Menu](overlays/menu.md): `Menu`, `MenuButton`, `MenuItem`, `MenuSection`,
+  `MenuSeparator`, `MenuTrigger`, `SubmenuTrigger` — выпадающий список команд по клику
+  на кнопку, например «Переименовать» и «Удалить»; выбор значения в поле — это `Select`
+- [Context menu](overlays/context-menu.md): `ContextMenu`,
+  `ContextMenuCheckboxItem`, `ContextMenuContent`, `ContextMenuItem`,
+  `ContextMenuLabel`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`,
+  `ContextMenuSeparator`, `ContextMenuSub`,
+  `ContextMenuSubContent`, `ContextMenuSubTrigger`, `ContextMenuTrigger` — меню команд, которое открывается
+  правой кнопкой мыши над файлом, строкой таблицы или карточкой
+- [Command palette](overlays/command-palette.md): `CommandPalette` — окно быстрого поиска
+  по командам приложения: пользователь вводит несколько букв и сразу запускает нужное действие
+
+## Таблица
+
+Готовые компоненты для списков сущностей поверх низкоуровневой `Table`.
+
+- [DataTable](table/data-table.md): `DataTable` — готовая таблица для списка сущностей: настройки колонок и плотности, состояния загрузки и ошибки, полоса с фильтрами и действиями над таблицей
+- [Table toolbar](table/toolbar.md): `TableToolbar`, `TablePreferences` — полоса над таблицей с заголовком, счётчиком и действиями, а также меню настроек: какие колонки показать, в каком порядке и насколько плотно
+- [FilterBar](table/filter-bar.md): `FilterBar`, `FilterBarAdd` — ряд применённых фильтров, каждый из которых можно снять, и кнопка добавления нового; для списков, где фильтров несколько и набор меняется
+- [SavedViews](table/saved-views.md): `SavedViews` — переключатель сохранённых наборов фильтров вроде «Мои» или «Черновики», которые пользователь создаёт сам и к которым возвращается одним щелчком
+
+## Оболочка приложения
+
+Компоненты, собранные из примитивов: каркас страницы, её навигация и шапка.
+
+- [AppShell](app-shell/app-shell.md): `AppShell`, `useAppShell` — каркас страницы приложения: боковая навигация слева, шапка сверху, содержимое посередине; сам следит за мобильным режимом, фокусом при смене экрана и ссылкой «к содержимому»
+- [SideNav](app-shell/side-nav.md): `SideNav`, `NavGroup`, `NavItem` — боковое меню приложения: разделы с пунктами-ссылками, текущий пункт подсвечен, меню можно свернуть до иконок
+- [MobileTabBar](app-shell/mobile-tab-bar.md): `MobileTabBar`, `MobileTabBarItem` — нижняя панель с главными разделами для телефона (до пяти пунктов): переход в один тап, на широком экране её заменяет `SideNav`
+- [TopBar](app-shell/top-bar.md): `TopBar` — шапка приложения с логотипом, поиском и действиями (уведомления, профиль); отличается от `PageHeader`, который задаёт заголовок самой страницы
+- [SplitPanel](app-shell/split-panel.md): `SplitPanel`, `useMediaQuery` — две области рядом или друг над другом с разделителем, который пользователь перетаскивает мышью: например, список и детали выбранной строки
+
+## Навигация
+
+- [Tabs](navigation/tabs.md): `Tabs` — ряд вкладок для переключения между равноправными представлениями одного экрана; панель с содержимым выводите сами
+- [Accordion](navigation/accordion.md): `Accordion`, `AccordionItem` — список секций, которые раскрываются и сворачиваются по клику: FAQ, настройки, длинная страница из самостоятельных разделов
+- [Breadcrumbs](navigation/breadcrumbs.md): `Breadcrumbs` — цепочка ссылок «Раздел / Подраздел / Страница», по которой видно, где пользователь, и можно вернуться на уровень выше
+- [Pagination](navigation/pagination.md): `Pagination`, `pageRange` — переключатель страниц для длинной выдачи: номера, соседние страницы, переход к первой и последней; `pageRange` считает, какие номера показать
+- [Stepper](navigation/stepper.md): `Stepper` — индикатор шагов мастера, импорта или оформления заказа: показывает текущий шаг и позволяет вернуться к уже пройденному
+- [TreeView](navigation/tree-view.md): `TreeView` — дерево с раскрываемыми ветками для категорий, папок и разделов; узлы можно выбирать, в том числе флажками
+- [Selection bar](navigation/selection-bar.md): `SelectionBar`, `useStickyOffset` — полоса над списком или сеткой, где выбрано несколько объектов: показывает «Выбрано 12», кнопки массовых действий и сброс выделения
+- [Contextual save bar](navigation/contextual-save-bar.md): `ContextualSaveBar` — полоса внизу окна, которая появляется после первой правки формы и предлагает сохранить или отменить несохранённые изменения
+- [Page header](navigation/page-header.md): `PageHeader` — шапка страницы: главный заголовок, пояснение под ним и основные действия вроде «Создать» или «Загрузить»; один на страницу
+- [Section header](navigation/section-header.md): `SectionHeader` — заголовок блока внутри страницы или карточки со счётчиком, ссылкой или маленькой кнопкой справа; для заголовка самой страницы есть `PageHeader`
+
+## Содержимое
+
+- [Typography](content/typography.md): `Text`, `Heading`, `Link` — текст страницы: заголовки нужного уровня, абзацы и подписи, ссылки для перехода по URL
+- [Card](content/card.md): `Card` — панель с фоном, рамкой и отступом, которая отделяет самостоятельный блок от фона страницы; содержимое в неё кладут сами
+- [Image](content/image.md): `Image` — картинка, которая показывает загрузку и заглушку, если URL пустой или файл не открылся
+- [Timeline](content/timeline.md): `Timeline` — последовательность шагов процесса, где у каждого шага свой итог и любой может завершиться ошибкой: конвейер задачи, история публикации
+- [CodeView](content/code-view.md): `CodeView` — блок с кодом или данными только для чтения, который можно скопировать целиком: ответ API, конфиг, тело вебхука; подсветку даёт помощник `highlightCodeNodes` из `@olddevs/ui/editor/highlight`
+- [Notifications](content/notifications.md): `NotificationItem`, `NotificationList`, `NotificationCenter` — лента уведомлений в поповере или на странице: что произошло, когда, прочитано ли; в отличие от `toast`, остаётся на экране
+- [MediaCard](content/media-card.md): `MediaCard` — плитка с превью, на которое наложены бейджи и кнопки; плитку можно выбрать среди других: кадры, документы, обложки
+- [SortableList](content/sortable-list.md): `SortableList` — короткий список, который пользователь переставляет перетаскиванием: разделы меню, шаги сценария, приоритеты; списки одной `group` обмениваются строками: так собирается канбан-доска
+- [EditableList](content/editable-list.md): `EditableList` — список, строки которого можно править на месте и переставлять перетаскиванием, а сам список — пополнять снизу: чек-лист, задачи; если нужен только порядок, хватит `SortableList`
+- [RichTextView](content/rich-text-view.md): `RichTextView` — показ готового форматированного текста из Редактора без самого Редактора; отдельный вход `@olddevs/ui/editor`, годится серверному компоненту
+- [VirtualGrid](content/virtual-grid.md): `VirtualGrid` — сетка из сотен и тысяч превью, которая отрисовывает только видимые ячейки и позволяет их выбирать; для десятка карточек хватит `Grid`
+- [Avatar](content/avatar.md): `Avatar`, `AvatarGroup` — круглое изображение человека: фото или, если его нет, инициалы; `AvatarGroup` показывает нескольких участников со счётчиком остатка «+N»
+- [Data display](content/data-display.md): `Badge`, `Stat`, `DescriptionList`, `Table` — четыре способа показать данные: счётчик или метка, ключевой показатель с пояснением, пары «свойство и значение», таблица однотипных записей
+- [Empty and loading](content/empty-and-loading.md): `EmptyState`, `ErrorState`, `Skeleton` — три состояния экрана без данных: заглушка при пустом результате, сообщение о сбое с повтором, серый каркас, пока данные грузятся
+- [Layout primitives](content/layout-primitives.md): `Separator`, `ScrollArea`, `AspectRatio`, `Kbd` — мелкие элементы раскладки: разделитель, прокручиваемый блок, область с заданными пропорциями, обозначение клавиши в тексте
+- [Grid](content/grid.md): `Grid` — сетка равных колонок, число которых меняется по ширине экрана: карточки тарифов, плитки показателей; для сотен элементов нужен `VirtualGrid`
+- [TagGroup](content/tag-group.md): `TagGroup`, `Tag` — набор тегов для показа рядом с записью: категории, проекты, статусы; тег можно сделать цветным, удаляемым или ссылкой, но не выбираемым
+- [Carousel](content/carousel.md): `Carousel` — горизонтальный ряд слайдов, который листают кнопками, свайпом и клавишами-стрелками, чтобы подборка занимала одну строку: галерея, рекомендации
+- [Keyboard and hidden text](content/keyboard.md): `Keyboard`, `VisuallyHidden` — экранная клавиатура для ввода в существующее поле касанием или мышью и текст, скрытый на экране, но доступный скринридеру
+
+`@olddevs/ui/icons` и exports из `lib/`/`hooks/` — не компоненты. Их описание
+находится в [icons.md](../icons.md) и [`api/utilities.md`](../api/utilities.md).

package/docs/components/inputs/choice-controls.en.md

@@ -0,0 +1,118 @@
+---
+component: Choice controls
+exports: [Checkbox, CheckboxGroup, Radio, RadioGroup]
+category: inputs
+status: stable
+source: src/components/inputs/Checkbox.tsx
+story: src/components/inputs/Checkbox.stories.tsx
+sourceHash: 46b11ed947ca
+---
+
+# Checkbox, CheckboxGroup, Radio and RadioGroup
+
+## Summary for AI
+
+`Checkbox` selects an independent yes/no, `CheckboxGroup` selects several values, `RadioGroup` gives one answer to a shared question. `Radio` exists only inside `RadioGroup`. The `appearance="card"` axis on both groups shows the options as cards with a label, a description and an icon.
+
+## When to use
+
+- `Checkbox`: a single setting, including `indeterminate` for the "some selected" state.
+- `CheckboxGroup`: several independent options; `value` is an array of strings.
+- `RadioGroup`: exactly one option from a mutually exclusive set; `value` is kept on the group.
+- `appearance="card"`: two to five options that people compare before choosing: a plan, an export format, an access mode, a set of modules. Details are in the "Choice cards" section.
+
+## When not to use
+
+- Do not use RadioGroup for several filters — use CheckboxGroup or ToggleGroup.
+- Do not let people clear a RadioGroup by "clicking the selected option"; add an explicit "Any" option.
+- Do not use cards for a long list of same-kind values or for single-line settings: a card takes three or four lines, and ten cards read worse than ten rows. Use the default appearance there.
+- Do not use Checkbox without `children` or `label`: it must have an accessible name.
+
+## Minimal example
+
+```tsx
+<CheckboxGroup label="Channels" value={channels} onChange={setChannels}>
+  <Checkbox value="telegram">Telegram</Checkbox>
+</CheckboxGroup>
+
+<RadioGroup label="View" value={view} onChange={setView}><Radio value="list">List</Radio></RadioGroup>
+```
+
+## Public API
+
+- `Checkbox`: controlled `checked`/`onCheckedChange` or `defaultChecked`; when rendering, `indeterminate` takes priority over checked. `name` and `value` are for native form submit.
+- `CheckboxGroup`: `value`, `onChange` and `label` are required; `errorMessage` replaces `description`, and `disabled` disables all children. The optional `tone` colors the checked boxes of the set (see below).
+- `RadioGroup`: `value: string | null`, but `onChange` returns a string; `null` is only the initial empty state. `Radio` accepts `value`, a description and disabled.
+- Both groups have `orientation`, `errorMessage`, `appearance` and `tone`; RadioGroup also sets a shared `size`.
+- **Group tone.** The group's `tone` reaches the options through context and colors what is checked: the circle and dot, the box with the checkmark and (in cards) the border of the selected one. For `RadioGroup` the tone exists only on the group; `Radio` has none of its own. For `CheckboxGroup` the tone is optional: **a `tone` set on the group overrides the `tone` of every `Checkbox` inside** (the set cannot drift apart in look, as with radios); if it is not set, each checkbox is colored with its own `tone`, as outside a group. A single `Checkbox` outside a group uses its own `tone` as before. Unchecked ones are always neutral.
+- `Radio` and `Checkbox` accept an optional `icon` and `description`.
+- **Border of the checked box.** A checked (and "some selected") checkbox has its box outlined in the `*-strong` color of its tone, and in `fg-3` for `neutral`: the `solid` fill falls short of 3:1 against the background (WCAG 1.4.11) for four tones out of five, and the kit did not change tokens for the sake of a checkbox. The border holds the edge of the box; the checkmark relies on text contrast on the fill. The same goes for a switched-on `Toggle`. `npm run contrast` measures it. **This is a deliberate decision by the owner, not an oversight:** the fill of a checked checkbox was not raised to 3:1, because its color comes from the `solid` tokens of the tones, shared across the whole kit.
+
+## Hit area
+
+The hit area of the checkbox and radio is 24 pixels high regardless of size
+and of whether a visible label is present; WCAG 2.5.8 requires this. The control
+itself takes the same space in the layout as before: a pseudo-element extends the
+area.
+
+Padding cannot be used to enlarge it: the control's height is held by the list
+row, 32 pixels, and a grown checkbox would stretch it. The visible size and the hit area
+are separated in the same way as with `Button size="xs"`.
+
+## Choice cards
+
+```tsx
+<RadioGroup label="Plan" appearance="card" value={plan} onChange={setPlan}>
+  <Radio value="free" icon={<StorageIcon size={20} />} description="Up to three projects">
+    Starter
+  </Radio>
+  <Radio value="team" description="No limits">Team</Radio>
+</RadioGroup>
+
+<CheckboxGroup label="Modules" appearance="card" value={modules} onChange={setModules}>
+  <Checkbox value="billing" icon={<PaymentIcon size={20} />}>Payments</Checkbox>
+</CheckboxGroup>
+```
+
+- **The axis is called `appearance`, not `variant`**: in the kit `variant` already
+  means `solid|soft|outline|ghost`, that is, how a tone is presented, while here
+  the look of the option itself changes: a row or a card. Values: `default` (the
+  default; look and behavior unchanged) and `card`. The prop-name dictionary of the
+  mirror (ADR-0036) does not use this name.
+- The axis lives on the group and reaches the options through context, like `size`
+  and `tone`: the set cannot drift apart in look. A single `Checkbox` outside a
+  group stays the regular one.
+- **The whole card is the hit area**, including the description and the empty
+  space of the card. The semantics are native: react-aria's `radio` or `checkbox`,
+  which also provides the arrow keys and Space. The description sits inside the
+  `<label>` element so that a click
+  on it selects the card, but it is hidden from the name (`aria-hidden`) and read
+  as a description through `aria-describedby`: a screen reader does not read it
+  twice. The icon is decorative and excluded from the name.
+- **Selection is a border in the tone and an indicator.** The circle or the
+  checkmark stay visible; the border is not the only sign. The tone is the group's
+  `tone` (optional on `CheckboxGroup`, see "Group tone"). Unselected cards are
+  neutral. The contrast of the selected card's border against the backgrounds and
+  against the card itself is measured by `npm run contrast` (threshold 3:1, WCAG
+  1.4.11); for `neutral` the border is `fg-3`, not the decorative `line`.
+- The focus ring is on the card, not on the circle.
+- `orientation="horizontal"` lays the cards out in a wrapping row; the vertical
+  layout is cards at the full width of the column.
+- Disabled and error work as in the regular groups: a disabled card is
+  semi-transparent and cannot be selected, `errorMessage` colors the border of all
+  cards `danger` and replaces the group's `description`.
+- `icon` applies without a card too: in the default appearance the icon sits
+  between the circle or box and the label.
+
+**An axis "for the future" (ADR-0048).** There was no requesting screen at release, so the
+API is modeled on comparable libraries: Chakra `RadioCard` and `CheckboxCard`,
+Mantine `Radio.Card`, Carbon `SelectableTile`, Cloudscape `Tiles`. Your screen is
+the first test of this API. Not included and not planned for now: an image slot
+over the icon, selecting a whole card rendered as a link.
+
+## Accessibility and forms
+
+- The group label is required: it is the question the set answers.
+- Do not pass `checked` to child Checkboxes inside a CheckboxGroup — the state is derived from the group's `value`.
+- Do not set `tone` on a `Checkbox` inside a `CheckboxGroup` that has a `tone`: it is ignored: the set has one tone for all. If you want different tones, do not set `tone` on the group.
+- Sources: `src/components/inputs/Checkbox.tsx`, `src/components/inputs/CheckboxGroup.tsx`, `src/components/inputs/CheckboxCard.tsx` (the card is internal, only the group pulls it in, so that a bare `Checkbox` does not drag it into the bundle), `src/components/inputs/RadioGroup.tsx`, the shared card classes are in `src/lib/choice-card.ts`; tests `checkbox*.test.tsx`, `radio-group.test.tsx`, `choice-cards.test.tsx`.

package/docs/components/inputs/choice-controls.md

@@ -0,0 +1,112 @@
+---
+component: Choice controls
+exports: [Checkbox, CheckboxGroup, Radio, RadioGroup]
+category: inputs
+status: stable
+source: src/components/inputs/Checkbox.tsx
+story: src/components/inputs/Checkbox.stories.tsx
+---
+
+# Checkbox, CheckboxGroup, Radio и RadioGroup
+
+## Кратко для AI
+
+`Checkbox` выбирает независимое «да/нет», `CheckboxGroup` — несколько значений, `RadioGroup` — один ответ на общий вопрос. `Radio` существует только внутри `RadioGroup`. Ось `appearance="card"` у обеих групп показывает варианты карточками с подписью, описанием и значком.
+
+## Когда использовать
+
+- `Checkbox`: отдельная настройка, включая `indeterminate` для состояния «часть выбрана».
+- `CheckboxGroup`: несколько независимых вариантов, `value` — массив строк.
+- `RadioGroup`: ровно один вариант из взаимоисключающего набора; `value` хранится на группе.
+- `appearance="card"`: два-пять вариантов, которые сравнивают до выбора: тариф, формат выгрузки, режим доступа, набор модулей. Подробности — в разделе «Карточки выбора».
+
+## Когда не использовать
+
+- Не используйте RadioGroup для нескольких фильтров — берите CheckboxGroup или ToggleGroup.
+- Не снимайте выбор RadioGroup «кликом по выбранному»; добавьте явный вариант «Любой».
+- Не используйте карточки для длинного списка однотипных значений и для настроек в одну строку: карточка занимает три-четыре строки, и десять карточек читаются хуже десяти строк. Там — обычный вид.
+- Не используйте Checkbox без `children` или `label`: у него должно быть доступное имя.
+
+## Минимальный пример
+
+```tsx
+<CheckboxGroup label="Каналы" value={channels} onChange={setChannels}>
+  <Checkbox value="telegram">Telegram</Checkbox>
+</CheckboxGroup>
+
+<RadioGroup label="Вид" value={view} onChange={setView}><Radio value="list">Список</Radio></RadioGroup>
+```
+
+## Public API
+
+- `Checkbox`: controlled `checked`/`onCheckedChange` или `defaultChecked`; `indeterminate` при отрисовке важнее checked. `name` и `value` предназначены для native form submit.
+- `CheckboxGroup`: обязательные `value`, `onChange`, `label`; `errorMessage` заменяет `description`, а `disabled` выключает всех детей. Необязательный `tone` красит отмеченные флажки набора (см. ниже).
+- `RadioGroup`: `value: string | null`, но `onChange` возвращает string; `null` — только начальное пустое состояние. `Radio` принимает `value`, описание и disabled.
+- У обеих групп есть `orientation`, `errorMessage`, `appearance` и `tone`; RadioGroup также задаёт общий `size`.
+- **Тон набора.** `tone` у группы приходит вариантам контекстом и красит отмеченное: кружок и точку, коробку с галочкой и (в карточках) рамку выбранной. У `RadioGroup` тон есть только у группы, у `Radio` своего нет. У `CheckboxGroup` тон необязателен: **заданный `tone` группы перекрывает `tone` каждого `Checkbox` внутри** (набор не может разъехаться по виду, как у радио); не заданный — каждый флажок красится своим `tone`, как и вне группы. Одиночный `Checkbox` вне группы работает со своим `tone` как раньше. Неотмеченные всегда нейтральны.
+- `Radio` и `Checkbox` принимают необязательный `icon` и `description`.
+- **Рамка отмеченной коробки.** У отмеченного (и «часть выбрана») флажка коробка обведена рамкой в `*-strong` своего тона, у `neutral` — `fg-3`: заливка `solid` против подложки не дотягивает до 3:1 (WCAG 1.4.11) у четырёх тонов из пяти, а менять токены ради флажка не стали. Границу коробки держит рамка, галочку — контраст текста на заливке. То же у включённого `Toggle`. Меряет `npm run contrast`. **Это осознанное решение владельца, а не недоработка:** заливку отмеченного флажка до 3:1 не поднимали, потому что её цвет задают токены `solid` тонов, общие для всего кита.
+
+## Зона нажатия
+
+Зона нажатия флажка и радио — 24 пикселя по высоте независимо от размера и
+наличия видимой подписи; столько требует WCAG 2.5.8. Сам контрол при этом занимает в
+раскладке прежнее место: зона расширена псевдоэлементом.
+
+Отступами её поднимать нельзя: высоту контрола держит строка списка, 32
+пикселя, и выросший флажок растянул бы её. Видимый размер и размер зоны нажатия
+разведены так же, как у `Button size="xs"`.
+
+## Карточки выбора
+
+```tsx
+<RadioGroup label="Тариф" appearance="card" value={plan} onChange={setPlan}>
+  <Radio value="free" icon={<StorageIcon size={20} />} description="До трёх проектов">
+    Стартовый
+  </Radio>
+  <Radio value="team" description="Без ограничений">Команда</Radio>
+</RadioGroup>
+
+<CheckboxGroup label="Модули" appearance="card" value={modules} onChange={setModules}>
+  <Checkbox value="billing" icon={<PaymentIcon size={20} />}>Платежи</Checkbox>
+</CheckboxGroup>
+```
+
+- **Ось называется `appearance`, а не `variant`**: `variant` в ките уже значит
+  `solid|soft|outline|ghost`, то есть подачу тона, а здесь меняется вид самого
+  пункта набора: строка или карточка. Значения: `default` (умолчание, вид и поведение
+  прежние) и `card`. Словарь имён свойств зеркала (ADR-0036) имени не занимает.
+- Ось живёт у группы и приходит вариантам контекстом, как `size` и `tone`: набор
+  не может разъехаться по виду. Одиночный `Checkbox` вне группы остаётся обычным.
+- **Вся карточка — зона нажатия**, включая описание и пустое место карточки.
+  Семантика родная: `radio` или `checkbox` из react-aria, он же обеспечивает
+  стрелки и пробел. Описание лежит внутри элемента `<label>`, чтобы щелчок по нему выбирал карточку, но скрыто от имени
+  (`aria-hidden`) и читается как описание через `aria-describedby`: скринридер не
+  читает его дважды. Иконка декоративная и из имени исключена.
+- **Выбранность — рамка в тоне и индикатор.** Кружок или галочка остаются видимыми,
+  рамка не единственный признак. Тон — `tone` у группы (у `CheckboxGroup` он
+  необязателен, см. «Тон набора»). Невыбранные карточки нейтральны.
+  Контраст рамки выбранной карточки против подложек и против самой карточки меряет
+  `npm run contrast` (порог 3:1, WCAG 1.4.11); для `neutral` рамка — `fg-3`, а не
+  декоративная `line`.
+- Кольцо фокуса — на карточке, а не на кружке.
+- `orientation="horizontal"` раскладывает карточки в строку с переносом; вертикальная
+  раскладка — карточки во всю ширину колонки.
+- Отключение и ошибка работают как у обычных групп: выключенная карточка
+  полупрозрачна и не выбирается, `errorMessage` красит рамку всех карточек в `danger`
+  и заменяет `description` группы.
+- `icon` работает и без карточки: в обычном виде иконка стоит между кружком или
+  коробкой и подписью.
+
+**Ось «на будущее» (ADR-0048).** Заказчика при выпуске не было, API взят по
+аналогам — Chakra `RadioCard` и `CheckboxCard`, Mantine `Radio.Card`, Carbon
+`SelectableTile`, Cloudscape `Tiles`. Ваш экран — первая проверка этого API. Не
+вошло и пока не заводится: слот картинки поверх иконки,
+выбор карточки целиком в виде ссылки.
+
+## Доступность и форма
+
+- Подпись группы обязательна: это вопрос, на который отвечает набор.
+- Не передавайте `checked` дочерним Checkbox внутри CheckboxGroup — состояние выводится из `value` группы.
+- Не задавайте `tone` у `Checkbox` внутри `CheckboxGroup` с заданным `tone`: он игнорируется, тон набора один на всех. Хотите разные тона — не задавайте `tone` у группы.
+- Источники: `src/components/inputs/Checkbox.tsx`, `src/components/inputs/CheckboxGroup.tsx`, `src/components/inputs/CheckboxCard.tsx` (карточка — внутренняя, её подключает только группа, чтобы голый `Checkbox` не тянул её в бандл), `src/components/inputs/RadioGroup.tsx`, общие классы карточки — `src/lib/choice-card.ts`; тесты `checkbox*.test.tsx`, `radio-group.test.tsx`, `choice-cards.test.tsx`.