How do I install the Tailwind skill?

Run npx skillmds@latest add hjewkes/tailwind in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Tailwind safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Tailwind?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Tailwind free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Tailwind?

hjewkes (@hjewkes) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Tailwind by hjewkes — Agent Skill

Name: Tailwind
Author: hjewkes

Tailwind

Tailwind CSS v4 with shadcn/ui — setup, configuration, component patterns, dark mode, and troubleshooting. Use when setting up Tailwind v4, building UI components, fixing Tailwind errors, migrating from v3, or styling with utility classes.

hjewkes 79fc4d9 10 files · 23.0 KB Updated Sep 17, 2026

File contents

Tailwind CSS v4

Combined from jezweb/claude-skills (tailwind-v4-shadcn + tailwind-patterns). Production-tested.

Setup Quick Start

pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node tw-animate-css
pnpm dlx shadcn@latest init
rm tailwind.config.ts  # v4 doesn't use this

Use @tailwindcss/vite plugin (NOT PostCSS). Set "config": "" in components.json.

The Four-Step CSS Architecture

Skip any step and the theme breaks. See references/setup.md for full details.

CSS Variables at :root — define colors with hsl() wrapper, NOT inside @layer base
@theme inline — map CSS vars to Tailwind utilities (--color-background: var(--background))
@layer base — apply base styles using unwrapped variables
Result — bg-background auto-switches in dark mode, no dark: prefix needed

Critical Rules

Always: semantic tokens (bg-primary not bg-blue-500), mobile-first (base → sm: → md:), hsl() in :root/.dark, consistent spacing (4/6/8/12/16/24 scale)

Never: tailwind.config.ts (v4 ignores it), @apply with @layer classes (use @utility), double-wrap hsl(var(--color)), raw colors, .dark { @theme {} }, dark: variants for semantic colors

Quick Error Reference

Symptom	Fix
`bg-primary` doesn't work	Add `@theme inline` block
Colors black/white	Remove double `hsl()` wrap
Dark mode stuck	Add ThemeProvider, check `.dark` on `<html>`
Build fails	Delete `tailwind.config.ts`
Animation errors	Replace `tailwindcss-animate` with `tw-animate-css`
`@apply` breaks	Use `@utility` directive instead
Base styles ignored	Don't wrap in `@layer base`, define at root

Full error details with solutions: references/common-errors.md

Component Patterns

Patterns use semantic tokens for automatic dark mode. See references/patterns.md for full library.

// Container
<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">

// Responsive grid
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">

// Card
<div className="bg-card text-card-foreground rounded-lg border border-border p-6">

// Button
<button className="bg-primary text-primary-foreground px-4 py-2 rounded-md hover:bg-primary/90 transition-colors">

Reference Files

references/setup.md — full 4-step architecture + vite config + components.json
references/common-errors.md — 8 documented v4 errors with solutions
references/patterns.md — layouts, cards, buttons, forms, nav, typography
references/dark-mode.md — ThemeProvider, toggle, OKLCH colors
references/migration.md — v3 → v4 checklist and gotchas
templates/ — index.css, components.json, theme-provider.tsx, vite.config.ts, utils.ts

---name: tailwinddescription: Tailwind CSS v4 with shadcn/ui — setup, configuration, component patterns, dark mode, and troubleshooting. Use when setting up Tailwind v4, building UI components, fixing Tailwind errors, migrating from v3, or styling with utility classes.---# Tailwind CSS v4Combined from jezweb/claude-skills (tailwind-v4-shadcn + tailwind-patterns). Production-tested.## Setup Quick Start```bashpnpm add tailwindcss @tailwindcss/vitepnpm add -D @types/node tw-animate-csspnpm dlx shadcn@latest initrm tailwind.config.ts # v4 doesn't use this```Use `@tailwindcss/vite` plugin (NOT PostCSS). Set `"config": ""` in `components.json`.## The Four-Step CSS ArchitectureSkip any step and the theme breaks. See `references/setup.md` for full details.1. **CSS Variables at `:root`** — define colors with `hsl()` wrapper, NOT inside `@layer base`2. **`@theme inline`** — map CSS vars to Tailwind utilities (`--color-background: var(--background)`)3. **`@layer base`** — apply base styles using unwrapped variables4. **Result** — `bg-background` auto-switches in dark mode, no `dark:` prefix needed## Critical Rules**Always**: semantic tokens (`bg-primary` not `bg-blue-500`), mobile-first (`base → sm: → md:`), `hsl()` in `:root`/`.dark`, consistent spacing (4/6/8/12/16/24 scale)**Never**: `tailwind.config.ts` (v4 ignores it), `@apply` with `@layer` classes (use `@utility`), double-wrap `hsl(var(--color))`, raw colors, `.dark { @theme {} }`, `dark:` variants for semantic colors## Quick Error Reference| Symptom | Fix ||---------|-----|| `bg-primary` doesn't work | Add `@theme inline` block || Colors black/white | Remove double `hsl()` wrap || Dark mode stuck | Add ThemeProvider, check `.dark` on `<html>` || Build fails | Delete `tailwind.config.ts` || Animation errors | Replace `tailwindcss-animate` with `tw-animate-css` || `@apply` breaks | Use `@utility` directive instead || Base styles ignored | Don't wrap in `@layer base`, define at root |Full error details with solutions: `references/common-errors.md`## Component PatternsPatterns use semantic tokens for automatic dark mode. See `references/patterns.md` for full library.```tsx// Container<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">// Responsive grid<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">// Card<div className="bg-card text-card-foreground rounded-lg border border-border p-6">// Button<button className="bg-primary text-primary-foreground px-4 py-2 rounded-md hover:bg-primary/90 transition-colors">```## Reference Files- `references/setup.md` — full 4-step architecture + vite config + components.json- `references/common-errors.md` — 8 documented v4 errors with solutions- `references/patterns.md` — layouts, cards, buttons, forms, nav, typography- `references/dark-mode.md` — ThemeProvider, toggle, OKLCH colors- `references/migration.md` — v3 → v4 checklist and gotchas- `templates/` — index.css, components.json, theme-provider.tsx, vite.config.ts, utils.ts

Frequently asked questions