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

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

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

// Тест: проблема в Tailwind или в данных?
function IsolatedTest() {
  // Хардкодим данные, убираем зависимость от API
  return (
    <div className="flex items-center gap-4 rounded-lg bg-white p-4 shadow">
      <span className="text-red-500">Test</span>
    </div>
  );
}

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

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

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

Шаг 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 — убедитесь, что <meta name="viewport"> установлен.
• Dark mode классы (dark:bg-gray-800) требуют настройки darkMode: 'class' в конфиге и добавления класса dark на <html>.
• Не обвиняйте Tailwind до проверки браузерной совместимости — некоторые утилиты используют CSS Grid subgrid или :has(), не поддерживаемые в старых Chrome.
• Проблема может быть в порядке импортов CSS — если глобальный reset импортируется после Tailwind base, он перезатирает стили.

• Сразу обвинять Tailwind CSS, не проверив соседние слои системы
• Чинить симптом без минимального воспроизведения и evidence
• Не учитывать версии, конфигурацию, окружение и recent changes

• Умеет локализовать проблему вокруг Tailwind CSS
• Двигается от симптома к гипотезам и проверкам
• Отличает баг инструмента от ошибки использования или окружения