jouwdriedee/.agents/skills/tailwindcss-development/SKILL.md

name, description, license, metadata

name	description	license	metadata
tailwindcss-development	Always invoke when the user's message includes 'tailwind' in any form. Also invoke for: building responsive grid layouts (multi-column card grids, product grids), flex/grid page structures (dashboards with sidebars, fixed topbars, mobile-toggle navs), styling UI components (cards, tables, navbars, pricing sections, forms, inputs, badges), adding dark mode variants, fixing spacing or typography, and Tailwind v3/v4 work. The core use case: writing or fixing Tailwind utility classes in HTML templates (Blade, JSX, Vue). Skip for backend PHP logic, database queries, API routes, JavaScript with no HTML/CSS component, CSS file audits, build tool configuration, and vanilla CSS.	MIT	author laravel

Tailwind CSS development

Documentation

Use search-docs for detailed Tailwind CSS v4 patterns and documentation.

Basic usage

• Use Tailwind CSS classes to style HTML. Before introducing new patterns, check and follow the project's existing Tailwind conventions.
• Offer to extract repeated patterns into components that match the project's conventions, such as Blade, JSX, or Vue components.
• Consider class placement, order, priority, and defaults. Remove redundant classes, add classes to parent or child elements carefully to reduce repetition, and group elements logically.

Tailwind CSS v4 specifics

• Always use Tailwind CSS v4 and avoid deprecated utilities.
• corePlugins is not supported in Tailwind v4.

CSS-first configuration

In Tailwind v4, you configure Tailwind in CSS with the @theme directive. You don't need a separate tailwind.config.js file:

@theme {
  --color-brand: oklch(0.72 0.11 178);
}

Import syntax

In Tailwind v4, import Tailwind with a regular CSS @import statement instead of the @tailwind directives used in v3:

- @tailwind base;
- @tailwind components;
- @tailwind utilities;
+ @import "tailwindcss";

Replaced utilities

Tailwind v4 removed deprecated utilities. Use the replacements shown below. For opacity, drop the *-opacity-* class and append the value as a modifier on the existing color: bg-blue-500 bg-opacity-50 becomes bg-blue-500/50, text-white text-opacity-75 becomes text-white/75.

Deprecated	Replacement
bg-opacity-*	bg-{color}/*
text-opacity-*	text-{color}/*
border-opacity-*	border-{color}/*
divide-opacity-*	divide-{color}/*
ring-opacity-*	ring-{color}/*
placeholder-opacity-*	placeholder-{color}/*
flex-shrink-*	shrink-*
flex-grow-*	grow-*
overflow-ellipsis	text-ellipsis
decoration-slice	box-decoration-slice
decoration-clone	box-decoration-clone

Spacing

Use gap utilities instead of margins for spacing between siblings:

<div class="flex gap-8">
    <div>Item 1</div>
    <div>Item 2</div>
</div>

Dark mode

If existing pages and components support dark mode, new pages and components must support it the same way, typically using the dark: variant:

<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
    Content adapts to color scheme
</div>

Common pitfalls

• Using deprecated v3 utilities, such as bg-opacity-* and flex-shrink-*
• Using @tailwind directives instead of @import "tailwindcss"
• Using tailwind.config.js instead of the CSS @theme directive
• Using margins for spacing between siblings instead of gap utilities
• Forgetting to add dark mode variants when the project uses dark mode