How to Do Tailwind CSS Configuration on Claude Code (v3 & v4)

To configure Tailwind CSS in Claude Code, use the /project context and describe your stack (Vite, Next.js, etc.). Claude will generate a correct tailwind.config.js or the new @config CSS-first setup for Tailwind v4. Suited for frontend developers who want to skip the docs-hunting and stay in flow. The main trade-off: Claude won't know your design tokens unless you paste them in the prompt.

• Tailwind v4 (released early 2025) replaces tailwind.config.js with inline CSS configuration using @theme and @config directives
• Claude Code can scaffold, extend, or migrate your Tailwind config in a single well-scoped prompt
• Keeping Claude Code running costs within limits prevents a 5-hour lockout mid-task

What is Tailwind CSS configuration and why does it matter in Claude Code?

Tailwind CSS is a utility-first framework where nearly all styling is controlled through a central configuration file. That config file governs your design tokens: colors, spacing, typography, breakpoints, and plugins like @tailwindcss/forms or @tailwindcss/typography.

In Claude Code, configuration tasks are a perfect fit for AI-assisted development because they're repetitive, pattern-driven, and easy to verify. You describe what you want, Claude writes the config, and you review the output against your design system. The risk of subtle errors (wrong hex value, missing extend wrapper) is low when the output is this readable.

Per Tailwind's official upgrade guide, v4 moves away from JavaScript config files entirely in favor of CSS-native configuration with @theme blocks. Claude Code handles both approaches, but you need to be explicit about which version you're using in your prompt.

How to configure Tailwind CSS (v3) with Claude Code

Tailwind v3 uses a tailwind.config.js file at the project root. Here are the exact workflows to use in Claude Code.

Generating a fresh config

Open Claude Code in your project directory and use a prompt like:

"Create a tailwind.config.js for a Next.js 14 project using the App Router. Include a custom color palette with primary, secondary, and neutral scales, extend the default font family to use Inter, and add the @tailwindcss/typography plugin."

Claude will scaffold a complete config, including the correct content glob paths for Next.js's app/ and components/ directories.

Extending an existing config

Paste your existing tailwind.config.js directly into the prompt, then append your request:

"Here is my current tailwind.config.js: [paste]. Add a custom breakpoint at 1440px called 2xl, extend the spacing scale with a 128 value (32rem), and enable the darkMode: 'class' strategy."

Key areas Claude can configure for you

• Content paths: correct globs for your framework (Next.js, Vite + React, SvelteKit, etc.)
• Theme extension: custom colors, fonts, spacing, border radius, shadows, and animation values under theme.extend
• Plugins: adding official plugins (@tailwindcss/forms, @tailwindcss/typography, @tailwindcss/aspect-ratio) or custom plugin functions
• Dark mode: toggling between 'media' and 'class' strategies
• Safelist and blocklist: preserving dynamically generated class names from purging

How to configure Tailwind CSS v4 with Claude Code

Tailwind CSS v4 introduces a CSS-first configuration model. There is no tailwind.config.js by default. Instead, configuration lives directly in your CSS entry file using @theme, @plugin, and @source directives (Tailwind v4 Beta Docs).

Prompt Claude Code explicitly for v4:

"I'm using Tailwind CSS v4 with Vite. In my src/index.css, write the @import 'tailwindcss' setup and a @theme block that defines a custom blue color palette and Inter as the default sans-serif font."

Claude will output something like:

@import "tailwindcss";

@theme {
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;
  --font-sans: "Inter", sans-serif;
}

If you still need a JS config for plugin compatibility, tell Claude:

"I need a tailwind.config.js alongside my CSS config to register the @tailwindcss/typography plugin with v4."

Useful Claude Code prompts for common Tailwind config tasks

Task	Prompt pattern
Migrate v3 config to v4	"Convert this tailwind.config.js to Tailwind v4 CSS-first format: [paste config]"
Add custom design tokens	"Add these brand colors to my Tailwind config as custom utilities: [paste hex values]"
Fix missing content paths	"My Tailwind classes are being purged in production. Here is my config and folder structure: [paste]. Fix the content globs."
Add a custom plugin	"Write a Tailwind plugin that adds a .text-balance utility using text-wrap: balance"
Debug a config issue	"My custom color brand-primary doesn't appear in autocomplete. Here's my config: [paste]. What's wrong?"

How to use Claude Code slash commands for config tasks

Claude Code's slash commands help scope configuration tasks precisely:

• /project: gives Claude context about your repo structure, so it picks the right framework-specific content paths automatically
• /file tailwind.config.js: loads the config file directly into context so Claude reads it before modifying
• /usage: check how much of your Claude Code session usage you've consumed before kicking off a large refactor

The /usage command is worth checking before any multi-file config migration. If you're near your limit, you risk a 5-hour lockout right when you're in the middle of aligning tokens across your design system. See how to check your Claude Code usage limits for a full breakdown of what the numbers mean.

What is the best way to track Claude Code usage during long config sessions?

Tailwind configuration tasks tend to be iterative: you prompt, review, tweak tokens, re-prompt. Several rounds of back-and-forth consume usage faster than a single large task. This is exactly the scenario where a mid-session usage spike can catch you off guard.

Usagebar is a macOS menu bar app that shows your live Claude Code usage at 50%, 75%, and 90% thresholds, so you always know where you stand without switching away from your editor. It uses the macOS Keychain to store credentials securely and shows you precisely when your 5-hour usage window resets, eliminating the guesswork.

It's pay-what-you-want (including free for students), and takes under a minute to set up. If you do long Tailwind config sessions in Claude Code, knowing your remaining capacity before you start a migration is genuinely useful.

Get Usagebar - instant download, flexible pricing.

You can also monitor usage directly via /usage in the Claude Code terminal, or by visiting claude.ai/settings/usage. For a deeper look at what the reset timer means for your workflow, see when does Claude Code usage reset.

Tips for getting accurate Tailwind configs from Claude Code

• Specify your Tailwind version: v3 and v4 have fundamentally different config formats. Always say "Tailwind v4" or "Tailwind v3" explicitly.
• Name your framework: Next.js, Vite, Remix, SvelteKit all need different content glob paths. Claude will pick the right one if you say so.
• Paste your current config: For extensions or fixes, give Claude the full existing file so it doesn't overwrite working settings.
• Paste your design tokens: Claude cannot read your Figma file or brand guide. Copy the hex values, font names, and spacing values into the prompt directly.
• Ask Claude to explain the output: For unfamiliar plugin APIs, append "briefly explain each change" to your prompt. This catches errors before you ship.

For related configuration workflows in Claude Code, see how to do Vite configuration on Claude Code and how to do Prettier configuration on Claude Code.

Key Takeaways

1. Always specify Tailwind v3 vs. v4 in your prompt; the config format is fundamentally different between versions.
2. Paste your existing config or design tokens directly into the prompt for accurate, non-destructive output.
3. Use /file and /project slash commands to give Claude Code the right context before modifying configs.
4. Check your usage with /usage or Usagebar before starting a multi-step config migration to avoid a mid-task 5-hour lockout.
5. For v4, configuration lives in your CSS file under @theme; for v3, it lives in tailwind.config.js under theme.extend.

Sources

• https://tailwindcss.com/docs/upgrade-guide
• https://tailwindcss.com/docs/v4-beta
• https://code.claude.com/docs/en/slash-commands
• https://claude.ai/settings/usage