Tailwind CSS Skill

Overview

Utility-first CSS framework for building custom designs with composable utility classes.

Objective

Enable developers to build responsive, maintainable UIs using Tailwind’s utility classes and configuration system.

When to Use

Use this skill when:

• Styling components with utility-first CSS
• Creating responsive designs with Tailwind breakpoints
• Configuring Tailwind theme (colors, spacing, typography)
• Building custom utilities or plugins
• Using JIT mode for performance

Don’t use this skill for:

• Material-UI styling (use mui skill)
• Plain CSS without Tailwind (use css skill)
• Complex animations requiring custom CSS (use css skill)

Critical Patterns

✅ REQUIRED: Use Utility Classes

<!-- ✅ CORRECT: Utility classes -->
<button
  class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
>
  Click Me
</button>

<!-- ❌ WRONG: Custom CSS for basic styling -->
<button class="custom-button">Click Me</button>
<style>
  .custom-button {
    background: blue;
    padding: 8px 16px;
  }
</style>

✅ REQUIRED: Configure Theme in tailwind.config

// ✅ CORRECT: Extend theme
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#1976d2',
      },
    },
  },
};

// ❌ WRONG: Hardcoding hex colors in classes
<div class="bg-[#1976d2]"> // Use theme colors instead

❌ NEVER: Overuse @apply

/* ❌ WRONG: Defeats utility-first purpose */
.btn {
  @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded;
}

/* ✅ CORRECT: Use utilities directly in HTML */
<button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">

✅ REQUIRED: Define Themes with @theme (Tailwind 4+)

/* ✅ CORRECT: Define theme tokens with @theme */
@theme {
  --color-primary: #4f46e5;
  --color-secondary: #9333ea;
  --font-sans: "Inter", sans-serif;
  --radius-md: 0.375rem;
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --spacing-4: 1rem;
}

/* Use in HTML: <div class="bg-primary text-secondary shadow-md"> */

/* ❌ WRONG: Hardcoding values in config (Tailwind 4+) */
tailwind.config.js:
module.exports = {
  theme: {
    colors: { primary: '#4f46e5' } // Use @theme instead
  }
}

✅ ALLOWED: Use @apply for Custom Component Classes

/* ✅ CORRECT: @apply for reusable component patterns */
.bg-custom-screen {
  @apply bg-slate-100 transition-colors duration-300;

  &:hover {
    @apply bg-blue-500;
  }
}

.card-base {
  @apply rounded-lg shadow-md p-6 bg-white;
}

/* Use when: Multiple components share the same utility pattern */
/* ❌ AVOID: Single-use classes (use utilities directly instead) */

Conventions

Refer to conventions for:

• Code organization

Refer to a11y for:

• Color contrast
• Focus indicators

Refer to css for:

• Custom CSS when needed

Tailwind Specific

• Use utility classes over custom CSS
• Configure theme in tailwind.config
• Use @apply for component classes sparingly
• Leverage JIT mode for performance
• Use responsive modifiers (sm:, md:, lg:)
• Enable dark mode with class or media strategy
• Configure content paths properly to avoid purging used classes
• Use arbitrary values [value] only when necessary (prefer theme extension)
• Combine utilities with @apply for reusable component patterns
• Optimize bundle size with proper content configuration

Decision Tree

Tailwind class exists? → Use utility class: className="bg-blue-500".

Dynamic value? → Use inline style: style={{ width: ${percent}% }} or arbitrary values: w-[${value}px].

Conditional styles? → Use clsx/cn helper: cn("base", condition && "variant").

Reusable component style? → Create component with utilities, avoid @apply.

Custom color/spacing? → Add to theme.extend in tailwind.config.js.

Responsive design? → Use breakpoint prefixes: md:flex lg:grid.

Dark mode? → Enable in config, use dark: prefix: dark:bg-gray-800.

Production build? → Ensure all template paths in content array or classes will be purged. Check for dynamic class names.

Custom animations? → Extend theme.animation and theme.keyframes in tailwind.config rather than custom CSS.

Complex component style? → Use @apply with @layer components for reusable patterns, but keep most styles as utilities in HTML.

Example

<div class="max-w-4xl mx-auto p-6">
  <h1 class="text-3xl font-bold text-gray-900 mb-4">Title</h1>
  <button
    class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:ring-2 focus:ring-blue-500"
  >
    Click Me
  </button>
</div>

tailwind.config.js:

module.exports = {
  content: ["./src/**/*.{astro,html,js,jsx,ts,tsx,vue,svelte}"], // ⚠️ CRITICAL
  darkMode: "class", // or 'media'
  theme: {
    extend: {
      colors: {
        brand: "#1976d2",
      },
    },
  },
};

Dark Mode

<!-- Enable with 'class' strategy -->
<html class="dark">
  <!-- dark: prefix works -->
  <div class="bg-white dark:bg-gray-900 text-black dark:text-white">
    Content adapts to dark mode
  </div>
</html>

// Toggle dark mode
document.documentElement.classList.toggle("dark");

Edge Cases

Arbitrary values: Use square brackets for one-off values: w-[137px], top-[117px]. Avoid overuse—extend theme instead.

Specificity conflicts: Tailwind utilities have same specificity. Order in HTML matters. Use ! prefix for important: !mt-0.

Purge/content configuration: Ensure all template paths are in content array or classes will be purged in production.

Third-party component styling: Some libraries use inline styles that override Tailwind. Use !important sparingly or wrapper divs.

@layer directive: Use @layer components for custom component styles, @layer utilities for custom utilities. Ensures proper ordering.

References

• https://tailwindcss.com/docs
• https://tailwindcss.com/docs/configuration