Рекомендации по написанию CSS

Наш CSS написан на Sass с использованием синтаксиса SCSS.

Компиляция

Исходные файлы SCSS компилируются в CSS с помощью системы сборки gulp. Для этого требуется Node.js. Чтобы установить библиотеки, необходимые для компиляции SCSS, выполните следующие действия из корневого каталога репозитория Wagtail:

$ npm install --no-save

Для компиляции ресурсов выполните:

$ npm run build

В качестве альтернативы файлы SCSS можно отслеживать, автоматически перекомпилируя их при любых изменениях, выполнив:

$ npm start

Проверка и форматирование SCSS

Wagtail использует инструмент проверки кода stylelint. Вам потребуется Node.js и npm на вашей машине разработки. Убедитесь, что зависимости проекта установлены, выполнив npm install --no-save

Проверка кода

Запустите инструмент проверки из корневого каталога проекта wagtail:

$ npm run lint:css

Инструмент проверки настроен на проверку вашего кода на соответствие приведенным ниже рекомендациям, а также на дополнительные проверки.

Форматирование кода

Если вы хотите автоматически исправлять ошибки, можно запустить данную команду напрямую с помощью:

$ npm run lint:css -- --fix

Изменение конфигурации инструмента проверки

Конфигурация правил проверки кода управляется в отдельном репозитории, чтобы её можно было легко использовать в других проектах Wagtail или плагинах. Эту конфигурацию можно найти по адресу stylelint-config-wagtail.

Справочник по стилю

Отступы

• Используйте мягкие табуляции с отступом в четыре пробела. Пробелы — единственный способ гарантировать, что код будет отображаться одинаково на любом устройстве.
• Размещайте пробелы после : в объявлениях свойств.
• Размещайте пробелы перед { в объявлениях правил.
• Разделяйте правила блоками с новой строки.
• При группировании селекторов размещайте каждый селектор на отдельной строке.
• Закрывающиеся фигурные скобки блоков объявлений ставьте на новой строке.
• Каждое объявление должно находиться на отдельной строке для более точного сообщения об ошибках.
• Добавляйте новую строку в конце файлов .scss.
• Удалите пробелы в конце строк в ваших правилах.
• Добавляйте пробел после запятой в значениях свойств, разделённых запятыми, например rgba()

Форматирование

• Используйте шестнадцатеричные цветовые коды #000, если не используется rgba() в сыром CSS (функция SCSS rgba() перегружена для приема шестнадцатеричных цветов в качестве параметра, например rgba(#000, .5)).
• Используйте // для блоков комментариев (вместо /* */).
• Используйте одинарные кавычки для строковых значений background: url('my/image.png')
• Избегайте указания единиц для нулевых значений, например margin: 0; вместо margin: 0px;.
• Старайтесь ограничивать использование сокращенных объявлений до случаев, когда необходимо явно задать все доступные значения.

Импорты Sass

Опускайте подчеркивания и расширения файлов в включаемых файлах:

// Bad
@import 'components/_widget.scss'

// Better
@import 'components/widget'

Пиксели против ем

Используйте rems для font-size, так как они обеспечивают абсолютный контроль над текстом. Кроме того, предпочтительнее безразмерные line-height потому что он не наследует процентное значение от родительского элемента, а вместо этого основывается на множителе font-size.

Специфичность (классы против идентификаторов)

В коде CSS всегда используйте классы вместо идентификаторов. Идентификаторы слишком специфичны и приводят к дублированию CSS.

При стилизации компонента начинайте с элемента + пространства имен класса, по умолчанию отдавайте предпочтение прямым селекторам потомков и используйте минимальную специфичность. Вот хороший пример:

<ul class="category-list">
    <li class="item">Category 1</li>
    <li class="item">Category 2</li>
    <li class="item">Category 3</li>
</ul>

.category-list { // element + class namespace

    // Direct descendant selector > for list items
    > li {
        list-style-type: disc;
    }

    // Minimal specificity for all links
    a {
        color: #f00;
    }
}

Конвенции именования классов

Никогда не ссылайтесь на имена классов с префиксом js- из файлов CSS. js- используются исключительно из JS-файлов.

Используйте префикс SMACSS is- префикс для правил состояния, которые совместно используются CSS и JS.

Разное

Как правило, избегайте ненужного вложения в SCSS. Максимально три уровня. Если вы не можете этого избежать, вернитесь назад и переосмыслите свою общую стратегию (либо необходимую специфичность, либо структуру вложения).

Примеры

Ниже приведены примеры, которые соответствуют указанным выше рекомендациям:

// Example of good basic formatting practices
.styleguide-format {
    color: #000;
    background-color: rgba(0, 0, 0, .5);
    border: 1px solid #0f0;
}

// Example of individual selectors getting their own lines (for error reporting)
.multiple,
.classes,
.get-new-lines {
    display: block;
}

// Avoid unnecessary shorthand declarations
.not-so-good {
    margin: 0 0 20px;
}
.good {
    margin-bottom: 20px;
}