Skip to main content
skill CX Codex

tailwindcss-performance — Claude Code skill: setup and install

tailwindcss-performance is a Claude Code skill for tuning Tailwind CSS builds and trimming generated CSS. It activates for Tailwind v4 performance work, content detection issues, and dynamic class names.

MIT 239 installs ★ 66 updated 2026-06-18

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-performance -a claude-code
Open on GitHub

What tailwindcss-performance does

The skill covers Tailwind CSS build settings, including source detection, removal of unused styles, minification, and CSS bundle size. For v4, it explains automatic source discovery and explicit file patterns with @source.

For dynamic classes, it outlines complete class names, data attributes, and adding classes with @source inline. It also covers Vite and PostCSS settings, critical CSS extraction, caching, and transitions. Tailwind does not detect class names assembled from string fragments, so those classes need full names or an explicit safelist.

What it helps with

  • reduce the size of a Tailwind CSS build
  • configure which files Tailwind scans
  • fix styles missing for dynamic class names
  • set up CSS minification in Vite or PostCSS
  • remove unused styles and theme values

Example prompts for the agent

  • Review this Tailwind v4 build and find what is adding to the CSS bundle.
  • Configure Tailwind source detection so it skips unrelated files.
  • Why are styles missing for the dynamic classes in this component?

How to install tailwindcss-performance

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/tailwindcss-performance/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tailwindcss-performance

How do I install tailwindcss-performance in Claude Code?

Run npx skills add JosiahSiegel/claude-plugin-marketplace --skill tailwindcss-performance -a claude-code. The skill file is placed at ~/.claude/skills/tailwindcss-performance/SKILL.md.

What does tailwindcss-performance do?

It helps tune Tailwind CSS builds, reduce generated CSS, configure class discovery, and investigate dynamic class names. It also covers minification and Tailwind v4 performance settings.

Why does Tailwind miss dynamically constructed classes?

Tailwind cannot detect class names assembled from string fragments. The skill describes using complete class names, data attributes, or adding classes with @source inline.

Source text

SKILL.md · MIT
---
name: tailwindcss-performance
description: |
  Tailwind CSS performance optimization including v4 improvements.
  PROACTIVELY activate for: (1) Tailwind v4 Oxide engine performance, (2) Lightning CSS minification, (3) reducing CSS bundle size, (4) content config tuning to avoid scanning unused files, (5) safelist for dynamic classes (without bloating), (6) production builds with @apply minimization, (7) critical CSS extraction, (8) HTTP caching of generated CSS, (9) avoiding @apply overuse (utility-first preferred), (10) PurgeCSS / content-detection edge cases.
  Provides: performance tuning checklist, Oxide engine notes, content config patterns, safelist guidance, and critical-CSS workflow.
---

# Tailwind CSS Performance Optimization

## v4 Performance Improvements

Tailwind CSS v4 features a completely rewritten engine in Rust:

| Metric | v3 | v4 |
|--------|----|----|
| Full builds | Baseline | Up to 5x faster |
| Incremental builds | Milliseconds | Microseconds (100x+) |
| Engine | JavaScript | Rust |

## JIT (Just-In-Time) Compilation

### How JIT Works

JIT generates styles on-demand as classes are discovered in your files:

1. Scans source files for class names
2. Generates only the CSS you use
3. Produces minimal, optimized output

### v4: Always JIT

Unlike v3, JIT is always enabled in v4—no configuration needed:

```css
@import "tailwindcss";
/* JIT is automatic */
```

## Content Detection

### Automatic Detection (v4)

v4 automatically detects template files—no content configuration required:

```css
/* v4 - Works automatically */
@import "tailwindcss";
```

### Explicit Content (v4)

If automatic detection fails, specify sources explicitly:

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

### Excluding Paths

```css
@source not "./src/legacy/**";
```

## Tree Shaking

### How It Works

Tailwind's build process removes unused CSS:

```text
Source: All possible utilities (~15MB+)
↓
Scan: Find used class names
↓
Output: Only used styles (~10-50KB typical)
```

### Production Build

```bash
# Vite - automatically optimized for production
npm run build

# PostCSS - ensure NODE_ENV is set
NODE_ENV=production npx postcss input.css -o output.css
```

## Dynamic Class Names

### The Problem

Tailwind can't detect dynamically constructed class names:

```javascript
// BAD - Classes won't be generated
const color = 'blue'
className={`text-${color}-500`}  // ❌ Not detected

const size = 'lg'
className={`text-${size}`}  // ❌ Not detected
```

### Solutions

#### 1. Use Complete Class Names

```javascript
// GOOD - Full class names
const colorClasses = {
  blue: 'text-blue-500',
  red: 'text-red-500',
  green: 'text-green-500',
}
className={colorClasses[color]}  // ✓ Detected
```

#### 2. Use Data Attributes

```javascript
// GOOD - Style based on data attributes
<div data-color={color} className="data-[color=blue]:text-blue-500 data-[color=red]:text-red-500">
```

#### 3. Safelist Classes

```css
/* In your CSS for v4 */
@source inline("text-blue-500 text-red-500 text-green-500");
```

#### 4. CSS Variables

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

```html
<div class="text-[var(--color-dynamic)]">Dynamic color</div>
```

## Optimizing Transitions

### Use Specific Transitions

```html
<!-- SLOW - Transitions all properties -->
<button class="transition-all duration-200">

<!-- FAST - Only transitions specific properties -->
<button class="transition-colors duration-200">
<button class="transition-transform duration-200">
<button class="transition-opacity duration-200">
```

### GPU-Accelerated Properties

Prefer `transform` and `opacity` for smooth animations:

```html
<!-- GOOD - GPU accelerated -->
<div class="transform hover:scale-105 transition-transform">

<!-- GOOD - GPU accelerated -->
<div class="opacity-100 hover:opacity-80 transition-opacity">

<!-- SLOW - May cause repaints -->
<div class="left-0 hover:left-4 transition-all">
```

## CSS Variable Usage

### Prefer Native Variables

In v4, use CSS variables directly instead of `theme()`:

```css
/* v3 - Uses theme() function */
.element {
  color: theme(colors.blue.500);
}

/* v4 - Use CSS variables (faster) */
.element {
  color: var(--color-blue-500);
}
```

### Static Theme Values

For performance-critical paths:

```css
@import "tailwindcss/theme.css" theme(static);
```

This inlines theme values instead of using CSS variables.

## Build Optimization

### Vite Configuration

```javascript
// vite.config.js
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [tailwindcss()],
  build: {
    // Minify CSS
    cssMinify: 'lightningcss',
    // Optimize chunks
    rollupOptions: {
      output: {
        manualChunks: {
          // Split vendor CSS if needed
        }
      }
    }
  }
})
```

### PostCSS with cssnano

```javascript
// postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {},
    cssnano: process.env.NODE_ENV === 'production' ? {} : false
  }
}
```

## Reducing Bundle Size

### 1. Avoid Unused Plugins

```css
/* Only load what you need */
@plugin "@tailwindcss/typography";
/* Don't load unused plugins */
```

### 2. Limit Color Palette

```css
@theme {
  /* Disable default colors */
  --color-*: initial;

  /* Define only needed colors */
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);
  --color-gray-100: oklch(0.95 0 0);
  --color-gray-900: oklch(0.15 0 0);
}
```

### 3. Limit Breakpoints

```css
@theme {
  /* Remove unused breakpoints */
  --breakpoint-2xl: initial;

  /* Keep only what you use */
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
}
```

## Caching Strategies

### Development

- v4's incremental builds are already extremely fast
- No additional caching needed in most cases

### CI/CD

```yaml
# GitHub Actions example
- name: Cache node_modules
  uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}

- name: Build
  run: npm run build
```

## Measuring Performance

### Build Time Analysis

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

# Verbose output
DEBUG=tailwindcss:* npm run build
```

### Bundle Analysis

```bash
# Install analyzer
npm install -D vite-bundle-analyzer

# Analyze bundle
npm run build -- --analyze
```

### CSS Size Check

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

# Gzipped size
gzip -c dist/assets/main.css | wc -c
```

## Performance Checklist

### Development

- [ ] JIT is working (styles update instantly)
- [ ] No console warnings about large files
- [ ] Hot reload is fast

### Production

- [ ] `NODE_ENV=production` is set
- [ ] CSS is minified
- [ ] Unused CSS is removed
- [ ] No dynamic class name issues
- [ ] CSS size is reasonable (<50KB typical)

### Common Issues

| Issue | Solution |
|-------|----------|
| Large CSS output | Check for dynamic classes, safelist issues |
| Slow builds | Ensure v4, check file globs |
| Missing styles | Check content detection, class names |
| Slow animations | Use GPU-accelerated properties |

## Lazy Loading CSS

For very large apps, consider code-splitting CSS:

```javascript
// Dynamically import CSS for routes
const AdminPage = lazy(() =>
  import('./admin.css').then(() => import('./AdminPage'))
)
```

## Best Practices Summary

1. **Let JIT do its work** - Don't safelist unnecessarily
2. **Use complete class names** - Avoid dynamic concatenation
3. **Specific transitions** - Not `transition-all`
4. **GPU properties** - Prefer `transform` and `opacity`
5. **Minimal theme** - Only define what you use
6. **Production builds** - Always use production mode
7. **Measure** - Check your actual CSS size

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

Similar skills

All skills for Frontend and UI →

From the same set96

The whole set →
tailwindcss-accessibility tailwindcss-accessibility is a Claude Code skill for building accessible interfaces with Tailwind CSS. It activates for WCAG work, focus styling, contrast, and ARIA patterns. CX Codex +1 302installs tailwindcss-framework-integration tailwindcss-framework-integration guides Tailwind CSS setup across React, Vite, Next.js, Vue, Nuxt, and SvelteKit. Useful for configuring bundler plugins, dark mode, and framework class merging. CX Codex +1 298installs ffmpeg-color-grading-chromakey ffmpeg-color-grading-chromakey is a Claude Code skill with FFmpeg filters for green screen removal, LUT application, and video color correction in AI-assisted editing. CX Codex +1 284installs tailwindcss-advanced-components The tailwindcss-advanced-components skill covers Tailwind CSS component variants with CVA, compound variants, and cn. Use it when building reusable React components in shadcn/ui-style projects. CX Codex +1 253installs viral-video-hooks-retention viral-video-hooks-retention — a skill that works on the first seconds of a video: hook formulas, five psychological triggers, ways to hold attention. Useful when the script is ready but viewers leave early. CX Codex +1 224installs powershell-shell-detection powershell-shell-detection is a Claude Code skill that identifies whether a script runs in PowerShell, Git Bash/MSYS2, or cmd. It helps with Windows paths and command invocation across shells. CX Codex +1 211installs tailwindcss-debugging tailwindcss-debugging diagnoses missing styles, fixes dynamic class name issues, and guides builds through Tailwind CSS v4 upgrades. CX Codex +1 209installs tailwindcss-plugins tailwindcss-plugins — a Tailwind CSS plugin reference the agent loads on its own: official typography, forms and container queries, custom plugin() utilities, and the v3 to v4 move. CX Codex +1 204installs

Project sponsors

Companies that keep this analytics open