# Mercury
## Практическая книга по дизайну интерфейса документации

Редакция для интерфейса 1.0 · 6 ноября 2026 года

**Область применения.** Эта книга описывает существующий фирменный стиль Mercury и компоновку документации, доработанную 6 ноября 2026 года. В ней объединены токены, сверенные с исходным кодом, и результаты наблюдений в браузере на закрытом предварительном стенде win-120. Предложения по редактуре и сопровождению отмечены явно. Книга не удостоверяет соответствие WCAG и не означает, что цитируемые эксперты одобряют эту реализацию.

<!-- PAGE 1: Identity -->

## 1. Характер Mercury

Документация Mercury должна помогать разобраться в технической работе и находить нужное. Её узнаваемость создают сложившийся знак mx, шрифт DM Sans, насыщенный цвет текста, сдержанные фиолетовые акценты и свободное пространство для чтения. Следующее полезное действие должно находиться рядом с информацией, которая позволяет его выполнить.

Книга предназначена для дизайнеров, инженеров и авторов документации, развивающих сайт Mercury. Она описывает текущий интерфейс как набор воспроизводимых решений: фирменный стиль, типографику, цвет, навигацию, доступность и реализацию. Книга не заменяет контракты библиотеки компонентов и не задаёт новый визуальный стиль.

**Предлагаемый стиль изложения:** точный, прямой и полезный. Начинайте с того, что читатель может сделать. Указывайте требования перед командой, ожидаемый результат — после неё; объясняйте ошибки там, где возможно восстановление. Сохраняйте идентификаторы такими, как в программном обеспечении. Отличайте наблюдавшийся результат от предполагаемого поведения.

| Используйте | Избегайте |
|---|---|
| «Установите mx, затем проверьте его версию». | Обещания без следующего выполнимого шага |
| «Для этого примера нужен работающий сервер». | Скрытого предварительного условия |
| «Откройте меню, чтобы выбрать курс». | Пространственных указаний, зависящих от настольной компоновки |
| «Команда завершается со статусом 0». | «Всё должно работать» |

Желаемое впечатление — спокойная компетентность. Иерархию следует выстраивать прежде всего положением, группировкой, размером и насыщенностью, а затем дополнительным оформлением. Так Mercury применяет изложенный Авророй Харли принцип близости: расстояние передаёт связи между элементами, и адаптивная компоновка должна сохранять эти связи. [NN/g: принцип близости в визуальном дизайне](https://www.nngroup.com/articles/gestalt-proximity/)

<!-- PAGE 2: Mark -->

## 2. Используйте существующий знак

Файл `brand/SOURCE` в репозитории фиксирует происхождение знака из плагина mx для JetBrains. Сохраняйте два его контура, округлые окончания и пропорции. Используйте предоставленные исходные SVG; не обводите знак по снимку экрана, не растягивайте его, не добавляйте обводки и не перерисовывайте формы букв.

| Файл | Назначение в этом репозитории |
|---|---|
| `mx-mark.svg` | Встроенный знак в шапке: m наследует цвет текста; x использует `--lms-accent` |
| `mx-mark-on-light.svg` | Изображение с фиксированными цветами для светлого фона |
| `mx-mark-on-dark.svg` | Изображение с фиксированными цветами для тёмного фона |
| `mx-tile.svg` | Сложившийся вариант в виде плитки в стиле плагина |
| `mx-tile-dark.svg` | Адаптированная тёмная плитка из репозитория |
| `favicon.svg` | Значок браузера, учитывающий тему |

Встроенный знак и изображения с фиксированными цветами намеренно различаются. Акцент встроенного знака следует теме LMS; варианты изображений сохраняют синие акценты, описанные в `brand/SOURCE`. Не «исправляйте» их все на фиолетовый без отдельного решения о фирменном стиле.

В текущей шапке знак размером 1.875rem × 1.375rem сочетается с текстовым начертанием названия размером 1.375rem, насыщенностью 800 и межбуквенным интервалом -0.04em. Это размеры в приложении, а не минимальные размеры воспроизведения для всех носителей. При масштабировании сохраняйте соотношение сторон SVG.

**Рекомендации по использованию:** не размещайте соседнее содержимое вплотную к знаку, проверяйте его в фактическом размере отображения и выбирайте предоставленный вариант для нужной поверхности. В изученных исходных материалах не утверждены универсальная величина охранного поля или минимальный размер для печати.

Когда знак и видимое текстовое начертание названия образуют одну ссылку на главную страницу, задайте ей одно понятное доступное имя. Декоративное содержимое SVG не должно повторять это имя. Если в узкой компоновке текстовое название скрыто, ссылке на главную всё равно нужно понятное доступное имя. Проверяйте дерево доступности отображённой страницы: внешний вид сам по себе ничего не доказывает.

<!-- PAGE 3: Color -->

## 3. Цвет выполняет задачу

Светлая тема использует белые и почти белые поверхности, чёрный основной текст и фиолетовый Mercury для фокуса и выделения выбранного. Тёмная тема использует существующие тёмные цветовые шкалы Mercury UI, сопоставленные тем же семантическим ролям. Сохраняйте смысл при смене темы; не создавайте тёмную тему механической инверсией цветов.

| Семантическая роль | Светлая тема | Тёмная тема |
|---|---|---|
| Страница, `--bg-primary` | #FFFFFF | #111113 |
| Вторичная поверхность, `--bg-secondary` | #FDFDFD | #18191B |
| Тонированная поверхность, `--bg-tertiary` | #F5F5F5 | #212225 |
| Основной текст, `--fg-primary` | #000000 | #EDEEF0 |
| Вторичный текст, `--fg-secondary` | #3D3D3D | #B0B4BA |
| Третичный текст, `--fg-tertiary` | #595D62 | #B0B4BA |
| Сплошной акцент, `--lms-accent` | #4E46B4 | #7474DC |
| Фирменный цвет текста, `--fg-brand` | #4E46B4 | #B1A9FF |

Используйте текстовые токены для текста, а токены поверхностей — для заливок. Подходящая акцентная заливка не обязательно подходит для акцентного текста или графики поверх фона. Цвет недоступного текста не заменяет цвет вторичного текста. Ссылки в основном содержимом сохраняют подчёркивание, чтобы их можно было распознать не только по цвету.

Для обычного текста обеспечивайте контраст не ниже 4.5:1; для крупного текста в определении WCAG действует исключение 3:1. Измеряйте фактическую пару «передний план / фон», учитывая наложения и состояния взаимодействия. [W3C: контраст (минимальный)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)

Информация, необходимая для распознавания элементов управления, состояний и значимой графики, обычно должна иметь контраст 3:1 с соседними цветами. Декоративный разделитель отличается от границы, необходимой для распознавания поля ввода. Проверка декоративных линий на 1.5:1 в репозитории — внутреннее правило дизайна, а не порог WCAG. [W3C: контраст нетекстового содержимого](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html)

<!-- PAGE 4: Type -->

## 4. Типографика учитывает потребности читателя

DM Sans используется для основного текста и крупных надписей. Для кода применяется существующий набор системных моноширинных шрифтов. Сохраняйте запасные шрифты: загрузка шрифта может завершиться ошибкой, а страница должна оставаться пригодной для работы без предпочтительной гарнитуры.

| Роль | Размер шрифта | Высота строки | Насыщенность |
|---|---|---|---|
| Главный заголовок | 2.5rem | 3rem | 700 |
| Главный заголовок, небольшие экраны | 2rem | 2.5rem | 700 |
| Заголовок раздела | 1.25rem | 1.75rem | 700 |
| Вводный абзац | 1.25rem | 1.6 без единицы измерения | Наследуется |
| Основной текст | 1rem | 1.75 без единицы измерения | Наследуется |
| Навигация | 0.875rem | 1.25rem | По роли |
| Мелкий текст | 0.8125rem | 1.25rem в оболочке сайта | По роли |
| Блок кода | 0.8125rem | 1.5rem | Моноширинный |

При корневом размере шрифта 16px величина 1rem равна 16px. Она не всегда равна 16px: `rem` зависит от корневого размера шрифта. Сохраняйте масштабируемость текста и не фиксируйте корневой размер только ради совпадения со снимком экрана. Единица `ch` определяется шириной продвижения глифа нуля; ширина строки 68ch не гарантирует ровно 68 символов пропорционального текста. [CSS: значения и единицы измерения](https://www.w3.org/TR/css-values-4/#font-relative-lengths)

Текущая ширина области чтения — 68ch. Мэтью Баттерик рекомендует в среднем 45-90 символов в строке; это основание проверять длину строки с точки зрения удобства чтения, а не считать одну CSS-ширину универсально верной. Его общая рекомендация по межстрочному интервалу — 120-145%, предпочтительно с безразмерным значением в CSS. Коэффициент 1.75 для основного текста Mercury и 1.6 для вводного абзаца — более свободные локальные настройки для технического чтения, проверенные на отображённой странице документации; они не входят в рекомендованный Баттериком диапазон. [Баттерик: длина строки](https://practicaltypography.com/line-length.html) · [Баттерик: межстрочный интервал](https://practicaltypography.com/line-spacing.html)

Оценивайте загруженный шрифт, фактический язык, код и переносы вместе. Технически корректная шкала размеров всё равно может не сработать, если длинные подписи накладываются друг на друга или метрики запасного шрифта меняют перенос строки.

<!-- PAGE 5: Rhythm -->

## 5. Отступы выражают структуру

Существующий `--lms-baseline` равен 0.25rem. При корневом размере шрифта 16px высота строки доработанного основного текста составляет 28px (семь шагов), а вводного абзаца — 32px (восемь шагов). Используйте это значение как общий шаг отступов: 0.5rem, 0.75rem, 1rem, 1.5rem, 2rem и 3rem образуют полезный набор для соседних элементов, групп и разделов.

Это ритм отступов. Он не гарантирует, что базовая линия каждого глифа попадёт на единую сетку: метрики шрифта, границы, переносы строк и пользовательские настройки влияют на отображение. Полезный ритм должен выдерживать увеличение текста, а не ограничивать его фиксированными блоками.

| Связь | Правило дизайна |
|---|---|
| Заголовок и его содержимое | Располагайте следующее за заголовком содержимое ближе, чем предыдущий раздел |
| Группа боковой панели и её ссылки | Связывайте подпись со ссылками, которые она предваряет |
| Соседние группы боковой панели | Явно разделяйте группы, не превращая каждую в карточку |
| Вложенные пункты навигации | Сохраняйте постоянный отступ и удобную для чтения ширину строки |
| Многострочный пункт навигации | Позволяйте высоте расти; сохраняйте явное отделение от соседей |

Такой подход к группировке осознанно применяет принцип близости. Харли описывает, как отступы проясняют связи и как эти связи могут меняться при сжатии компоновки. Выдвижная панель на телефоне должна сохранять структуру курсов, даже когда колонки настольной версии исчезают. [NN/g: принцип близости](https://www.nngroup.com/articles/gestalt-proximity/)

В текущей оболочке сайта шапка, основная часть и подвал используют общий контейнер с максимальной шириной 80rem. В настольной версии навигационная колонка имеет ширину 15rem и отделена от содержимого промежутком 3rem; колонка локального оглавления шириной 12.5rem появляется, когда для неё есть место. Это значения, установленные при изучении приложения, а не универсальные токены компонентов Mercury.

Доработанная боковая панель выравнивает заголовки раскрываемых блоков, группы и текст ссылок по отступу 0.75rem от края. Над подписями групп оставлено 0.75rem, под ними — 0.25rem. Строки ссылок имеют вертикальные внутренние отступы 0.5rem и минимальную высоту 2.25rem на настольных устройствах; для неточных указателей она увеличивается до 2.75rem. Высота заголовков раскрываемых блоков — не менее 2.75rem. Текущая страница выделена полужирным текстом, тонированной поверхностью и внутренним фиолетовым маркером толщиной 0.125rem. Эти значения наблюдались в браузере при корневом размере шрифта 16px. Проверяйте короткую подпись, подпись с переносом, раскрытый курс и текущую страницу в обеих темах.

<!-- PAGE 6: Navigation -->

## 6. Навигация остаётся узнаваемой и управляемой

Для переходов используйте обычные ссылки, а для показа и скрытия групп ссылок — раскрываемые блоки. HTML-элемент `details` представляет раскрываемый блок, а `summary` задаёт его видимую подпись. Сохраняйте этот встроенный элемент управления, прежде чем добавлять собственное поведение. [WHATWG: интерактивные элементы](https://html.spec.whatwg.org/multipage/interactive-elements.html#the-details-element)

Собственной кнопке раскрытия нужны корректное состояние раскрытия и активация с клавиатуры; APG описывает активацию клавишами Enter и Space, а также необязательный атрибут `aria-controls`. У встроенного `details` уже есть собственное состояние. Не добавляйте статическое значение `aria-expanded`, которое не соответствует тому, открыт ли элемент. [WAI APG: шаблон раскрываемого блока](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)

Навигация сайта не становится меню ARIA автоматически. В примере навигации APG роль меню намеренно не используется, поскольку она создаёт ожидания другой модели взаимодействия. Сохраняйте навигационные ориентиры, списки, ссылки и понятные имена. Текущее мобильное меню открывается и закрывается встроенным элементом summary; Escape его не закрывает. Эта книга не утверждает, что в меню реализованы модальное удержание фокуса или клавиатурное поведение пользовательского меню. Указывайте `aria-current="page"` у фактического текущего пункта назначения и выделяйте его визуально также насыщенностью или формой. [WAI APG: навигация с раскрываемыми блоками](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/)

При работе с клавиатурой индикатор фокуса должен оставаться видимым. Не допускайте его обрезки на краю прокручиваемой боковой панели. Закреплённые шапки и открытые панели тоже нужно проверять: WCAG AA требует, чтобы компонент в фокусе не был полностью перекрыт содержимым, созданным автором. Более строгая цель дизайна — сохранять видимым весь элемент управления. [W3C: видимый фокус](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) · [W3C: фокус не перекрыт](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html)

Критерий WCAG 2.5.8 уровня AA обычно требует области взаимодействия размером 24 × 24 CSS-пикселя либо соблюдения одного из оговорённых исключений, включая достаточные промежутки. Сенсорные элементы управления Mercury размером 2.75rem выбраны ради удобства: это 44px при корневом размере шрифта 16px. Не называйте 44px минимальным требованием AA. [W3C: размер области взаимодействия (минимальный)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)

<!-- PAGE 7: Resilience -->

## 7. Адаптация — часть дизайна

Шапка сочетает резервные правила по размеру области просмотра с контейнерными запросами в em, поэтому её компактные элементы управления также реагируют на увеличение текста. На небольших экранах сохраняйте компактность основного фирменного обозначения и элементов управления, а второстепенные направления открывайте через раскрываемую навигацию. Сохраняйте доступ к полезным подписям. Не разрывайте обычные слова в таблицах. Разрешайте перенос длинных идентификаторов в основном тексте; при необходимости разрешайте примерам кода и содержимому, которому действительно нужны два измерения, прокручиваться в собственной области.

Требование WCAG к перекомпоновке относится к обычному вертикальному содержимому при ширине, эквивалентной 320 CSS-пикселям: информация и функциональность должны сохраняться без необходимости прокрутки в двух направлениях. Предусмотрены исключения для содержимого, смысл или использование которого требуют двух измерений. Проверяйте документ, а не только снимок области просмотра. [W3C: перекомпоновка](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html)

Проверка текстовых интервалов — нагрузочное условие, а не обязательный стиль по умолчанию. При одновременном применении соответствующих пользовательских настроек — высоты строки 1.5 размера шрифта, интервала между абзацами 2 размера шрифта, межбуквенного интервала 0.12 размера шрифта и интервала между словами 0.16 размера шрифта — содержимое и функциональность должны оставаться доступными. Для языков и систем письма, в которых свойство не используется, действуют исключения. [W3C: текстовые интервалы](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html)

Проверяйте светлую и тёмную темы, увеличение текста в браузере, длинные подписи навигации, обход с клавиатуры и открытую выдвижную панель у края области просмотра. Расчёт контраста подтверждает свойства цветовой пары, но не порядок чтения или поведение программы экранного доступа. Снимок экрана подтверждает внешний вид в одном состоянии, но не работоспособность.

Придавайте движению определённую цель. Эмиль Ковальски объясняет, как исходная точка движения связывает раскрывающийся список с его переключателем и как в рабочих интерфейсах немедленное обновление может быть полезнее анимации. Для документации Mercury это довод в пользу сдержанности: анимация должна помогать сохранять ориентацию, не задерживая доступ. Текущая оболочка включает переход между документами только тогда, когда читатель не запросил сокращение движения. Это локальное правило продукта; статья содержит советы по дизайну. [Эмиль Ковальски: хорошие и отличные анимации](https://emilkowal.ski/ui/good-vs-great-animations)

<!-- PAGE 8: Governance -->

## 8. Поддерживайте единую систему с прослеживаемыми решениями

Источник истины для этого интерфейса — репозиторий. Рассматривайте книгу как удобное для чтения дополнение и обновляйте её, когда меняется утверждённая реализация. Сохраняйте различие между общими токенами Mercury UI и токенами приложения `--lms-`.

| Решение | Определяющие локальные источники |
|---|---|
| Геометрия знака и происхождение файлов | `sites/mercury/brand/SOURCE` и предоставленные исходные SVG |
| Шрифт, палитра, типографическая шкала, размеры | `sites/mercury/theme/lms.css` |
| Компоновка оболочки и адаптация интерфейса | `sites/mercury/theme/shell.css` |
| Проверки цветовых пар | `sites/mercury/theme/tokens.check.py` |
| Фактические имена и состояния навигации | Отображённая разметка и дерево доступности браузера |

Для изменения фиксируйте пользу для читателя, изменённый токен или правило и подтверждающие свидетельства. Используйте существующую рабочую задачу, не создавая отдельный ритуал согласования. На изменяемой границе проверяйте один корректный случай и один существенный нагрузочный случай. Сохраняйте несвязанную с задачей работу.

Перед публикацией новой редакции книги сверяйте таблицы со значениями в коммите, просматривайте PDF в размере для чтения, проверяйте работоспособность ссылок на источники и фиксируйте, какие проверки в браузере и проверки взаимодействия действительно выполнены. Явно указывайте невыполненные проверки. Проверка токенов, осмотр в браузере и сеанс с программой экранного доступа дают разные виды свидетельств.

Иерархия источников выбрана намеренно. Рекомендация WCAG 2.2 содержит нормативные требования; страницы W3C Understanding объясняют их. WHATWG определяет поведение HTML. APG предоставляет рекомендации по взаимодействию и иллюстративные шаблоны. NN/g, Баттерик и Ковальски дают экспертные советы по дизайну. Ни один из этих источников не определяет фирменный стиль Mercury и не одобряет эту реализацию. [WCAG 2.2](https://www.w3.org/TR/WCAG22/) · [APG: прочтите в первую очередь](https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/)

<!-- PAGE 9: Verification -->

## 9. Свидетельства и следующая проверка

**Проверка, 6 ноября 2026 года.** Реальное приложение Mercury работало в изолированном контейнере win-120; предварительный просмотр через петлевой интерфейс загружал изменённые стили репозитория. Страницы Start и Hypergraph Units были осмотрены в светлой и тёмной темах. На настольной странице Start контраст обычного текста боковой панели и подписей групп составил 6.63:1 в светлой теме и 9.06:1 в тёмной. Контраст акцента текущей страницы с поверхностью выделения составил соответственно 6.74:1 и 4.00:1. Высота строк ссылок на настольном экране была не менее 36px; высота ссылок в открытом мобильном меню — не менее 44px.

Клавиша Enter закрывала и вновь открывала курс, сохраняя фокус с видимым контуром толщиной 2px. Мобильным меню управляли через его элемент summary. Проверки при ширине 390px и 320px не обнаружили выхода содержимого за ширину страницы. Проверка с корневым размером текста 200% выявила переполнение шапки при ширине 390px; доработка контейнерных запросов устранила его. Повторные проверки при 390px и на настольном экране прошли, включая доступ с клавиатуры к нижнему пункту меню. Отдельная проверка с переопределением текстовых интервалов по WCAG при ширине 320px сохранила переносы и доступ к меню. Это нагрузочные проверки в браузере, а не сертификация на физическом устройстве или с программой экранного доступа. Проверка отображённой компоновки отклонила намеренно уменьшенный отступ группы; затем это изменение удалили. Существующая проверка токенов прошла сценарии контраста в светлой и тёмной темах и отрицательные тестовые примеры.

| Наблюдавшаяся пара | Контраст в светлой теме | Контраст в тёмной теме |
|---|---|---|
| Вторичный текст боковой панели на фоне страницы | 6.63:1 | 9.06:1 |
| Маркер текущей страницы на поверхности выделения | 6.74:1 | 4.00:1 |
| Основной текст на фоне страницы | 21.00:1 | 16.25:1 |

**Ограничения и следующая проверка.** Вернитесь к плотности текста с учётом отзывов читателей, особенно на длинных страницах. Полезными следующими шагами остаются сеанс с ассистивными технологиями, проверка большего числа языков и тестирование на физических сенсорных устройствах. Ревизии реализации: `bf507e4ee` (ритм чтения и навигация) и `50c377ab9` (шапка при увеличенном тексте). PDF был отрендерен и осмотрен; все 11 страниц содержат извлекаемый текст, и текст не выходит за поля страниц. Это визуальное издание без тегов структуры; этот Markdown служит его редактируемым текстовым дополнением. Доработки зафиксированы в исходном коде и доступны в локальном предварительном просмотре; эта редакция не утверждает, что они выпущены в промышленную эксплуатацию.