Урок 03. Частые ошибки

📁 Раздел: Введение ⏱️ Время изучения: ~50 мин 🎯 Сложность: Начальная

⚡ Кратко

Динамические имена классов, забытый источник, свой CSS вне слоёв и попытка «настроить» тему в несуществующем конфиге — четыре следствия непонимания движка.

Ошибка 1. Классы, которых нет в исходниках

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

❌ Неправильно

const cls = `text-${level}-600`

✅ Правильно

const LEVELS = {
  info: "text-sky-600",
  warn: "text-amber-600",
  error: "text-rose-600",
}
const cls = LEVELS[level]

Почему коварно: если text-sky-600 случайно встречается в другом файле, класс окажется в сборке и ошибка временно «исчезнет» — до первого рефакторинга того файла.

Ошибка 2. Шаблоны бэкенда вне сканирования

Как ломается: страницы, отрисованные сервером, выглядят как голый HTML, хотя классы в шаблоне есть.

@import "tailwindcss";
@source "../app/views";   /* каталог шаблонов Rails/Django/Laravel */

Почему: автоопределение отталкивается от корня проекта и игнорирует то, что игнорирует git. Каталог сборки, временные папки, внешние пакеты нужно подключать явно.

Ошибка 3. Свой CSS сильнее утилит

Как ломается: добавляете p-8, но отступ не меняется, потому что где-то есть .card { padding: 1rem; }.

❌ Правило вне слоёв

.card { padding: 1rem; }

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

@layer components {
  .card { padding: 1rem; }
}

Почему: неслоёные правила в каскаде сильнее любых слоёных. Положив свой CSS в components, вы возвращаете утилитам право переопределять его — как и ожидается в утилитарном подходе.

Ошибка 4. Настройка темы «по памяти» из v3

Как ломается: создаёте tailwind.config.js, добавляете цвет — ничего не меняется, ошибок нет.

Почему: в v4 этот файл не читается автоматически. Либо переносите тему в @theme, либо явно подключайте старый конфиг через @config на время миграции.

Ошибка 5. Ожидание, что тема сама «применится»

Токен --color-brand-500 не красит ничего сам по себе: он лишь делает доступными утилиты. Чтобы кнопка стала фирменной, класс bg-brand-500 всё равно нужно написать в разметке — или связать токен с семантическим именем, как это делает shadcn/ui (урок 19).