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

Tailwind CSS

Wagtail использует утилитарные классы через Tailwind, сгенерированные на основе значений, заданных в файле tailwind.config.js

Для использования этих утилит вам необходимо добавить префикс w- к именам ваших классов, чтобы избежать конфликтов с другими предопределёнными стилями с похожими именами.

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

Запустите проверку кода из корня проекта wagtail:

$ npm run lint:css

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

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

Для автоматического форматирования с помощью Prettier выполните:

$ npm run format

Если вы хотите автоматически исправлять ошибки проверки:

$ npm run lint:css -- --fix

Изменение настроек проверки

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

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

• Используйте шестнадцатеричные коды цветов #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'

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

Используйте 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- prefix для правил состояния, которые используются как в 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;
}