В чём разница между extend и прямым переопределением темы в конфигурации Tailwind?

extend vs переопределение: суть разницы

В Tailwind CSS v3 есть два места для пользовательских значений в tailwind.config.js: theme.extend (добавляет поверх дефолтов) и theme напрямую (полностью заменяет namespace). В v4 аналогичная логика реализована через @theme с возможностью сброса через initial.

Tailwind v3: extend vs прямое переопределение

// tailwind.config.js
module.exports = {
  theme: {
    // ПРЯМОЕ ПЕРЕОПРЕДЕЛЕНИЕ: удаляет ВСЕ стандартные тени
    // После этого shadow-sm, shadow-md, shadow-lg — не существуют
    boxShadow: {
      card: '0 4px 16px rgb(0 0 0 / 0.08)',
    },

    extend: {
      // РАСШИРЕНИЕ: добавляет shadow-card, НЕ удаляя shadow-sm/md/lg/xl
      boxShadow: {
        card: '0 4px 16px rgb(0 0 0 / 0.08)',
      },

      // Цвета: добавляет brand-* поверх blue, red, gray и т.д.
      colors: {
        brand: {
          500: '#3b82f6',
          700: '#1d4ed8',
        },
      },

      // Spacing: добавляет 18 (4.5rem) поверх 1,2,3...
      spacing: {
        18: '4.5rem',
      },
    },
  },
};

Что происходит при прямом переопределении

Если вынести ключ из extend в theme напрямую — Tailwind заменяет весь namespace. Типичная ошибка:

// ОПАСНО: theme.colors без extend
module.exports = {
  theme: {
    colors: {
      brand: { 500: '#3b82f6' },
      // white, black, transparent, slate, gray... — всё исчезло!
    },
  },
};

После этого классы text-white, bg-gray-100, border-transparent перестают работать — их нет в сгенерированном CSS.

Tailwind v4: @theme и сброс через initial

@import "tailwindcss";

@theme {
  /* РАСШИРЕНИЕ: добавляет --color-brand-500, не трогая остальные цвета */
  --color-brand-500: oklch(0.62 0.18 255);
  --color-brand-700: oklch(0.48 0.16 255);
}

@import "tailwindcss";

@theme {
  /* ПОЛНАЯ ЗАМЕНА: сначала сбрасываем все дефолтные цвета */
  --color-*: initial;

  /* Затем задаём только нужные */
  --color-brand-500: oklch(0.62 0.18 255);
  --color-white:     #ffffff;
  --color-black:     #000000;
  --color-transparent: transparent;
}

Когда что выбирать

• extend / без initial — в 95% случаев. Сохраняет дефолтную шкалу, добавляет брендовые токены поверх.
• прямое переопределение / initial — когда строите изолированную дизайн-систему и дефолтная палитра Tailwind только мешает (создаёт лишние классы, конфликты с lint-правилами). Используется в больших продуктах с жёстким design token governance.

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

• Забытый white/black при полной замене — --color-*: initial удаляет в том числе white, black, transparent; без явного восстановления сломаются все компоненты.
• Прямое переопределение fonts удаляет font-sans/serif/mono — если задать theme.fontFamily без extend, пропадают дефолтные font-* классы.
• Конфликт плагинов — сторонние плагины Tailwind могут ожидать наличие дефолтных цветов или spacing; полная замена ломает их стили.
• Нет предупреждения в консоли — Tailwind не сообщает, что дефолтные значения были удалены; ошибки проявляются только в браузере.
• theme.colors vs theme.extend.colors в v3 IntelliSense — VSCode-плагин Tailwind IntelliSense показывает разные подсказки в зависимости от того, в каком месте конфига лежит ключ.
• Partial override — переопределение только части шкалы (например, только gray) при прямом size: theme.colors.gray = {...} удаляет остальные цвета, если не использован spread.
• Обратная совместимость при миграции v3→v4 — в v4 нет theme.extend из конфига; логику нужно переносить в @theme вручную.

• Смешивать «extend и переопределение темы» с похожим механизмом без критерия выбора.
• Игнорировать риск: неверно оценить границы применения темы «extend и переопределение темы» и получить хрупкое решение.
• Показывать только синтаксис и не объяснять поведение в runtime или сборке.

• Объясняет сохранение стандартных токенов против замены namespace.
• Показывает на примере, как работает: в v3 theme.extend добавлял значения поверх defaults, а прямое переопределение могло удалить стандартную шкалу; в v4 похожая идея выражается через добавление или сброс CSS theme variables.
• Называет production-нюанс и граничный случай для темы «extend и переопределение темы».