TailwindCSS Design Patterns Skill

TailwindCSS Design Patterns

TailwindCSS implementation companion for web-design-mastery skill. Translates Refactoring UI principles into Tailwind utility classes.

Prerequisite: This skill provides Tailwind-specific syntax. For design theory and decision-making, reference web-design-mastery skill.

⚠️ CRITICAL: Project Brand Colors First

ALWAYS check tailwind.config.js for custom colors before using generic colors.

If the project defines primary, secondary, brand, or similar custom colors, USE THEM:

// tailwind.config.js
colors: {
  primary: { 50: '...', 500: '...', 900: '...' },
  secondary: { ... },
  brand: { ... }
}

Priority order:

Project-defined colors (primary, secondary, brand, accent)
Generic Tailwind colors (zinc, gray, slate) as fallback only

Usage examples with project colors:

<!-- ✅ CORRECT: Use project colors -->
<button class="bg-primary-600 hover:bg-primary-700 text-white">
<a class="text-primary-600 hover:text-primary-700">
<div class="border-primary-500 bg-primary-50">
<input class="focus:border-primary-500 focus:ring-primary-500">

<!-- Active/selected states -->
<nav class="bg-primary-50 text-primary-700">

<!-- ❌ AVOID when project colors exist -->
<button class="bg-blue-600">  <!-- Generic, ignores brand -->
<button class="bg-zinc-900">  <!-- Only if no primary defined -->

Rules:

Primary = main CTAs, active states, links, focus rings
Secondary = alternative actions, supporting elements
Brand/Accent = highlights, decorative elements
Neutral (zinc/gray) = structure, text, borders only

Spacing Classes (4px Grid)

| Token | Size | Classes | Use Case | |-------|------|---------|----------| | 1 | 4px | gap-1, p-1, m-1 | Micro gaps | | 2 | 8px | gap-2, p-2, m-2 | Tight, within components | | 3 | 12px | gap-3, p-3, m-3 | Related elements | | 4 | 16px | gap-4, p-4, m-4 | Standard padding | | 6 | 24px | gap-6, p-6, m-6 | Between sections | | 8 | 32px | gap-8, p-8, m-8 | Major separation | | 12 | 48px | gap-12, p-12 | Large gaps | | 16 | 64px | gap-16, py-16 | Hero spacing |

Rule: Symmetric padding by default. p-4 not pt-6 pb-2 pl-4 pr-8.

Typography Classes

| Size | Class | Use Case | |------|-------|----------| | 12px | text-xs | Labels, meta, fine print | | 14px | text-sm | Body text, default | | 16px | text-base | Emphasis | | 18px | text-lg | Subheadings | | 20px | text-xl | Card titles | | 24px | text-2xl | Page titles | | 30px | text-3xl | Hero subheading | | 36px+ | text-4xl, text-5xl | Hero heading |

Weight Classes:

| Role | Class | |------|-------| | Body | font-normal | | Labels | font-medium | | Headings | font-semibold |

Tracking (Letter-spacing):

<!-- Headlines: tighter -->
<h1 class="text-3xl font-semibold tracking-tight">

<!-- All-caps: wider -->
<span class="text-xs font-medium uppercase tracking-wide">

Color Hierarchy

Text Colors (4-Level System)

<!-- Light mode -->
<span class="text-zinc-900">Primary</span>
<span class="text-zinc-600">Secondary</span>
<span class="text-zinc-400">Muted</span>
<span class="text-zinc-300">Faint</span>

<!-- Dark mode -->
<span class="dark:text-zinc-100">Primary</span>
<span class="dark:text-zinc-400">Secondary</span>
<span class="dark:text-zinc-500">Muted</span>
<span class="dark:text-zinc-600">Faint</span>

Status Colors

<span class="text-emerald-600 dark:text-emerald-400">Success</span>
<span class="text-amber-600 dark:text-amber-400">Warning</span>
<span class="text-red-600 dark:text-red-400">Error</span>
<span class="text-blue-600 dark:text-blue-400">Info</span>

Brand Colors (Priority)

Check tailwind.config.js first. If primary/secondary defined, use them:

<button class="bg-primary-600 hover:bg-primary-700">
<a class="text-primary-600 hover:text-primary-700">
<div class="border-primary-500 bg-primary-50">

Shadow & Depth Strategies

Pick ONE per project:

Strategy A: Flat (Borders)

<div class="border border-zinc-200 dark:border-zinc-800">

Strategy B: Subtle Lift

<div class="shadow-sm border border-zinc-200/50">

Strategy C: Layered (Premium)

<div class="shadow-sm ring-1 ring-black/5">

Strategy D: Surface Shift

<div class="bg-zinc-50"> <!-- page -->
  <div class="bg-white"> <!-- elevated -->

Shadow Scale:

| Level | Class | Use Case | |-------|-------|----------| | 1 | shadow-sm | Cards, buttons | | 2 | shadow | Dropdowns | | 3 | shadow-md | Popovers | | 4 | shadow-lg | Modals | | 5 | shadow-xl | Full-screen overlays |

Component Recipes

Cards

<!-- Flat -->
<div class="rounded-lg border border-zinc-200 bg-white p-4 dark:border-zinc-800 dark:bg-zinc-900">

<!-- Elevated -->
<div class="rounded-lg bg-white p-4 shadow-sm ring-1 ring-black/5 dark:bg-zinc-900">

Buttons

<!-- Primary -->
<button class="rounded-md bg-zinc-900 px-3 py-1.5 text-sm font-medium text-white hover:bg-zinc-800 dark:bg-zinc-100 dark:text-zinc-900 dark:hover:bg-zinc-200">

<!-- Secondary -->
<button class="rounded-md border border-zinc-300 bg-white px-3 py-1.5 text-sm font-medium text-zinc-700 hover:bg-zinc-50 dark:border-zinc-700 dark:bg-zinc-800 dark:text-zinc-300">

<!-- Ghost -->
<button class="rounded-md px-3 py-1.5 text-sm font-medium text-zinc-600 hover:bg-zinc-100 hover:text-zinc-900 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-100">

Inputs

<input class="w-full rounded-md border border-zinc-300 bg-white px-3 py-2 text-sm text-zinc-900 placeholder:text-zinc-400 focus:border-zinc-500 focus:outline-none focus:ring-1 focus:ring-zinc-500 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-100" />

Navigation Item

<!-- Default -->
<a class="flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium text-zinc-600 hover:bg-zinc-100 hover:text-zinc-900 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-100">

<!-- Active -->
<a class="flex items-center gap-2 rounded-md bg-zinc-100 px-3 py-2 text-sm font-medium text-zinc-900 dark:bg-zinc-800 dark:text-zinc-100">

Animation Classes

| Duration | Class | Use Case | |----------|-------|----------| | 150ms | duration-150 | Hovers, toggles | | 200ms | duration-200 | Standard transitions | | 300ms | duration-300 | Page transitions |

<div class="transition-all duration-200 ease-out">
<div class="transition-colors duration-150">

Staggered Animation:

<div class="animate-fade-in [animation-delay:0ms]">
<div class="animate-fade-in [animation-delay:50ms]">
<div class="animate-fade-in [animation-delay:100ms]">

Dark Mode Pattern

<div class="bg-white dark:bg-zinc-950">
  <h1 class="text-zinc-900 dark:text-zinc-100">
  <p class="text-zinc-600 dark:text-zinc-400">
  <div class="border-zinc-200 dark:border-zinc-800">

Dark mode adjustments:

Borders > shadows (shadows less visible)
Desaturate status colors slightly
Reduce contrast on secondary elements

Anti-Patterns

<!-- ❌ NEVER -->
<div class="shadow-2xl">           <!-- Too dramatic -->
<button class="rounded-2xl px-3">  <!-- Radius too large for size -->
<div class="pt-8 pb-2 pl-6 pr-3">  <!-- Asymmetric without reason -->
<div class="border-4 border-purple-500"> <!-- Thick decorative -->
<div class="animate-bounce">       <!-- Bouncy in enterprise UI -->

<!-- ✅ INSTEAD -->
<div class="shadow-sm">
<button class="rounded-md px-3">
<div class="p-4">
<div class="border border-zinc-200">
<div class="transition-all duration-200">

Reference Files

| Topic | File | |-------|------| | Component depth patterns | depth-strategies.md | | Complete component library | components.md | | Responsive patterns | responsive.md |

Agent Skills: TailwindCSS Design Patterns

Install this agent skill to your local

Skill Files