@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/palette.md

@@ -0,0 +1,396 @@
+# Палитра
+
+Страница показывает значения цветов кита: какие примитивы палитры (кроме меток) объявлены и какой роли
+каждый из них присвоен в каждой теме. Контракт имён и слоёв описан в
+[Темы, токены и бренды](theming.md) — здесь только числа.
+
+Источник правды — [`styles.css`](../styles.css). Таблицы ниже переписаны из него
+вручную, поэтому правило одно: **меняете токен — правьте файл, а страницу
+приводите в соответствие тем же изменением.** Разошедшаяся таблица хуже
+отсутствующей.
+
+## Как читать
+
+Цвет проходит три шага, и на каждом у него своё имя:
+
+```
+--od-blue-6  →  --accent-strong  →  text-accent-strong
+  примитив          роль               класс Tailwind
+```
+
+Компонент пишет класс, класс стоит на роли, роль берёт примитив. Тема меняет
+только средний шаг: `--accent-strong` в светлой теме указывает на `--od-blue-2`
+вместо `--od-blue-6`, а класс и значение самого примитива остаются прежними.
+
+## Слой 1 — примитивы
+
+### Нейтрали
+
+Три шкалы, по одной на тему. Шаг растёт по светлоте: 1 — самый тёмный, 12 —
+самый светлый. Направление использования у тёмных шкал и у светлой
+**противоположное**: в `slate` и `navy` нижние ступени — фоны, верхние —
+текст; в `cloud` наоборот, единица — чернила, двенадцать — белая бумага.
+
+| Шаг | `--od-slate-*` (dark) | `--od-cloud-*` (light) | `--od-navy-*` (dim) |
+| --- | --------------------- | ---------------------- | ------------------- |
+| 1   | `#26272d`             | `#17212b`              | `#15202b`           |
+| 2   | `#2e2f36`             | `#45515f`              | `#1e2732`           |
+| 3   | `#363740`             | `#545f6e`              | `#253341`           |
+| 4   | `#3c3d46`             | `#636e7a`              | `#2d3a44`           |
+| 5   | `#41424c`             | `#9aa6b2`              | `#2f3e4f`           |
+| 6   | `#494a55`             | `#d9e2ec`              | `#38444d`           |
+| 7   | `#4d4e59`             | `#e3ebf4`              | `#3a4d5f`           |
+| 8   | `#5a5c66`             | `#e7edf3`              | `#3f5066`           |
+| 9   | `#aeb0b9`             | `#edf2f7`              | `#9faab2`           |
+| 10  | `#afb0b7`             | `#f4f7fa`              | `#9babb8`           |
+| 11  | `#dadce4`             | `#f8fafc`              | `#afb8c1`           |
+| 12  | `#f4f5f8`             | `#ffffff`              | `#f7f9f9`           |
+
+Четвёртая короткая шкала — **тушь** `--od-ink-*`, нейтральный тёмно-серый без
+синевы `cloud`: фон инверсной поверхности в светлой теме.
+
+| Шаг | `--od-ink-*` | Роль                                |
+| --- | ------------ | ----------------------------------- |
+| 1   | `#1f1f1f`    | `--surface-inverse` в light         |
+| 2   | `#333333`    | `--surface-inverse-hover` в light   |
+| 3   | `#4a4a4a`    | `--surface-inverse-pressed` в light |
+
+### Тона
+
+Колонка «Где взят» — единственный способ понять, зачем в семье именно столько
+ступеней: каждая существует под конкретную роль в конкретной теме, лишних нет.
+
+| Примитив        | Значение  | Где взят                                    |
+| --------------- | --------- | ------------------------------------------- |
+| `--od-blue-1`   | `#1767c2` | `--accent-hover` в light                    |
+| `--od-blue-2`   | `#1c6cc6` | `--accent-strong` в light                   |
+| `--od-blue-3`   | `#1e76da` | `--accent` во всех темах                    |
+| `--od-blue-4`   | `#1f7ae0` | база альф `--accent-soft` и `--focus-ring`  |
+| `--od-blue-5`   | `#3290f4` | `--accent-hover` в dark и dim               |
+| `--od-blue-6`   | `#7fc1ff` | `--accent-strong` в dark и dim              |
+| `--od-blue-7`   | `#e8f1ff` | `--accent-soft` в light                     |
+| `--od-green-1`  | `#17724c` | `--success-strong` в light                  |
+| `--od-green-2`  | `#1f9d68` | `--success` в light                         |
+| `--od-green-3`  | `#3fb47f` | `--success` в dark и dim                    |
+| `--od-green-4`  | `#7ad1a9` | `--success-strong` в dark и dim             |
+| `--od-amber-1`  | `#895a0d` | `--warning-strong` в light                  |
+| `--od-amber-2`  | `#c98512` | `--warning` и `--rating-star` в light       |
+| `--od-amber-3`  | `#f0b341` | `--warning` и `--rating-star` в dark и dim  |
+| `--od-amber-4`  | `#f2bf5f` | `--warning-strong` в dark и dim             |
+| `--od-red-1`    | `#b82d2d` | `--danger-strong` в light                   |
+| `--od-red-2`    | `#da3c2b` | `--danger` в dark и dim                     |
+| `--od-red-3`    | `#d14343` | `--danger` в light                          |
+| `--od-red-4`    | `#e0594b` | база альфы `--danger-soft` в dark и dim     |
+| `--od-red-5`    | `#eea8a0` | `--danger-strong` в dark и dim              |
+| `--od-lime-1`   | `#3f6212` | `--draft-strong` в light                    |
+| `--od-lime-2`   | `#4d7c0f` | `--draft` в light                           |
+| `--od-lime-3`   | `#a3e635` | `--draft` в dark и dim                      |
+| `--od-lime-4`   | `#d9f99d` | `--draft-strong` в dark и dim               |
+| `--od-violet-1` | `#5947e0` | `--accent-hover` при `data-accent="violet"` |
+| `--od-violet-2` | `#5744e9` | `--accent-strong` того же акцента в light   |
+| `--od-violet-3` | `#6d5df0` | `--accent` при `data-accent="violet"`       |
+| `--od-violet-4` | `#b8b2f8` | `--accent-strong` того же акцента в тёмных  |
+| `--od-indigo-1` | `#4f7be8` | `--accent-alt` в light                      |
+| `--od-indigo-2` | `#7d63ef` | `--accent-alt` в dark и dim                 |
+
+Фиолетовый — второй акцент кита, индиго — дополнительный тон `accent-alt`;
+лаймовый держит `draft`, пометку несохранённых правок, и заведён отдельным тоном
+намеренно. Оттенок выбран по свободному месту на круге — 57° до янтаря
+валидации и 70° до зелёного успеха; разбор — в комментарии у `--draft` в
+`styles.css`.
+
+### Полупрозрачные примитивы
+
+Альфа зашита в значение, а не считается через `color-mix`: гейт контраста
+разбирает цвета, записанные литералами, и на вычисляемых выражениях ослеп бы ровно на тех
+токенах, ради которых написан.
+
+| Примитив            | Значение                    | Кто берёт                           |
+| ------------------- | --------------------------- | ----------------------------------- |
+| `--od-blue-4-a16`   | `rgba(31, 122, 224, 0.16)`  | `--accent-soft` в dark и dim        |
+| `--od-blue-4-a18`   | `rgba(31, 122, 224, 0.18)`  | `--focus-ring` в light              |
+| `--od-blue-4-a20`   | `rgba(31, 122, 224, 0.2)`   | `--focus-ring` в dark и dim         |
+| `--od-blue-4-a35`   | `rgba(31, 122, 224, 0.35)`  | `--selection-light`                 |
+| `--od-blue-5-a45`   | `rgba(50, 144, 244, 0.45)`  | `--selection-dark`                  |
+| `--od-green-2-a12`  | `rgba(31, 157, 104, 0.12)`  | `--success-soft` в light            |
+| `--od-green-3-a12`  | `rgba(63, 180, 127, 0.12)`  | `--success-soft` в dark и dim       |
+| `--od-amber-2-a14`  | `rgba(201, 133, 18, 0.14)`  | `--warning-soft` в light            |
+| `--od-amber-3-a13`  | `rgba(240, 179, 65, 0.13)`  | `--warning-soft` в dark и dim       |
+| `--od-red-3-a12`    | `rgba(209, 67, 67, 0.12)`   | `--danger-soft` в light             |
+| `--od-red-4-a12`    | `rgba(224, 89, 75, 0.12)`   | `--danger-soft` в dark и dim        |
+| `--od-lime-2-a10`   | `rgba(77, 124, 15, 0.1)`    | `--draft-soft` в light              |
+| `--od-lime-3-a14`   | `rgba(163, 230, 53, 0.14)`  | `--draft-soft` в dark и dim         |
+| `--od-violet-3-a14` | `rgba(109, 93, 240, 0.14)`  | `--accent-soft` фиолетового акцента |
+| `--od-violet-3-a20` | `rgba(109, 93, 240, 0.2)`   | `--focus-ring` фиолетового акцента  |
+| `--od-violet-3-a32` | `rgba(109, 93, 240, 0.32)`  | `--selection-light` фиолетового     |
+| `--od-violet-4-a30` | `rgba(184, 178, 248, 0.3)`  | `--selection-dark` фиолетового      |
+| `--od-indigo-1-a14` | `rgba(79, 123, 232, 0.14)`  | `--accent-alt-soft` в light         |
+| `--od-indigo-2-a14` | `rgba(125, 99, 239, 0.14)`  | `--accent-alt-soft` в dark и dim    |
+| `--od-slate-1-a72`  | `rgba(38, 39, 45, 0.72)`    | `--topbar-bg` в dark                |
+| `--od-cloud-10-a84` | `rgba(244, 247, 250, 0.84)` | `--topbar-bg` в light               |
+| `--od-navy-1-a72`   | `rgba(21, 32, 43, 0.72)`    | `--topbar-bg` в dim                 |
+| `--od-scrim-dark`   | `rgba(6, 7, 9, 0.78)`       | `--overlay-scrim` в dark и dim      |
+| `--od-scrim-light`  | `rgba(236, 242, 248, 0.78)` | `--overlay-scrim` в light           |
+
+## Слой 2 — роли по темам
+
+`dark` — умолчание, `light` и `dim` переопределяют базовый блок. Там, где стоит
+«= dark», тема роль **не** переопределяет: сумрак меняет только поверхности,
+подписи, рамки, тени и `--topbar-bg`, а тона и акцент берёт у тёмной темы.
+
+### Поверхности
+
+| Токен                   | dark                | light                | dim                |
+| ----------------------- | ------------------- | -------------------- | ------------------ |
+| `--surface-app`         | `slate-1` `#26272d` | `cloud-10` `#f4f7fa` | `navy-1` `#15202b` |
+| `--surface-panel`       | `slate-2` `#2e2f36` | `cloud-12` `#ffffff` | `navy-2` `#1e2732` |
+| `--surface-panel-hover` | `slate-3` `#363740` | `cloud-9` `#edf2f7`  | `navy-3` `#253341` |
+| `--surface-elevated`    | `slate-5` `#41424c` | `cloud-11` `#f8fafc` | `navy-5` `#2f3e4f` |
+| `--surface-contrast`    | `slate-7` `#4d4e59` | `cloud-7` `#e3ebf4`  | `navy-7` `#3a4d5f` |
+
+### Инверсная поверхность
+
+Плашка, которая обязана отличаться от всего вокруг знаком, а не шагом
+яркости: Меню выделения Редактора (`toolbar="bubble"`), стоящее прямо на
+Документе. Светлая в тёмных темах, тёмная в светлой. Для неё есть утилиты:
+`bg-surface-inverse`, `bg-surface-inverse-hover`, `bg-surface-inverse-pressed`,
+`text-text-on-inverse`, `outline-accent-on-inverse`.
+
+| Токен                       | dark                 | light                | dim    |
+| --------------------------- | -------------------- | -------------------- | ------ |
+| `--surface-inverse`         | `cloud-11` `#f8fafc` | `ink-1` `#1f1f1f`    | = dark |
+| `--surface-inverse-hover`   | `cloud-8` `#e7edf3`  | `ink-2` `#333333`    | = dark |
+| `--surface-inverse-pressed` | `cloud-6` `#d9e2ec`  | `ink-3` `#4a4a4a`    | = dark |
+| `--text-on-inverse`         | `cloud-1` `#17212b`  | `cloud-12` `#ffffff` | = dark |
+| `--accent-on-inverse`       | `blue-2` `#1c6cc6`   | `blue-6` `#7fc1ff`   | = dark |
+
+- **Текст и иконки** на всех трёх фонах плашки (покой, наведение, нажатие)
+  держат не меньше 8.8:1, с большим запасом против 4.5 для текста и 3 для иконок.
+- **`--accent-on-inverse` — контур фокуса** на плашке: `--accent-strong`
+  противоположной темы (плашка в тёмной теме светлая, и ей нужен тёмный
+  синий). Поэтому ось акцента и бренд меняют его зеркально к
+  `--accent-strong` — см. «Оси акцента и бренда». По замеру не ниже 4.0:1 (порог
+  гейта — 3:1) на любом из трёх фонов плашки.
+- **Отдельная группа, а не `--surface-contrast`.** Тот — ступень обычной шкалы
+  фонов (`bg-4`) и отличается от поверхности `panel` на шаг; над текстом шаг сливается с
+  Документом.
+- Меню и поповеры, открытые из такой плашки, остаются на обычной поверхности
+  поповера: инверсия — у плашки, а не у всего, что из неё открыто.
+
+Пары проверяет `npm run contrast` во всех темах, акцентах и брендах.
+
+### Подписи
+
+| Токен               | dark                 | light                | dim                 |
+| ------------------- | -------------------- | -------------------- | ------------------- |
+| `--text-primary`    | `slate-12` `#f4f5f8` | `cloud-1` `#17212b`  | `navy-12` `#f7f9f9` |
+| `--text-secondary`  | `slate-11` `#dadce4` | `cloud-2` `#45515f`  | `navy-11` `#afb8c1` |
+| `--text-muted`      | `slate-9` `#aeb0b9`  | `cloud-3` `#545f6e`  | `navy-9` `#9faab2`  |
+| `--text-muted-2`    | `slate-10` `#afb0b7` | `cloud-4` `#636e7a`  | `navy-10` `#9babb8` |
+| `--text-disabled`   | `slate-8` `#5a5c66`  | `cloud-5` `#9aa6b2`  | `navy-8` `#3f5066`  |
+| `--text-on-accent`  | `cloud-12` `#ffffff` | `cloud-12` `#ffffff` | = dark              |
+| `--text-on-warning` | `cloud-1` `#17212b`  | = dark               | = dark              |
+| `--text-on-success` | `cloud-1` `#17212b`  | = dark               | = dark              |
+
+Шкала подписей держит три ступени контраста в каждой теме: `secondary` ≥ 7.5,
+`muted` ≥ 6.0, `muted-2` ≥ 4.5 по худшей из подложек. Нижняя ступень — это уровень AA
+по WCAG для текста, две верхние взяты с запасом не ради нормы, а чтобы ступени остались
+различимы.
+
+`--text-on-warning` и `--text-on-success` объявлены один раз и темами не
+переопределяются: белый на жёлтой заливке даёт 1.87 при требуемых 4.5, и
+подбором оттенка это не чинится, поэтому у этих двух тонов текст тёмный.
+
+### Рамки
+
+| Токен              | dark                | light               | dim                |
+| ------------------ | ------------------- | ------------------- | ------------------ |
+| `--border-default` | `slate-6` `#494a55` | `cloud-6` `#d9e2ec` | `navy-6` `#38444d` |
+| `--border-soft`    | `slate-4` `#3c3d46` | `cloud-8` `#e7edf3` | `navy-4` `#2d3a44` |
+
+### Акцент
+
+| Токен               | dark                                | light                               | dim    |
+| ------------------- | ----------------------------------- | ----------------------------------- | ------ |
+| `--accent`          | `blue-3` `#1e76da`                  | `blue-3` `#1e76da`                  | = dark |
+| `--accent-hover`    | `blue-5` `#3290f4`                  | `blue-1` `#1767c2`                  | = dark |
+| `--accent-soft`     | `blue-4-a16` `rgba(31,122,224,.16)` | `blue-7` `#e8f1ff`                  | = dark |
+| `--accent-strong`   | `blue-6` `#7fc1ff`                  | `blue-2` `#1c6cc6`                  | = dark |
+| `--focus-ring`      | `blue-4-a20` `rgba(31,122,224,.2)`  | `blue-4-a18` `rgba(31,122,224,.18)` | = dark |
+| `--selection`       | `--selection-dark`                  | `--selection-light`                 | = dark |
+| `--selection-dark`  | `blue-5-a45` `rgba(50,144,244,.45)` | `blue-5-a45` `rgba(50,144,244,.45)` | = dark |
+| `--selection-light` | `blue-4-a35` `rgba(31,122,224,.35)` | `blue-4-a35` `rgba(31,122,224,.35)` | = dark |
+| `--accent-alt`      | `indigo-2` `#7d63ef`                | `indigo-1` `#4f7be8`                | = dark |
+| `--accent-alt-soft` | `indigo-2-a14`                      | `indigo-1-a14`                      | = dark |
+
+### Тона состояний
+
+У каждого тона два токена, потому что у него две несовместимые роли: `--<тон>` —
+заливка под контрастным текстом (темнее), `--<тон>-strong` — тот же тон как
+текст, рамка и индикатор на фоне (в тёмных темах светлее, в светлой темнее).
+
+| Токен              | dark                | light               | dim    |
+| ------------------ | ------------------- | ------------------- | ------ |
+| `--success`        | `green-3` `#3fb47f` | `green-2` `#1f9d68` | = dark |
+| `--success-soft`   | `green-3-a12`       | `green-2-a12`       | = dark |
+| `--success-strong` | `green-4` `#7ad1a9` | `green-1` `#17724c` | = dark |
+| `--warning`        | `amber-3` `#f0b341` | `amber-2` `#c98512` | = dark |
+| `--warning-soft`   | `amber-3-a13`       | `amber-2-a14`       | = dark |
+| `--warning-strong` | `amber-4` `#f2bf5f` | `amber-1` `#895a0d` | = dark |
+| `--rating-star`    | `amber-3` `#f0b341` | `amber-2` `#c98512` | = dark |
+| `--danger`         | `red-2` `#da3c2b`   | `red-3` `#d14343`   | = dark |
+| `--danger-soft`    | `red-4-a12`         | `red-3-a12`         | = dark |
+| `--danger-strong`  | `red-5` `#eea8a0`   | `red-1` `#b82d2d`   | = dark |
+| `--draft`          | `lime-3` `#a3e635`  | `lime-2` `#4d7c0f`  | = dark |
+| `--draft-soft`     | `lime-3-a14`        | `lime-2-a10`        | = dark |
+| `--draft-strong`   | `lime-4` `#d9f99d`  | `lime-1` `#3f6212`  | = dark |
+
+## Слой 3 — компонентные токены
+
+| Токен             | dark          | light          | dim          |
+| ----------------- | ------------- | -------------- | ------------ |
+| `--overlay-scrim` | `scrim-dark`  | `scrim-light`  | = dark       |
+| `--topbar-bg`     | `slate-1-a72` | `cloud-10-a84` | `navy-1-a72` |
+
+Девять токенов маркера Редактора `--marker-<имя>` и `--marker-text` лежат в [таблице маркера](#маркер-редактора)
+ниже: значение у темы своё, а селектор — `[data-theme]` любого элемента, не `:root`.
+
+`--rating-star` — роль слоя 2, а не компонентный токен: он объявлен рядом с
+`--warning`, но отдельным токеном, потому что цвет сегодня тот же, а правка
+предупреждения не должна перекрашивать оценки. Остальные три токена слоя 3 —
+`--modal-shadow`, `--sidenav-w` и `--sidenav-w-collapsed` — цвета не несут, их
+значения в [theming.md](theming.md).
+
+## Метки пользователя
+
+Закрытый набор из восьми оттенков под то, что красит сам человек: проект,
+ярлык, категорию. `blue`, `violet`, `teal`, `green`, `amber`, `red`, `pink`,
+`steel` — токены `--label-<оттенок>` и утилиты `bg-label-<оттенок>`,
+`text-label-<оттенок>`, `border-label-<оттенок>`.
+
+**Это не тоны.** Тон описывает смысл: `danger` — «действие разрушительно».
+Метка означает ровно то, что в неё вложил человек. Занять смысловые тоны под
+метки нельзя: кружок цвета `danger` рядом с проектом прочитается как ошибка, а
+тон перестанет значить то, что значит. Поэтому ступени примитивов у меток свои
+и сдвинуты относительно тонов — даже там, где при создании набора просили «зелёный» и
+«красный».
+
+**Имена по оттенку, а не по назначению.** Имя уезжает в базу потребителя ключом
+цвета и переживает смену значений; `label-1` через полгода не скажет никому
+ничего.
+
+**Не зависят ни от акцента, ни от бренда.** Оба блока (акцента и бренда) переопределяют только
+`--accent*`, а метки смотрят прямо в примитивы. Переключив акцент с синего на
+фиолетовый, пользователь не должен обнаружить, что все его проекты сменили
+цвет.
+
+**Порог — нетекстовый, 3:1.** Метка — это графический признак, а не подпись
+(WCAG 1.4.11). Текст **внутри** заливки не предполагается: восемь оттенков,
+читаемых под текстом во всех трёх темах, стоили бы вдвое большего набора, а
+подпись рядом решает ту же задачу. Все восемь проверяются `npm run contrast` во
+всех трёх темах — витрина `Foundations/Label colours` показывает набор целиком.
+
+Из кита едут `LABEL_HUES` (порядок и состав набора), `LABEL_BG_CLASS` и
+`LABEL_TEXT_CLASS`. Словари, а не склейка `bg-label-${hue}`: Tailwind сканирует
+исходники как текст, и класс, собранный в рантайме, молча не попадёт в CSS.
+
+Выбор цвета собирается на существующем `ColorPicker` — своего компонента набор
+не требует.
+
+## Маркер Редактора
+
+Девять токенов `--marker-<имя>` компонентного слоя: заливка маркера
+`RichTextEditor` и `RichTextView`. Названия цвета, как в
+Notion, — не тоны: `yellow` не значит «предупреждение». Все девять выбираются в
+сетке «Цвет маркера». Три ярких — одинаковые во всех темах
+(примитивы `--od-marker-yellow`, `-green`, `-pink`), текст на них тёмный:
+`--marker-text` (`--od-marker-text`). У шести прежних цветов Notion примитивы
+свои: `--od-marker-<имя>-d` (тёмные, приглушённые) и `--od-marker-<имя>-l`
+(пастель), текст на них — основной текст темы.
+
+| Токен             | `light` (`-l`) | `dark` и `dim` (`-d`) |
+| ----------------- | -------------- | --------------------- |
+| `--marker-yellow` | `#ffea80`      | `#ffea80`             |
+| `--marker-green`  | `#aaff80`      | `#aaff80`             |
+| `--marker-pink`   | `#ff80bf`      | `#ff80bf`             |
+| `--marker-blue`   | `#d3e5ef`      | `#28456c`             |
+| `--marker-gray`   | `#e3e2e0`      | `#5a5a5a`             |
+| `--marker-brown`  | `#eee0da`      | `#603b2c`             |
+| `--marker-orange` | `#fadec9`      | `#854c1d`             |
+| `--marker-purple` | `#e8deee`      | `#492f64`             |
+| `--marker-red`    | `#ffe2dd`      | `#6e3630`             |
+| `--marker-text`   | `#1a1a1a`      | `#1a1a1a`             |
+
+Сумрак своих значений не имеет: тёмные заливки годятся обеим тёмным темам.
+**Селектор — `[data-theme]` любого элемента**, а не `:root[data-theme]`, и моста
+`@theme` у токенов нет: так вложенная обёртка с другой темой получает свои
+значения (`theming.md`); яркая тройка и `--marker-text` от темы не зависят.
+Тёмный текст держит контраст 4.5:1 на яркой тройке во всех темах (14.4 на жёлтом и зелёном, 7.5 на
+розовом), а основной текст `fg-0` — на шести читаемых маркерах (худший — `orange`, 6.32, в
+`dark`); проверяет `npm run contrast`. Маркеры не зависят ни от акцента, ни от бренда. Сохранённые имена
+маркера прежней палитры (`accent`, `success`, …) переводятся в ближайший цвет —
+таблица в [документации Редактора](components/inputs/rich-text-editor.md#цвет-маркер-и-выравнивание).
+
+## Оси акцента и бренда
+
+Заданный бренд отменяет ось акцента целиком: у обоих блоков одинаковая
+специфичность, а бренд стоит в файле ниже.
+
+| Токен                 | `data-accent="violet"` | `data-brand="teal"` |
+| --------------------- | ---------------------- | ------------------- |
+| `--accent`            | `violet-3` `#6d5df0`   | `teal-2` `#0f766e`  |
+| `--accent-hover`      | `violet-1` `#5947e0`   | `teal-1` `#115e59`  |
+| `--accent-soft`       | `violet-3-a14`         | `teal-3-a16`        |
+| `--accent-strong`     | `violet-4` `#b8b2f8`   | `teal-4` `#5eead4`  |
+| `--focus-ring`        | `violet-3-a20`         | `teal-3-a20`        |
+| `--selection-dark`    | `violet-4-a30`         | `teal-3-a35`        |
+| `--selection-light`   | `violet-3-a32`         | `teal-2-a30`        |
+| `--accent-on-inverse` | `violet-2` `#5744e9`   | `teal-1` `#115e59`  |
+
+В светлой теме `--accent-strong` у обоих берёт своё значение — `violet-2`
+`#5744e9` и `teal-1` `#115e59`: токен читается **на** фоне, и светлому фону
+нужен тёмный оттенок вместо светлого. `--accent-on-inverse` устроен зеркально:
+в светлой теме плашка тёмная, и он берёт светлый оттенок — `violet-4`
+`#b8b2f8` и `teal-4` `#5eead4`. `--selection` в светлой теме у обоих — их
+`--selection-light`: блок акцента и бренда стоит ниже светлой темы, поэтому
+светлое выделение возвращает парный блок.
+
+**Выделение** (`--selection`) — заливка выделенного текста:
+глобальный `::selection` и роль `--rte-selection` Редактора. Отличие от
+фона — 1.7–2.0:1 в тёмных темах и 1.5–1.6:1 в светлой, на уровне выделения
+VS Code и macOS; 3:1 не цель, потому что в тёмной теме такая заливка уже не
+держит 4.5:1 светлого текста поверх. `--selection-light` — светлый вариант при
+любой теме приложения: его берёт белый Лист Редактора (`surface="paper"`).
+`--selection-dark` — зеркально тёмный при любой теме: его берёт
+поле HTML-режима Редактора, тёмное и в светлой теме; тёмные темы присваивают
+его `--selection`.
+
+Примитивы бренда `teal` объявлены внутри его же блока и в общую палитру не
+входят: `#115e59`, `#0f766e`, `#14b8a6`, `#5eead4` плюс четыре альфы —
+`rgba(20, 184, 166, 0.16)`, `rgba(20, 184, 166, 0.2)`, `rgba(20, 184, 166, 0.35)`
+и `rgba(15, 118, 110, 0.3)`. Это образец
+для копии — как завести свой бренд, описано в
+[theming.md](theming.md#как-завести-бренд).
+
+## Алиасы совместимости
+
+Компоненты красятся через них: классы Tailwind ссылаются на эти имена.
+
+| Алиас                         | Роль                                           |
+| ----------------------------- | ---------------------------------------------- |
+| `--bg-0` … `--bg-4`           | `--surface-app` … `--surface-contrast`         |
+| `--fg-0` … `--fg-4`           | `--text-primary` … `--text-disabled`           |
+| `--line`, `--line-soft`       | `--border-default`, `--border-soft`            |
+| `--tg`, `--tg-2`, `--tg-soft` | `--accent`, `--accent-strong`, `--accent-soft` |
+| `--ok`, `--ok-soft`           | `--success`, `--success-soft`                  |
+| `--warn`, `--warn-soft`       | `--warning`, `--warning-soft`                  |
+| `--err`, `--err-soft`         | `--danger`, `--danger-soft`                    |
+| `--purple`, `--purple-soft`   | `--accent-alt`, `--accent-alt-soft`            |
+
+Новых заводить не нужно: полные имена — целевой словарь, алиасы держатся ради
+кода потребителя и будут удалены, когда им перестанут пользоваться.
+
+## Что дальше
+
+- [Темы, токены и бренды](theming.md) — слои, правила и как завести бренд.
+- [Доступность](accessibility.md) — требования, которые проверяет гейт контраста.