Tailwind CSS

When to Use

shadcn/ui is the primary component framework. This skill covers the Tailwind CSS utility system that powers shadcn components — use it for layout, responsive design, spacing, theming, and custom styling beyond what shadcn provides out of the box.

Use this skill for:

• Page layout (flex, grid, positioning, spacing)
• Responsive design (breakpoints, container queries)
• Theming and design tokens (@theme directive, CSS variables)
• Customizing shadcn/ui components with utility overrides
• Animation and transitions
• State-based styling (hover, focus, disabled)

Defer to the shadcn-ui skill for: component selection, composition patterns (Dialog, Sheet, Command), form integration (react-hook-form + zod), and accessibility.

Setup (v4)

Tailwind v4 uses CSS-first configuration. No tailwind.config.js needed.

Import

/* globals.css */
@import "tailwindcss";

This single import replaces the v3 directives (@tailwind base, @tailwind components, @tailwind utilities). Template files are auto-discovered — no content paths required.

Installation

# Next.js / Vite (PostCSS)
npm install tailwindcss @tailwindcss/postcss

# Vite plugin (alternative)
npm install tailwindcss @tailwindcss/vite

PostCSS config:

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Vite plugin (if not using PostCSS):

// vite.config.ts
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

Important: Sass and Less are incompatible with Tailwind v4. Use plain CSS with @theme and @layer directives.

Theming with @theme

The @theme directive defines design tokens in CSS. Each token creates both a utility class and a CSS variable.

Defining Tokens

@import "tailwindcss";

@theme {
  --font-display: "Satoshi", sans-serif;
  --color-brand: oklch(0.72 0.18 50);
  --color-brand-light: oklch(0.92 0.05 50);
  --radius-lg: 0.75rem;
  --breakpoint-3xl: 120rem;
}

This generates:

• font-display utility class
• bg-brand, text-brand color utilities
• rounded-lg using the custom radius
• 3xl: responsive breakpoint
• CSS variables: var(--font-display), var(--color-brand), etc.

Overriding vs Extending Defaults

/* Extend — adds to existing colors */
@theme {
  --color-brand: oklch(0.72 0.18 50);
}

/* Override — replaces ALL colors */
@theme {
  --color-*: initial;
  --color-brand: oklch(0.72 0.18 50);
  --color-white: #fff;
  --color-black: #000;
}

Use --color-*: initial (namespace wildcard) to clear defaults before defining your own.

Aligning with shadcn/ui Tokens

shadcn/ui defines semantic tokens in :root and .dark (see shadcn-ui skill for full setup). Tailwind's @theme can reference these:

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-ring: var(--ring);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
}

The inline keyword tells Tailwind not to emit the variables (shadcn already defines them in :root).

Utility-First Patterns

Core Principle

Style by composing utility classes directly in markup:

<div className="flex items-center gap-3 rounded-lg border p-4">
  <Avatar className="h-10 w-10" />
  <div>
    <p className="text-sm font-medium">Jane Doe</p>
    <p className="text-xs text-muted-foreground">jane@example.com</p>
  </div>
</div>

Spacing

p-4       → padding: 1rem (all sides)
px-6      → padding-left + padding-right: 1.5rem
py-2      → padding-top + padding-bottom: 0.5rem
m-auto    → margin: auto
mt-8      → margin-top: 2rem
gap-4     → gap: 1rem (flex/grid)
space-y-4 → vertical spacing between children (margin-based)

Typography

text-sm           → 0.875rem / 1.25rem
text-lg           → 1.125rem / 1.75rem
font-semibold     → font-weight: 600
tracking-tight    → letter-spacing: -0.025em
leading-relaxed   → line-height: 1.625
truncate          → overflow hidden + text-overflow ellipsis + whitespace nowrap
line-clamp-3      → clamp to 3 lines

Arbitrary Values

Use brackets for one-off values not in the theme:

<div className="w-[calc(100%-2rem)] top-[117px] grid-cols-[1fr_2fr_1fr]">

Use underscores for spaces in arbitrary values: grid-cols-[1fr_2fr_1fr].

Prefer theme tokens (w-96, gap-4) over arbitrary values. Only use brackets when the design truly requires a one-off value not in your design system.

State Variants

<button className="bg-primary hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50 disabled:pointer-events-none">
  Save
</button>

Common variants: hover:, focus:, focus-visible:, active:, disabled:, aria-selected:, data-[state=open]:.

Group and Peer Modifiers

{/* Parent hover affects children */}
<div className="group rounded-lg border p-4 hover:border-primary">
  <h3 className="font-medium group-hover:text-primary">Title</h3>
  <p className="text-muted-foreground group-hover:text-foreground">Description</p>
</div>

{/* Peer state affects siblings */}
<input className="peer" type="email" />
<p className="hidden text-sm text-destructive peer-invalid:block">
  Invalid email
</p>

@apply (Use Sparingly)

@apply extracts utilities into custom CSS classes. In v4, variant modifiers (hover:, md:, focus:) cannot be used inside @apply — use native CSS pseudo-classes and media queries instead, or prefer React components for stateful patterns.

/* OK — simple atomic pattern */
@layer components {
  .prose-link {
    @apply text-primary underline underline-offset-4;
  }
}

/* Prefer a React component instead of @apply for anything with variants */

Layout Patterns

Flexbox

{
  /* Horizontal bar with items centered, space between */
}
<div className="flex items-center justify-between gap-4">
  <Logo />
  <nav className="flex items-center gap-6">{/* links */}</nav>
  <UserMenu />
</div>;

{
  /* Vertical stack */
}
<div className="flex flex-col gap-4">
  <Card />
  <Card />
</div>;

Grid

{
  /* Equal-width columns */
}
<div className="grid grid-cols-3 gap-6">
  <Card />
  <Card />
  <Card />
</div>;

{
  /* Spanning columns */
}
<div className="grid grid-cols-4 gap-6">
  <div className="col-span-3">{/* Main */}</div>
  <div>{/* Sidebar */}</div>
</div>;

{
  /* Auto-fill responsive grid (no breakpoints needed) */
}
<div className="grid grid-cols-[repeat(auto-fill,minmax(280px,1fr))] gap-6">
  {items.map((item) => (
    <Card key={item.id} />
  ))}
</div>;

Common Recipes

Sticky header + scrollable content:

<div className="flex h-screen flex-col">
  <header className="sticky top-0 z-10 border-b bg-background px-6 py-3">
    {/* Header */}
  </header>
  <main className="flex-1 overflow-y-auto p-6">{/* Scrollable content */}</main>
</div>

Sidebar layout:

<div className="flex h-screen">
  <aside className="w-64 shrink-0 border-r bg-muted/40 p-4">
    {/* Sidebar */}
  </aside>
  <main className="flex-1 overflow-y-auto p-6">{/* Content */}</main>
</div>

Centered content (both axes):

<div className="flex min-h-screen items-center justify-center">
  <Card className="w-full max-w-md">{/* Centered card */}</Card>
</div>

Responsive Design

Mobile-First Breakpoints

Unprefixed utilities apply to all screen sizes. Prefixed utilities apply at that breakpoint and above.

Prefix	Min-width	Target
(none)	0px	All sizes (mobile base)
sm:	640px	Large phones
md:	768px	Tablets
lg:	1024px	Laptops
xl:	1280px	Desktops
2xl:	1536px	Large desktops

Responsive Stacking to Grid

{
  /* Single column on mobile, 2 cols on tablet, 3 cols on desktop */
}
<div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
  <Card />
  <Card />
  <Card />
</div>;

Responsive Typography

<h1 className="text-2xl font-bold md:text-3xl lg:text-4xl">Dashboard</h1>

Responsive Spacing

<section className="px-4 py-8 md:px-8 md:py-12 lg:px-16 lg:py-16">
  {/* Content with increasing padding on larger screens */}
</section>

Show/Hide by Breakpoint

{
  /* Mobile navigation toggle — hidden on desktop */
}
<Button className="md:hidden" variant="ghost" size="icon">
  <Menu className="h-5 w-5" />
</Button>;

{
  /* Desktop sidebar — hidden on mobile */
}
<aside className="hidden md:block w-64">{/* Sidebar */}</aside>;

Container Queries

Container queries respond to a parent container's size instead of the viewport:

{
  /* Define container */
}
<div className="@container">
  {/* Respond to container size */}
  <div className="flex flex-col @md:flex-row @md:items-center gap-4">
    <Avatar />
    <div>
      <p className="text-sm @lg:text-base">Name</p>
    </div>
  </div>
</div>;

Container breakpoints: @sm (320px), @md (448px), @lg (512px), @xl (576px), etc.

Custom Breakpoints

@theme {
  --breakpoint-3xl: 120rem;
  --breakpoint-xs: 480px;
}

Dark Mode

With shadcn/ui (Preferred Approach)

When using shadcn/ui, dark mode is handled by CSS variables. The :root and .dark selectors define token values, and utilities like bg-background, text-foreground, border-border automatically switch. No dark: prefix needed for themed elements.

{
  /* These auto-switch between light/dark — no dark: prefix */
}
<div className="bg-background text-foreground border-border">
  <p className="text-muted-foreground">Auto-themed content</p>
</div>;

See the shadcn-ui skill for next-themes setup and theme toggle implementation.

dark: Variant (For Non-Themed Values)

Use dark: only when you need behavior outside the shadcn token system:

{
  /* Custom illustration that needs different treatment in dark mode */
}
<div className="bg-blue-50 dark:bg-blue-950">
  <img className="opacity-100 dark:opacity-80" src="/illustration.svg" />
</div>;

Media Query Strategy

For system-only dark mode (no toggle), Tailwind uses prefers-color-scheme by default. The class-based strategy (required for next-themes toggle) is configured by shadcn's setup.

Customizing shadcn Components with Tailwind

Using cn() to Override Styles

shadcn components accept className. Use cn() (from @/lib/utils) to merge your utilities with the component's defaults:

import { Button } from "@/components/ui/button";

{
  /* Full-width button with left-aligned text */
}
<Button className="w-full justify-start text-left font-normal">
  Select a date
</Button>;

{
  /* Card with custom max-width and shadow */
}
<Card className="max-w-lg shadow-lg">
  <CardContent>{/* ... */}</CardContent>
</Card>;

cn() handles class conflicts — your overrides win over component defaults (e.g., adding justify-start replaces the button's default justify-center).

Adding Responsive Behavior

{
  /* Dialog content that's full-width on mobile, constrained on desktop */
}
<DialogContent className="w-full max-w-full sm:max-w-lg">
  {/* ... */}
</DialogContent>;

{
  /* Sidebar that collapses on mobile */
}
<SheetContent side="left" className="w-[280px] sm:w-[350px]">
  {/* ... */}
</SheetContent>;

When to Customize via Utilities vs Component Source

Scenario	Approach
One-off sizing/spacing tweak	className override
Consistent variant across the app	Edit component source in components/ui/
New variant (e.g., variant="warning")	Add to component's cva() variants
Layout around component	Wrapper div with utilities

Animation and Transitions

Transitions

{
  /* Smooth hover effect */
}
<div className="transition-colors duration-200 hover:bg-muted">
  {/* content */}
</div>;

{
  /* Transform on hover */
}
<div className="transition-transform duration-300 hover:scale-105">
  {/* content */}
</div>;

{
  /* Multiple properties */
}
<div className="transition-all duration-200 ease-in-out">{/* content */}</div>;

Common duration values: duration-75, duration-100, duration-150, duration-200, duration-300, duration-500.

Built-in Animations

<Loader2 className="h-4 w-4 animate-spin" />      {/* Spinning loader */}
<div className="animate-pulse">Loading...</div>      {/* Pulsing skeleton */}
<div className="animate-bounce">↓</div>              {/* Bouncing arrow */}

tw-animate-css

The tw-animate-css package replaces the deprecated tailwindcss-animate plugin. It provides enter/exit animations used by shadcn/ui components (Dialog, Sheet, Popover, etc.).

npm install tw-animate-css

/* globals.css */
@import "tailwindcss";
@import "tw-animate-css";

Custom Keyframes

/* globals.css */
@theme {
  --animate-fade-in: fade-in 0.3s ease-out;
  --animate-slide-up: slide-up 0.4s ease-out;
}

@keyframes fade-in {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

@keyframes slide-up {
  from {
    transform: translateY(1rem);
    opacity: 0;
  }
  to {
    transform: translateY(0);
    opacity: 1;
  }
}

Usage: <div className="animate-fade-in">.

Anti-Patterns

1. Dynamic Class Construction

// BAD — Tailwind can't scan dynamically built class names
function Badge({ color }: { color: string }) {
  return <span className={`bg-${color}-500 text-${color}-50`}>...</span>;
}

// GOOD — use a static lookup map
const colorStyles = {
  red: "bg-red-500 text-red-50",
  blue: "bg-blue-500 text-blue-50",
  green: "bg-green-500 text-green-50",
} as const;

function Badge({ color }: { color: keyof typeof colorStyles }) {
  return <span className={colorStyles[color]}>...</span>;
}

Tailwind scans source files for complete class names at build time. String interpolation produces class names that don't exist in the source, so they won't be generated.

2. @apply Overuse

/* BAD — reimplements what a React component does better */
.card {
  @apply flex flex-col gap-4 rounded-lg border bg-background p-6 shadow-sm;
}
.card-title {
  @apply text-lg font-semibold leading-none tracking-tight;
}

/* GOOD — use shadcn's <Card> component, or a custom React component */

@apply hides styles from the markup, makes them harder to override, and in v4, modifiers like hover: and responsive prefixes don't work on custom classes. Prefer React components for anything with variants or state.

3. Hardcoded Colors Instead of Theme Tokens

// BAD — breaks dark mode, ignores theme
<div className="bg-white text-gray-900 border-gray-200">

// GOOD — uses semantic tokens (auto-switches in dark mode)
<div className="bg-background text-foreground border-border">

Always use semantic token classes (bg-primary, text-muted-foreground, border-border) instead of raw color values. The tokens are defined by shadcn's CSS variables and switch automatically between light/dark.

4. Redundant dark: With CSS Variables

// BAD — unnecessary when using shadcn tokens
<div className="bg-background dark:bg-background text-foreground dark:text-foreground">

// ALSO BAD — fighting the token system
<div className="bg-white dark:bg-gray-900 text-black dark:text-white">

// GOOD — tokens handle light/dark automatically
<div className="bg-background text-foreground">

If you're using shadcn/ui's CSS variable system, dark: prefixes on themed properties are redundant. Only use dark: for values outside the token system.

5. Desktop-First Design

// BAD — styles for large screens, then overrides for small
<div className="grid grid-cols-3 gap-8 sm:grid-cols-1 sm:gap-4">

// GOOD — mobile base, enhance for larger screens
<div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3 lg:gap-8">

Tailwind breakpoints are min-width (mobile-first). Start with mobile styles (no prefix), then add complexity at larger breakpoints.

6. Mixing Sass/Less with v4

// BAD — Sass is incompatible with Tailwind v4's Oxide engine
$primary: #3b82f6;
.button {
  background: $primary;
  @apply rounded-lg px-4 py-2;
}

/* GOOD — use native CSS with @theme */
@theme {
  --color-primary: oklch(0.62 0.21 255);
}

Tailwind v4 processes CSS natively through its Rust-based engine. Sass/Less syntax causes build failures.

7. Overly Long Class Strings Without Extraction

// BAD — same pattern repeated in 5 places
<div className="flex items-center gap-3 rounded-lg border bg-card p-4 shadow-sm transition-colors hover:bg-accent">
  ...
</div>;
{
  /* ...repeated 4 more times */
}

// GOOD — extract to a component
function ListItem({ children, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      className={cn(
        "flex items-center gap-3 rounded-lg border bg-card p-4 shadow-sm transition-colors hover:bg-accent",
        props.className,
      )}
      {...props}
    >
      {children}
    </div>
  );
}

If a utility combination repeats more than twice, extract it to a React component. Always forward className via cn() so consumers can override styles.