Tailwind CSS Skill
This skill targets Tailwind CSS v4. In v4 the configuration lives in CSS, not in tailwind.config.ts. If the project still has a tailwind.config.* file, it is on v3 or it loads the file with @config. Check package.json before you choose syntax.
Longer examples: references/components.md (variant components and form inputs) and references/v3-to-v4.md (migration and renamed utilities).
Core Configuration (v4)
BAD: v3 directives and a JS config for tokens
/* styles/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
// tailwind.config.ts
export default {
content: ['./src/**/*.{js,ts,jsx,tsx}'],
theme: { extend: { colors: { brand: { 500: '#3b82f6' } } } },
};
GOOD: one CSS file, tokens in @theme
/* styles/globals.css */
@import "tailwindcss";
@theme {
--color-brand-50: oklch(0.97 0.02 240);
--color-brand-500: oklch(0.62 0.19 260);
--color-brand-900: oklch(0.3 0.1 265);
--font-display: "Inter", sans-serif;
--breakpoint-xs: 475px;
}
Every @theme variable in a utility namespace becomes a utility (bg-brand-500, font-display, xs:flex) and a CSS variable (var(--color-brand-500)). Spacing needs no tokens: p-18 works because spacing is a multiple of one base unit. Do not mix inline style={{}} with Tailwind for values the tokens already cover.
Install (build tool plugin, no content array needed):
npm install tailwindcss @tailwindcss/vite # Vite
npm install tailwindcss @tailwindcss/postcss # Next.js and other PostCSS setups
cn() Utility Pattern
BAD: string concatenation, conflicting classes are not resolved
export function Card({ className }: { className?: string }) {
// p-4 and p-8 both apply, and CSS source order decides the winner
return <div className={`p-4 rounded-lg bg-white ${className}`} />;
}
// <Card className="p-8 bg-blue-50" />
GOOD: clsx plus tailwind-merge, the last class wins
// lib/cn.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
// components/Card.tsx
import { cn } from '@/lib/cn';
interface CardProps {
className?: string;
variant?: 'default' | 'outlined';
}
export function Card({ className, variant = 'default' }: CardProps) {
return (
<div
className={cn(
'p-4 rounded-lg',
variant === 'default' && 'bg-white shadow-sm',
variant === 'outlined' && 'border border-gray-300',
className
)}
/>
);
}
// <Card className="p-8 bg-blue-50" /> => p-8 and bg-blue-50 override correctly
Responsive Design Patterns
Unprefixed classes are the mobile base. Each prefix (sm:, md:, lg:) means "from this width up".
BAD: desktop-first thinking, the base class is overridden by nothing
<div className="grid-cols-4 md:grid-cols-2 sm:grid-cols-1" />
GOOD: mobile-first progressive enhancement
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4" />
Add or change breakpoints with --breakpoint-* in @theme (see Core Configuration). Use max-md: only for a rule that must stop at a width.
Dark Mode Implementation
In v4 the dark: variant follows prefers-color-scheme by default. For a manual toggle, override the variant in CSS.
BAD: branching class strings in JS
<div className={isDark ? 'bg-gray-900 text-white' : 'bg-white text-gray-900'} />
GOOD: dark: variants, with a class-based switch when you need a toggle
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
<div className="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">Content</div>
Put or remove the dark class on <html> from a small script or a theme library, and add suppressHydrationWarning to <html> if the class is set before hydration. Do not hardcode className="dark" in the layout: that locks dark mode on.
Custom Utilities and Plugins
BAD: the same long class list copied across the code
<div className="backdrop-blur-md bg-white/10 border border-white/20 rounded-lg" />
// repeated in 20 places
GOOD: @utility for a reusable rule, @plugin for a package plugin
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@utility glass {
backdrop-filter: blur(12px);
background-color: rgb(255 255 255 / 0.1);
border: 1px solid rgb(255 255 255 / 0.2);
}
<div className="glass rounded-lg shadow-xl">Content</div>
A custom @utility works with every variant (hover:glass, md:glass). To keep an existing JS plugin or config, load it with @config "../tailwind.config.ts"; or @plugin "./my-plugin.js";.
Anti-Pattern: @apply Overuse
BAD: a CSS file full of @apply
.button { @apply px-4 py-2 bg-blue-500 text-white rounded-sm hover:bg-blue-600; }
.card { @apply p-6 bg-white rounded-lg shadow-md; }
.input { @apply w-full px-3 py-2 border border-gray-300 rounded-sm; }
/* Loses composability and duplicates what a component does better */
GOOD: a component that owns its classes
Wrap the classes in a component and use cva for variants. The full Button and Input examples are in references/components.md. Use @apply only for styles you cannot put in markup, such as third-party HTML you do not control.
Animation Utilities
BAD: a loose keyframe and class that bypass the theme
@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
.fade-in { animation: fadeIn 0.5s ease-in; }
GOOD: keyframes and the animation token inside @theme
@theme {
--animate-fade-in: fade-in 0.5s ease-out;
--animate-shimmer: shimmer 2s infinite linear;
@keyframes fade-in {
0% { opacity: 0; transform: translateY(10px); }
100% { opacity: 1; transform: translateY(0); }
}
@keyframes shimmer {
0% { background-position: -200% 0; }
100% { background-position: 200% 0; }
}
}
<div className="animate-fade-in motion-reduce:animate-none">Content</div>
Always pair motion with motion-reduce: so users who ask for less motion get none.
Performance: Content Detection and Dynamic Classes
v4 finds source files on its own. It respects .gitignore and skips node_modules and binary files. You do not write a content array.
BAD: building class names from fragments
// Tailwind scans text, so it never sees "bg-red-500" here
<div className={`bg-${color}-500`} />
GOOD: complete class names in a lookup, and @source for extra paths
const colorMap = {
error: 'bg-red-500',
success: 'bg-green-500',
info: 'bg-blue-500',
} as const;
export function Alert({ type }: { type: keyof typeof colorMap }) {
return <div className={colorMap[type]}>Alert</div>;
}
@import "tailwindcss";
@source "../node_modules/@my-company/ui"; /* a package that is ignored by default */
@source inline("bg-{red,green,blue}-{400,500,600}"); /* classes that only exist at runtime (v4.1+) */
Container Queries
Container queries are built in to v4. No plugin is needed.
BAD: viewport breakpoints for a component that lives in a narrow sidebar
<div className="p-4 md:p-6 lg:p-8">
<h2 className="text-lg md:text-xl lg:text-2xl">Title</h2>
</div>
GOOD: the component responds to its own container
<div className="@container">
<div className="p-4 @md:p-6 @lg:p-8">
<h2 className="text-lg @md:text-xl @lg:text-2xl">Title</h2>
</div>
</div>
Arbitrary Values and CSS Variables
BAD: magic numbers in class names
<section className="h-[calc(100vh-64px)] pt-[72px]">Content</section>
GOOD: named variables, referenced with the shorthand
@theme {
--header-height: 4rem;
--content-padding: 4.5rem;
}
<section className="h-[calc(100vh-var(--header-height))] pt-(--content-padding)">Content</section>
pt-(--content-padding) is the v4 shorthand for pt-[var(--content-padding)].
Focus States
Keep a visible focus indicator. In v4, outline-none removes the outline completely. Use outline-hidden when you replace it with a ring, and prefer focus-visible: so the ring shows for keyboard users.
BAD: focus removed and nothing replaces it
<input className="focus:outline-none" />
GOOD: the ring replaces the outline
<input className="rounded-lg border px-3 py-2 focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-blue-500" />
Workflow: Apply This Skill
- Check the version: read
package.jsonand look fortailwind.config.*and@tailwinddirectives. Use v3 syntax only when the project is on v3. - Audit className usage: find string concatenation that should use
cn(). - Check @apply usage: replace it with components or
@utility. - Verify tokens: colors, spacing and breakpoints live in
@theme, not in magic values. - Test dark mode: confirm
dark:variants work and the toggle (if any) sets thedarkclass. - Review responsive design: mobile-first, container queries for reusable components.
- Check dynamic classes: complete class names only, or
@source inline(...). - Build: run the project build and check the CSS size.
Common Fixes
Fix: Tailwind classes not applying
- Confirm the CSS file has
@import "tailwindcss";and is imported once by the app. - Confirm the build plugin (
@tailwindcss/viteor@tailwindcss/postcss) is installed and registered. - If the file lives in an ignored path (
node_modules,.gitignore), add@source. - Clear the framework cache, for example delete the
.nextfolder. - Check for specificity: a later or more specific rule can override the utility.
Fix: Dynamic classes not working
- Use complete class strings in a lookup object, never
text-${color}-500. - For classes that only exist at runtime, use
@source inline(...).
Fix: Dark mode not switching
- Default is
prefers-color-scheme. For a toggle, add the@custom-variant darkline. - Check the
<html>element actually gets thedarkclass. - Check the
dark:variants sit on the affected elements.