К основному содержанию
скилл CX Codex

tailwindcss-debugging — скилл для Claude Code

Скилл tailwindcss-debugging помогает ассистенту находить причины пропавших стилей, чинить динамические классы и переводить сборки на Tailwind CSS v4.

MIT 209 установок ★ 66 обновлён 2026-06-18

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-debugging -a claude-code
Открыть на GitHub

Что делает tailwindcss-debugging

Скилл передаёт агенту базу готовых решений для частых сбоев верстки на Tailwind CSS. Он охватывает типичные ошибки: динамическую конкатенацию строк вроде text-${color}-500, которую не видит компилятор, сбои горячей перезагрузки, конфликты директивы @layer и специфичности селекторов, а также настройку плагинов @tailwindcss/typography и @tailwindcss/forms.

Заметная часть инструкций посвящена переходу на Tailwind CSS v4. Скилл подсказывает, как заменить старый tailwind.config.js и плагин PostCSS на @tailwindcss/postcss, настроить директивы @theme, @source и зарегистрировать селекторный dark mode через @custom-variant dark. Также внутри есть пошаговый чеклист для проверки кеша сборщиков Vite или Next.js.

Скилл рассчитывает на современные версии фреймворка, поэтому при миграции на v4 без обновления пакета @tailwindcss/postcss сборка продолжит падать с ошибкой Unknown at-rule @theme.

Какие задачи решает

  • Исправить динамические имена классов, которые выпадают из финальной сборки
  • Перевести проект со связки Tailwind v3 на правила и синтаксис v4
  • Устранить конфликты специфичности стилей и переопределения через @layer
  • Настроить плагин @tailwindcss/postcss и директивы @source для детекта файлов

Примеры запросов агенту

  • В браузере не применяются классы Tailwind после сборки, проверь конфиг и исходники
  • Переведи стили проекта с Tailwind v3 на v4 и обнови PostCSS
  • Почему класс кнопки перебивается стилями из Typography prose?

Как установить tailwindcss-debugging

1Через Skills CLI (Vercel)

npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-debugging -a claude-code

2Вручную: положить файлы

~/.claude/skills/tailwindcss-debugging/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/tailwindcss-debugging/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о tailwindcss-debugging

Как установить tailwindcss-debugging в Claude Code?

Выполните в терминале команду npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-debugging -a claude-code. Файл навыка сохранится в ~/.claude/skills/tailwindcss-debugging/SKILL.md.

Что делает tailwindcss-debugging?

Он даёт ИИ-ассистенту чеклисты и алгоритмы для отладки Tailwind CSS: от поиска склеенных динамических классов до миграции на синтаксис v4 и настройки PostCSS.

Поможет ли скилл при ошибке Unknown at-rule @theme?

Да, скилл содержит инструкцию по устранению этой ошибки путём установки актуальных пакетов tailwindcss@latest и @tailwindcss/postcss@latest.

Исходный текст

SKILL.md · MIT
---
name: tailwindcss-debugging
description: |
  Tailwind CSS debugging and troubleshooting common issues.
  PROACTIVELY activate for: (1) classes not applying / no styles in browser, (2) JIT mode not picking up dynamic class names (string concatenation), (3) v3-to-v4 migration errors, (4) PostCSS configuration issues, (5) IntelliSense not autocompleting in VS Code, (6) production build missing classes (purge/content config), (7) CSS variable conflicts, (8) specificity issues with @layer, (9) prefix conflicts with other CSS frameworks, (10) HMR not updating styles.
  Provides: troubleshooting decision tree, dynamic-class allowlist patterns, content-config templates, IntelliSense setup, and PostCSS debugging steps.
---

# Tailwind CSS Debugging & Troubleshooting

## Common Issues & Solutions

### 1. Styles Not Applying

#### Check Content Detection

v4 automatically detects content, but if styles are missing:

```css
/* Explicitly specify sources */
@import "tailwindcss";
@source "./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}";
```

#### Verify Class Names

```html
<!-- WRONG - Dynamic class won't be detected -->
<div class={`text-${color}-500`}>

<!-- CORRECT - Use complete class names -->
<div class={color === 'blue' ? 'text-blue-500' : 'text-red-500'}>
```

#### Check Build Process

```bash
# Restart dev server
npm run dev

# Clear cache and rebuild
rm -rf node_modules/.vite
npm run build
```

### 2. v4 Migration Issues

#### PostCSS Plugin Changed

```javascript
// OLD (v3)
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {}
  }
}

// NEW (v4)
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}
```

#### Configuration Moved to CSS

```css
/* v4 - Configure in CSS, not JS */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.6 0.2 250);
}
```

#### Dark Mode Variant

```css
/* v4 - Add if using selector strategy */
@custom-variant dark (&:where(.dark, .dark *));
```

### 3. Classes Being Overridden

#### Check Specificity

```css
/* Browser DevTools: Inspect element → Styles panel */
/* Look for crossed-out styles */
```

#### Solutions

```html
<!-- Use !important (last resort) -->
<div class="!mt-0">

<!-- Or increase specificity with variants -->
<div class="[&]:mt-0">
```

#### Check Import Order

```css
/* Your custom CSS should come after Tailwind */
@import "tailwindcss";
@import "./custom.css";  /* After Tailwind */
```

### 4. Typography Plugin Issues

#### Styles Not Applied

```css
/* Ensure plugin is loaded */
@plugin "@tailwindcss/typography";
```

#### Utilities Overridden by Prose

```html
<!-- Use element modifiers -->
<article class="prose prose-h1:text-4xl prose-a:text-blue-600">

<!-- Or escape prose entirely -->
<article class="prose">
  <div class="not-prose">
    <CustomComponent />
  </div>
</article>
```

### 5. Forms Plugin Issues

#### Styles Not Applied to Plain Inputs

```html
<!-- Forms plugin only styles inputs with type attribute -->
<input type="text" />  <!-- ✓ Styled -->
<input />              <!-- ✗ Not styled -->
```

#### Using Class Strategy

```css
@plugin "@tailwindcss/forms" {
  strategy: class;
}
```

```html
<!-- Now explicitly opt-in -->
<input type="text" class="form-input" />
```

## Debugging Tools

### VS Code Extension

```bash
# Install Tailwind CSS IntelliSense
code --install-extension bradlc.vscode-tailwindcss
```

Features:
- Autocomplete for class names
- Hover previews showing CSS
- Linting for errors
- Color decorators

### Debug Screens Plugin

```bash
npm install -D @tailwindcss/debug-screens
```

```css
@plugin "@tailwindcss/debug-screens";
```

```html
<!-- Shows current breakpoint in corner -->
<body class="debug-screens">
```

### Browser DevTools

1. **Inspect Element** → See computed styles
2. **Styles Panel** → See which rules apply
3. **Filter** → Search for Tailwind classes
4. **Computed Tab** → See final computed values

### Check Generated CSS

```bash
# Output CSS to file for inspection
npx tailwindcss -o output.css --content './src/**/*.{html,js}'

# With verbose logging
DEBUG=tailwindcss:* npm run build
```

## v4 Specific Debugging

### Check Plugin Loading

```bash
# Look for plugin-related errors
npm run build 2>&1 | grep -i plugin
```

### Verify CSS Variable Output

```css
/* In browser DevTools, check :root for variables */
:root {
  --color-blue-500: oklch(...);
  --spacing-4: 1rem;
}
```

### Content Detection Issues

```css
/* Add explicit sources if auto-detection fails */
@source "./src/**/*.tsx";
@source "./components/**/*.tsx";

/* Exclude paths */
@source not "./src/generated/**";
```

## Common Error Messages

### "Cannot find module '@tailwindcss/postcss'"

```bash
npm install -D @tailwindcss/postcss
```

### "Unknown at-rule @theme"

Using v3 tooling with v4 syntax. Update your build setup:

```bash
npm install -D tailwindcss@latest @tailwindcss/postcss@latest
```

### "Class 'X' doesn't exist"

Dynamic class generation issue:

```javascript
// BAD
const classes = `bg-${dynamic}-500`

// GOOD
const colorMap = {
  primary: 'bg-blue-500',
  danger: 'bg-red-500'
}
const classes = colorMap[dynamic]
```

### "Styles not updating in development"

```bash
# Restart dev server
npm run dev

# Clear Vite cache
rm -rf node_modules/.vite

# Clear Next.js cache
rm -rf .next
```

## Performance Debugging

### Large CSS Output

```bash
# Check CSS file size
ls -lh dist/assets/*.css

# If too large, check for:
# 1. Dynamic class generation
# 2. Unnecessary safelisting
# 3. Unused plugins
```

### Slow Builds

```bash
# Time the build
time npm run build

# v4 should be very fast
# Full build: <1s
# Incremental: microseconds
```

## Debugging Checklist

### Initial Setup

- [ ] Correct import: `@import "tailwindcss";`
- [ ] PostCSS plugin: `@tailwindcss/postcss` (not `tailwindcss`)
- [ ] Vite plugin: `@tailwindcss/vite` (if using Vite)
- [ ] CSS file imported in entry point
- [ ] Development server restarted after changes

### Styles Not Applying

- [ ] Class name is complete (no dynamic generation)
- [ ] File is in content path
- [ ] Browser cache cleared
- [ ] No CSS specificity conflicts
- [ ] Check DevTools for overridden styles

### After Migration

- [ ] tailwind.config.js removed or converted
- [ ] @theme directive used for customization
- [ ] PostCSS config updated
- [ ] Dark mode variant added if using selector strategy
- [ ] Plugins updated to v4-compatible versions

### Production Issues

- [ ] NODE_ENV=production
- [ ] Build output includes styles
- [ ] CSS file linked correctly
- [ ] No dynamic class generation issues

## Getting Help

### Create Minimal Reproduction

```bash
# Create fresh project
npm create vite@latest repro -- --template react-ts
cd repro
npm install -D tailwindcss @tailwindcss/vite

# Add minimal code that shows the issue
# Share on GitHub Issues or Discord
```

### Resources

- [Official Docs](https://tailwindcss.com/docs)
- [GitHub Issues](https://github.com/tailwindlabs/tailwindcss/issues)
- [Tailwind CSS Discord](https://tailwindcss.com/discord)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/tailwind-css)

© JosiahSiegel · MIT · JosiahSiegel/claude-plugin-marketplace

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
tailwind PyModel С правилами настройки и стилизации на Tailwind CSS v4. Запускается при работе со сборкой, темами через @theme и оптимизацией CSS-бандла. CX Codex +1 671установок tailwindcss MengTo Помогает верстать интерфейсы на Tailwind CSS: сетки, типографика, адаптив, темы и паттерны компонентов. CX Codex +1 2 000установок postcss-best-practices Mindrally Скилл postcss-best-practices с рекомендациями по настройке PostCSS, сжатию стилей через cssnano и интеграции с Vite, Webpack и Next.js. CX Codex +1 755установок tailwindcss-development laravel Скилл tailwindcss-development пишет и правит Tailwind-классы в Blade, JSX и Vue. Срабатывает сам, когда в запросе встречается слово tailwind. CX Codex +1 1 000установок tailwind-expert 0xfurai Субагент tailwind-expert по Tailwind CSS для Claude Code: помогает настраивать темы, собирать адаптивную вёрстку и чистить стили с PurgeCSS. CX Codex ★ 1 029звёзд репо unocss Anthony Fu Скилл даёт агенту справочник по UnoCSS: конфиг, правила, шорткаты, пресеты и трансформеры. Пригодится при настройке проекта на UnoCSS или при переносе знаний Tailwind на него. CX Codex +1 16 400установок

Из того же набора96

Весь набор →
tailwindcss-advanced-components Скилл tailwindcss-advanced-components для Claude Code помогает собирать варианты React-компонентов на Tailwind CSS с CVA, compound variants и cn. Описывает паттерны в стиле shadcn/ui. CX Codex +1 253установок tailwindcss-performance Скилл tailwindcss-performance для Claude Code помогает ускорить сборку Tailwind CSS и уменьшить размер CSS. Активируется при настройке Tailwind v4, поиске лишних стилей и разборе проблем с динамическими классами. CX Codex +1 239установок viral-video-hooks-retention Скилл viral-video-hooks-retention для Claude Code разбирает первые секунды видео: формулы хуков, психологические триггеры и приёмы удержания. Помогает переписать начало ролика или найти просадку в сценарии. CX Codex +1 224установок powershell-shell-detection Скилл powershell-shell-detection помогает определить, где выполняется скрипт: в PowerShell, Git Bash/MSYS2 или cmd. Он пригодится при переносе команд и путей между оболочками Windows. CX Codex +1 211установок tailwindcss-plugins Скилл tailwindcss-plugins для Claude Code — справочник по официальным и пользовательским плагинам Tailwind CSS. Агент обращается к нему для настройки типографики, форм, container queries и переноса с v3 на v4. CX Codex +1 204установок windows-path-troubleshooting Скилл windows-path-troubleshooting объясняет, как записывать пути Windows для Read, Write и Edit и как перевести путь из Git Bash, чтобы не ловить ENOENT. CX Codex +1 199установок viral-video-animated-captions Скилл viral-video-animated-captions собирает вшитые в видео субтитры со словной подсветкой и анимацией в духе CapCut: таймкоды Whisper идут в ASS, FFmpeg прожигает их в ролик. CX Codex +1 196установок ffmpeg-audio-processing Скилл ffmpeg-audio-processing для Claude Code выбирает кодек, извлекает аудиодорожку из видео и нормализует громкость по EBU R128 через ffmpeg. Обрабатывает звук для подкастов и эфирных мастеров. CX Codex +1 195установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой