Основания
Утилиты
Пять утилит, и это потолок. Если понадобилась шестая, обычно нужен компонент.
Разметка
<span class="inst-u-dim">приглушённый текст</span>
<span class="inst-u-mono">a4f7c2e</span>
<span class="inst-u-prose-nums">1 234 567</span>
Использование
Каждая существует потому, что описывает работу, которой у компонента нет.
<span class="inst-u-truncate">Очень длинное имя файла, которое не влезает</span>
<span class="inst-u-visually-hidden">Действия</span>
| Что | Обязательно | Почему |
|---|---|---|
| Утилита называет работу | да | «Обрезать», «спрятать визуально», «табличные цифры». Не «отступ 12px» |
inst-u-visually-hidden, а не display: none |
да | Скрытое через display выпадает из дерева доступности вместе со смыслом |
| Отступ утилитой | нет, и не будет | Ритм — работа примитивов потока, а не разметки экрана |
Устройство
inst-u-mono объявлен в одном правиле с code, kbd, samp, pre:
code, kbd, samp, pre, .inst-u-mono {
font-family: var(--font-mono);
font-size: 0.925em;
}
Моноширинный шрифт оптически крупнее санса на том же кегле, поэтому поправка
обязательна. Объявлена она один раз намеренно: когда у утилиты было своё
правило, <code class="inst-u-mono"> получал 0.925 × 0.925 и уезжал под
объявленный пол в 11px.
Внутри блока кода поправка уже применена контейнером — второй раз не нужна.
Шкала
| Класс | Что делает | Когда |
|---|---|---|
inst-u-truncate |
Обрезает строку многоточием | Заголовок, который иначе вытолкнет соседа за край: строка очереди, путь в дифе, подпись дорожки |
inst-u-visually-hidden |
Прячет визуально, оставляет скринридеру | Подпись, которую заменяет иконка; заголовок области, лишний на экране, но нужный на слух |
inst-u-mono |
Моноширинное начертание | Идентификатор или хеш внутри обычного текста |
inst-u-prose-nums |
Пропорциональные цифры | Число в прозе, где табличные цифры выглядят разреженными |
inst-u-dim |
--text-secondary |
Второстепенная часть строки, для которой заводить класс избыточно |
Правила
Утилит отступов — mt-3, p-2, pt-0d25. Причина не в эстетике: шкала
нарочно разрежена сверху, чтобы «чуть побольше» просто не было в наборе, а
набор утилит отступов возвращает это решение первым же классом и переносит
ответственность за ритм из кита в разметку каждого экрана.
Вместо них — три примитива потока с зазором, названным намерением, а не
числом: стопка, кластер и сетка с шагами
--tight / обычный / --loose. Плотность контейнера перенастраивает все три
разом.
| Хочется | Возьмите другое |
|---|---|
| Отступ между элементами | inst-stack или inst-cluster |
| Выравнивание и раскладка | примитивы раскладки |
| Цвет текста | Семантический токен в своём правиле, не утилита |
| Размер шрифта | Компонент. Кегль — часть роли элемента, а не украшение |
Доступность
inst-u-visually-hidden |
Единственный правильный способ спрятать текст от глаза, оставив скринридеру. display: none и visibility: hidden убирают его отовсюду, включая озвучивание |
| Фокус внутри скрытого | Если внутри скрытого блока есть фокусируемый элемент, фокус уедет в невидимое место. Классический случай — «перейти к содержимому»: там нужен inst-skip-link, который проявляется по фокусу |
inst-u-truncate |
Режет визуально: полный текст остаётся в DOM и озвучивается. Для мыши добавьте title, иначе значение доступно только на слух |
inst-u-dim |
--text-secondary держит 4.5:1. Не путайте с --text-faint — это порог декорации (3:1), и текст им красить нельзя |
inst-u-prose-nums |
Пропорциональные цифры нельзя ставить в колонку: разряды перестанут стоять друг под другом |
API
| Имя | Значение | Что делает |
|---|---|---|
| токен | ||
--text-secondary | light-dark(var(--n-9), var(--n-5)) | |
--font-mono | ui-monospace, "Cascadia Code", "JetBrains Mono", "SF Mono", Consolas, "Liberation Mono", monospace | |
Утилиты намеренно не имеют собственных токенов: каждая либо переключает свойство платформы, либо берёт один существующий семантический токен.
Почему кит устроен именно так — конституция · Открытый код под MIT, github.com/keshon/instrument