Утилиты и компоненты

Эта страница проводит границу между утилитами и компонентами и собирает правила всей части в один список для проверки разметки.

Утилиты и компоненты: где проходит граница

Утилиты и компоненты дополняют друг друга. Эта глава объясняет, что утилита может и чего не может сделать с компонентом и когда вместо утилит нужен компонент или собственный CSS.

Компонент сильнее утилиты

Каскадные слои Framework идут в порядке sf.reset, sf.tokens, sf.base, sf.utilities, sf.components, sf.overrides, sf.states. Слой sf.components объявлен после sf.utilities и поэтому сильнее его, какой бы ни была специфичность селектора (см. Каскадные слои).

Практическое следствие: утилитой нельзя перебить собственное правило компонента. Если sf-button задаёт свой внутренний отступ, класс p-4 на кнопке его не изменит. Чтобы изменить вид компонента, меняйте его настройки (size, appearance, scheme) или общие токены (см. Как менять дизайн), а не навешивайте утилиту и не повышайте специфичность.

То же относится к утилите на части компонента. Например, sr-only на подписи внутри кнопки подпись не спрячет: правило кнопки .sf-button > * задаёт своим частям position: relative из слоя sf.components, и position: absolute утилиты проигрывает. Кнопке без видимого текста дают доступное имя атрибутом aria-label, а не прячут подпись утилитой.

Утилиты на компоненте при этом полезны — для того, чего компонент не задаёт сам: внешнего отступа, ширины в раскладке, места в сетке, видимости на разных экранах.

<button type="submit" class="sf-button sf-button--default sf-button--primary sf-button--size-1 m-top-2 w-full md:w-fit">
  <span class="sf-button-text-container">Отправить</span>
</button>

Когда утилиты, а когда компонент

Выбирайте утилиты, когда:

• нужно расставить элементы (раскладка, промежутки, выравнивание);
• оформление встречается один-два раза и не имеет устойчивой структуры;
• нужно адаптировать уже существующий блок к месту на странице.

Выбирайте компонент, когда:

• одна и та же структура с одним и тем же набором классов повторяется по проекту: каждый повтор — копия, которую придётся править везде;
• у элемента есть варианты (size, appearance, status), которые должны меняться согласованно;
• нужны состояния, которых утилиты не дают: наведение только на широком экране, зависимость части от состояния родителя, анимация открытия;
• нужно поведение — тогда это Smart-компонент (см. Когда применять, а когда нет).

Признак, что пора писать компонент: одинаковая строка из десяти утилит встречается в трёх местах.

Собственный CSS проекта

Утилиты не заменяют весь CSS проекта. Если значение не помещается ни в одну утилиту, пишите правило проекта, но с теми же токенами: сначала семантический токен нужного назначения, затем примитив шкалы (--sf-c2), затем собственный токен проекта, ссылающийся на системный (см. Порядок выбора). Случайные числа в пикселях — нет.

Правило проекта пишите в собственном слое проекта (см. Как переопределять правильно). Вид компонентов Framework меняйте общими токенами, а не правилами поверх их классов (см. Как менять дизайн).

Смотрите также: Каскадные слои — каскадные слои; Настройки: общий язык компонентов — настройки компонентов; Компонент проекта или утилиты — компонент проекта; Когда применять, а когда нет — Smart-компоненты.

Свод правил

Правила этой части одним списком — для проверки разметки.

1. Одна утилита — одно свойство. Вид собирается из нескольких утилит.
2. Утилиты пишутся без префикса sf-; классы компонентов — с ним.
3. Имя читается слева направо: условие, ограничение, свойство, параметр, значение. Минус — перед всем классом.
4. Для отступов и промежутков используйте шкалу 0, 1/4, 1/3, 1/2, 1…8; абсолютные a0…i9 — только для фиксированных размеров.
5. Цвет — только через роли. Палитра — для декора.
6. Стороны — логические: inline-start и inline-end, start и end.
7. Сначала базовый вид без условий, затем изменения для более широких экранов. Условия ширины — для структуры, а не для подгонки размеров.
8. Для фокуса — focus-visible:, а не focus:.
9. Блок, который стоит в разных местах, адаптируйте условиями контейнера cq-*, а не окна.
10. Компонент не раскладывает себя сам: Flex, колонку и выравнивание пишите в разметке.
11. Утилита не перебивает компонент. Вид компонента меняется его настройками и токенами темы.
12. Не составляйте имена по аналогии — проверяйте их в справочнике.

Смотрите также

• Значения утилит — это токены и шкалы из разделов Токены, цвет и темы и Размер, пространство, текст и форма (см. Дизайн-токены, Соразмерные ступени, Шкала интервалов). Утилита ничего не добавляет к системе значений, только даёт к ней доступ из разметки.
• Loader, поставка и закреплённый план ресурсов — Как работает Loader.
• Классы и настройки компонентов, модификаторы компонентов — Анатомия: корень, части, модификаторы, состояния и Настройки: общий язык компонентов.
• Сборка целых страниц из областей и блоков — Макеты и композиция; утилиты раскладки — её строительный материал.
• Проверки раскладки и правила качества — Принципы качества для всего Framework и Как Framework проверяет себя.