code-architecture-tailwind-v4-best-practices

Guide Tailwind CSS v4 component patterns for React and Vue variants.

1|Updated Mar 20, 2026

Search Tags:#accessibility #tailwind #cva #component-patterns #css-first #tailwind-v4 #tailwind-variants

Ready to run

npx skills add https://github.com/Thomashighbaugh/opencode --skill code-architecture-tailwind-v4-best-practices-thomashighbaugh

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: code-architecture-tailwind-v4-best-practices
Source: https://github.com/Thomashighbaugh/opencode/tree/main/skills/code-architecture-tailwind-v4-best-practices
Command: npx skills add https://github.com/Thomashighbaugh/opencode --skill code-architecture-tailwind-v4-best-practices-thomashighbaugh

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This guide resolves uncertainty around how and when to apply Tailwind CSS v4 patterns for buttons and components, helping teams choose between using utilities directly, CVA, or tailwind-variants while adopting the new CSS-first @theme approach.

Core Features & Use Cases

Decision guidance on when to use pure utilities (1–2 variants), CVA (3+ variants), or tailwind-variants (responsive, multi-part components).
CSS-first configuration instructions using @theme for design tokens and utilities generation without tailwind.config.js.
State and accessibility patterns including data-attribute state handling, ARIA practices, and focus/disabled handling.
Migration and compatibility notes highlighting breaking changes from v3 and recommended automated upgrades.

Quick Start

Create a button using utilities for simple variants and adopt CVA only when the component requires three or more distinct variants.

Frequently Asked Questions about code-architecture-tailwind-v4-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I choose between CVA and tailwind-variants for React components?▼

Use CVA for components with three or more distinct variants, and adopt tailwind-variants when managing responsive, multi-part components. Pure utilities are recommended only for simple components with one or two variants.

What is the best way to configure Tailwind v4 design tokens?▼

Configure Tailwind v4 design tokens using the CSS-first @theme approach. This method generates utilities directly from CSS variables, eliminating the need for a tailwind.config.js file.

How do I handle accessibility and state in Tailwind v4 components?▼

Handle component state and accessibility in Tailwind v4 by using data-attribute state handling. Apply proper ARIA practices and manage focus and disabled states directly within your component patterns.

What are the major migration differences when upgrading to Tailwind v4?▼

Tailwind v4 migration involves breaking changes from v3, primarily shifting to CSS-first configuration with @theme. Automated upgrade tools are recommended to help transition your existing component styles smoothly.

When should I abstract Tailwind utilities into component variants?▼

Abstract Tailwind utilities into component variants when a component requires three or more distinct visual styles. For one or two variants, applying pure utilities directly in your React or Vue markup is recommended.