ADR-1: Правила использования БЭМ

Статус

Принято (05.09.2025)

Контекст

В проекте используется методология БЭМ для организации CSS-стилей.
Нужно единообразно именовать блоки, элементы и модификаторы, а также установить правила вложенности и структуры SCSS.

Решение

Основные понятия БЭМ

• Блок — самодостаточный компонент интерфейса, может использоваться повторно.
• Элемент — часть блока, имеющая смысл только внутри него.
• Модификатор — флаг, изменяющий внешний вид или поведение блока/элемента.

Правила именования

• Блок: block-name
• Элемент: block-name__element-name
• Модификатор:
  • для блока: block-name_modifier-name
  • для элемента: block-name__element-name_modifier-name

Пример:

.button {
  &__icon {
    &_red { }
  }
  &_red { }
}

Связь блоков с Vue-компонентами

• Каждый Vue-компонент имеет основной блок БЭМ, имя которого совпадает с названием файла компонента (в kebab-case).
• Даже если название длинное — не сокращаем.
• Это исключает дубли и путаницу в IDE.

Пример:

<!-- BaseHeader.vue -->
<template>
  <header class="base-header">
    <div class="base-header__logo"></div>
    <nav class="base-header__nav"></nav>
  </header>
</template>

<style lang="scss">
.base-header {
  &__logo { }
  &__nav { }
  &_sticky { }
}
</style>

<!-- UserProfileCard.vue -->
<template>
  <div class="user-profile-card">
    <div class="user-profile-card__avatar"></div>
    <div class="user-profile-card__info"></div>
  </div>
</template>

<style lang="scss">
.user-profile-card {
  &__avatar { }
  &__info { }
}
</style>

Дополнительные правила

• Использование !important запрещено. Допускается только в исключительных случаях, если нет другого решения.
• Медиа-запросы всегда пишутся внизу блока.
• Медиа-запросы должны быть вложены внутрь блока. Блоки не могут быть вложены внутрь медиа-запроса.

Последствия

• ✅ Единообразный стиль именования классов.
• ✅ Легкий поиск и автоподсказки в IDE.
• ✅ Прозрачная связь компонентов Vue и CSS-классов.
• ❌ Иногда классы получаются длинными.