tailwind

name	tailwind
description	WHEN building design systems or component libraries with Tailwind CSS; covers design tokens, CVA patterns and dark mode.

Prerequisites

• Load the web:css skill for CSS Best Practices.
• Load the web:react skill for React Best Practices.
• Load the web:typescript skill for TypeScript Best Practices.
• load the web:web-design skill for Design Best Practices.

Tailwind Design System

Build production-ready design systems with Tailwind CSS, including design tokens, component variants, responsive patterns, and accessibility.

Quick Reference

Topic	Guide
Tailwind config, global CSS, tokens	setup.md
CVA pattern with type-safe variants	cva-components.md
Animation utilities and Dialog	animations.md
Utility functions (cn, focusRing)	utilities.md
Do's and Don'ts for maintainability	best-practices.md

When to Use This Skill

• Creating a component library with Tailwind
• Implementing design tokens and theming
• Building responsive and accessible components
• Standardizing UI patterns across a codebase
• Migrating to or extending Tailwind CSS

Core Concepts

Design Token Hierarchy

Brand Tokens (abstract)
    └── Semantic Tokens (purpose)
        └── Component Tokens (specific)

Example:
    blue-500 → primary → button-bg

Component Architecture

Base styles → Variants → Sizes → States → Overrides

When to Use Each Guide

Setup

Use setup.md when you need:

• Initial Tailwind configuration
• CSS variable setup for theming
• Design token structure
• Global styles foundation

CVA Components

Use cva-components.md when you need:

• Type-safe component variants
• Button, Badge, or similar components
• Standardized variant APIs
• Reusable component patterns

Animations

Use animations.md when you need:

• Entry/exit animations
• Dialog or modal transitions
• Tailwind CSS Animate utilities
• State-based animations

Utilities

Use utilities.md when you need:

• Class name composition (cn function)
• Common utility patterns
• Focus ring, disabled state helpers

Best Practices

Use best-practices.md for:

• Guidance on semantic naming
• Do's and Don'ts
• Accessibility requirements
• Performance considerations

Quick Decision Trees

Where should colors be defined?

Is this a one-off color?
├── Yes → Use arbitrary value sparingly (e.g., bg-[#abc123])
└── No → Is it semantic (primary, destructive)?
    ├── Yes → Add to semantic tokens in setup.md
    └── No → Is it a brand color?
        ├── Yes → Add to theme.extend.colors
        └── No → Use existing Tailwind color

Installation

# Required packages
yarn add tailwindcss postcss autoprefixer
yarn add class-variance-authority clsx tailwind-merge
yarn add tailwindcss-animate

Resources

• Tailwind CSS Documentation
• CVA Documentation
• shadcn/ui
• Radix Primitives