Справочник компонентов

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

Peer-зависимость — только griffincss-core. От griffincss-utils пакет не зависит: компонент обязан выглядеть правильно сам по себе, утилиты нужны, чтобы его подвинуть.

Именование плоское, в один дефис: .gr-btn-primary, а не .gr-btn--primary. Тот же строй, что в ядре и утилитах — двух синтаксисов в библиотеке нет.

Двадцать шесть модулей тремя волнами. Первая — статические: ни один не открывается, ни одному не нужен JS. Вторая — навигация и раскрытие: всё, что открывается, открывается средствами платформы — <details>, <dialog>, Popover API, — а не скриптом библиотеки. Третья — обратная связь и состояния: прогресс, кольцо занятости, заглушки на время загрузки, тосты, шаги процесса и пустое состояние.

Кнопки (scss/_button.scss)

Состояния: :hover (внутри @media (hover: hover)), :active, :focus-visible, :disabled, [aria-disabled="true"], [aria-busy="true"].

Вариант задаёт цвета четырьмя переменными — --gr-btn-bg, --gr-btn-fg, --gr-btn-border и триплетом --gr-btn-fg-hsl. Поэтому :hover и :active написаны один раз на все девять: они кладут поверх фона варианта вуаль из его же цвета текста (--gr-btn-veil-hover, --gr-btn-veil-active), а насколько это темнее или светлее — решает тема.

Ссылки (scss/_link.scss)

Модуль нужен потому, что ресет снимает с <a> и цвет, и подчёркивание (color: inherit; text-decoration: none) — это правильно для ссылки-обёртки вокруг карточки, но обычную ссылку в тексте оставляет неотличимой от текста.

.gr-link и .gr-btn-link — разные вещи: первая ведёт по адресу, вторая выполняет действие на текущей странице. Выбирает разметка, оформление лишь подтверждает выбор.

Линия объявлена только длинными свойствами — text-decoration-line, -thickness, -style. Сокращённое text-decoration сбрасывает остальные длинные в исходные значения, поэтому одно text-decoration: underline в :hover обнуляло бы толщину from-font из базового класса.

.gr-link-quiet применим там, где ссылка опознаётся по положению — навигация, ряд карточек, футер, — но не в тексте абзаца. Режим для слабовидящих перекрывает его: правило [data-gr-a11y="low-vision"] a[href] из темы возвращает и цвет, и подчёркивание.

Формы (scss/_form.scss)

Состояния: :focus-visible, :user-invalid, [aria-invalid="true"], [aria-invalid="false"], :disabled, :read-only. :user-invalid, а не :invalid: пустое обязательное поле не должно краснеть до того, как его тронули.

Успех — только по явному [aria-invalid="false"]. Пары :user-valid у :user-invalid нет намеренно: браузер считает валидным любое непустое поле без ограничений, и форма зеленела бы сама собой по мере заполнения. Обе стороны ставит одна и та же серверная проверка.

Обязательность рисует .gr-field:has([required]) .gr-label::after — атрибут required уже стоит в разметке, и требовать рядом ещё и класс значило бы держать два источника правды.

Выбор (scss/_choice.scss)

Элемент не подменяется: класс ставится на сам <input>, а не на спрятанный input рядом с оформленным <span>. Родная разметка сохраняет участие в форме, клавиатуру и объявление состояния скринридером.

Ползунок (scss/_range.scss)

Шесть вендорных псевдоэлементов, каждый — отдельным правилом: неизвестный селектор в группе делает невалидной всю группу, и бегунок остался бы системным в обоих движках. accent-color при этом не снимается — он единственное, что делает ползунок частью библиотеки там, где appearance: none ещё не применён.

Заполненную часть дорожки Firefox рисует сам (::-moz-range-progress) и без скрипта. У WebKit псевдоэлемента для неё нет: там след — градиент по --gr-progress, и без слоя он просто не появляется. Чисто-CSS-приём (тень бегунка, обрезанная дорожкой) отвергнут: та же обрезка съедает круглую ручку.

Направление следа задано ручкой --gr-range-dir, а не стороной в каждом градиенте: логической формы у градиента нет, а в RTL движок разворачивает ползунок — и одно правило :dir(rtl) разворачивает след во всех дорожках сразу, включая пару.

Карточки (scss/_card.scss)

Токены компонента читаются с запасным значением, на компоненте не объявляются, поэтому переопределение на любой обёртке доходит до карточки:

Таблицы (scss/_table.scss)

Сообщения (scss/_alert.scss)

Слово берёт --gr-alert-color (безопасный для текста), полоса и подложка — --gr-alert-fill. У предупреждения это разные цвета: подробности ниже, в разделе о токенах.

Статус читается словом, а не только цветом: цветная полоса не переживает чёрно-белую печать, дальтонизм и монохромный режим высокого контраста, а слово переживает. Роль (role="alert" или role="status") объявляется разметкой — модуль её не подставляет.

Плашки (scss/_badge.scss)

Статус задаёт три цвета, а не один: --gr-badge-color для текста и линии, --gr-badge-fill для заливки и --gr-badge-on-fill для чернил на ней. У четырёх статусов из пяти первые два совпадают; расходятся они у предупреждения — см. --gr-color-warning-surface в таблице токенов.

Аватары (scss/_avatar.scss)

Фолбэк не требует скрипта: нет картинки — нет и перекрытия, инициалы остаются видны. Битая ссылка даёт тот же результат.

Навигация (scss/_nav.scss)

Активный пункт помечается aria-current="page" — тем же признаком, по которому его находит программа чтения с экрана. Отдельного класса на это нет: класс подсветил бы пункт только зрячему.

Сворачивание не прячет навигацию внутрь <details>: содержимое <details> скрывает сам браузер, и вернуть его на широком экране без скрипта нечем. Навигация стоит следующим соседом переключателя, поэтому раскрытием управляет .gr-nav-toggle[open] + .gr-nav-collapse, а с 768px медиазапрос отменяет сворачивание целиком:

<div class="gr-navbar">
  <a class="gr-navbar-brand" href="/">Сайт</a>
  <details class="gr-nav-toggle"><summary>Меню</summary></details>
  <nav class="gr-nav gr-nav-collapse">…</nav>
</div>

Хлебные крошки (scss/_breadcrumb.scss)

Разделитель рисует ::before у каждого пункта, кроме первого; символ — переменная --gr-breadcrumb-sep (по умолчанию /). Последний пункт не ссылка, а текст с aria-current="page".

Меню (scss/_menu.scss)

Собственного раскрытия у модуля нет — это оформление списка. Открывает его .gr-dropdown.

Выпадающая панель (scss/_dropdown.scss)

Два пути, оба без скрипта. <details class="gr-dropdown"> работает везде, но не закрывается по Esc и по клику мимо — <details> о них не знает. <button popovertarget> с панелью popover получает и то, и другое от браузера; привязать её к кнопке умеет только CSS anchor positioning, поэтому там, где его нет, панель раскрывается листом у нижнего края экрана. Положение не то — меню доступно и закрывается штатно.

Третий способ — .gr-dropdown-hover: панель держится, пока указатель на обёртке, и уходит с четвертьсекундной задержкой; зазор до панели перекрыт невидимым мостиком, иначе наведение прерывалось бы на полпути. Скрипт не нужен и здесь: показ — :hover внутри @media (hover: hover), а на сенсорном экране и с клавиатуры — :focus-within, поэтому кнопка обязана быть <button>. Цена способа: aria-expanded без скрипта не обновить (кнопке ставят aria-haspopup="true" и молчат об открытости), а закрытия по Esc платформа тут не даёт — наведение для браузера не «открытое состояние». Годится для навигации; меню с «Удалить» и «Выйти» делают на <details> или на попапе, где состояние настоящее.

Аккордеон (scss/_accordion.scss)

Эксклюзивность (открыт только один раздел) даёт платформа: общий атрибут name у соседних <details>. CSS на это не нужен вовсе.

Плавное раскрытие включается только там, где браузер умеет анимировать высоту до auto (interpolate-size: allow-keywords) и выбирать содержимое <details> селектором (::details-content). Без обоих условий раздел раскрывается сразу — и это рабочее состояние, а не поломка.

Вкладки (scss/_tabs.scss)

Без скрипта это ссылки-якоря и подряд идущие секции: страница читается и печатается целиком. Со скриптом (griffincss-ui.js) появляются role="tablist", стрелки, Home/End и roving tabindex, а неактивные панели прячет атрибут hidden — не правило библиотеки: display: none убрал бы панель с экрана, но оставил бы её в порядке обхода.

Модальное окно (scss/_modal.scss)

Верхний слой без z-index, удержание фокуса внутри окна, закрытие по Esc, возврат фокуса на кнопку, инертность страницы под окном — всё это даёт <dialog>. Открывает окно showModal(), закрывает <form method="dialog"> внутри него — без единой строки собственного JS.

Единственное, чего <dialog> не умеет, — закрытие щелчком по подложке. Его добавляет опциональный griffincss-ui.js, и включается оно атрибутом на самом окне, а не глобальной настройкой:

<dialog class="gr-modal" data-gr-overlay-close>…</dialog>

<script src="griffincss-ui/dist/griffincss-ui.js"></script>

Работает и на .gr-drawer — это тот же <dialog>. После такого закрытия dialog.returnValue равен "overlay", поэтому обработчик отличит щелчок мимо от кнопки «Сохранить». Выделение текста, начатое внутри окна и законченное за его краем, окно не закрывает: рантайм сверяет обе половины щелчка. У окна с наполовину заполненной формой атрибут просто не ставят.

Выдвижная панель (scss/_drawer.scss)

Пояса берутся у модалки — .gr-modal-header, -body, -footer работают и здесь: панель отличается положением, а не устройством. Стороны заданы логическими свойствами, поэтому в разметке справа налево панель «конца строки» выезжает слева.

Подсказка (scss/_tooltip.scss)

Показывается и указателем, и с клавиатуры, и то и другое — чистым CSS: :hover внутри @media (hover: hover) и :focus-within. aria-describedby в разметке обязателен, иначе подсказку получит только тот, кто её видит. Прячут её visibility и прозрачность, а не display: none: скрытая через display, она исчезла бы из дерева доступности вместе со связью.

Пагинация (scss/_pagination.scss)

Текущая страница помечается aria-current="page" и выделяется заливкой, а не только цветом: в ряду одинаковых цифр разница в оттенке замечается хуже, чем разница в весе пятна. Недоступная кнопка «дальше» получает aria-disabled="true" и остаётся в порядке обхода — исчезнувшая кнопка сбивает счёт нажатий Tab, приглушённая не сбивает.

Полоса выполнения и шкала (scss/_progress.scss)

Дорожку и заполнение рисуют вендорные псевдоэлементы, и каждый объявлен своим правилом: неизвестный селектор делает невалидной всю группу, поэтому ::-webkit-progress-value рядом с ::-moz-progress-bar не покрасил бы ни того, ни другого.

У шкалы классов-статусов нет намеренно. <meter> сам вычисляет по low, high и optimum, попало ли значение в хороший диапазон; класс позволил бы разметке сказать «плохо» там, где элемент вычислил «хорошо».

<progress> — про ход задачи, у которой есть конец. <meter> — про измеренную величину: заполненность диска, оценку, запас.

Рейтинг (scss/_rating.scss)

Два одинаковых ряда знаков друг над другом: нижний (::before) задаёт ширину и рисует пустые знаки, верхний (::after) залит и обрезан по доле оценки. Заливка одного ряда через background-clip: text потребовала бы color: transparent, а прозрачный текст исчезает в режиме принудительных цветов вместе со всей оценкой.

Разрядки между знаками нет намеренно: интервал сдвигал бы границу заливки на целое число промежутков, и доля перестала бы совпадать с оценкой. Обрезка идёт от логического края (inset-inline-start), поэтому под dir="rtl" ряд разворачивается сам — правил на [dir] в модуле нет.

Иконок библиотека не везёт: вид задаётся глифом в --gr-rating-symbol, и на этом граница. Оценка обязана быть и словом — role="img" с aria-label вида «4,5 из 5».

Кольцо занятости (scss/_spinner.scss)

Размеры в em, а не в rem: кольцо внутри кнопки должно быть по её кеглю. Пустому <span> нужны role="status" и подпись, иначе о загрузке узнает только тот, кто видит кольцо; рядом с видимым словом «Сохраняем…» хватает aria-hidden="true".

При prefers-reduced-motion вращение замедляется, но не снимается: остановленный индикатор занятости сообщает «зависло».

Заглушка на время загрузки (scss/_skeleton.scss)

Залито оттенком currentcolor, а не серым: непрозрачный цвет совпал бы с одной из подложек и стал бы невидимым. .gr-skeleton-group задаёт отступы и зазоры сама, поэтому в карточке встаёт вместо .gr-card-body — у самой .gr-card внутренних отступов нет. Обёртке нужен aria-hidden="true", а рядом — слово в role="status": пустые прямоугольники в озвучке не значат ничего.

Мерцание по prefers-reduced-motion снимается совсем — в отличие от спиннера: заглушка сообщает о загрузке самим своим присутствием.

Всплывающие уведомления (scss/_toast.scss)

Единственный компонент библиотеки без статического применения: показывает и убирает тосты griffincss-ui.js.

<div class="gr-toast-region gr-toast-region-bottom-end"
     role="status" aria-live="polite"></div>

Griffincss.ui.toast('Черновик сохранён', { status: 'success', title: 'Готово' });

Регион ставят на страницу один раз и пустым: программа чтения с экрана следит за изменениями внутри aria-live, а не за появлением самой области. Появление тоста объявлено через @starting-style, поэтому рантайму не нужны ни второй кадр, ни пара «добавил класс — снял класс».

Шаги процесса (scss/_steps.scss)

Текущий шаг помечается aria-current="step" — тем же признаком, по которому его находит программа чтения с экрана; класса для него нет. Знак в маркере (номер, галочка) кладут в разметку: цвет не переживает чёрно-белую печать и дальтонизм, знак переживает.

Линия — хвост шага, ведущий к следующему: ::after у левого, в колонке — у верхнего. Залита она у пройденного, у текущего остаётся серой. Так решено потому, что только у левого шага длину линии считает сам CSS: сколько текста висит под маркером предыдущего шага, правило, написанное на следующего, знать не может, и в колонке хвост, растущий вверх, не доставал бы до соседнего маркера.

Пустое состояние (scss/_empty.scss)

Ширина пояснения ограничена в ch, а не в пикселях, поэтому ограничение в 46 знаков остаётся таким же и в режиме для слабовидящих. Слот под кнопку есть потому, что пустое состояние без действия — тупик.

Рантайм компонентов (dist/griffincss-ui.js)

ES5-совместимый файл без зависимостей, пишется руками и не компилируется. Автостарт по DOMContentLoaded; отключается атрибутом data-auto="false" на теге <script>. Делает четыре вещи, которых платформа не даёт:

Таймер тоста останавливается под указателем и под фокусом и дочитывает остаток, а не начинается заново. Все обработчики — делегированные, по одному на документ: Griffincss.ui.start() и .destroy() поднимают и снимают их целиком.

Клавиатура вкладок включается только при data-gr-tabs. Без атрибута и без скрипта та же разметка остаётся списком ссылок-якорей и секциями подряд — страница читается сверху вниз и печатается целиком.

События рантайма

Рантайм сообщает о действиях пользователя событиями CustomEvent — по образцу griffincss:themechange у рантайма темы. События всплывают, слушать их можно на документе.