home / skills / busirocket / agents-skills / busirocket-tailwindcss-v4

busirocket-tailwindcss-v4 skill

safe

This skill guides Tailwind CSS v4 setup and styling decisions to prevent drift, maximize utilities, and keep global tokens consistent.

npx playbooks add skill busirocket/agents-skills --skill busirocket-tailwindcss-v4

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

1.9 KB

---
name: busirocket-tailwindcss-v4
description:
  Tailwind CSS v4 setup and styling strategy. Use when configuring Tailwind v4,
  writing component styles, deciding between utility classes and custom CSS, and
  avoiding style drift.
metadata:
  author: cristiandeluxe
  version: "1.0.0"
---

# Tailwind CSS v4 Best Practices

Setup and styling patterns for Tailwind CSS v4 projects.

## When to Use

Use this skill when:

- Setting up Tailwind CSS v4 in a project
- Writing component styles with Tailwind utilities
- Deciding when to extract custom CSS vs using utilities
- Avoiding style drift and maintaining consistency

## Non-Negotiables (MUST)

- Import Tailwind via a single global CSS entry: `@import 'tailwindcss';`
- Keep that global CSS imported from the root layout.
- Prefer Tailwind utilities in `className` for most styling.
- Avoid large custom CSS files; keep custom CSS truly global (resets, tokens).
- Avoid heavy use of arbitrary values unless necessary; prefer consistent
  tokens.

## Class Strategy

- If class strings become hard to read:
  - Extract a small presentational component.
  - Or extract a `components/<area>/...` wrapper rather than inventing large
    custom CSS.

## Rules

### Setup

- `tailwind-setup` - Tailwind CSS v4 setup (single global CSS import)

### Class Strategy

- `tailwind-class-strategy` - Prefer utilities, extract components when needed
- `tailwind-avoid-drift` - Avoid style drift (keep custom CSS global, prefer
  tokens)

### Ordering

- `tailwind-css-ordering` - CSS order depends on import order

## Related Skills

- `busirocket-react` - Component extraction patterns

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/tailwind-setup.md
rules/tailwind-class-strategy.md
rules/tailwind-avoid-drift.md
```

Each rule file contains:

- Brief explanation of why it matters
- Code examples (correct and incorrect patterns)
- Additional context and best practices

Overview

This skill provides a practical Tailwind CSS v4 setup and styling strategy for TypeScript/React/Next.js/Rust/Tauri projects. It focuses on a single global import, sensible use of utility classes, and rules to prevent style drift while keeping styles maintainable. Use it to standardize how teams structure Tailwind usage and when to extract component styles.

How this skill works

The skill inspects project conventions and offers clear rules: import Tailwind once from a global CSS entry, prefer utility classes in className, and limit custom CSS to truly global needs (resets, tokens). When utility class strings grow unreadable, the guidance suggests extracting small presentational components or wrapper components rather than creating large ad-hoc CSS files. It also emphasizes CSS ordering based on import order and discourages heavy use of arbitrary values.

When to use it

Setting up Tailwind CSS v4 for a new or existing project
Writing component styles and choosing between utilities or custom CSS
Refactoring messy or inconsistent styling across a codebase
Defining team conventions to avoid style drift and duplicated rules
Deciding where to place global tokens, resets, and component wrappers

Best practices

Import Tailwind via a single global CSS entry and load it from the root layout
Prefer utility classes inside className for most styling to keep components explicit
Keep custom CSS minimal and truly global: tokens, resets, and theme-level rules only
Avoid large custom CSS files; extract small presentational components or wrappers instead
Use design tokens rather than arbitrary values to maintain consistent spacing and colors
Rely on import order for predictable CSS ordering; document any overrides clearly

Example use cases

Bootstrapping Tailwind v4 in a Next.js app with a single global CSS import
Refactoring a component with long className strings into a small presentational subcomponent
Establishing team rules to store tokens and resets in global CSS and prevent per-component drift
Choosing between adding an arbitrary value and creating a shared token for repeated spacing
Creating a components/<area>/ wrapper to contain layout rules without inventing a new global stylesheet

FAQ

Why a single global import?

A single import guarantees consistent processing order and avoids duplicate or conflicting Tailwind builds across the app.

When should I write custom CSS instead of utilities?

Use custom CSS only for truly global concerns (resets, tokens, theme) or when utilities cannot express a required behavior clearly. Prefer extracting components for presentational complexity.