Организация проекта на 5000 строк

Файл на восемьсот строк ещё читается: нужное находится поиском. На двух тысячах поиск перестаёт помогать — совпадений слишком много. На пяти тысячах открывать файл страшно.

Хаос никогда не создаётся сознательно. Он набегает по строчке: правило дописали в конец, потому что «так быстрее», значение продублировали, потому что «в тот раз работало».

Структура нужна не ради красоты. Она отвечает на один вопрос: где лежит то, что я сейчас правлю, и куда положить то, что я сейчас пишу.

1styles/2  main.css              подключает всё, задаёт порядок слоёв34  base/5    reset.css           сброс браузерных стилей6    tokens.css          переменные: палитра, шкалы, тени7    typography.css      заголовки, текст, ссылки8    forms.css           базовый вид полей910  layout/11    container.css       ширины и поля страницы12    grid.css            сетки раскладки13    header.css          шапка и подвал1415  components/16    button.css          по файлу на компонент17    card.css18    modal.css1920  utilities/21    spacing.css         отступы по шкале22    visibility.css      скрытие, доступность

Правило деления простое и совпадает со слоями каскада из двадцать шестого урока.

base — то, что действует на голые теги. layout — то, что расставляет блоки по странице. components — сущности со своими именами. utilities — одиночные правки, побеждающие всё.

Без слоёв порядок подключения — единственное, что определяет приоритет при равном весе селекторов. Со слоями он перестаёт быть хрупким: даже если файл случайно окажется не на своём месте, слой удержит приоритет.

1/* Порядок слоёв объявлен первой строкой — дальше он нерушим */2@layer reset, tokens, base, layout, components, utilities;34@import url("base/reset.css")       layer(reset);5@import url("base/tokens.css")      layer(tokens);6@import url("base/typography.css")  layer(base);7@import url("base/forms.css")       layer(base);89@import url("layout/container.css") layer(layout);10@import url("layout/grid.css")      layer(layout);11@import url("layout/header.css")    layer(layout);1213@import url("components/button.css") layer(components);14@import url("components/card.css")   layer(components);15@import url("components/modal.css")  layer(components);1617@import url("utilities/spacing.css")    layer(utilities);18@import url("utilities/visibility.css") layer(utilities);

Комментарий, повторяющий код, бесполезен и быстро устаревает. Комментарий, объясняющий почему, живёт годами.

/* Отступ 16 пикселей */
padding: 16px;

/* Красный цвет */
color: #c8394a;

/* 34px — высота липкой шапки: под неё
   резервируем место при переходе по якорю */
scroll-padding-top: 34px;

/* Safari до 17 не понимал :has() внутри
   @supports — поэтому проверка отдельной строкой */
@supports selector(:has(*)) { … }

В любом проекте старше года есть правила, которые больше нигде не применяются. Опасность не в весе файла, а в том, что их боятся удалять: непонятно, не сломается ли что-то.

Надёжного автоматического способа нет: классы могут добавляться скриптом или приходить из шаблонов на сервере. Но есть порядок действий, который снижает риск почти до нуля.

Отдельная страница со всеми компонентами в одном месте окупается быстрее, чем кажется. На ней сразу видно, что кнопок стало пять вместо трёх, а два бейджа отличаются на два пикселя.

Никакого инструмента не нужно: обычная HTML-страница, подключающая те же стили.

1<link rel="stylesheet" href="styles/main.css">23<main class="container stack gap-8">4  <section>5    <h2>Кнопки</h2>6    <div class="row gap-2">7      <button class="btn btn--primary">Основная</button>8      <button class="btn btn--ghost">Второстепенная</button>9      <button class="btn btn--primary" disabled>Недоступная</button>10    </div>11  </section>1213  <section>14    <h2>Карточки</h2>15    <div class="grid gap-4">16      <!-- обычная, со скидкой, без картинки, длинное название -->17    </div>18  </section>19</main>

Правило @supports проверяет, понимает ли браузер конструкцию. Оно нужно не всегда: незнакомое свойство и так игнорируется. Но есть два случая, где без него не обойтись.

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

1/* База: работает везде */2.cards {3  display: flex;4  flex-wrap: wrap;5  gap: 16px;6}78.card { flex: 1 1 240px; }910/* Улучшение: применяется целиком или не применяется вовсе */11@supports (grid-template-rows: subgrid) {12  .cards {13    display: grid;14    grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));15    grid-auto-rows: auto 1fr auto;16  }1718  .card {19    grid-row: span 3;20    grid-template-rows: subgrid;21  }22}

Короткий список вопросов, который ловит большую часть проблем ещё до того, как они попадут в проект.

• Селектор длиннее двух частей — почему?
• Есть !important — что он перебивает и нельзя ли иначе?
• Новое значение цвета или отступа — почему не из шкалы?
• У компонента появился внешний margin — точно ли это его забота?
• Правило дописано в конец файла — это его место или так вышло?
• Добавлен новый компонент — он есть на стайлгайде?

• Двадцать папок на лендинге. Для трёхсот строк структура из пяти каталогов — чистые накладные расходы. Одного файла достаточно, пока поиск работает.
• Заводить структуру задним числом ради структуры. Большая перекладка файлов — риск без немедленной пользы. Вводи новый порядок в новом коде, старый трогай при очередной правке.
• Двадцать @import без сборки. Задержка загрузки съест выигрыш от аккуратности.
• Стайлгайд, который никто не открывает. Если он устарел на полгода, он вреднее отсутствия: показывает то, чего в проекте уже нет.

<article class="card text-center">  <h3 class="card__title">Раф</h3>  <p class="card__text">Должен быть по центру</p></article>

.text-center { text-align: center; }​.card {  padding: var(--space-4);  background: var(--color-surface);  border-radius: 12px;  text-align: left;}​* { box-sizing: border-box; }​:root {  --space-4: 16px;  --color-surface: #f4f4f8;}​h3 { margin: 0 0 6px; font-size: 16px; }p { margin: 0; font-size: 14px; }​.card__title { color: #16181d; }.card__text { color: #5b6070; }

1<article class="card text-center">2  <h3 class="card__title">Раф</h3>3  <p class="card__text">Должен быть по центру</p>4</article>

1@layer reset, tokens, base, components, utilities;23@layer reset {4  * { box-sizing: border-box; }5}67@layer tokens {8  :root {9    --space-4: 16px;10    --color-surface: #f4f4f8;11  }12}1314@layer base {15  h3 { margin: 0 0 6px; font-size: 16px; }16  p { margin: 0; font-size: 14px; }17}1819@layer components {20  .card {21    padding: var(--space-4);22    background: var(--color-surface);23    border-radius: 12px;24    text-align: left;25  }2627  .card__title { color: #16181d; }28  .card__text { color: #5b6070; }29}3031@layer utilities {32  .text-center { text-align: center; }33}