tailwind-css

Tailwind CSS Skill

Overview

Expert guidance for Tailwind CSS styling with mobile-first responsive design, custom themes, and utility-first approach. Focuses on accessibility, dark mode, and performance optimization.

When This Skill Applies

This skill triggers when users request:

• Styling: "Style this KPI card", "Button component style", "Design a form"
• Responsive: "Mobile-first layout", "Responsive dashboard", "Grid with breakpoints"
• Themes: "Custom dark theme", "Extend tailwind theme", "Color scheme"
• Layouts: "Dashboard grid", "Card layout", "Flexible container"

Core Rules

1. Mobile-First Design

// ✅ GOOD: Mobile-first progressive enhancement
<div className="w-full px-4 py-2 sm:w-1/2 sm:px-6 md:w-1/3 md:px-8 lg:w-1/4">
  <KPICard />
</div>

// Breakpoints:
// sm: 640px   - Small tablets/phones
// md: 768px   - Tablets
// lg: 1024px  - Desktops
// xl: 1280px  - Large screens
// 2xl: 1536px - Extra large screens

Requirements:

• Base styles for mobile (no prefix)
• Progressive enhancement with sm:, md:, lg: prefixes
• Start with mobile layout, enhance for larger screens
• Use responsive breakpoints: sm:640px, md:768px, lg:1024px

2. Responsive Utilities

// ✅ GOOD: Fluid responsive layouts
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">
  {items.map(item => <Item key={item.id} item={item} />)}
</div>

// ✅ GOOD: Responsive spacing
<div className="p-4 sm:p-6 md:p-8 lg:p-12">
  Content
</div>

// ✅ GOOD: Container queries (if needed)
<div className="@container">
  <div className="@lg:grid-cols-2">
    Nested responsive content
  </div>
</div>

Requirements:

• Use fluid utilities (w-full, flex-1) for mobile
• Add breakpoints (sm:, md:, lg:) for larger screens
• Consider container queries for nested responsive components
• Test layouts at multiple breakpoints (375px, 768px, 1024px, 1440px)

3. Custom Themes

// tailwind.config.ts
export default {
  darkMode: 'class', // or 'media'
  content: ['./src/**/*.{ts,tsx}'],
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          500: '#3b82f6',
          900: '#1e3a8a',
        },
        erp: {
          'card': '#ffffff',
          'card-dark': '#1f2937',
        },
      },
      spacing: {
        '18': '4.5rem',
        '88': '22rem',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
  plugins: [],
};

Requirements:

• Extend theme in tailwind.config.ts, don't override
• Use semantic names (primary, secondary, accent)
• Define custom colors, fonts, spacing in theme
• Support CSS variables for dynamic theming
• Use darkMode: 'class' for manual dark mode toggle

4. Component Styling

// ✅ GOOD: Utility-first approach
export const Button = ({ variant, size, children }) => (
  <button className={`
    font-semibold rounded-lg
    ${variant === 'primary' ? 'bg-blue-500 text-white hover:bg-blue-600' : 'bg-gray-200 text-gray-800 hover:bg-gray-300'}
    ${size === 'sm' ? 'px-3 py-1 text-sm' : 'px-4 py-2'}
    transition-colors duration-200
    focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2
  `}>
    {children}
  </button>
);

// ✅ GOOD: CVA or class-variance-authority for variants
import { cva } from 'class-variance-authority';

const buttonVariants = cva(
  'font-semibold rounded-lg transition-colors',
  {
    variants: {
      variant: {
        primary: 'bg-blue-500 text-white hover:bg-blue-600',
        secondary: 'bg-gray-200 text-gray-800 hover:bg-gray-300',
      },
      size: {
        sm: 'px-3 py-1 text-sm',
        md: 'px-4 py-2',
      },
    },
  }
);

Requirements:

• Prefer inline utility classes over custom CSS
• Use @apply sparingly (only for repeated patterns)
• Extract complex variants with CVA or similar libraries
• Follow shadcn/ui patterns for consistent styling
• Use template literals for conditional classes

Output Requirements

Code Files

1. Component Styling:
2. Inline utility classes in JSX/TSX
3. Conditional classes for variants (dark/light, sizes)
4. Focus states and transitions

1. Configuration:
2. tailwind.config.ts updates for custom themes
3. globals.css for global styles and directives

1. Dark Mode Support:

``jsx <div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white"> Content with dark mode </div> ``

Integration Requirements

• shadcn/ui: Follow shadcn design tokens and patterns
• Accessibility: WCAG 2.1 AA compliant colors, focus-visible states
• Performance: Enable JIT mode, purge unused classes
• i18n: Support RTL layouts when needed

Documentation

• PHR: Create Prompt History Record for styling decisions
• ADR: Document theme decisions (color schemes, breakpoints)
• Comments: Document non-obvious utility combinations

Workflow

1. Analyze Layout Requirements
2. Identify mobile breakpoints
3. Determine responsive needs
4. Check dark mode requirements

1. Apply Mobile-First Styles
2. Base styles without breakpoints
3. Progressive enhancement for larger screens
4. Test on mobile viewport (375px)

1. Add Responsive Breakpoints
2. sm: for tablets (640px)
3. md: for tablets (768px)
4. lg: for desktops (1024px)
5. Test at each breakpoint

1. Apply Dark Mode
2. Add dark: variants for colors/backgrounds
3. Test in both light and dark modes
4. Ensure contrast ratios in both modes

1. Validate Accessibility
2. Check color contrast ratios (4.5:1 minimum)
3. Add focus-visible states for interactive elements
4. Ensure touch targets are 44px+ on mobile

Quality Checklist

Before completing any styling:

• [ ] No Horizontal Scroll Mobile: Layout fits 375px without horizontal scroll
• [ ] Touch Targets: All interactive elements 44px+ on mobile
• [ ] Dark/Light Variants: Dark mode support with dark: classes
• [ ] Utility-First: Minimal custom CSS, use Tailwind utilities
• [ ] Purge Unused: No unused utility classes in production
• [ ] Focus States: focus-visible or focus:ring on all interactive elements
• [ ] Contrast Ratios: WCAG 2.1 AA compliant colors (4.5:1 for text)
• [ ] Responsive Breakpoints: Tested at sm/md/lg breakpoints
• [ ] Consistent Spacing: Use Tailwind's spacing scale (0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 56, 64)
• [ ] Transitions: Add transition-* classes for smooth state changes

Common Patterns

KPI Card (Mobile-First)

export const KPICard = ({ title, value, trend, loading }) => (
  <div className="
    w-full p-4 bg-white dark:bg-gray-800
    rounded-lg shadow-sm border border-gray-200 dark:border-gray-700
    sm:p-6 md:p-8
  ">
    {loading ? (
      <Skeleton className="h-20" />
    ) : (
      <>
        <h3 className="text-sm font-medium text-gray-600 dark:text-gray-400">
          {title}
        </h3>
        <p className="text-2xl font-bold text-gray-900 dark:text-white mt-2">
          {value}
        </p>
        {trend && (
          <span className={`
            inline-flex items-center mt-2 text-sm
            ${trend > 0 ? 'text-green-600 dark:text-green-400' : 'text-red-600 dark:text-red-400'}
          `}>
            {trend > 0 ? '↑' : '↓'} {Math.abs(trend)}%
          </span>
        )}
      </>
    )}
  </div>
);

Responsive Dashboard Grid

export const DashboardGrid = ({ children }) => (
  <div className="
    w-full grid gap-4
    grid-cols-1
    sm:grid-cols-2
    md:grid-cols-3
    lg:grid-cols-4
    xl:grid-cols-5
    p-4
  ">
    {children}
  </div>
);

Form with Responsive Layout

export const ResponsiveForm = () => (
  <form className="
    w-full max-w-lg mx-auto
    p-4 sm:p-6 md:p-8
    bg-white dark:bg-gray-800
    rounded-lg shadow-md
  ">