fquiz/.agents/skills/tailwind-css-patterns/references/reference.md

Tailwind CSS Documentation

Tailwind CSS is a utility-first CSS framework that generates styles by scanning HTML, JavaScript, and template files for class names. It provides a comprehensive design system through CSS utility classes, enabling rapid UI development without writing custom CSS. The framework operates at build-time, analyzing source files and generating only the CSS classes actually used in the project, resulting in optimized production bundles with zero runtime overhead.

The framework includes an extensive default color palette (18 colors with 11 shades each), responsive breakpoint system, customizable design tokens via CSS custom properties, and support for dark mode, pseudo-classes, pseudo-elements, and media queries through variant prefixes. Tailwind CSS v4.1 introduces CSS-first configuration using the @theme directive, native support for custom utilities via @utility, seamless integration with modern build tools through Vite, PostCSS, and framework-specific plugins, and enhanced arbitrary value syntax for maximum flexibility.

Installation with Vite

Installing Tailwind CSS using the Vite plugin for modern JavaScript frameworks.

# Create a new Vite project
npm create vite@latest my-project
cd my-project

# Install Tailwind CSS and Vite plugin
npm install tailwindcss @tailwindcss/vite

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

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

/* src/style.css */
@import "tailwindcss";

# Hello world!

Utility Classes with Variants

Applying conditional styles using variant prefixes for hover, focus, and responsive breakpoints.

 Save changes

Content adapts to color scheme preference

 Submit

Custom Theme Configuration

Defining custom design tokens using the @theme directive in CSS.

/* app.css */
@import "tailwindcss";

@theme {
 /* Custom fonts */
 --font-display: "Satoshi", "sans-serif";
 --font-body: "Inter", system-ui, sans-serif;

 /* Custom colors */
 --color-brand-50: oklch(0.98 0.02 264);
 --color-brand-100: oklch(0.95 0.05 264);
 --color-brand-500: oklch(0.55 0.22 264);
 --color-brand-900: oklch(0.25 0.12 264);

 /* Custom breakpoints */
 --breakpoint-3xl: 120rem;
 --breakpoint-4xl: 160rem;

 /* Custom spacing */
 --spacing-18: calc(var(--spacing) * 18);

 /* Custom animations */
 --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
 --ease-snappy: cubic-bezier(0.2, 0, 0, 1);
}

Custom design system

Arbitrary Values

Using square bracket notation for one-off custom values without leaving HTML.

Pixel-perfect positioning

Custom hex colors, font sizes, and content

Any CSS property

Reference custom properties

Complex grid layouts

Font size from CSS variable

Color from CSS variable

Color System

Working with Tailwind's comprehensive color palette and opacity modifiers.

Color utilities across all properties

Alpha channel with percentage

Arbitrary opacity values

Opacity from CSS variable

Adapts to color scheme

Dark Mode

Implementing dark mode with CSS media queries or manual toggle.

Content automatically adapts

/* Manual dark mode toggle with class selector */
@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));

Controlled by .dark class

// Dark mode toggle logic
// On page load or theme change
document.documentElement.classList.toggle(
 "dark",
 localStorage.theme === "dark" ||
 (!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches)
);

// User chooses light mode
localStorage.theme = "light";

// User chooses dark mode
localStorage.theme = "dark";

// User chooses system preference
localStorage.removeItem("theme");

State Variants

Styling elements based on pseudo-classes and parent/sibling state.

- Item content


**Title**
Description

Please provide a valid email address.


 Option

Responsive Design

Building mobile-first responsive layouts with breakpoint variants.

# Responsive heading

Text scales with viewport


Desktop only

Mobile only

Custom breakpoint

Below medium

Custom Utilities

Creating reusable custom utility classes with variant support.

/* Simple custom utility */
@utility content-auto {
 content-visibility: auto;
}

/* Complex utility with nesting */
@utility scrollbar-hidden {
 &::-webkit-scrollbar {
 display: none;
 }
}

/* Functional utility with theme values */
@theme {
 --tab-size-2: 2;
 --tab-size-4: 4;
 --tab-size-github: 8;
}

@utility tab-* {
 tab-size: --value(--tab-size-*);
}

/* Supporting arbitrary, bare, and theme values */
@utility opacity-* {
 opacity: --value([percentage]);
 opacity: calc(--value(integer) * 1%);
 opacity: --value(--opacity-*);
}

/* Utility with modifiers */
@utility text-* {
 font-size: --value(--text-*, [length]);
 line-height: --modifier(--leading-*, [length], [*]);
}

/* Negative value support */
@utility inset-* {
 inset: --spacing(--value(integer));
 inset: --value([percentage], [length]);
}

@utility -inset-* {
 inset: --spacing(--value(integer) * -1);
 inset: calc(--value([percentage], [length]) * -1);
}

Custom utilities work with variants

Variants and arbitrary values supported

Utility with modifier (font-size/line-height)

Custom Variants

Registering custom conditional styles with the @custom-variant directive.

/* Simple custom variant */
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

/* Variant with media query */
@custom-variant any-hover {
 @media (any-hover: hover) {
 &:hover {
 @slot;
 }
 }
}

/* ARIA state variant */
@custom-variant aria-asc (&[aria-sort="ascending"]);
@custom-variant aria-desc (&[aria-sort="descending"]);

/* Data attribute variant */
@custom-variant data-checked (&[data-ui~="checked"]);

 Midnight theme button


 Sortable column

Checked state

One-off custom selectors

Applying Variants in CSS

Using the @variant directive to apply variants within custom CSS.

/* Single variant */
.my-element {
 background: white;

 @variant dark {
 background: black;
 }
}

/* Nested variants */
.my-button {
 background: white;

 @variant dark {
 background: gray;

 @variant hover {
 background: black;
 }
 }
}

/* Compiled output */
.my-element {
 background: white;
}

@media (prefers-color-scheme: dark) {
 .my-element {
 background: black;
 }
}

Layer Organization

Organizing custom styles into Tailwind's cascade layers.

@import "tailwindcss";

/* Base styles for HTML elements */
@layer base {
 h1 {
 font-size: var(--text-2xl);
 font-weight: bold;
 }

 h2 {
 font-size: var(--text-xl);
 font-weight: 600;
 }

 body {
 font-family: var(--font-body);
 }
}

/* Reusable component classes */
@layer components {
 .btn {
 padding: --spacing(2) --spacing(4);
 border-radius: var(--radius);
 font-weight: 600;
 transition: all 150ms;
 }

 .btn-primary {
 background-color: var(--color-blue-500);
 color: white;
 }

 .card {
 background-color: var(--color-white);
 border-radius: var(--radius-lg);
 padding: --spacing(6);
 box-shadow: var(--shadow-xl);
 }

 /* Third-party component overrides */
 .select2-dropdown {
 border-radius: var(--radius);
 box-shadow: var(--shadow-lg);
 }
}

Square corners despite card class

 Component with utility overrides

Functions and Directives

Using Tailwind's CSS functions for dynamic values and opacity adjustments.

/* Alpha function for opacity */
.my-element {
 color: --alpha(var(--color-lime-300) / 50%);
 background: --alpha(var(--color-blue-500) / 25%);
}

/* Spacing function */
.my-element {
 margin: --spacing(4);
 padding: calc(--spacing(6) - 1px);
}

/* In arbitrary values */

/* Source directive for additional content */
@source "../node_modules/@my-company/ui-lib";

/* Apply directive for inline utilities */
.select2-dropdown {
 @apply rounded-b-lg shadow-md;
}

.select2-search {
 @apply rounded border border-gray-300;
}

.select2-results__group {
 @apply text-lg font-bold text-gray-900;
}

Pseudo-elements

Styling ::before, ::after, ::placeholder, and other pseudo-elements.

 Email


- First item
- Second item

Select this text to see custom colors

Typography with pseudo-elements

Media Queries

Conditional styling based on user preferences and device capabilities.

 Respects user preference

 Only animates if motion allowed

 Adjusts for contrast needs


Hidden in portrait mode

Layout adapts to orientation

 Not shown when printing

Only visible in print

Progressive enhancement

Summary

Tailwind CSS provides a complete utility-first design system that eliminates the need for writing custom CSS in most cases. The framework's primary use cases include rapid prototyping, building production applications with consistent design systems, creating responsive layouts, implementing dark mode, and maintaining design consistency across large teams. By using utility classes directly in markup, developers can iterate quickly, avoid naming conventions, and prevent CSS bloat since only used styles are generated.

The v4.1 release enhances the developer experience with CSS-first configuration, eliminating JavaScript configuration files for most projects. Integration patterns include using the Vite plugin for modern frameworks, PostCSS for custom build pipelines, the Tailwind CLI for simple projects, and CDN scripts for rapid prototyping. The framework excels at component-driven development when combined with React, Vue, Svelte, or other modern frameworks, where utility classes are co-located with component logic. Custom design systems can be fully defined in CSS using @theme, with project-specific utilities and variants extending the framework's capabilities without writing JavaScript plugins.