Skip to main content
skill CX Codex

tailwind-patterns — Claude Code skill for Tailwind CSS v4

The tailwind-patterns skill guides Tailwind CSS v4 setup, responsive layouts, and design tokens. Use it when starting a v4 project or moving one from v3.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add coco-research/coco --skill tailwind-patterns -a claude-code
Open on GitHub

What tailwind-patterns does

The skill covers CSS theme setup with @theme, semantic token names, and native container queries. It explains when a component should respond to its parent’s width instead of the viewport. Dark mode, grid layouts, typography, and transitions are also covered.

It gives guidance on turning repeated utility combinations into components and flags common pitfalls, including mixing v3 configuration with v4’s CSS-first approach. The material recommends avoiding heavy use of @apply and dynamic class names built from template strings. For a v3 migration, it advises moving fully to CSS-based configuration.

What it helps with

  • define design tokens in CSS with @theme
  • build components that adapt to container width
  • move a project from Tailwind CSS v3 to v4
  • choose a dark-mode strategy and responsive breakpoints
  • decide when to extract repeated utility classes into a component

Example prompts for the agent

  • Set up a Tailwind CSS v4 theme with semantic color tokens using @theme.
  • Move this project from Tailwind CSS v3 configuration to the v4 CSS-first approach.
  • Build a responsive card that changes layout with its container width.

How to install tailwind-patterns

1Skills CLI (Vercel)

npx skills add coco-research/coco --skill tailwind-patterns -a claude-code

2Manually: put the files in place

~/.claude/skills/tailwind-patterns/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tailwind-patterns/

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

Questions about tailwind-patterns

How do I install tailwind-patterns in Claude Code?

Run npx skills add coco-research/coco --skill tailwind-patterns -a claude-code. The skill file is at ~/.claude/skills/tailwind-patterns/SKILL.md.

What does tailwind-patterns do?

It provides guidance on Tailwind CSS v4 configuration, tokens, responsive layouts, and component patterns. It also covers migration from v3 and common implementation pitfalls.

How do container queries differ from breakpoints?

Breakpoints respond to viewport width; container queries respond to a parent element’s width. The skill points to container queries for responsive components that should work across different contexts.

Source text

SKILL.md · MIT
---
name: tailwind-patterns
description: "Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture. Use when building with Tailwind v4 or migrating from v3."
domain: design
supports: [claude-code, cursor, codex, generic]
version: 0.1.0
---

# Tailwind CSS Patterns (v4 - 2025)

Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture. Use when building with Tailwind CSS v4, migrating from v3, configuring design tokens in CSS, implementing responsive layouts, or applying utility-first patterns.

---

## 1. Tailwind v4 Architecture

### What Changed from v3

| v3 (Legacy) | v4 (Current) |
|-------------|--------------|
| `tailwind.config.js` | CSS-based `@theme` directive |
| PostCSS plugin | Oxide engine (10x faster) |
| JIT mode | Native, always-on |
| Plugin system | CSS-native features |
| `@apply` directive | Still works, discouraged |

### v4 Core Concepts

| Concept | Description |
|---------|-------------|
| **CSS-first** | Configuration in CSS, not JavaScript |
| **Oxide Engine** | Rust-based compiler, much faster |
| **Native Nesting** | CSS nesting without PostCSS |
| **CSS Variables** | All tokens exposed as `--*` vars |

---

## 2. CSS-Based Configuration

### Theme Definition

```css
@theme {
  /* Colors - use semantic names */
  --color-primary: oklch(0.7 0.15 250);
  --color-surface: oklch(0.98 0 0);
  --color-surface-dark: oklch(0.15 0 0);
  
  /* Spacing scale */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;
  
  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}
```

### When to Extend vs Override

| Action | Use When |
|--------|----------|
| **Extend** | Adding new values alongside defaults |
| **Override** | Replacing default scale entirely |
| **Semantic tokens** | Project-specific naming (primary, surface) |

---

## 3. Container Queries (v4 Native)

### Breakpoint vs Container

| Type | Responds To |
|------|-------------|
| **Breakpoint** (`md:`) | Viewport width |
| **Container** (`@container`) | Parent element width |

### Container Query Usage

| Pattern | Classes |
|---------|---------|
| Define container | `@container` on parent |
| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |
| Named containers | `@container/card` for specificity |

### When to Use

| Scenario | Use |
|----------|-----|
| Page-level layouts | Viewport breakpoints |
| Component-level responsive | Container queries |
| Reusable components | Container queries (context-independent) |

---

## 4. Responsive Design

### Breakpoint System

| Prefix | Min Width | Target |
|--------|-----------|--------|
| (none) | 0px | Mobile-first base |
| `sm:` | 640px | Large phone / small tablet |
| `md:` | 768px | Tablet |
| `lg:` | 1024px | Laptop |
| `xl:` | 1280px | Desktop |
| `2xl:` | 1536px | Large desktop |

### Mobile-First Principle

1. Write mobile styles first (no prefix)
2. Add larger screen overrides with prefixes
3. Example: `w-full md:w-1/2 lg:w-1/3`

---

## 5. Dark Mode

### Configuration Strategies

| Method | Behavior | Use When |
|--------|----------|----------|
| `class` | `.dark` class toggles | Manual theme switcher |
| `media` | Follows system preference | No user control |
| `selector` | Custom selector (v4) | Complex theming |

### Dark Mode Pattern

| Element | Light | Dark |
|---------|-------|------|
| Background | `bg-white` | `dark:bg-zinc-900` |
| Text | `text-zinc-900` | `dark:text-zinc-100` |
| Borders | `border-zinc-200` | `dark:border-zinc-700` |

---

## 6. Modern Layout Patterns

### Flexbox Patterns

| Pattern | Classes |
|---------|---------|
| Center (both axes) | `flex items-center justify-center` |
| Vertical stack | `flex flex-col gap-4` |
| Horizontal row | `flex gap-4` |
| Space between | `flex justify-between items-center` |
| Wrap grid | `flex flex-wrap gap-4` |

### Grid Patterns

| Pattern | Classes |
|---------|---------|
| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |
| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |
| Sidebar layout | `grid grid-cols-[auto_1fr]` |

> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.

---

## 7. Modern Color System

### OKLCH vs RGB/HSL

| Format | Advantage |
|--------|-----------|
| **OKLCH** | Perceptually uniform, better for design |
| **HSL** | Intuitive hue/saturation |
| **RGB** | Legacy compatibility |

### Color Token Architecture

| Layer | Example | Purpose |
|-------|---------|---------|
| **Primitive** | `--blue-500` | Raw color values |
| **Semantic** | `--color-primary` | Purpose-based naming |
| **Component** | `--button-bg` | Component-specific |

---

## 8. Typography System

### Font Stack Pattern

| Type | Recommended |
|------|-------------|
| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |
| Mono | `'JetBrains Mono', 'Fira Code', monospace` |
| Display | `'Outfit', 'Poppins', sans-serif` |

### Type Scale

| Class | Size | Use |
|-------|------|-----|
| `text-xs` | 0.75rem | Labels, captions |
| `text-sm` | 0.875rem | Secondary text |
| `text-base` | 1rem | Body text |
| `text-lg` | 1.125rem | Lead text |
| `text-xl`+ | 1.25rem+ | Headings |

---

## 9. Animation & Transitions

### Built-in Animations

| Class | Effect |
|-------|--------|
| `animate-spin` | Continuous rotation |
| `animate-ping` | Attention pulse |
| `animate-pulse` | Subtle opacity pulse |
| `animate-bounce` | Bouncing effect |

### Transition Patterns

| Pattern | Classes |
|---------|---------|
| All properties | `transition-all duration-200` |
| Specific | `transition-colors duration-150` |
| With easing | `ease-out` or `ease-in-out` |
| Hover effect | `hover:scale-105 transition-transform` |

---

## 10. Component Extraction

### When to Extract

| Signal | Action |
|--------|--------|
| Same class combo 3+ times | Extract component |
| Complex state variants | Extract component |
| Design system element | Extract + document |

### Extraction Methods

| Method | Use When |
|--------|----------|
| **React/Vue component** | Dynamic, JS needed |
| **@apply in CSS** | Static, no JS needed |
| **Design tokens** | Reusable values |

---

## 11. Anti-Patterns

| Don't | Do |
|-------|-----|
| Arbitrary values everywhere | Use design system scale |
| `!important` | Fix specificity properly |
| Inline `style=` | Use utilities |
| Duplicate long class lists | Extract component |
| Mix v3 config with v4 | Migrate fully to CSS-first |
| Use `@apply` heavily | Prefer components |

---

## 12. Performance Principles

| Principle | Implementation |
|-----------|----------------|
| **Purge unused** | Automatic in v4 |
| **Avoid dynamism** | No template string classes |
| **Use Oxide** | Default in v4, 10x faster |
| **Cache builds** | CI/CD caching |

---

> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.

© coco-research · MIT · coco-research/coco

Similar skills

All skills for Frontend and UI →

From the same set82

The whole set →
redesign-existing-projects redesign-existing-projects — a Claude skill that audits an existing site or app for the usual AI-design tells and fixes them inside the current stack, leaving behaviour alone. CX Codex +1 ★ 328repo stars database-architect Get database architecture recommendations, data models, and migration plans. Use the subagent when shaping a schema, scaling a system, or splitting data across services. CX Codex ★ 328repo stars c4-architecture c4-architecture generates architecture documentation using C4 model: system context, containers, components and deployment as Mermaid diagrams. CX Codex +1 ★ 328repo stars create-subagent create-subagent helps create isolated subagents with targeted system prompts and YAML configurations for code reviews, debugging, and data tasks. CX Codex +1 ★ 328repo stars create-skill create-skill guides you through authoring agent skills by defining directory layout, SKILL.md frontmatter, and precise description triggers. CX Codex +1 ★ 328repo stars ultra-think ultra-think is a Claude Code skill that examines architecture decisions from four viewpoints, compares approaches, and gives one recommendation. CX Codex +1 ★ 328repo stars generate-tests generate-tests writes tests for a file, module or component, after first detecting the project's framework and conventions. CX Codex +1 ★ 328repo stars m0-handoff m0-handoff saves session state into STATE.md and the local M0 daemon so another session or tool picks up right where you stopped. CX Codex +1 ★ 328repo stars

Project sponsors

Companies that keep this analytics open