@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/theming.md

@@ -0,0 +1,518 @@
+# Темы, токены и бренды
+
+Страница отвечает на три вопроса: как устроены цвета кита, что из этого можно
+переопределять у себя и как завести собственный бренд.
+
+Источник значений — [`styles.css`](../styles.css). Здесь описан контракт: имена,
+слои и правила. Значения меняются в файле, а не здесь.
+
+## Четыре слоя
+
+| Слой            | Что это                                           | Имена                                    | Правит потребитель      |
+| --------------- | ------------------------------------------------- | ---------------------------------------- | ----------------------- |
+| 1. Примитивы    | Палитра: цвет как значение, без роли и без темы   | `--od-<семья>-<шаг>`                     | **нет**                 |
+| 2. Семантика    | Роль: что чем красится                            | `--surface-*`, `--text-*`, `--accent*` … | да, осторожно           |
+| 3. Компонентные | Отличия одной семьи компонентов от общего правила | закрытый список ниже                     | да                      |
+| 4. Бренд        | Блок `[data-brand="…"]` поверх слоёв 2 и 3        | примитивы бренда + присвоения ролей      | **да, это точка входа** |
+
+Правило чтения: **слой ниже не знает о слое выше**. `--od-slate-1` не знает, что
+он фон приложения; это знает `--surface-app`. Компонент не знает ни того, ни
+другого — он пишет класс `bg-bg-0`, за которым стоит мост `@theme`.
+
+### Слой 1 — примитивы
+
+Три нейтральных ramp'а, по одному на тему (`slate` — тёмная, `cloud` — светлая,
+`navy` — сумрак), и семь тоновых семей. Внутри ramp'а шаг растёт по светлоте:
+1 — самый тёмный, 12 — самый светлый.
+
+Три ramp'а вместо одного — не дублирование: нейтрали каждой темы подобраны
+руками под свой фон, и свести их к одной шкале значило бы перекрасить две
+темы из трёх.
+
+**Переопределять примитивы у себя не нужно и не поддерживается.** `--od-blue-3`
+принадлежит палитре кита; его правка задела бы всё, что на нём стоит, включая
+темы, о которых вы не думали. Точка правки — слой 4.
+
+Полупрозрачные примитивы называются `--od-<семья>-<шаг базы>-a<альфа>`
+(`--od-blue-4-a16` — четвёртый шаг синего с альфой 0.16) и **зашивают альфу в
+значение**, а не считают её через `color-mix`. Причина прикладная:
+`scripts/contrast.mjs` разбирает `var(--x)` и цвета, записанные литералами, но не вычисляемые
+выражения. Если бы кит считал `*-soft` через `color-mix`, гейт контраста ослеп бы ровно
+на тех токенах, ради которых написан.
+
+### Слой 2 — семантика
+
+Роли: поверхности (`--surface-app`, `--surface-panel`, …), текст
+(`--text-primary` … `--text-disabled`), рамки, роли тонов:
+`accent`, `success`, `warning`, `danger` и вне словаря тонов `draft`.
+Здесь же живут тени `--shadow-1`, `--shadow-2` — шкала высоты уровня системы.
+
+У каждого тона два токена, потому что у него две несовместимые роли: `--<тон>`
+— заливка под контрастным текстом (темнее), `--<тон>-strong` — тот же тон как
+текст, рамка и индикатор на фоне (в тёмных темах светлее). Одним значением
+обе не закрыть; подробности и числа — в комментариях `styles.css`.
+
+**Инверсная поверхность** — отдельная группа ролей для плашки,
+которая стоит прямо на Документе и обязана отличаться от него знаком, а не
+шагом: Меню выделения Редактора. `--surface-inverse` (фон),
+`--surface-inverse-hover` и `--surface-inverse-pressed` (наведение и нажатие),
+`--text-on-inverse` (текст и иконки) — светлые в `dark` и `dim`, тёмные в
+`light`. Контур фокуса на ней — `--accent-on-inverse`: это `--accent-strong`
+противоположной темы, поэтому акцент и бренд задают его зеркально. Значения
+и пары контраста — [palette.md](palette.md#инверсная-поверхность).
+
+Алиасы `--bg-0…4`, `--fg-0…4`, `--line`, `--tg`, `--ok`, `--warn`, `--err` —
+слой совместимости. Именно ими красятся компоненты — через классы Tailwind
+(`bg-bg-1`, `text-fg-2`). Заводить новые не нужно.
+
+### Слой 3 — компонентные токены
+
+Список **закрытый**. Компонентный токен заводится, когда у семьи есть настоящая
+причина отличаться от семантики, а не «на всякий случай»; токен без читателя не
+заводится вовсе.
+
+| Токен                   | Кто читает                                           |
+| ----------------------- | ---------------------------------------------------- |
+| `--overlay-scrim`       | `Dialog`, `Drawer`, `CommandPalette`, `ModalOverlay` |
+| `--modal-shadow`        | `Dialog`                                             |
+| `--topbar-bg`           | `SelectionBar` в прилипшем состоянии, `TopBar`       |
+| `--sidenav-w`           | `SideNav`, сетка `AppShell` — развёрнутая ширина     |
+| `--sidenav-w-collapsed` | они же в иконочном режиме                            |
+| `--marker-<имя>`        | маркер `RichTextEditor` и `RichTextView` — девять    |
+| `--marker-text`         | тёмный текст на любом маркере, один во всех темах    |
+
+**`--marker-<имя>` — девять токенов маркера Редактора** (`gray`, `brown`, `orange`,
+`yellow`, `green`, `blue`, `purple`, `pink`, `red`). Три из них
+(`yellow`, `green`, `pink`) яркие и **одинаковы во всех темах**, их объявляет блок
+`:root, [data-theme]` без пары; шесть прежних («читаемые», в меню Панели
+их нет) имеют своё значение у темы: пастель в `light`, приглушённый тёмный в
+`dark` и `dim`. Текст на маркере тёмный — токен `--marker-text`. Отличие от
+остальных токенов слоя — **селектор**: они объявлены на `[data-theme="…"]` любого
+элемента, а не на `:root[data-theme="…"]`, и читаются переменной напрямую
+(`bg-(--marker-yellow)`), без моста `@theme`. Поэтому во вложенной обёртке с
+другой темой маркер берёт значение ближайшей темы. Мост объявлен на корне, и
+`var()` в нём подставляется там — через него вложенная тема не сработала бы.
+Тёмный текст `--marker-text` держит контраст 4.5:1 на яркой тройке во всех темах, а основной текст — на шести читаемых маркерах (`npm run contrast`).
+
+`--topbar-bg` назван по роли, а не по читателю: это
+полупрозрачный фон шапки.
+
+**Ширины сайдбара — переменные, а не пропы.** Значение нужно одновременно
+сайдбару и сетке каркаса, а мобильную раскладку переключает CSS, а не
+JavaScript: число, идущее пропом в два компонента, — это ререндер ради того, что
+CSS умеет прочитать сам. От темы ширины не зависят и в блоках тем не
+повторяются. Менять их достаточно в одном месте:
+
+```css
+:root {
+  --sidenav-w: 280px;
+}
+```
+
+**`--topbar-h` в этот список не входит: это не токен, а измерение.** У неё нет
+значения по умолчанию, которое имело бы смысл, и место её не в слоях темы.
+Публикует её тот, у кого шапка: с 2.1.0 это `TopBar` кита
+(ADR-0019), а у
+приложения со своей шапкой — по-прежнему само приложение
+(ADR-0016). Кит её
+читает — `useStickyOffset`.
+
+**Нижний край устроен так же: `--bottombar-h`.** Её публикует слот `bottomBar`
+у `AppShell` (имя — проп `bottomBarHeightVar`), а читают липнущие к низу
+`ContextualSaveBar` и `Toaster`. На `md` и шире нижняя панель скрыта и значение равно
+`0px`; без слота переменной нет, и читатели берут запасное `0px`. Тоже
+измерение, а не токен: значения по умолчанию у неё нет.
+
+## Типографическая шкала
+
+Размер текста берётся из шкалы в семь ступеней. Ступень — пара «кегль / строка»,
+объявленная в [`styles.css`](../styles.css) как `--text-<ступень>` и
+`--text-<ступень>--line-height`; Tailwind превращает её в класс `text-<ступень>`.
+
+| Класс          | Размер / строка | Где стоит                                      |
+| -------------- | --------------- | ---------------------------------------------- |
+| `text-caption` | 11 / 16         | подписи полей, uppercase                       |
+| `text-xs`      | 12 / 16         | счётчики, пояснения                            |
+| `text-sm`      | 13 / 20         | рабочий размер кита — подписи кнопок и пунктов |
+| `text-md`      | 14 / 20         | основной текст                                 |
+| `text-lg`      | 16 / 24         | подзаголовки                                   |
+| `text-xl`      | 20 / 28         | заголовки секций                               |
+| `text-2xl`     | 26 / 32         | заголовок страницы                             |
+
+**У каждой ступени задана высота строки.** Без неё высота выводится из
+унаследованного множителя `1.5` и получается дробной: соседние контролы
+расходятся по высоте на доли пикселя.
+
+**Шкала переопределяет три штатные ступени Tailwind, а не дополняет их:**
+
+| Класс      | Tailwind | Кит     | Сдвиг |
+| ---------- | -------- | ------- | ----- |
+| `text-sm`  | 14 / 20  | 13 / 20 | −1 px |
+| `text-lg`  | 18 / 28  | 16 / 24 | −2 px |
+| `text-2xl` | 24 / 32  | 26 / 32 | +2 px |
+
+`text-caption` и `text-md` — свои ступени: у Tailwind вместо `text-md` стоит
+`text-base`. Шкала кита начинается ниже штатной, потому что рабочий размер здесь
+13 пикселей.
+
+**Для приложения это молчаливое изменение.** `styles.css` подключается в CSS
+приложения, поэтому переопределение действует и на ваши собственные классы:
+после подключения `styles.css` класс `text-sm` в вашей разметке станет 13 пикселей вместо 14,
+`text-lg` — 16 вместо 18, `text-2xl` — 26 вместо 24. Ни сборка, ни типы этого не
+заметят. Прежние 14 пикселей даёт `text-md`; для остальных размеров, которые
+должны остаться прежними, задайте значение литералом (`text-[18px]`). Не
+переопределяйте `--text-sm`, `--text-lg` и `--text-2xl` обратно: на них стоят и
+компоненты кита.
+
+Не все компоненты берут размер из шкалы. Часть задаёт его литералом
+(`text-[13px]`, `text-[11px]`), и такой размер переопределение `--text-*`
+не сдвигает. Новые компоненты кита берут ступени.
+
+## Движение
+
+### Шкала: четыре ступени и три кривые
+
+Длительность и кривая берутся из шкалы, а не придумываются. Обе шкалы закрыты:
+пятая ступень — разбор в ADR, а не строка в `styles.css`
+(ADR-0047).
+
+| Ступень               | Значение | Когда                              |
+| --------------------- | -------- | ---------------------------------- |
+| `--duration-fast`     | 100ms    | наведение, нажатие, шеврон, флажок |
+| `--duration-base`     | 150ms    | подсказка, якорная панель, меню    |
+| `--duration-moderate` | 250ms    | окно, ящик, затемнение, раскрытие  |
+| `--duration-slow`     | 400ms    | крупное перемещение по экрану      |
+
+| Кривая            | Значение                     | Когда                     |
+| ----------------- | ---------------------------- | ------------------------- |
+| `--ease-standard` | `cubic-bezier(0.2, 0, 0, 1)` | перемещение внутри экрана |
+| `--ease-enter`    | `cubic-bezier(0, 0, 0.2, 1)` | вход: замедление к месту  |
+| `--ease-exit`     | `cubic-bezier(0.4, 0, 1, 1)` | выход: ускорение прочь    |
+
+Имена по роли, а не по значению: `duration-fast`, не `duration-100`. Ступень
+пишется классом — `duration-moderate`, `ease-enter`; кривые Tailwind заводит из
+темы сам, ступени объявлены в `styles.css` через `@utility`.
+
+**Длительность называется только там, где она отличается от умолчания.**
+Умолчание переходов Tailwind переведено на шкалу:
+
+```css
+--default-transition-duration: var(--duration-base);
+--default-transition-timing-function: var(--ease-standard);
+```
+
+Поэтому `transition-colors` без класса длительности уже идёт 150ms по кривой
+`standard`, и `transition-colors duration-base` — лишнее слово. Отсюда же рычаг
+темпа у потребителя: переопределив ступень у себя, вы сдвигаете все переходы
+кита, у которых длительность не названа явно.
+
+```css
+:root {
+  --duration-base: 120ms; /* плотная админка: весь кит становится резче */
+}
+```
+
+Живая шкала — в витрине, раздел `Foundations/Motion`.
+
+### Анимации
+
+Анимации кита объявлены токенами `--animate-*` в том же `@theme`, что и цвета.
+Токен — единственная точка, где у анимации есть длительность и кривая; в
+компонентах их нет. В таблицах ниже — токены, которые читают компоненты кита.
+
+| Токен                              | Кто читает                             |
+| ---------------------------------- | -------------------------------------- |
+| `--animate-fadein`                 | затемнение окон, список меню, `Select` |
+| `--animate-sheetin`                | `Dialog`, `ModalOverlay`               |
+| `--animate-popoverIn`              | `Popover`                              |
+| `--animate-tooltipIn`              | `Tooltip`                              |
+| `--animate-shimmer`                | `.skeleton`                            |
+| `--animate-progress-indeterminate` | `Progress`, когда доля неизвестна      |
+| `--animate-spin`                   | `Spinner`                              |
+
+**Уход оверлеев — свои токены, короче входа.** Пара `-in` / `-out` читается с
+одного взгляда, а ступень выхода на одну ниже: закрытие не должно ощущаться
+медленнее открытия.
+
+| Токен                  | Кто читает                           | Ступень        |
+| ---------------------- | ------------------------------------ | -------------- |
+| `--animate-fadeout`    | затемнение окон, меню, `ContextMenu` | `base` → 150ms |
+| `--animate-rowout`     | уход строки `EditableList`           | `base` → 150ms |
+| `--animate-sheetout`   | `Dialog`                             | 150ms          |
+| `--animate-tooltipOut` | `Tooltip`                            | 100ms          |
+| `--animate-popoverOut` | `Popover`                            | 100ms          |
+
+Уход задаётся **токеном, а не `opacity-0`**: переход в ноль без длительности —
+это не выход, а то же мгновенное пропадание, записанное длиннее, и гейт `reduce`
+такой записи не видит.
+
+Парность `-in` / `-out` — соглашение, а не правило гейта: у `imgFadeIn` выхода
+нет и быть не должно, а `shimmer`, `spin` и `pulse` — циклы, а не переходы.
+
+**У `ModalOverlay` ухода нет.** У него нет пропа `open`: затемнение монтирует
+условием потребитель, и к моменту закрытия узла уже нет в дереве. Разбор — в
+самом файле компонента.
+
+**При `prefers-reduced-motion: reduce` кит гасит своё движение сам.** Токены
+переопределяются одним блоком в конце `styles.css`: перемещающие кейфреймы
+заменяются на `fadeOnly` — та же длительность и кривая, только прозрачность.
+Движение снимается, но элемент всё равно появляется: `animation: none` дал бы не покой, а
+рывок.
+
+Два токена не гасятся — `--animate-progress-indeterminate` и `--animate-spin`.
+Оба сообщают «идёт работа», и остановленными читаются как поломка, а не как
+тишина. Разбор — ADR-0043.
+
+Переходы цвета (`transition-colors`, `transition-shadow`, `transition-opacity`)
+не гасятся: правило про движение, а смена цвета ничего не перемещает.
+Перемещающие переходы — вращение шевронов у `Accordion`, `Table` и `TreeView` —
+гасятся вариантом `motion-reduce:` по месту: за ними стоят зашитые значения
+Tailwind, а не переменная кита.
+
+**Граница с приложением.** Кит гасит только токены и классы кита.
+Глобального сброса вида `*, ::before, ::after { animation-duration: 0.01ms
+!important }` в пакете нет и не будет: он погасил бы анимации приложения и сторонних
+библиотек на той же странице, а снять это было бы нечем. Анимации
+приложения гасите вы сами, тем же приёмом:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --my-slide-in: none;
+  }
+}
+```
+
+Токен `--animate-*`, который вы завели сами поверх кита, обязан получить пару в блоке
+`reduce`: иначе `tests/motion.test.ts` уронит сборку кита, но не вашу, и следить за этим
+у себя вам.
+
+## Темы и акценты
+
+Две независимые оси на `<html>`:
+
+```html
+<html data-theme="light" data-accent="violet"></html>
+```
+
+`data-theme` — `dark` (умолчание, атрибут можно не ставить), `light`, `dim`.
+`data-accent` — `blue` (умолчание), `violet`.
+
+Оси независимы везде, кроме одного места: `--accent-strong` читается
+**на** фоне, и светлой теме нужен тёмный акцент вместо светлого. Поэтому в
+файле есть парный блок `:root[data-theme="light"][data-accent="violet"]` — он
+специфичнее и стоит после обоих.
+
+## Как завести бренд
+
+Бренд — это **один блок CSS**. Ни один компонент при этом не правится; если
+пришлось править компонент, значит от бренда ждут того, чего слой токенов не
+выражает, и это отдельный разговор.
+
+Порядок ровно такой и проверен на `teal`, который лежит в пакете как образец:
+
+**1. Объявите примитивы бренда внутри его блока.** Не переопределяйте `--od-*`
+кита.
+
+```css
+:root[data-brand="acme"] {
+  --od-acme-1: #7a2e0e;
+  --od-acme-2: #9a3412;
+  --od-acme-3: #f97316;
+  --od-acme-4: #fdba74;
+  --od-acme-3-a16: rgba(249, 115, 22, 0.16);
+  --od-acme-3-a20: rgba(249, 115, 22, 0.2);
+  --od-acme-3-a35: rgba(249, 115, 22, 0.35);
+  --od-acme-2-a30: rgba(154, 52, 18, 0.3);
+
+  /* 2. Присвойте их ролям. */
+  --accent: var(--od-acme-2);
+  --accent-hover: var(--od-acme-1);
+  --accent-soft: var(--od-acme-3-a16);
+  --accent-strong: var(--od-acme-4);
+  --focus-ring: var(--od-acme-3-a20);
+  /* Контур фокуса на инверсной плашке: тёмный шаг — плашка в тёмных темах светлая. */
+  --accent-on-inverse: var(--od-acme-1);
+  /* Выделение текста: светлая ступень под тёмную подложку и вариант для светлой.
+     `--selection-dark` берёт и поле HTML Редактора, тёмное в любой теме. */
+  --selection-dark: var(--od-acme-3-a35);
+  --selection: var(--selection-dark);
+  --selection-light: var(--od-acme-2-a30);
+}
+```
+
+**3. Проверьте светлую тему отдельно.** `--accent-strong` читается на фоне,
+и светлой теме почти наверняка понадобится свой шаг; `--accent-on-inverse` —
+наоборот, светлый: плашка Меню выделения в светлой теме тёмная. `--selection`
+вернётся к светлому варианту только здесь: блок бренда стоит ниже светлой темы
+и перекрыл бы его тёмным.
+
+```css
+:root[data-theme="light"][data-brand="acme"] {
+  --accent-strong: var(--od-acme-1);
+  --accent-on-inverse: var(--od-acme-4);
+  --selection: var(--selection-light);
+}
+```
+
+**4. Поставьте блоки в конец файла — после блоков акцента.** Это не стиль, а
+работающее правило: `:root[data-brand]` и `:root[data-accent]` имеют одинаковую
+специфичность (0,2,0), и при равной специфичности побеждает тот, кто ниже.
+Заданный бренд обязан отменять ось акцента целиком, а не смешиваться с ней.
+Парный блок с темой берёт два атрибута (0,3,0) и стоит после парного блока темы
+с акцентом — по той же причине.
+
+**5. Внесите бренд в `BRANDS` в `scripts/contrast.mjs` и прогоните `npm run contrast`.**
+Скрипт **упадёт**, если бренд объявлен в CSS и не внесён в список: гейт обязан
+либо мерить бренд, либо сказать, что не может. Бренд, не проходящий по
+контрасту, — это бренд, которого нет.
+
+Так и получился `teal`: первый подбор давал 4.26 при требуемых 4.5 на
+`--accent-soft` поверх `surface-panel-hover` в светлой теме, и гейт это показал.
+Пример не подогнан задним числом — он прошёл ту же проверку, что предстоит вам.
+
+**6. Включите бренд на `<html>`:**
+
+```html
+<html data-theme="light" data-brand="acme"></html>
+```
+
+Порядок и структура блоков проверяются тестом
+[`tests/token-layers.test.ts`](../tests/token-layers.test.ts): он падает, если
+блок бренда уехал выше акцента, если бренд переопределяет примитив кита или
+задаёт роль, которой нет в базе.
+
+## Переключатель темы
+
+**Компонента переключателя в ките нет и не будет** — это решение, а не пробел
+(ADR-0020). `Segmented` уже
+даёт нужную форму, а кнопка завязана на хранилище и раскладку конкретного
+приложения. Кит отдаёт то, что действительно повторяется: списки осей,
+нормализацию, применение и скрипт раннего применения — см.
+[api/utilities.md](api/utilities.md).
+
+Подписи тем — **строки приложения**, а не каталога кита: кит не переводит то,
+чего не рендерит.
+
+### Общая часть
+
+```tsx
+import { applyTheme, normalizeTheme, UI_THEMES, type UiTheme } from "@olddevs/ui";
+import { ThemeAutoIcon, ThemeDarkIcon, ThemeLightIcon } from "@olddevs/ui/icons";
+
+/**
+ * Названий два, потому что они стоят в разных падежах: «Тема: тёмная» —
+ * именительный, «Переключить на тёмную» — винительный. Одна строка на оба места
+ * даёт «переключить на светлая», и скринридер читает это вслух.
+ */
+const THEMES = {
+  dark: { name: "тёмная", target: "тёмную", icon: <ThemeDarkIcon /> },
+  light: { name: "светлая", target: "светлую", icon: <ThemeLightIcon /> },
+  dim: { name: "сумрак", target: "сумрак", icon: <ThemeAutoIcon /> },
+} satisfies Record<UiTheme, { name: string; target: string; icon: React.ReactNode }>;
+
+const STORAGE_KEY = "ui-prefs";
+
+function useTheme() {
+  const [theme, setTheme] = useState<UiTheme>(() => {
+    if (typeof window === "undefined") return "dark";
+    try {
+      return normalizeTheme(JSON.parse(localStorage.getItem(STORAGE_KEY) ?? "{}").theme);
+    } catch {
+      return "dark";
+    }
+  });
+
+  const change = (next: UiTheme) => {
+    setTheme(next);
+    applyTheme(document.documentElement, { theme: next });
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ theme: next }));
+  };
+
+  return [theme, change] as const;
+}
+```
+
+Формат хранения тот же, что читает `themeInitScript` — подключите его, иначе
+пользователь увидит вспышку чужой темы до гидратации.
+
+### Форма 1 — явный выбор
+
+Три сегмента подряд. Берите её там, где место есть: настройки, панель профиля.
+
+```tsx
+import { Segmented } from "@olddevs/ui";
+
+function ThemePicker() {
+  const [theme, setTheme] = useTheme();
+  return (
+    <Segmented
+      value={theme}
+      onChange={setTheme}
+      options={UI_THEMES.map((value) => ({
+        value,
+        label: "",
+        icon: THEMES[value].icon,
+        tooltip: `Тема: ${THEMES[value].name}`,
+      }))}
+    />
+  );
+}
+```
+
+`label: ""` рядом с иконкой — штатный способ сказать «только иконка»; доступное
+имя сегмент берёт из `tooltip`, и без него аудит роняет прогон.
+
+### Форма 2 — цикл одной кнопкой
+
+Одна кнопка, перебирающая темы по кругу. Берите её в шапке, где места нет.
+
+```tsx
+import { Button, Tooltip } from "@olddevs/ui";
+
+function ThemeCycleButton() {
+  const [theme, setTheme] = useTheme();
+  const next = UI_THEMES[(UI_THEMES.indexOf(theme) + 1) % UI_THEMES.length]!;
+  const label = `Тема: ${THEMES[theme].name}. Переключить на ${THEMES[next].target}`;
+
+  return (
+    <Tooltip content={label}>
+      <Button
+        variant="ghost"
+        iconOnly
+        icon={THEMES[theme].icon}
+        aria-label={label}
+        onClick={() => setTheme(next)}
+      />
+    </Tooltip>
+  );
+}
+```
+
+**Подпись обязана называть и текущее состояние, и следующий шаг** — и это не
+стилистика. Без текущего скринридер объявит кнопку без состояния: ровно тот
+дефект, который был у переключателя в приложении-источнике до его
+переписывания. Без следующего шаг не угадать, потому что у цикла из **трёх**
+состояний он из иконки не выводится — у двух вывелся бы, и там хватило бы одной
+половины.
+
+Тот же текст идёт в подсказку: зрячий пользователь стоит перед той же задачей,
+что и пользователь скринридера.
+
+## Чего делать не стоит
+
+- **Переопределять примитивы кита.** См. слой 1.
+- **Красить компонент мимо токена.** Литеральный цвет в разметке не переживёт ни
+  смены темы, ни бренда, и не попадёт в гейт контраста.
+- **Заводить свой токен «под будущее».** Слой 3 закрыт намеренно.
+- **Ставить блок бренда выше акцента.** Работать будет через раз — там, где
+  акцент не задан.
+- **Считать `*-soft` через `color-mix`.** Гейт контраста перестанет их видеть.
+- **Задавать анимацию литералом, а не через `var(--animate-*)`.** Правило, не читающее
+  `var(--animate-*)`, не подчиняется блоку `prefers-reduced-motion` — оно просто
+  продолжает бежать.
+
+## Что дальше
+
+- [Подключение пакета](getting-started.md) — `@import` и `@source` у потребителя.
+- [Соглашения](conventions.md) — словарь пропсов и границы public API.