Как понять, что проблема в проекте связана с Tailwind CSS, а не с API, сетью, дизайном состояния или плохой архитектурой?

Question

Accepted Answer

Принцип локализации

Большинство багов в frontend-проектах не принадлежат одному слою. Чтобы понять, виноват ли Tailwind CSS, нужно изолировать его от остальной системы. Стратегия: минимальный воспроизводимый пример → отключение Tailwind → сравнение с нативным CSS.

Шаг 1 — Воспроизвести изолированно

Создайте минимальный компонент без API-запросов, без Redux/Zustand, без React Query:

// Тест: проблема в Tailwind или в данных?
function IsolatedTest() {
  // Хардкодим данные, убираем зависимость от API
  return (
    
      Test
    
  );
}

Если визуальная проблема воспроизводится без данных — виноват CSS/Tailwind слой. Если нет — проблема в state или API.

Шаг 2 — Проверить сгенерированный CSS

Tailwind JIT генерирует CSS только для классов, найденных в content-сканировании. Возможные причины «пропавших» стилей:

Динамически собранный className: `text-${color}-500` — JIT не найдёт такой класс.
Класс есть в JS, но файл не в content paths — нужно проверить tailwind.config.js → content или @source в v4.
Specificity-конфликт: глобальный CSS переопределяет Tailwind-класс — проверяем DevTools → Computed Styles → Overridden rules.

# Проверить, что класс попал в итоговый CSS
grep -r 'text-red-500' .next/static/css/
# или через PostCSS debug
npx tailwindcss -i ./src/globals.css -o /tmp/out.css --content './src/**/*.tsx'
grep 'text-red-500' /tmp/out.css

Шаг 3 — Отделить API/сеть

Если компонент рендерится не так при реальных данных, но корректно при хардкоде:

Проверьте Network tab — может прийти пустой массив или null, вызывающий conditional rendering.
Проверьте React DevTools — правильный ли state передаётся в компонент.
Добавьте console.log прямо перед return, чтобы убедиться, что className формируется корректно.

Шаг 4 — Проверить дизайн состояния

Частая ошибка: className зависит от состояния, но условие записано неверно:

// Ошибка: оба класса могут применяться одновременно при неверной логике
const cls = isError ? 'border-red-500' : '';
const cls2 = isValid ? 'border-green-500' : '';
// Правильно: один источник состояния
const borderCls = isError ? 'border-red-500' : isValid ? 'border-green-500' : 'border-gray-300';

Шаг 5 — Исключить архитектурные причины

CSS Cascade: если стили определены в @layer base или @layer components, они имеют меньший specificity, чем inline styles.
CSS-in-JS конфликт: если рядом используется Emotion/styled-components, их runtime-стили могут перекрывать Tailwind.
Purge в production: в dev Tailwind генерирует все классы, в production — только используемые. «Работает в dev, сломано в prod» — первый признак проблемы с content paths.

Подводные камни

«Работает локально, сломано в production» — почти всегда проблема с JIT content paths, не с Tailwind как таковым.
DevTools показывает класс на элементе, но стиль не применяется — проверьте !important или specificity в глобальном CSS.
Tailwind v4 изменил приоритет слоёв — правила из @layer utilities имеют иной порядок, чем в v3.
При использовании clsx или cn легко передать конфликтующие классы (p-2 p-4) — используйте tailwind-merge для разрешения конфликтов.
Responsive-классы (md:flex) не работают при неправильном viewport meta — убедитесь, что установлен.
Dark mode классы (dark:bg-gray-800) требуют настройки darkMode: 'class' в конфиге и добавления класса dark на .
Не обвиняйте Tailwind до проверки браузерной совместимости — некоторые утилиты используют CSS Grid subgrid или :has(), не поддерживаемые в старых Chrome.
Проблема может быть в порядке импортов CSS — если глобальный reset импортируется после Tailwind base, он перезатирает стили.

Как понять, что проблема в проекте связана с Tailwind CSS, а не с API, сетью, дизайном состояния или плохой архитектурой?

Принцип локализации

Шаг 1 — Воспроизвести изолированно

Шаг 2 — Проверить сгенерированный CSS

Шаг 3 — Отделить API/сеть

Шаг 4 — Проверить дизайн состояния

Шаг 5 — Исключить архитектурные причины

Подводные камни

What hurts your answer

What they're listening for

Related topics