/tailwindcss-development

name: tailwindcss-development
description: "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."
license: MIT
metadata:
  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. Check and follow existing Tailwind conventions in the project before introducing new patterns.
• Offer to extract repeated patterns into components that match the project's conventions (e.g., Blade, JSX, Vue).
• 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, configuration is CSS-first using the `@theme` directive — no separate `tailwind.config.js` file is needed:

<!-- CSS-First Config -->

@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:

<!-- v4 Import Syntax -->

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

Replaced Utilities

Tailwind v4 removed deprecated utilities. Use the replacements shown below. Opacity values remain numeric.

| Deprecated | Replacement | |------------|-------------| | bg-opacity-* | bg-black/* | | text-opacity-* | text-black/* | | border-opacity-* | border-black/* | | divide-opacity-* | divide-black/* | | ring-opacity-* | ring-black/* | | placeholder-opacity-* | placeholder-black/* | | 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:

<!-- Gap Utilities -->

<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:

<!-- Dark Mode -->

<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 (bg-opacity-*, flex-shrink-*, etc.)
• Using `@tailwind` directives instead of `@import "tailwindcss"`
• Trying to use `tailwind.config.js` instead of 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