Tailwind Conventions

Tailwind CSS Conventions Skill

Consistent patterns for Tailwind CSS in React/Next.js applications.

Class Organization Order

Always organize classes in this order for readability:

className={cn(
  // 1. Layout (position, display, flex/grid)
  "relative flex flex-col",
  // 2. Sizing (width, height, padding, margin)
  "w-full max-w-md p-4 mx-auto",
  // 3. Visual (background, border, shadow)
  "bg-white border border-gray-200 rounded-lg shadow-sm",
  // 4. Typography (font, text, color)
  "text-sm font-medium text-gray-900",
  // 5. States (hover, focus, active, disabled)
  "hover:bg-gray-50 focus:ring-2 focus:ring-blue-500",
  // 6. Responsive (sm:, md:, lg:, xl:)
  "md:flex-row md:p-6",
  // 7. Dark mode
  "dark:bg-gray-800 dark:text-white"
)}

Utility Function (cn)

Use clsx + tailwind-merge for conditional classes:

// lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

// Usage

Responsive Design

Mobile-First Approach

// Start with mobile, add breakpoints for larger screens

Common Breakpoints

• sm: - 640px+ (large phones)
• md: - 768px+ (tablets)
• lg: - 1024px+ (laptops)
• xl: - 1280px+ (desktops)
• 2xl: - 1536px+ (large screens)

Responsive Typography

Dark Mode

Using CSS Variables (Recommended)

/* globals.css */
:root {
  --background: 255 255 255;
  --foreground: 10 10 10;
}

.dark {
  --background: 10 10 10;
  --foreground: 255 255 255;
}

// tailwind.config.ts
theme: {
  extend: {
    colors: {
      background: 'rgb(var(--background) / )',
      foreground: 'rgb(var(--foreground) / )',
    }
  }
}

// Usage - no dark: prefix needed

Using dark: Prefix

Component Patterns

Button Variants

const buttonVariants = {
  base: "inline-flex items-center justify-center rounded-md font-medium transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none",
  variants: {
    primary: "bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500",
    secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200 focus:ring-gray-500",
    outline: "border border-gray-300 bg-transparent hover:bg-gray-50 focus:ring-gray-500",
    ghost: "bg-transparent hover:bg-gray-100 focus:ring-gray-500",
    destructive: "bg-red-600 text-white hover:bg-red-700 focus:ring-red-500",
  },
  sizes: {
    sm: "h-8 px-3 text-sm",
    md: "h-10 px-4 text-sm",
    lg: "h-12 px-6 text-base",
  }
};

Card Pattern

  
    Title
    Description
  

Input Pattern

Spacing Conventions

Consistent Spacing Scale

• gap-1 / p-1 = 4px (tight)
• gap-2 / p-2 = 8px (compact)
• gap-4 / p-4 = 16px (default)
• gap-6 / p-6 = 24px (comfortable)
• gap-8 / p-8 = 32px (spacious)

Container Pattern

  {/* Content */}

Animation

Transitions

// Smooth color/opacity transitions

// Transform transitions (scale, translate)

// All properties

Built-in Animations

     // Loading spinner
    // Skeleton loading
   // Attention grabber
     // Notification dot

Accessibility

Focus States

// Always visible focus rings

// Focus-visible for keyboard only

Screen Reader

Loading...  // Hidden visually, announced
   // Decorative, ignored

Layout Patterns

CSS Grid Layouts

// 12-column grid

  Main content
  Sidebar

// Auto-fit responsive grid

  {items.map(item => )}

// Dashboard grid

  
  
  
  

Sidebar Layout

// Fixed sidebar + scrollable content

  
    {/* Nav items */}
  
  
    {/* Main content */}
  

// Collapsible sidebar

  
    {/* Sidebar content */}
  
  {/* Content */}

Form Layouts

// Stacked form

  
    Email
    
  
  
    Password
    
  
  
    Sign In
  

// Inline form (search bar)

  
  Search

// Two-column form

  
    First Name
    
  
  
    Last Name
    
  
  
    Email
    
  

Header/Footer Layout

// Sticky header + footer

  
    
      {/* Nav content */}
    
  
  
    {/* Page content */}
  
  
    {/* Footer content */}
  

Centered Content

// Horizontally centered with max-width
{/* Content */}

// Vertically and horizontally centered

  {/* Centered card */}

Anti-Patterns

• Don't use @apply excessively - defeats Tailwind's purpose
• Don't create overly specific custom classes
• Don't fight the spacing scale - use what's provided
• Don't inline complex conditional logic - extract to variables
• Don't forget dark mode when adding colors
• Don't use arbitrary values [123px] when scale values exist

---

Version

• v1.0.0 (2025-12-05): Added YAML frontmatter, initial documented version

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: benshapyro
• Source: benshapyro/cadre-devkit-claude
• License: MIT

Install and usage instructions live in the source repository linked above.