Tailwind Ui

Tailwind UI Skill

Tailwind CSS v4.1 development with accessibility and theming baked in.

Quick Reference

v4.1 Critical Changes

Never use deprecated utilities — always use replacements:

Essential Patterns

<!-- Gap over space utilities -->
<div class="flex gap-4">...</div>

<!-- Opacity modifiers -->
<div class="bg-primary-500/60">...</div>

<!-- Line height modifiers -->
<p class="text-base/7">...</p>

<!-- Dynamic viewport height (mobile-safe) -->
<div class="min-h-dvh">...</div>

<!-- Size utility for equal dimensions -->
<div class="size-12">...</div>

Reference Files

Load these based on the task:

• [references/v4-migration.md](references/v4-migration.md) — Full v4.1 breaking changes, upgrade process, new features
• [references/accessibility.md](references/accessibility.md) — WCAG 2.1 AA patterns: contrast, focus, screen readers
• [references/theming.md](references/theming.md) — @theme setup, CSS variables, light/dark mode
• [references/components.md](references/components.md) — Accessible component patterns (buttons, forms, cards, nav)

Theme Asset

• [assets/theme-starter.css](assets/theme-starter.css) — Starter @theme with primary/secondary/tertiary color scales

Core Principles

1. Use Tailwind's scale — Avoid arbitrary values like ml-[16px]; use ml-4 2. Never use @apply — Use CSS variables or framework components 3. Gap over margins — Use gap-* in flex/grid, not space-* or child margins 4. Test both modes — Always verify light AND dark mode appearance 5. Accessibility first — Every interactive element needs visible focus states and proper contrast

Accessibility Reference (WCAG 2.1 AA)

Color Contrast

Minimum Ratios (AA)

• Normal text: 4.5:1
• Large text (18px+ or 14px+ bold): 3:1
• UI components & graphics: 3:1

Safe Color Combinations

For text on backgrounds, ensure sufficient contrast:

<!-- ✅ High contrast patterns -->
<p class="bg-white text-gray-900">Dark on light</p>
<p class="bg-gray-900 text-white">Light on dark</p>
<p class="bg-primary-500 text-white">White on primary (verify contrast)</p>

<!-- ⚠️ Test these combinations -->
<p class="bg-gray-100 text-gray-600">May fail contrast</p>

Testing Contrast

Use browser DevTools or tools like:

• axe DevTools extension
• WAVE extension
• Chrome's built-in contrast checker (inspect element → color picker)

Opacity and Contrast

Opacity reduces contrast — always verify:

<!-- ⚠️ Opacity affects readability -->
<p class="text-gray-900/70">Verify this passes 4.5:1</p>

Focus States

Every interactive element must have a visible focus indicator.

Focus Ring Pattern

<!-- ✅ Standard focus ring -->
<button class="focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-2">
  Click me
</button>

<!-- ✅ For dark backgrounds -->
<button class="focus-visible:ring-2 focus-visible:ring-white focus-visible:ring-offset-2 focus-visible:ring-offset-gray-900">
  Click me
</button>

Focus-Visible vs Focus

Use focus-visible: for keyboard-only focus states (hides ring on mouse click):

<!-- ✅ Keyboard-only focus ring -->
<a href="#" class="focus-visible:ring-2 focus-visible:ring-primary-500">Link</a>

<!-- Use focus: when you want ring on all focus (including mouse) -->
<input class="focus:ring-2 focus:ring-primary-500" />

Focus Within

Style parent when child is focused:

<div class="focus-within:ring-2 focus-within:ring-primary-500">
  <input type="text" class="border-0 focus:ring-0" />
</div>

Custom Focus Styles

Ensure 3:1 contrast for focus indicators:

<!-- ✅ High-visibility focus -->
<button class="
  focus-visible:outline-2 
  focus-visible:outline-offset-2 
  focus-visible:outline-primary-500
">
  Accessible button
</button>

Screen Reader Support

Visually Hidden Content

Use sr-only for screen-reader-only text:

<!-- Icon button with accessible label -->
<button>
  <svg class="size-5" aria-hidden="true">...</svg>
  <span class="sr-only">Close menu</span>
</button>

<!-- Skip link -->
<a href="#main" class="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4">
  Skip to main content
</a>

Hiding from Screen Readers

Use aria-hidden="true" for decorative elements:

<!-- Decorative icon -->
<span aria-hidden="true">🎉</span>

<!-- Decorative SVG -->
<svg aria-hidden="true" class="size-5">...</svg>

Live Regions

For dynamic content updates:

<!-- Polite announcement (waits for pause) -->
<div aria-live="polite" class="sr-only">
  {{ statusMessage }}
</div>

<!-- Assertive announcement (interrupts) -->
<div aria-live="assertive" class="sr-only">
  {{ errorMessage }}
</div>

Form Labels

Always associate labels with inputs:

<!-- ✅ Explicit association -->
<label for="email" class="block text-sm/6 font-medium">Email</label>
<input id="email" type="email" class="..." />

<!-- ✅ Implicit association -->
<label class="block">
  <span class="text-sm/6 font-medium">Email</span>
  <input type="email" class="..." />
</label>

<!-- ✅ Hidden label for icon inputs -->
<label for="search" class="sr-only">Search</label>
<input id="search" type="search" placeholder="Search..." />

Error States

Announce errors to screen readers:

<input 
  id="email" 
  type="email" 
  aria-invalid="true"
  aria-describedby="email-error"
  class="border-red-500 focus:ring-red-500"
/>
<p id="email-error" class="text-sm text-red-600" role="alert">
  Please enter a valid email address
</p>

Motion and Animation

Reduced Motion

Respect user preferences:

<!-- ✅ Disable animations when preferred -->
<div class="transition-transform motion-reduce:transition-none motion-reduce:transform-none">
  Animated content
</div>

<!-- ✅ Alternative: reduce animation intensity -->
<div class="duration-300 motion-reduce:duration-0">
  Fade in
</div>

Safe Animation Patterns

<!-- ✅ Opacity is generally safe -->
<div class="transition-opacity">...</div>

<!-- ⚠️ Transform can cause vestibular issues -->
<div class="transition-transform motion-reduce:transition-none">...</div>

Interactive Elements

Minimum Target Size

Interactive elements should be at least 44×44px:

<!-- ✅ Adequate touch target -->
<button class="min-h-11 min-w-11 p-3">
  <svg class="size-5">...</svg>
</button>

<!-- ✅ Adequate link target -->
<a href="#" class="inline-block py-3 px-4">Link</a>

Disabled States

Communicate disabled state visually and semantically:

<button 
  disabled
  class="bg-gray-300 text-gray-500 cursor-not-allowed"
  aria-disabled="true"
>
  Disabled
</button>

Semantic Structure

Heading Hierarchy

Use proper heading levels (don't skip):

<h1>Page Title</h1>
  <h2>Section</h2>
    <h3>Subsection</h3>
  <h2>Another Section</h2>

Landmarks

Use semantic HTML for landmarks:

<header>...</header>
<nav aria-label="Main">...</nav>
<main id="main">...</main>
<aside>...</aside>
<footer>...</footer>

Checklist

Before shipping, verify:

• [ ] Color contrast meets 4.5:1 for text, 3:1 for UI
• [ ] All interactive elements have visible focus states
• [ ] Icon buttons have accessible labels
• [ ] Form inputs have associated labels
• [ ] Error messages are announced to screen readers
• [ ] Animations respect prefers-reduced-motion
• [ ] Touch targets are at least 44×44px
• [ ] Heading hierarchy is logical
• [ ] Skip link is present for keyboard users

Accessible Component Patterns

Accessible, theme-aware component patterns for Tailwind CSS v4.1.

Buttons

Primary Button

<button class="
  inline-flex items-center justify-center gap-2
  px-4 py-2 min-h-11
  bg-primary-500 text-white font-medium
  rounded-sm shadow-xs
  hover:bg-primary-600
  focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500
  disabled:bg-gray-300 disabled:text-gray-500 disabled:cursor-not-allowed
  dark:disabled:bg-gray-700 dark:disabled:text-gray-400
">
  Button text
</button>

Secondary Button

<button class="
  inline-flex items-center justify-center gap-2
  px-4 py-2 min-h-11
  bg-white text-gray-900 font-medium
  border border-gray-300
  rounded-sm shadow-xs
  hover:bg-gray-50
  focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500
  dark:bg-gray-800 dark:text-white dark:border-gray-600 dark:hover:bg-gray-700
">
  Button text
</button>

Icon Button

<button class="
  inline-flex items-center justify-center
  size-11 p-2
  text-gray-500 hover:text-gray-700
  rounded-sm
  hover:bg-gray-100
  focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500
  dark:text-gray-400 dark:hover:text-white dark:hover:bg-gray-800
">
  <svg class="size-5" aria-hidden="true">...</svg>
  <span class="sr-only">Close</span>
</button>

Form Inputs

Text Input

<div>
  <label for="email" class="block text-sm/6 font-medium text-gray-900 dark:text-white">
    Email
  </label>
  <input
    type="email"
    id="email"
    class="
      mt-2 block w-full
      px-3 py-2
      bg-white text-gray-900 placeholder-gray-400
      border border-gray-300 rounded-sm shadow-xs
      focus:ring-2 focus:ring-primary-500 focus:border-primary-500
      dark:bg-gray-800 dark:text-white dark:placeholder-gray-500
      dark:border-gray-600 dark:focus:ring-primary-400
    "
    placeholder="you@example.com"
  />
</div>

Input with Error

<div>
  <label for="email-error" class="block text-sm/6 font-medium text-gray-900 dark:text-white">
    Email
  </label>
  <input
    type="email"
    id="email-error"
    aria-invalid="true"
    aria-describedby="email-error-message"
    class="
      mt-2 block w-full
      px-3 py-2
      bg-white text-gray-900
      border-2 border-red-500 rounded-sm
      focus:ring-2 focus:ring-red-500 focus:border-red-500
      dark:bg-gray-800 dark:text-white
    "
  />
  <p id="email-error-message" class="mt-2 text-sm text-red-600 dark:text-red-400" role="alert">
    Please enter a valid email address.
  </p>
</div>

Select

<div>
  <label for="country" class="block text-sm/6 font-medium text-gray-900 dark:text-white">
    Country
  </label>
  <select
    id="country"
    class="
      mt-2 block w-full
      px-3 py-2
      bg-white text-gray-900
      border border-gray-300 rounded-sm shadow-xs
      focus:ring-2 focus:ring-primary-500 focus:border-primary-500
      dark:bg-gray-800 dark:text-white dark:border-gray-600
    "
  >
    <option>United States</option>
    <option>Canada</option>
  </select>
</div>

Checkbox

<div class="flex items-center gap-3">
  <input
    type="checkbox"
    id="remember"
    class="
      size-4
      rounded-xs border-gray-300
      text-primary-500 
      focus:ring-2 focus:ring-primary-500 focus:ring-offset-2
      dark:border-gray-600 dark:bg-gray-800
      dark:focus:ring-offset-gray-900
    "
  />
  <label for="remember" class="text-sm/6 text-gray-900 dark:text-white">
    Remember me
  </label>
</div>

Cards

Basic Card

<article class="
  bg-white rounded-sm shadow-sm
  border border-gray-200
  overflow-hidden
  dark:bg-gray-800 dark:border-gray-700
">
  <div class="p-6">
    <h3 class="text-lg/7 font-semibold text-gray-900 dark:text-white">
      Card Title
    </h3>
    <p class="mt-2 text-sm/6 text-gray-600 dark:text-gray-300">
      Card description text goes here.
    </p>
  </div>
</article>

Interactive Card

<a 
  href="#"
  class="
    block
    bg-white rounded-sm shadow-sm
    border border-gray-200
    overflow-hidden
    hover:shadow-md hover:border-gray-300
    focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500
    transition-shadow
    dark:bg-gray-800 dark:border-gray-700
    dark:hover:border-gray-600
  "
>
  <div class="p-6">
    <h3 class="text-lg/7 font-semibold text-gray-900 dark:text-white">
      Clickable Card
    </h3>
    <p class="mt-2 text-sm/6 text-gray-600 dark:text-gray-300">
      The entire card is clickable.
    </p>
  </div>
</a>

Card with Image

<article class="
  bg-white rounded-sm shadow-sm
  border border-gray-200
  overflow-hidden
  dark:bg-gray-800 dark:border-gray-700
">
  <img 
    src="image.jpg" 
    alt="Description of image"
    class="w-full h-48 object-cover"
  />
  <div class="p-6">
    <h3 class="text-lg/7 font-semibold text-gray-900 dark:text-white">
      Card Title
    </h3>
    <p class="mt-2 text-sm/6 text-gray-600 dark:text-gray-300">
      Card description text.
    </p>
  </div>
</article>

Navigation

Primary Navigation

<nav aria-label="Main navigation" class="bg-white border-b border-gray-200 dark:bg-gray-900 dark:border-gray-700">
  <div class="max-w-7xl mx-auto px-4">
    <div class="flex items-center justify-between h-16">
      <a href="/" class="text-xl font-bold text-gray-900 dark:text-white">
        Logo
      </a>
      <ul class="flex items-center gap-1">
        <li>
          <a 
            href="#" 
            class="
              px-4 py-2 rounded-sm
              text-sm/6 font-medium
              text-gray-900 hover:bg-gray-100
              focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500
              dark:text-white dark:hover:bg-gray-800
            "
            aria-current="page"
          >
            Home
          </a>
        </li>
        <li>
          <a 
            href="#"
            class="
              px-4 py-2 rounded-sm
              text-sm/6 font-medium
              text-gray-600 hover:text-gray-900 hover:bg-gray-100
              focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500
              dark:text-gray-300 dark:hover:text-white dark:hover:bg-gray-800
            "
          >
            About
          </a>
        </li>
      </ul>
    </div>
  </div>
</nav>

Skip Link

Always include a skip link for keyboard users:

<a 
  href="#main-content"
  class="
    sr-only focus:not-sr-only
    focus:absolute focus:top-4 focus:left-4 focus:z-50
    focus:px-4 focus:py-2
    focus:bg-primary-500 focus:text-white
    focus:rounded-sm focus:shadow-lg
  "
>
  Skip to main content
</a>

Breadcrumbs

<nav aria-label="Breadcrumb">
  <ol class="flex items-center gap-2 text-sm/6">
    <li>
      <a href="#" class="text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-white">
        Home
      </a>
    </li>
    <li aria-hidden="true" class="text-gray-400">/</li>
    <li>
      <a href="#" class="text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-white">
        Products
      </a>
    </li>
    <li aria-hidden="true" class="text-gray-400">/</li>
    <li>
      <span class="text-gray-900 font-medium dark:text-white" aria-current="page">
        Current Page
      </span>
    </li>
  </ol>
</nav>

Alerts

Info Alert

<div 
  role="alert"
  class="
    flex gap-3 p-4
    bg-blue-50 text-blue-800 
    border border-blue-200 rounded-sm
    dark:bg-blue-900/20 dark:text-blue-300 dark:border-blue-800
  "
>
  <svg class="size-5 shrink-0 mt-0.5" aria-hidden="true">...</svg>
  <div>
    <h4 class="font-medium">Information</h4>
    <p class="mt-1 text-sm/6">This is an informational message.</p>
  </div>
</div>

Error Alert

<div 
  role="alert"
  class="
    flex gap-3 p-4
    bg-red-50 text-red-800
    border border-red-200 rounded-sm
    dark:bg-red-900/20 dark:text-red-300 dark:border-red-800
  "
>
  <svg class="size-5 shrink-0 mt-0.5" aria-hidden="true">...</svg>
  <div>
    <h4 class="font-medium">Error</h4>
    <p class="mt-1 text-sm/6">Something went wrong. Please try again.</p>
  </div>
</div>

Modals/Dialogs

Dialog Structure

<!-- Backdrop -->
<div 
  class="fixed inset-0 bg-black/50 dark:bg-black/70"
  aria-hidden="true"
></div>

<!-- Dialog -->
<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title"
  class="
    fixed inset-0 flex items-center justify-center p-4
  "
>
  <div class="
    w-full max-w-md
    bg-white rounded-sm shadow-xl
    dark:bg-gray-800
  ">
    <div class="p-6">
      <h2 id="dialog-title" class="text-lg/7 font-semibold text-gray-900 dark:text-white">
        Dialog Title
      </h2>
      <p class="mt-2 text-sm/6 text-gray-600 dark:text-gray-300">
        Dialog content goes here.
      </p>
    </div>
    <div class="flex justify-end gap-3 px-6 py-4 bg-gray-50 dark:bg-gray-900/50">
      <button class="px-4 py-2 text-sm font-medium text-gray-700 hover:text-gray-900 dark:text-gray-300 dark:hover:text-white">
        Cancel
      </button>
      <button class="px-4 py-2 text-sm font-medium bg-primary-500 text-white rounded-sm hover:bg-primary-600">
        Confirm
      </button>
    </div>
  </div>
</div>

Loading States

Spinner

<div role="status" class="flex items-center gap-2">
  <svg 
    class="size-5 animate-spin text-primary-500" 
    viewBox="0 0 24 24"
    aria-hidden="true"
  >
    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" fill="none"/>
    <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"/>
  </svg>
  <span class="sr-only">Loading...</span>
</div>

Skeleton

<div class="animate-pulse">
  <div class="h-4 bg-gray-200 rounded-sm w-3/4 dark:bg-gray-700"></div>
  <div class="mt-2 h-4 bg-gray-200 rounded-sm w-1/2 dark:bg-gray-700"></div>
</div>

Accessibility Checklist per Component

• [ ] Visible focus states with adequate contrast
• [ ] Proper ARIA attributes where needed
• [ ] Screen reader text for icon-only buttons
• [ ] Labels associated with form inputs
• [ ] Error states announced with role="alert"
• [ ] Light and dark mode both styled
• [ ] Minimum 44×44px touch targets
• [ ] Motion respects prefers-reduced-motion

Theming Reference

@theme Configuration

Define custom theme values in your CSS:

@import 'tailwindcss';

@theme {
  /* Custom colors become utilities: bg-brand, text-brand, etc. */
  --color-brand: #0033a0;
  
  /* Color scales */
  --color-primary-500: #0033a0;
  --color-primary-600: oklch(from #0033a0 calc(l - 0.1) c h);
  
  /* Custom spacing */
  --spacing-18: 4.5rem;
  
  /* Custom radius */
  --radius-pill: 9999px;
}

CSS Variables Access

Access theme values in custom CSS:

.custom-element {
  background: var(--color-primary-500);
  border-radius: var(--radius-lg);
  padding: var(--spacing-4);
}

/* Spacing function for calculations */
.custom-layout {
  margin-top: calc(100vh - --spacing(16));
}

Light/Dark Mode Setup

Supporting Both Mechanisms

Support class-based toggle AND system preference:

@import 'tailwindcss';

/* Dark mode activates with .dark class OR system preference */
@variant dark (&:where(.dark, .dark *));
@variant dark (@media (prefers-color-scheme: dark));

Theme-Aware Colors

Define colors that adapt to light/dark:

@theme {
  /* Semantic colors that flip in dark mode */
  --color-surface: white;
  --color-surface-dark: #1a1a1a;
  
  --color-text: #111827;
  --color-text-dark: #f3f4f6;
}

<div class="bg-surface text-text dark:bg-surface-dark dark:text-text-dark">
  Content adapts to mode
</div>

Dark Mode Patterns

Basic Pattern

Light styles first, then dark overrides:

<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">
  Mode-aware content
</div>

Ensuring Neither Mode Is Neglected

Always test both modes. Common oversights:

<!-- ❌ Forgot dark mode -->
<div class="bg-white text-gray-900">
  Invisible in dark mode
</div>

<!-- ❌ Forgot light mode -->
<div class="dark:bg-gray-900 dark:text-white">
  Unstyled in light mode
</div>

<!-- ✅ Both modes covered -->
<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">
  Works in both modes
</div>

Systematic Approach

1. Design light mode first with full styling 2. Add dark: variants for every color utility 3. Test by toggling modes frequently during development

Border and Divide Colors

Don't forget borders:

<div class="border border-gray-200 dark:border-gray-700">
  <div class="divide-y divide-gray-200 dark:divide-gray-700">
    <div>Item 1</div>
    <div>Item 2</div>
  </div>
</div>

Ring and Focus Colors

<button class="
  focus-visible:ring-2 
  focus-visible:ring-primary-500 
  focus-visible:ring-offset-2
  focus-visible:ring-offset-white
  dark:focus-visible:ring-offset-gray-900
">
  Button
</button>

Shadows in Dark Mode

Shadows are less visible on dark backgrounds:

<!-- ✅ Adjusted shadow for dark mode -->
<div class="shadow-lg dark:shadow-2xl dark:shadow-black/25">
  Card
</div>

Form Inputs

<input class="
  bg-white border-gray-300 text-gray-900 placeholder-gray-400
  dark:bg-gray-800 dark:border-gray-600 dark:text-white dark:placeholder-gray-500
  focus:ring-primary-500 focus:border-primary-500
"/>

Color Palette Strategy

Using oklch for Scales

Generate consistent color scales from a base color:

@theme {
  /* Base color */
  --color-primary-500: #0033a0;
  
  /* Lighter shades (increase lightness) */
  --color-primary-400: oklch(from #0033a0 calc(l + 0.1) c h);
  --color-primary-300: oklch(from #0033a0 calc(l + 0.2) c h);
  
  /* Darker shades (decrease lightness) */
  --color-primary-600: oklch(from #0033a0 calc(l - 0.1) c h);
  --color-primary-700: oklch(from #0033a0 calc(l - 0.15) c h);
}

Semantic Color Naming

Consider semantic names for common use cases:

@theme {
  /* Action colors */
  --color-action-primary: var(--color-primary-500);
  --color-action-secondary: var(--color-secondary-500);
  
  /* Status colors */
  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  
  /* Surface colors */
  --color-surface-1: white;
  --color-surface-2: #f9fafb;
  --color-surface-3: #f3f4f6;
}

Theme Toggle Implementation

Angular Example

// theme.service.ts
@Injectable({ providedIn: 'root' })
export class ThemeService {
  private darkMode = signal(false);
  
  constructor() {
    // Check system preference on init
    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    const stored = localStorage.getItem('theme');
    this.darkMode.set(stored === 'dark' || (!stored && prefersDark));
    this.applyTheme();
  }
  
  toggle() {
    this.darkMode.update(v => !v);
    localStorage.setItem('theme', this.darkMode() ? 'dark' : 'light');
    this.applyTheme();
  }
  
  private applyTheme() {
    document.documentElement.classList.toggle('dark', this.darkMode());
  }
}

<!-- Theme toggle button -->
<button (click)="themeService.toggle()" class="p-2 rounded-sm">
  <svg class="size-5 dark:hidden"><!-- sun icon --></svg>
  <svg class="size-5 hidden dark:block"><!-- moon icon --></svg>
  <span class="sr-only">Toggle theme</span>
</button>

Checklist

• [ ] Both light and dark modes have complete styling
• [ ] Borders and dividers adapt to mode
• [ ] Focus rings have appropriate offset colors
• [ ] Form inputs are styled for both modes
• [ ] Shadows are visible in dark mode
• [ ] Text contrast meets WCAG AA in both modes
• [ ] Theme toggle persists preference
• [ ] System preference is respected as default

Tailwind CSS v4.1 Migration Reference

Upgrade Process

1. Ensure clean git state 2. Run: npx @tailwindcss/upgrade@latest 3. Review all changes for false positives 4. Test thoroughly

Removed Utilities

These utilities no longer exist — use the replacement:

Renamed Utilities

Layout and Spacing

Gap Over Space

Always use gap-* in flex/grid layouts:

<!-- ❌ Never -->
<div class="flex space-x-4">...</div>

<!-- ✅ Always -->
<div class="flex gap-4">...</div>

Space utilities break with flex-wrap and add margins to children. Gap works correctly in all cases.

Viewport Units

Use dynamic viewport height for mobile compatibility:

<!-- ❌ Buggy on mobile Safari -->
<div class="min-h-screen">...</div>

<!-- ✅ Works everywhere -->
<div class="min-h-dvh">...</div>

Size Utility

Use size-* for equal width and height:

<!-- ❌ Verbose -->
<div class="h-12 w-12">...</div>

<!-- ✅ Concise -->
<div class="size-12">...</div>

Typography

Line Height Modifiers

Never use separate leading-* classes:

<!-- ❌ Old pattern -->
<p class="text-base leading-7">...</p>

<!-- ✅ v4 pattern -->
<p class="text-base/7">...</p>

Font Size Reference

• text-xs = 12px
• text-sm = 14px
• text-base = 16px
• text-lg = 18px
• text-xl = 20px

Gradients

Linear Gradients

<!-- ✅ v4 syntax -->
<div class="bg-linear-to-r from-primary-500 to-secondary-500">...</div>

Radial Gradients

<div class="bg-radial from-primary-500 to-transparent">...</div>
<div class="bg-radial-[at_50%_75%] from-sky-200 to-indigo-900">...</div>

Conic Gradients

<div class="bg-conic from-primary-500 via-secondary-500 to-primary-500">...</div>

New v4.1 Features

Container Queries

<article class="@container">
  <div class="flex flex-col @md:flex-row @lg:gap-8">
    <img class="w-full @md:w-48" />
    <div class="mt-4 @md:mt-0">...</div>
  </div>
</article>

Text Shadows

<h1 class="text-shadow-lg">Large shadow</h1>
<p class="text-shadow-sm/50">With opacity</p>

Masking

<div class="mask-t-from-50%">Top fade</div>
<div class="mask-radial-[100%_100%] mask-radial-from-75%">Radial mask</div>

CSS Variables

Accessing Theme Values

.custom {
  background: var(--color-primary-500);
  border-radius: var(--radius-lg);
}

Spacing Function

.custom {
  margin-top: calc(100vh - --spacing(16));
}

Responsive Design

Only add breakpoint variants when values change:

<!-- ❌ Redundant -->
<div class="px-4 md:px-4 lg:px-4">...</div>

<!-- ✅ Efficient -->
<div class="px-4 lg:px-8">...</div>

Common Pitfalls

1. Using old opacity utilities instead of /opacity syntax 2. Redundant breakpoint classes 3. space-* in flex/grid instead of gap-* 4. Separate leading-* instead of line-height modifiers 5. min-h-screen instead of min-h-dvh 6. Using @apply instead of CSS variables or components 7. Arbitrary values when scale values exist