tailwind-v4

Q: How do I install tailwind-v4?

Run npx skills add https://github.com/existential-birds/beagle --skill tailwind-v4 in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tailwind-v4/ (personal) or .claude/skills/tailwind-v4/ (project).

by existential-birdsFrontend & Design

Tailwind CSS v4 with CSS-first configuration and design tokens. Use when setting up Tailwind v4, defining theme variables, using OKLCH colors, or configuring dark mode. Triggers on @theme, @tailwindcss/vite, oklch, CSS variables, --color-, tailwind v4.

Installs: 812
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/existential-birds/beagle --skill tailwind-v4

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads tailwind-v4 automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Tailwind CSS v4 Best Practices

Quick Reference

Vite Plugin Setup:

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

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

CSS Entry Point:

/* src/index.css */
@import 'tailwindcss';

@theme Inline Directive:

@theme inline {
  --color-primary: oklch(60% 0.24 262);
  --color-surface: oklch(98% 0.002 247);
}

Key Differences from v3

Feature	v3	v4
Configuration	tailwind.config.js	@theme in CSS
Build Tool	PostCSS plugin	@tailwindcss/vite
Colors	rgb() / hsl()	oklch() (default)
Theme Extension	extend: {} in JS	CSS variables
Dark Mode	darkMode config option	CSS variants

@theme Directive Modes

default (standard mode)

Generates CSS variables that can be referenced elsewhere:

@theme {
  --color-brand: oklch(60% 0.24 262);
}

/* Generates: :root { --color-brand: oklch(...); } */
/* Usage: text-brand → color: var(--color-brand) */

Note: You can also use @theme default explicitly to mark theme values that can be overridden by non-default @theme declarations.

inline

Inlines values directly without CSS variables (better performance):

@theme inline {
  --color-brand: oklch(60% 0.24 262);
}

/* Usage: text-brand → color: oklch(60% 0.24 262) */

reference

Inlines values as fallbacks without emitting CSS variables:

@theme reference {
  --color-internal: oklch(50% 0.1 180);
}

/* No :root variable, but utilities use fallback */
/* Usage: bg-internal → background-color: var(--color-internal, oklch(50% 0.1 180)) */

OKLCH Color Format

OKLCH provides perceptually uniform colors with better consistency across hues:

oklch(L% C H)

L (Lightness): 0% (black) to 100% (white)
C (Chroma): 0 (gray) to ~0.4 (vibrant)
H (Hue): 0-360 degrees (red → yellow → green → blue → magenta)

Examples:

--color-sky-500: oklch(68.5% 0.169 237.323);  /* Bright blue */
--color-red-600: oklch(57.7% 0.245 27.325);   /* Vibrant red */
--color-zinc-900: oklch(21% 0.006 285.885);   /* Near-black gray */

CSS Variable Naming

Tailwind v4 uses double-dash CSS variable naming conventions:

@theme {
  /* Colors: --color-{name}-{shade} */
  --color-primary-500: oklch(60% 0.24 262);

  /* Spacing: --spacing multiplier */
  --spacing: 0.25rem;  /* Base unit for spacing scale */

  /* Fonts: --font-{family} */
  --font-display: 'Inter Variable', system-ui, sans-serif;

  /* Breakpoints: --breakpoint-{size} */
  --breakpoint-lg: 64rem;

  /* Custom animations: --animate-{name} */
  --animate-fade-in: fade-in 0.3s ease-out;
}

No Config Files Needed

Tailwind v4 eliminates configuration files:

No tailwind.config.js - Use @theme in CSS instead
No postcss.config.js - Use @tailwindcss/vite plugin
TypeScript support - Add @types/node for path resolution

{
  "devDependencies": {
    "@tailwindcss/vite": "^4.0.0",
    "@types/node": "^22.0.0",
    "tailwindcss": "^4.0.0",
    "vite": "^6.0.0"
  }
}

Progressive Disclosure

Setup & Installation: See references/setup.md for Vite plugin configuration, package setup, TypeScript config
Theming & Design Tokens: See references/theming.md for @theme modes, color palettes, custom fonts, animations
Dark Mode Strategies: See references/dark-mode.md for media queries, class-based, attribute-based approaches

Gates (setup verification)

Before recommending @theme choices, OKLCH tokens, or v4 utilities, confirm the project is actually on the v4 integration path:

Build wiring: The Vite config loads tailwindcss() from @tailwindcss/vite, and the CSS entry uses @import 'tailwindcss'. If this fails, stop — fix wiring per references/setup.md first.
Major versions: package.json lists tailwindcss (and @tailwindcss/vite when using Vite) at major 4, not a v3 PostCSS-only toolchain.
Theme source: New theme tokens live in @theme / @theme inline in CSS — not tailwind.config.js extend (v3). If a v3 config still drives the theme, migrating wiring takes precedence over token tweaks.

Decision Guide

When to use @theme inline vs default

Use @theme inline:

Better performance (no CSS variable overhead)
Static color values that won't change
Animation keyframes with multiple values
Utilities that need direct value inlining

Use @theme (default):

Dynamic theming with JavaScript
CSS variable references in custom CSS
Values that change based on context
Better debugging (inspect CSS variables in DevTools)

When to use @theme reference

Use @theme reference:

Provide fallback values without CSS variable overhead
Values that should work even if variable isn't defined
Reducing :root bloat while maintaining utility support
Combining with inline for direct value substitution

Common Patterns

Two-Tier Variable System

Semantic variables that map to design tokens:

@theme {
  /* Design tokens (OKLCH colors) */
  --color-blue-600: oklch(54.6% 0.245 262.881);
  --color-slate-800: oklch(27.9% 0.041 260.031);

  /* Semantic mappings */
  --color-primary: var(--color-blue-600);
  --color-surface: var(--color-slate-800);
}

/* Usage: bg-primary, bg-surface */

Custom Font Configuration

@theme {
  --font-display: 'Inter Variable', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  --font-display--font-variation-settings: 'wght' 400;
  --font-display--font-feature-settings: 'cv02', 'cv03', 'cv04';
}

/* Usage: font-display, font-mono */

Animation Keyframes

@theme inline {
  --animate-beacon: beacon 2s ease-in-out infinite;

  @keyframes beacon {
    0%, 100% {
      opacity: 1;
      transform: scale(1);
    }
    50% {
      opacity: 0.5;
      transform: scale(1.05);
    }
  }
}

/* Usage: animate-beacon */

FAQ

What does the tailwind-v4 skill do?

How do I install tailwind-v4?

Run npx skills add https://github.com/existential-birds/beagle --skill tailwind-v4 in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tailwind-v4/ (personal) or .claude/skills/tailwind-v4/ (project).

Which AI agents can use tailwind-v4?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is tailwind-v4 safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains tailwind-v4?

It is published by existential-birds in existential-birds/beagle. It has 812 recorded installs.

More from existential-birds/beagle

View all →

react-flow

existential-birds/beagle

React Flow (@xyflow/react) for workflow visualization with custom nodes and edges. Use when building graph visualizations, creating custom workflow nodes, implementing edge labels, or controlling viewport. Triggers on ReactFlow, @xyflow/react, Handle, NodeProps, EdgeProps, useReactFlow, fitView.

Frontend & Design1.3K installs

python-code-review

existential-birds/beagle

Reviews Python code for type safety, async patterns, error handling, and common mistakes. Use when reviewing .py files, checking type hints, async/await usage, or exception handling.

Code Quality & Workflow920 installs

langgraph-code-review

existential-birds/beagle

Reviews LangGraph code for bugs, anti-patterns, and improvements. Use when reviewing code that uses StateGraph, nodes, edges, checkpointing, or other LangGraph features. Catches common mistakes in state management, graph structure, and async patterns.

Code Quality & Workflow884 installs

react-flow-advanced

existential-birds/beagle

Advanced React Flow patterns for complex use cases. Use when implementing sub-flows, custom connection lines, programmatic layouts, drag-and-drop, undo/redo, or complex state synchronization.

Frontend & Design631 installs

react-router-v7

existential-birds/beagle

React Router v7 best practices for data-driven routing. Use when implementing routes, loaders, actions, Form components, fetchers, navigation guards, protected routes, or URL search params. Triggers on createBrowserRouter, RouterProvider, useLoaderData, useActionData, useFetcher, NavLink, Outlet.

Frontend & Design573 installs

react-flow-architecture

existential-birds/beagle

Architectural guidance for building node-based UIs with React Flow. Use when designing flow-based applications, making decisions about state management, integration patterns, or evaluating whether React Flow fits a use case.

Frontend & Design529 installs

Popular frontend & design skills

View category →

setup-matt-pocock-skills

mattpocock/skills

Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.

Frontend & Design1.1M installs

frontend-design

anthropics/skills

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

OfficialFrontend & Design1M installs

hyperframes-animation

heygen-com/hyperframes

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Frontend & Design1M installs

prototype

mattpocock/skills

Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

Frontend & Design999.2K installs

hyperframes-core

heygen-com/hyperframes

The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Frontend & Design930.5K installs

vercel-react-best-practices

vercel-labs/agent-skills

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

OfficialFrontend & Design843.1K installs

tailwind-v4

Install

Install

Describe the task

Review the result

SKILL.md

Tailwind CSS v4 Best Practices

Quick Reference

Key Differences from v3

@theme Directive Modes

default (standard mode)

inline

reference

OKLCH Color Format

CSS Variable Naming

No Config Files Needed

Progressive Disclosure

Gates (setup verification)

Decision Guide

When to use @theme inline vs default

When to use @theme reference

Common Patterns

Two-Tier Variable System

Custom Font Configuration

Animation Keyframes

FAQ

More from existential-birds/beagle

Popular frontend & design skills