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

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

⚡ Кратко

Конкретные цвета вместо токенов, правка компонентов вместо темы, забытая тёмная половина, слабый контраст приглушённого текста.

Ошибка 1. Палитра вместо токенов

Как ломается: в тёмной теме карточка остаётся белой, потому что цвет задан жёстко.

❌ Конкретный цвет

<div class="bg-white text-slate-900 border-slate-200">…</div>

✅ Токен

<div class="bg-card text-card-foreground border-border">…</div>

Исключение: декоративные элементы, которые сознательно должны выглядеть одинаково в обеих темах — например, логотип бренда.

Ошибка 2. Правка компонента вместо темы

Как ломается: «перекрасили» кнопку, а бейджи, ссылки и кольца фокуса остались старого цвета.

Как правильно: если цвет относится к роли («основное действие»), меняйте токен. Компонент трогают, когда меняется именно оформление этого компонента, а не роль.

Ошибка 3. Обновили светлую тему, забыли тёмную

Как ломается: в тёмной теме кнопка сливается с фоном или, наоборот, «горит».

/* правило: любая правка токена — сразу в двух блоках */
:root { --primary: oklch(0.55 0.21 264); }
.dark { --primary: oklch(0.62 0.19 264); }   /* ← не забыть */

Ошибка 4. Слишком приглушённый muted-foreground

Как ломается: подписи и подсказки не читаются на солнце и на плохих экранах.

Основной текст — максимальный контраст

Приглушённый — проверьте, что он ещё читается

А так уже слишком бледно

<div class="space-y-2 rounded-lg bg-card p-3 ring-1 ring-border">
  <p class="text-sm text-card-foreground">Основной текст — максимальный контраст</p>
  <p class="text-sm text-muted-foreground">Приглушённый — проверьте, что он ещё читается</p>
  <p class="text-sm text-muted-foreground/60">А так уже слишком бледно</p>
</div>

Как правильно: --muted-foreground — не «почти невидимый», а «менее важный». Проверяйте его контраст так же строго, как основной текст.

Ошибка 5. Тема в двух местах

Как ломается: часть переменных в index.css, часть — в theme.css, и никто не знает, какая победит.

Как правильно: один файл темы. Если нужны отдельные темы для брендов, делайте их дополнительными классами (.theme-acme) с полным набором переменных.

Ошибка 6. Копирование темы под старую версию

Готовые темы из интернета часто написаны для v3: значения в них — три числа без hsl(). Вставленные в проект на v4 они дают невалидный цвет, и элементы теряют оформление вовсе. Признак: в теме нет ни oklch(, ни hsl(.