Правила именования CSS-классов и организации файлов стилей
Хаотичные имена классов и бессистемное подключение стилей превращают поддержку интерфейса в угадайку. Правила ниже проверены на крупных проектах и помогают исключить конфликты, упростить отладку и сделать поведение вёрстки предсказуемым. Они не гонятся за идеалом для браузерного рендеринга: накладные расходы минимальны, а выгода для команды ощутима сразу.
Базовые соглашения: классы и имена файлов
Все имена CSS-классов и файлов пишем в нижнем регистре. Слова внутри имени разделяем дефисом. Такой подход совпадает с тем, как большинство разработчиков именуют директории и PHP-файлы, поэтому порог входа практически нулевой.
/* Хорошо */
.widget-latest-comments {}
.post-view {}
/* Плохо */
.widgetLatestComments {}
.post_view {}Имена файлов оформляем по тому же принципу: post.css, widget-latest-comments.css, markdown.css. Никаких camelCase, нижних подчёркиваний и пробелов.
Структура CSS-файлов в проекте
Раскладываем стили по отдельным файлам с чёткой зоной ответственности. Это упрощает навигацию и ревью. Рекомендуемая структура для типичного PHP-приложения на фреймворке:
- global.css — глобальные стили: сброс, типографика, кнопки, утилиты. Всё, что переиспользуется в разных местах.
- layout.css — стили базовых макетов: шапка, подвал, боковые колонки, основная сетка.
- ControllerID.css — файл, привязанный к конкретному контроллеру. Для
PostControllerсоздаёмpost.css. - widget-WidgetClass.css — стили конкретного виджета. Например,
LatestCommentsобращается кwidget-latest-comments.css. - FeatureName.css — крупные обособленные функции. Например, редактор Markdown использует
markdown.css.
Отдельно подключаем файлы сторонних библиотек и CSS-фреймворков — их не смешиваем с собственным кодом.
Правила именования CSS-классов
Для стилизации элементов используем классы, а не id. Идентификатор может встречаться на странице только один раз, класс — сколько угодно. Это особенно важно в PHP-шаблонах, где один и тот же блок часто рендерится в цикле.
Общие классы
Переиспользуемые классы начинаем с префикса g- и размещаем в global.css:
.g-submit-button {
padding: 0.5rem 1.25rem;
border-radius: 6px;
}
.g-link-button {
text-decoration: none;
}Префикс сразу подсказывает, что класс лежит в глобальном слое и его изменение может затронуть весь проект.
Корневой контейнер представления
Каждый файл, который выводит контент, оборачиваем в корневой контейнер с классом, повторяющим путь до шаблона. Это создаёт локальное пространство имён для стилей и исключает конфликты между разными разделами.
Для представления post/index.php корневой контейнер выглядит так:
<div class="post-index">
<?php foreach ($posts as $post): ?>
<article class="item">
<h2><?= htmlspecialchars($post->title, ENT_QUOTES) ?></h2>
</article>
<?php endforeach; ?>
</div>Стили размещаем в post.css, и каждое объявление начинается с имени корневого контейнера:
/* post.css */
.post-index .item {
margin-bottom: 1.5rem;
}Виджеты
Для виджетов работает та же схема. Виджет LatestComments получает корневой класс widget-latest-comments и обращается к файлу widget-latest-comments.css:
<aside class="widget-latest-comments">
<?php foreach ($comments as $comment): ?>
<div class="comment">
<?= htmlspecialchars($comment->text, ENT_QUOTES) ?>
</div>
<?php endforeach; ?>
</aside>/* widget-latest-comments.css */
.widget-latest-comments .comment {
border-left: 3px solid #e2e8f0;
}Макеты
Файл макета тоже получает корневой контейнер с префиксом layout-. Макет main использует класс layout-main. Чтобы избежать конфликтов с контентными классами, внутренние элементы макета начинаются с имени корневого контейнера:
<body class="layout-main">
<header class="layout-main-header">...</header>
<main class="layout-main-content">...</main>
<footer class="layout-main-footer">...</footer>
</body>Это правило удерживает стили макета от пересечения со стилями внутренних представлений.
Подключение CSS-файлов в PHP-контроллере
Современные PHP-приложения управляют ассетами через встроенный механизм фреймворка. Жёстко прописывать <link> в шаблоне не нужно — вместо этого регистрируем файлы в коде.
Пример регистрации набора стилей через абстрактный менеджер ассетов:
declare(strict_types=1);
final readonly class AssetManager
{
/**
* @param list<string> $cssFiles
*/
public function register(array $cssFiles): void
{
foreach ($cssFiles as $file) {
if (!str_ends_with($file, '.css')) {
throw new InvalidArgumentException(
"Некорректный CSS-файл: {$file}"
);
}
// Здесь — добавление в очередь вывода или регистрация в шаблоне
}
}
}В конфигурации приложения храним список файлов отдельно от логики:
return [
'assets' => [
'css' => [
'global.css',
'layout.css',
'post.css',
'widget-latest-comments.css',
],
],
];Продакшен: объединение и сжатие
В режиме разработки подключаем каждый CSS-файл отдельно — так проще отлаживать. В продакшене объединяем и минифицируем стили в один файл. Это сокращает число HTTP-запросов и ускоряет загрузку страницы.
Итоговому файлу даём имя с временной меткой, например styles-202611221550.css. Браузер кэширует такой файл и не запрашивает его повторно, пока не изменится имя.
Собираем файл консольной PHP-командой. Логика простая: читаем список из конфигурации, склеиваем содержимое, прогоняем через минификатор и записываем результат:
declare(strict_types=1);
final class CssBuildCommand
{
public function run(): void
{
$files = [
'global.css',
'layout.css',
'post.css',
];
$combined = '';
foreach ($files as $file) {
$content = file_get_contents(__DIR__ . '/css/' . $file);
if ($content === false) {
throw new RuntimeException("Не удалось прочитать {$file}");
}
$combined .= $content . PHP_EOL;
}
// Здесь вызывается минификатор — например, класс-обёртка над библиотекой
$minified = (new CssMinifier())->minify($combined);
$filename = 'styles-' . date('YmdHi') . '.css';
file_put_contents(__DIR__ . '/css/' . $filename, $minified);
// Обновляем параметр в конфигурации приложения
$this->updateConfig($filename);
}
}В основном макете проверяем, собран ли общий файл. Если да — подключаем только его, если нет — перебираем список из конфигурации:
<head>
<?php if ($cssCompressed): ?>
<link rel="stylesheet" href="<?= htmlspecialchars($cssBaseUrl . '/' . $cssCompressed, ENT_QUOTES) ?>">
<?php else: ?>
<?php foreach ($cssFiles as $css): ?>
<link rel="stylesheet" href="<?= htmlspecialchars($cssBaseUrl . '/' . $css, ENT_QUOTES) ?>">
<?php endforeach; ?>
<?php endif; ?>
</head>Именование jQuery- и JS-селекторов
Правила для CSS-классов распространяются и на селекторы в JavaScript. При выборке элементов начинаем с имени корневого контейнера, а не с голого класса .item или тега a.
Если нужно повесить обработчик клика на ссылки внутри новостных блоков, селектор строится с учётом контекста:
// Привязываемся к контексту представления
$('.news-index .item a').on('click', function () {
// ...
});Такой подход гарантирует, что обработчик не зацепит случайные элементы из других разделов, даже если там встречаются те же классы.
Чек-лист внедрения
- Классы и файлы называем строчными буквами через дефис.
- Общие переиспользуемые стили кладём в
global.cssс префиксомg-. - Каждое представление оборачиваем в корневой контейнер с классом, совпадающим с путём до шаблона.
- Стили представления начинаются с имени корневого контейнера.
- Виджеты получают префикс
widget-и отдельный файл. - Макеты используют префикс
layout-, внутренние элементы наследуют корневое имя. - В разработке подключаем файлы по отдельности, в продакшене — один минифицированный файл с временной меткой.
- Селекторы в JavaScript строим от корневого контейнера.
Частые вопросы
Почему для стилей лучше использовать классы, а не id?
Идентификатор может встречаться на странице только один раз, а класс — сколько угодно. В PHP-шаблонах один и тот же блок часто выводится в цикле, поэтому классы гораздо практичнее и не создают ограничений.
Зачем нужен префикс g- у глобальных классов?
Он сразу показывает, что класс лежит в global.css и используется в разных местах. При правке таких классов разработчик понимает, что изменения могут затронуть весь проект, а не только отдельный раздел.
Как правильно подключать CSS в продакшене?
Стили объединяют в один файл, минифицируют и добавляют в имя временную метку. Браузер кэширует такой файл и не запрашивает его повторно, пока не изменится имя. Подключение лучше выполнять через менеджер ассетов фреймворка.
Нужно ли следовать этим правилам в JavaScript-селекторах?
Да. Селекторы следует строить от имени корневого контейнера представления. Это привязывает выборку к конкретному разделу и предотвращает случайное срабатывание обработчиков на элементах из других блоков.