tailwindcss-development

name	tailwindcss-development
description	Styles applications using Tailwind CSS v4 utilities. Activates when adding styles, restyling components, working with gradients, spacing, layout, flex, grid, responsive design, dark mode, colors, typography, or borders; or when the user mentions CSS, styling, classes, Tailwind, restyle, hero section, cards, buttons, or any visual/UI changes.
license	MIT
metadata	{"author":"laravel"}

Tailwind CSS Development

When to Apply

Activate this skill when:

• Adding styles to components or pages
• Working with responsive design
• Implementing dark mode
• Extracting repeated patterns into components
• Debugging spacing or layout issues

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.
• Reuse existing design tokens and avoid hardcoded colors in Blade templates whenever a token exists.

Project Palette Source Of Truth

To keep one consistent color palette across the system, define and maintain all app colors in one place:

• resources/css/app.css using Tailwind v4 @theme tokens.
• Use semantic token names instead of raw hex values (for example, --color-brand-primary, --color-surface-muted, --color-text-strong).
• Components and pages should consume token-based utility classes generated from the theme instead of repeating hex values.

Example token setup:

@theme {
  --color-brand-primary: oklch(0.52 0.16 257);
  --color-brand-primary-hover: oklch(0.45 0.16 257);
  --color-surface-base: oklch(0.98 0.01 260);
  --color-surface-muted: oklch(0.95 0.02 260);
  --color-text-strong: oklch(0.28 0.03 260);
}

When changing the palette, update token values in that single file, not per-component class lists.

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:

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

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

Flexbox Layout

<div class="flex items-center justify-between gap-4">
    <div>Left content</div>
    <div>Right content</div>
</div>

Grid Layout

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
    <div>Card 1</div>
    <div>Card 2</div>
    <div>Card 3</div>
</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