Skip to main content
skill CX Codex

tailwind · oakoss — Claude Code skill: what it does, how to install

A Tailwind CSS v4 skill for themes, components, dark mode, container queries, v3 migrations, shadcn/ui, and build troubleshooting.

MIT 233 installs ★ 29 updated 2026-08-17

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

What tailwind does

This skill guides Tailwind CSS v4 work through CSS-first configuration. It covers @theme for design tokens, the @import "tailwindcss" entry point, custom utilities with @utility, plugin loading with @plugin, and explicit scan paths via @source.

It also covers dark mode, container queries, shadcn/ui integration, and migration from v3. The reference includes dynamic utility values, logical spacing and inset utilities, text shadows, masks, and form-state variants. A legacy Tailwind v3 project with no upgrade plan is outside its intended use.

What it helps with

  • configure a Tailwind theme with @theme
  • build components with container queries
  • migrate a project from Tailwind v3 to v4
  • map CSS variables for shadcn/ui
  • diagnose a Tailwind build error

Example prompts for the agent

  • Set up a Tailwind CSS v4 theme with @theme and replace raw colors with semantic tokens.
  • Migrate this project from Tailwind v3 to v4 and update the configuration across its files.
  • Check the shadcn/ui integration and fix the Tailwind build error.

How to install tailwind

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill tailwind -a claude-code

2Manually: put the files in place

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

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

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

Questions about tailwind

How do I install tailwind in Claude Code?

Run npx skills add oakoss/agent-skills --skill tailwind -a claude-code, then check ~/.claude/skills/tailwind/SKILL.md.

What does the tailwind skill do?

It supports Tailwind CSS v4 themes, design tokens, components, dark mode, container queries, plugins, and build troubleshooting.

Can I use tailwind for a Tailwind v3 project?

It covers migration from v3 to v4. A legacy v3 project that will not be upgraded is outside its intended use.

Source text

SKILL.md · MIT
---
name: tailwind
description: 'Tailwind CSS v4 patterns and design systems. Use when configuring Tailwind themes, building components, implementing dark mode, using container queries, migrating from v3, integrating shadcn/ui, or fixing build errors. Use for tailwind, css, styling, theme, design-tokens.'
license: MIT
metadata:
  author: oakoss
  version: '1.0'
  source: 'https://tailwindcss.com/docs'
user-invocable: false
---

# Tailwind CSS (v4+)

## Overview

Tailwind CSS v4 skill covering CSS-first configuration, design tokens, component patterns, shadcn/ui integration, dark mode, container queries, migration from v3, and custom utilities.

**When to use:** Configuring Tailwind themes, building utility-first components, implementing dark mode, using container queries, migrating from v3, integrating shadcn/ui, troubleshooting build errors.

**When NOT to use:** Tailwind v3 legacy projects that will not upgrade, projects using a different styling approach (CSS Modules, styled-components) without plans to adopt Tailwind.

## Quick Reference

| Pattern              | API                                                   | Key Points                                       |
| -------------------- | ----------------------------------------------------- | ------------------------------------------------ |
| CSS-first config     | `@theme { --color-brand: oklch(...); }`               | All config in CSS, no `tailwind.config.js`       |
| Import entry         | `@import "tailwindcss";`                              | Replaces `@tailwind base/components/utilities`   |
| Custom utilities     | `@utility name { ... }`                               | Replaces `@layer utilities`, works with variants |
| Functional utilities | `@utility tab-* { tab-size: --value(--tab-size-*); }` | Accept dynamic values via `--value()`            |
| Plugin loading       | `@plugin "@tailwindcss/typography";`                  | Replaces `require()` in config                   |
| Container queries    | `@container` parent + `@md:` child                    | Built-in, no plugin needed                       |
| Named containers     | `@container/sidebar` + `@md/sidebar:`                 | Scope queries to specific containers             |
| Dark mode variant    | `@custom-variant dark (&:where(.dark, .dark *));`     | Class-based dark mode override                   |
| Theme inline         | `@theme inline { --color-bg: var(--bg); }`            | Inlines values at build, single-theme only       |
| Source detection     | `@source "../node_modules/my-lib";`                   | Explicitly add scan paths                        |
| Reference import     | `@reference "../../app.css";`                         | Use theme in Vue/Svelte scoped styles            |
| Override defaults    | `--color-*: initial;` inside `@theme`                 | Reset a category before redefining               |
| Dynamic values       | `grid-cols-(--my-var)`                                | Use CSS variables in utility values              |
| Text shadows         | `text-shadow-*`                                       | Built-in text shadow utilities                   |
| Starting styles      | `starting:opacity-0`                                  | `@starting-style` variant for entry animations   |
| Masks                | `mask-*`                                              | CSS mask utilities for image/gradient masking    |
| Field sizing         | `field-sizing-content`                                | Auto-sizing textareas and inputs                 |
| Inset shadows        | `inset-shadow-*`, `inset-ring-*`                      | Inner shadow and ring utilities                  |
| User validation      | `user-valid:`, `user-invalid:`                        | Form validation after user interaction           |
| Pointer queries      | `pointer-fine:`, `pointer-coarse:`                    | Target input device precision                    |
| Inert                | `inert:opacity-50`                                    | Style inert elements                             |
| Logical spacing      | `pbs-*`, `pbe-*`, `mbs-*`, `mbe-*`                    | Block-direction padding/margin (v4.2)            |
| Logical sizing       | `inline-*`, `block-*`, `min-inline-*`, `max-block-*`  | Logical width/height utilities (v4.2)            |
| Logical inset        | `inset-s-*`, `inset-e-*`, `inset-bs-*`, `inset-be-*`  | Logical positioning; replaces `start-*`/`end-*`  |
| Logical borders      | `border-bs-*`, `border-be-*`                          | Block-direction border utilities (v4.2)          |
| Font features        | `font-features-['smcp']`                              | OpenType `font-feature-settings` (v4.2)          |
| New color palettes   | `mauve`, `olive`, `mist`, `taupe`                     | Additional neutral palettes (v4.2)               |
| Webpack integration  | `@tailwindcss/webpack`                                | Run Tailwind as a webpack plugin (v4.2)          |
| Color space          | OKLCH                                                 | Default in v4, sRGB fallbacks generated          |

## Common Mistakes

| Mistake                                   | Correct Pattern                                  |
| ----------------------------------------- | ------------------------------------------------ |
| Using `tailwind.config.js` in v4          | Configure via `@theme { ... }` in CSS            |
| `hsl(var(--background))` double-wrap      | Reference directly: `var(--background)`          |
| `:root`/`.dark` inside `@layer base`      | Define at root level, outside any `@layer`       |
| `@apply` with `@layer components` classes | Use `@utility` directive for custom utilities    |
| `@theme inline` for multi-theme switching | Use `@theme` without `inline` for dynamic themes |
| Raw colors like `bg-blue-500` everywhere  | Semantic tokens (`bg-primary`) that auto-adapt   |
| `require()` or `@import` for plugins      | Use `@plugin "package-name";`                    |
| `tailwindcss-animate` in v4               | Use `tw-animate-css` instead                     |
| Missing `@theme inline` with shadcn/ui    | Map all CSS variables in `@theme inline` block   |
| Using `theme('colors.brand')` in CSS      | Use `var(--color-brand)` native CSS variables    |
| Using deprecated `start-*`/`end-*` inset  | Use `inset-s-*`/`inset-e-*` logical utilities    |

## Delegation

- **Class pattern discovery and usage examples**: Use `Explore` agent
- **v3 to v4 migration across multiple files**: Use `Task` agent
- **Design token hierarchy and theming architecture**: Use `Plan` agent

> If the `motion` skill is available, delegate complex animation patterns (spring physics, gestures, scroll-linked) to it.

## References

- [Configuration](references/configuration.md) -- CSS-first config, @theme, @theme inline, @utility, @plugin, @source, @reference, @variant directives
- [Design Tokens](references/design-tokens.md) -- OKLCH token system, brand scales, semantic tokens, shadows, z-index, fluid typography
- [Component Patterns](references/component-patterns.md) -- Layouts, grids, container queries, 3D transforms, subgrid, CVA variants
- [UI Patterns](references/ui-patterns.md) -- Buttons, forms, navigation, cards, typography with variants, states, accessibility
- [Dark Mode](references/dark-mode.md) -- Class-based dark mode, multi-theme systems, ThemeProvider, @custom-variant
- [shadcn/ui Integration](references/shadcn-integration.md) -- Four-step architecture, components.json, tw-animate-css, Vite setup
- [Migration](references/migration.md) -- v3 to v4 migration steps, breaking changes, upgrade tool, common gotchas
- [Troubleshooting](references/troubleshooting.md) -- Common errors, build fixes, CSS layer issues, PostCSS problems

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

tailwind by other authors comes first.

tailwind boraoztunc A skill for Tailwind CSS v4.2 in HyperFrames compositions, with rules for stable browser rendering and v3-to-v4 fixes. CX Codex +1 218installs tailwind PyModel A skill for Claude Code and Codex covering Tailwind CSS v4 styling and configuration. Agents consult its 42 rules for build setups, @theme tokens, and CSS bundle tuning. CX Codex +1 671installs tailwind bobmatnyc A Tailwind CSS reference the agent reads before writing markup: utility classes, breakpoints, dark mode, config. Useful when components should follow the framework's own idioms. CX Codex +1 277installs tailwind-v4-shadcn secondsky tailwind-v4-shadcn sets up Tailwind CSS v4 with shadcn/ui, Vite, and React. Solves broken CSS variables, theme switching errors, and v4 migration pitfalls. CX Codex +1 8,300installs tailwind-v4 existential-birds tailwind-v4 — a skill that tells your coding agent how to set up Tailwind CSS v4: theme in CSS, design tokens, OKLCH colors and dark mode. CX Codex +1 827installs tailwind-design-system giuseppe-trisciuoglio tailwind-design-system is a Claude Code skill that creates and orchestrates design systems with Tailwind CSS v4.1+ and shadcn/ui. It defines oklch tokens and CSS variable themes. CX Codex +1 4,800installs tailwind-css-patterns giuseppe-trisciuoglio tailwind-css-patterns is a Claude Code skill with Tailwind CSS patterns for responsive interfaces and components. It activates for styling React, Vue, or Svelte components, building design systems, and adding dark mode. CX Codex +1 18,100installs tailwind-theme-builder jezweb tailwind-theme-builder is a Claude Code skill that configures Tailwind v4 and shadcn/ui themes with dark mode. It activates for theme setup, v3-to-v4 migrations, and colour or CSS configuration errors. CX Codex +1 3,300installs tailwind-4 prowler-cloud tailwind-4 is a Claude Code skill for styling with Tailwind CSS 4. It activates around className, variants, and dynamic values. CX Codex +1 617installs

From the same set106

The whole set →
coolify A skill for driving self-hosted Coolify from your agent: app deploys, webhooks, CI/CD and build-pack troubleshooting. CX Codex +1 385installs application-security application-security walks your code and design through OWASP Top 10 and STRIDE, then hands over a pre-deploy checklist plus the compliance angles for GDPR, HIPAA, SOC 2 and PCI-DSS. CX Codex +1 287installs drizzle-orm Equips coding agents with schema conventions, query patterns, and migration workflows for Drizzle ORM across PostgreSQL, MySQL, and SQLite. CX Codex +1 263installs brand-designer brand-designer is a Claude Code skill for building visual brand identities, from logos to brand guidelines. It responds to requests for palettes, typography systems, and social media templates. CX Codex +1 242installs vitest-testing vitest-testing adds Vitest patterns and best practices to Claude Code. Helps write reliable unit, component, and hook tests without typical async mistakes. CX Codex +1 226installs content-humanizer content-humanizer rewrites model-written drafts so they read like a person wrote them: sentence rhythm, tone, and the hedging that gives AI text away. CX Codex +1 225installs zod-validation zod-validation guides AI coding agents through Zod v4 schema validation in TypeScript. Helps write schemas, parse incoming payloads, and generate JSON Schema definitions. CX Codex +1 222installs tanstack-form This skill guides TanStack Form v1 usage in React, covering state, validation, and submission. Use it for complex forms and changing field lists. CX Codex +1 222installs

Project sponsors

Companies that keep this analytics open