Tailwindcss Core

---
name: tailwindcss-core
description: "Use when configuring Tailwind CSS-first (no config.js), defining @theme tokens, or creating custom utilities/variants. Do NOT use for v3-to-v4 migration or category utility lookup."
user-invocable: false
---

<objective>
Documents Tailwind CSS v4.3's CSS-first configuration directives: `@import "tailwindcss"`, `@theme` for defining theme tokens as CSS custom properties, `@source` for scanning additional source files, `@utility`/`@variant` for custom utilities and variants, `@apply` for composing utilities in custom CSS, and `@config` for loading a legacy JS config.

Also covers dark-mode variant setup, responsive breakpoints via `@theme`, CSS layer hierarchy (`theme, base, components, utilities`), and plugin integration — the full CSS-first replacement for `tailwind.config.js`.
</objective>

# Tailwind CSS Core v4.3

## Overview

Tailwind CSS v4 (since v4.0; current stable v4.3) uses a **CSS-first** approach that eliminates the need for a traditional `tailwind.config.js` file. All configuration is now done directly in your CSS files via specialized directives.

## Key Concepts

### 1. @import "tailwindcss"

Entry point to load Tailwind CSS. Place at the beginning of your main CSS file.

```css
@import "tailwindcss";
```

This directive automatically loads:
- Base utilities
- Responsive variants
- Layers (theme, base, components, utilities)

### 2. @theme

Directive to define or customize theme values via CSS custom properties.

```css
@theme {
  --color-primary: #3b82f6;
  --color-secondary: #ef4444;
  --spacing-custom: 2.5rem;
  --radius-lg: 1rem;
}
```

Variables are accessible in generated utilities:
- `--color-*` → classes `bg-primary`, `text-primary`, etc.
- `--spacing-*` → classes `p-custom`, `m-custom`, etc.
- `--radius-*` → classes `rounded-lg`, etc.

### 3. @source

Directive to include additional source files with glob patterns.

```css
@source "./routes/**/*.{ts,tsx}";
@source "./components/**/*.{tsx,jsx}";
@source "../packages/ui/src/**/*.{ts,tsx}";
```

Tailwind will scan these files to generate utilities used in your project.

### 4. @utility and @variant

Directives to create custom utilities and variants.

```css
@utility truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

/* Define a new variant with @custom-variant */
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

/* Apply an existing variant inside CSS with @variant
   (stacked `hover:focus` and compound `hover, focus` forms since v4.3) */
.card {
  @variant hover:focus {
    background: var(--color-sky-600);
  }
}
```

### 5. @apply

Directive to apply Tailwind classes in your custom CSS rules.

```css
.btn {
  @apply px-4 py-2 rounded-lg font-semibold;
}

.btn-primary {
  @apply bg-blue-500 text-white hover:bg-blue-600;
}
```

### 6. @config

Directive to load external configuration if needed.

```css
@config "./tailwind.config.js";
```

(Optional in v4, mainly used for backward compatibility)

## Dark Mode

Dark mode configuration in Tailwind v4.3:

```css
@import "tailwindcss";

/* Default: `dark:` follows prefers-color-scheme — no config needed */
```

Or via manual class (override the `dark` variant with `@custom-variant`):

```css
@custom-variant dark (&:where(.dark, .dark *));
```

## Responsive Breakpoints

Breakpoints are defined via `@theme`:

```css
@theme {
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --breakpoint-2xl: 1536px;
}
```

Responsive variants are used with utilities:

```html
<div class="text-sm md:text-base lg:text-lg"></div>
```

## Layer Hierarchy

```css
@layer theme, base, components, utilities;

@import "tailwindcss";

/* Your customizations */
@layer components {
  .btn { @apply px-4 py-2 rounded; }
}

@layer utilities {
  .text-shadow { text-shadow: 0 2px 4px rgba(0,0,0,0.1); }
}
```

## Plugin Integration

Load Tailwind plugins:

```css
@import "tailwindcss";
@plugin "flowbite/plugin";
@source "../node_modules/flowbite";
```

## Specificity Order

In CSS-first, import and declaration order determines specificity:

1. `@import "tailwindcss"` - Base utilities
2. `@theme { ... }` - Theme variables
3. `@layer components { ... }` - Custom components
4. `@layer utilities { ... }` - Custom utilities

## CSS-first Mode Benefits

- No complex JavaScript config file
- Type-safe via CSS variables
- Declarative and readable configuration
- Replaces CSS preprocessors (Tailwind v4 is not designed to be used with Sass/Less/Stylus)
- Simplified maintenance for large projects

## Detailed References

See specific files for:
- `theme.md` - Complete theme variable configuration
- `directives.md` - Syntax and examples of all directives
- `config.md` - Advanced configuration and use cases