Mercury
Практическая книга по дизайну интерфейса документации
Редакция для интерфейса 1.0 · 6 ноября 2026 года
Полный текст доступен без JavaScript. Включите JavaScript для настройки чтения и лаборатории дизайна.
Область применения. Эта книга описывает существующий фирменный стиль Mercury и компоновку документации, доработанную 6 ноября 2026 года. В ней объединены токены, сверенные с исходным кодом, и результаты наблюдений в браузере на закрытом предварительном стенде win-120. Предложения по редактуре и сопровождению отмечены явно. Книга не удостоверяет соответствие WCAG и не означает, что цитируемые эксперты одобряют эту реализацию.
1. Характер Mercury
Документация Mercury должна помогать разобраться в технической работе и находить нужное. Её узнаваемость создают сложившийся знак mx, шрифт DM Sans, насыщенный цвет текста, сдержанные фиолетовые акценты и свободное пространство для чтения. Следующее полезное действие должно находиться рядом с информацией, которая позволяет его выполнить.
Книга предназначена для дизайнеров, инженеров и авторов документации, развивающих сайт Mercury. Она описывает текущий интерфейс как набор воспроизводимых решений: фирменный стиль, типографику, цвет, навигацию, доступность и реализацию. Книга не заменяет контракты библиотеки компонентов и не задаёт новый визуальный стиль.
Предлагаемый стиль изложения: точный, прямой и полезный. Начинайте с того, что читатель может сделать. Указывайте требования перед командой, ожидаемый результат — после неё; объясняйте ошибки там, где возможно восстановление. Сохраняйте идентификаторы такими, как в программном обеспечении. Отличайте наблюдавшийся результат от предполагаемого поведения.
| Используйте | Избегайте |
|---|
| «Установите mx, затем проверьте его версию». | Обещания без следующего выполнимого шага |
| «Для этого примера нужен работающий сервер». | Скрытого предварительного условия |
| «Откройте меню, чтобы выбрать курс». | Пространственных указаний, зависящих от настольной компоновки |
| «Команда завершается со статусом 0». | «Всё должно работать» |
Желаемое впечатление — спокойная компетентность. Иерархию следует выстраивать прежде всего положением, группировкой, размером и насыщенностью, а затем дополнительным оформлением. Так Mercury применяет изложенный Авророй Харли принцип близости: расстояние передаёт связи между элементами, и адаптивная компоновка должна сохранять эти связи. NN/g: принцип близости в визуальном дизайне
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 не должно повторять это имя. Если в узкой компоновке текстовое название скрыто, ссылке на главную всё равно нужно понятное доступное имя. Проверяйте дерево доступности отображённой страницы: внешний вид сам по себе ничего не доказывает.
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: контраст (минимальный)
Информация, необходимая для распознавания элементов управления, состояний и значимой графики, обычно должна иметь контраст 3:1 с соседними цветами. Декоративный разделитель отличается от границы, необходимой для распознавания поля ввода. Проверка декоративных линий на 1.5:1 в репозитории — внутреннее правило дизайна, а не порог WCAG. W3C: контраст нетекстового содержимого
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: значения и единицы измерения
Текущая ширина области чтения — 68ch. Мэтью Баттерик рекомендует в среднем 45-90 символов в строке; это основание проверять длину строки с точки зрения удобства чтения, а не считать одну CSS-ширину универсально верной. Его общая рекомендация по межстрочному интервалу — 120-145%, предпочтительно с безразмерным значением в CSS. Коэффициент 1.75 для основного текста Mercury и 1.6 для вводного абзаца — более свободные локальные настройки для технического чтения, проверенные на отображённой странице документации; они не входят в рекомендованный Баттериком диапазон. Баттерик: длина строки · Баттерик: межстрочный интервал
Оценивайте загруженный шрифт, фактический язык, код и переносы вместе. Технически корректная шкала размеров всё равно может не сработать, если длинные подписи накладываются друг на друга или метрики запасного шрифта меняют перенос строки.
5. Отступы выражают структуру
Существующий --lms-baseline равен 0.25rem. При корневом размере шрифта 16px высота строки доработанного основного текста составляет 28px (семь шагов), а вводного абзаца — 32px (восемь шагов). Используйте это значение как общий шаг отступов: 0.5rem, 0.75rem, 1rem, 1.5rem, 2rem и 3rem образуют полезный набор для соседних элементов, групп и разделов.
Это ритм отступов. Он не гарантирует, что базовая линия каждого глифа попадёт на единую сетку: метрики шрифта, границы, переносы строк и пользовательские настройки влияют на отображение. Полезный ритм должен выдерживать увеличение текста, а не ограничивать его фиксированными блоками.
| Связь | Правило дизайна |
|---|
| Заголовок и его содержимое | Располагайте следующее за заголовком содержимое ближе, чем предыдущий раздел |
| Группа боковой панели и её ссылки | Связывайте подпись со ссылками, которые она предваряет |
| Соседние группы боковой панели | Явно разделяйте группы, не превращая каждую в карточку |
| Вложенные пункты навигации | Сохраняйте постоянный отступ и удобную для чтения ширину строки |
| Многострочный пункт навигации | Позволяйте высоте расти; сохраняйте явное отделение от соседей |
Такой подход к группировке осознанно применяет принцип близости. Харли описывает, как отступы проясняют связи и как эти связи могут меняться при сжатии компоновки. Выдвижная панель на телефоне должна сохранять структуру курсов, даже когда колонки настольной версии исчезают. NN/g: принцип близости
В текущей оболочке сайта шапка, основная часть и подвал используют общий контейнер с максимальной шириной 80rem. В настольной версии навигационная колонка имеет ширину 15rem и отделена от содержимого промежутком 3rem; колонка локального оглавления шириной 12.5rem появляется, когда для неё есть место. Это значения, установленные при изучении приложения, а не универсальные токены компонентов Mercury.
Доработанная боковая панель выравнивает заголовки раскрываемых блоков, группы и текст ссылок по отступу 0.75rem от края. Над подписями групп оставлено 0.75rem, под ними — 0.25rem. Строки ссылок имеют вертикальные внутренние отступы 0.5rem и минимальную высоту 2.25rem на настольных устройствах; для неточных указателей она увеличивается до 2.75rem. Высота заголовков раскрываемых блоков — не менее 2.75rem. Текущая страница выделена полужирным текстом, тонированной поверхностью и внутренним фиолетовым маркером толщиной 0.125rem. Эти значения наблюдались в браузере при корневом размере шрифта 16px. Проверяйте короткую подпись, подпись с переносом, раскрытый курс и текущую страницу в обеих темах.
6. Навигация остаётся узнаваемой и управляемой
Для переходов используйте обычные ссылки, а для показа и скрытия групп ссылок — раскрываемые блоки. HTML-элемент details представляет раскрываемый блок, а summary задаёт его видимую подпись. Сохраняйте этот встроенный элемент управления, прежде чем добавлять собственное поведение. WHATWG: интерактивные элементы
Собственной кнопке раскрытия нужны корректное состояние раскрытия и активация с клавиатуры; APG описывает активацию клавишами Enter и Space, а также необязательный атрибут aria-controls. У встроенного details уже есть собственное состояние. Не добавляйте статическое значение aria-expanded, которое не соответствует тому, открыт ли элемент. WAI APG: шаблон раскрываемого блока
Навигация сайта не становится меню ARIA автоматически. В примере навигации APG роль меню намеренно не используется, поскольку она создаёт ожидания другой модели взаимодействия. Сохраняйте навигационные ориентиры, списки, ссылки и понятные имена. Текущее мобильное меню открывается и закрывается встроенным элементом summary; Escape его не закрывает. Эта книга не утверждает, что в меню реализованы модальное удержание фокуса или клавиатурное поведение пользовательского меню. Указывайте aria-current="page" у фактического текущего пункта назначения и выделяйте его визуально также насыщенностью или формой. WAI APG: навигация с раскрываемыми блоками
При работе с клавиатурой индикатор фокуса должен оставаться видимым. Не допускайте его обрезки на краю прокручиваемой боковой панели. Закреплённые шапки и открытые панели тоже нужно проверять: WCAG AA требует, чтобы компонент в фокусе не был полностью перекрыт содержимым, созданным автором. Более строгая цель дизайна — сохранять видимым весь элемент управления. W3C: видимый фокус · W3C: фокус не перекрыт
Критерий WCAG 2.5.8 уровня AA обычно требует области взаимодействия размером 24 × 24 CSS-пикселя либо соблюдения одного из оговорённых исключений, включая достаточные промежутки. Сенсорные элементы управления Mercury размером 2.75rem выбраны ради удобства: это 44px при корневом размере шрифта 16px. Не называйте 44px минимальным требованием AA. W3C: размер области взаимодействия (минимальный)
7. Адаптация — часть дизайна
Шапка сочетает резервные правила по размеру области просмотра с контейнерными запросами в em, поэтому её компактные элементы управления также реагируют на увеличение текста. На небольших экранах сохраняйте компактность основного фирменного обозначения и элементов управления, а второстепенные направления открывайте через раскрываемую навигацию. Сохраняйте доступ к полезным подписям. Не разрывайте обычные слова в таблицах. Разрешайте перенос длинных идентификаторов в основном тексте; при необходимости разрешайте примерам кода и содержимому, которому действительно нужны два измерения, прокручиваться в собственной области.
Требование WCAG к перекомпоновке относится к обычному вертикальному содержимому при ширине, эквивалентной 320 CSS-пикселям: информация и функциональность должны сохраняться без необходимости прокрутки в двух направлениях. Предусмотрены исключения для содержимого, смысл или использование которого требуют двух измерений. Проверяйте документ, а не только снимок области просмотра. W3C: перекомпоновка
Проверка текстовых интервалов — нагрузочное условие, а не обязательный стиль по умолчанию. При одновременном применении соответствующих пользовательских настроек — высоты строки 1.5 размера шрифта, интервала между абзацами 2 размера шрифта, межбуквенного интервала 0.12 размера шрифта и интервала между словами 0.16 размера шрифта — содержимое и функциональность должны оставаться доступными. Для языков и систем письма, в которых свойство не используется, действуют исключения. W3C: текстовые интервалы
Проверяйте светлую и тёмную темы, увеличение текста в браузере, длинные подписи навигации, обход с клавиатуры и открытую выдвижную панель у края области просмотра. Расчёт контраста подтверждает свойства цветовой пары, но не порядок чтения или поведение программы экранного доступа. Снимок экрана подтверждает внешний вид в одном состоянии, но не работоспособность.
Придавайте движению определённую цель. Эмиль Ковальски объясняет, как исходная точка движения связывает раскрывающийся список с его переключателем и как в рабочих интерфейсах немедленное обновление может быть полезнее анимации. Для документации Mercury это довод в пользу сдержанности: анимация должна помогать сохранять ориентацию, не задерживая доступ. Текущая оболочка включает переход между документами только тогда, когда читатель не запросил сокращение движения. Это локальное правило продукта; статья содержит советы по дизайну. Эмиль Ковальски: хорошие и отличные анимации
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 · APG: прочтите в первую очередь
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 служит его редактируемым текстовым дополнением. Доработки зафиксированы в исходном коде и доступны в локальном предварительном просмотре; эта редакция не утверждает, что они выпущены в промышленную эксплуатацию.