home / skills / tapforce / agents-skills / tapforce-tailwindcss

tapforce-tailwindcss skill

safe

/skills/tapforce-tailwindcss

This skill provides best practices for setting up and developing UX/UI with Tailwind CSS ^4 across projects.

npx playbooks add skill tapforce/agents-skills --skill tapforce-tailwindcss

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

Files (17)

SKILL.md

5.1 KB

---
name: tapforce-tailwindcss
description: Best practices for setting up and developing UX/UI for projects using Tailwind CSS ^4. Use when setting up new projects with Tailwind CSS support or when projects have Tailwind CSS installed.
license: ISC
metadata:
  author: tapforce
  version: "1.0"
compatibility: Requires Node.js ^20.0.0, Tailwind CSS ^4.0.0, pnpm ^10.0.0
allowed-tools: Bash Read Write
---

# Tapforce Tailwind CSS Skill

This skill provides best practices for setting up and developing UX/UI for projects using Tailwind CSS ^4.

## When to Use

Use this skill when:
- Setting up a new project that needs Tailwind CSS support
- Working with projects that have Tailwind CSS installed
- Configuring Tailwind CSS ^4 for different project types
- Implementing UI components with Tailwind CSS utilities

## Requirements

- Project uses Tailwind CSS ^4 or needs to start with Tailwind CSS
- Project must be supported by Tailwind CSS (see installation guides)
- Node.js ^20.0.0 environment
- Prefer pnpm ^10.0.0 as package manager

## Project Validation

### Check Existing Installation

If the project already has Tailwind CSS installed:

1. **Check version**: Verify Tailwind CSS version is ^4.0.0
2. **Compatibility**: Ensure project type supports Tailwind CSS ^4
3. **Configuration**: Check for proper Tailwind CSS setup

If version doesn't match ^4.0.0, refuse to continue and recommend upgrade.

### Project Type Support

Verify project type compatibility from official documentation:
- Vite: https://tailwindcss.com/docs/installation/using-vite
- PostCSS: https://tailwindcss.com/docs/installation/using-postcss
- Tailwind CLI: https://tailwindcss.com/docs/installation/tailwind-cli
- Framework guides: https://tailwindcss.com/docs/installation/framework-guides
- Play CDN: https://tailwindcss.com/docs/installation/play-cdn

## Installation Setup

### Preferred Project Setup

For best practices, projects should:
- Use Node.js as base
- Use pnpm as package manager
- Use popular JS frameworks (SvelteKit, Next.js, Nuxt.js, etc.)
- Default to SvelteKit if framework not decided

### Installation by Project Type

See [installation guide](references/installation.md) for detailed setup instructions based on project type.

## Tailwind CSS ^4 Compatibility

Tailwind CSS ^4 has breaking changes compared to ^3. See [compatibility guide](references/compatibility.md) for detailed information.

## Core Concepts

### Styling with Utility Classes

Use utility classes for styling instead of custom CSS. See [styling guide](references/styling.md) for comprehensive examples.

### Hover, Focus, and Other States

Implement interactive states using Tailwind's state variants. See [states guide](references/states.md) for patterns and examples.

### Responsive Design

Create responsive layouts using Tailwind's breakpoint system. See [responsive guide](references/responsive.md) for implementation patterns.

### Dark Mode

Implement dark mode support using Tailwind's dark mode utilities. See [dark mode guide](references/dark-mode.md) for setup strategies.

### Theme and Colors

Customize themes and work with colors effectively. See [theme guide](references/theme.md) for customization patterns.

### Adding Custom Styles

Add custom CSS when utilities aren't sufficient. See [custom styles guide](references/custom-styles.md) for best practices.

### Detecting Classes in Source Files

Understand how Tailwind detects classes in your source files. See [detection guide](references/detection.md) for configuration.

### Functions and Directives

Use Tailwind's CSS functions and directives. See [functions guide](references/functions.md) for advanced usage.

## Rules

This skill includes the following rules:

### Utility-First Approach
- **Rule**: [utility-first](rules/utility-first.md)
- **Description**: Rules for preferring Tailwind utilities over custom CSS

### Arbitrary Values
- **Rule**: [arbitrary-values](rules/arbitrary-values.md)
- **Description**: Rules for using arbitrary values when built-in utilities are insufficient

### CSS Organization
- **Rule**: [css-organization](rules/css-organization.md)
- **Description**: Rules for organizing CSS files and custom styles

### Utility Directives
- **Rule**: [utility-directives](rules/utility-directives.md)
- **Description**: Rules for defining custom utilities with @utility directive

### Color Consistency
- **Rule**: [color-consistency](rules/color-consistency.md)
- **Description**: Rules for maintaining consistent color value formats

### Version Validation
- **Rule**: [version-validation](rules/version-validation.md)
- **Description**: Rules for validating Tailwind CSS ^4 installation and compatibility

## Best Practices

- Always prefer Tailwind ^4 utility classes over custom CSS
- Use arbitrary values for custom styling when built-in classes are insufficient
- Centralize custom CSS variables in the root CSS file
- Use @utility directive for shared custom styles
- Maintain consistent color value formats (hsl() by default, oklch() for shadcn-svelte)
- Reference official documentation for framework-specific setup
- Test responsive designs across all breakpoints
- Implement proper dark mode support
- Use semantic HTML with Tailwind utilities for accessibility

Overview

This skill provides practical best practices and setup guidance for projects using Tailwind CSS ^4. It focuses on validating installations, configuring modern workflows (Node.js + pnpm), and applying utility-first UI patterns for reliable, maintainable UX/UI. Use it to standardize Tailwind ^4 on new projects or to audit and improve existing setups.

How this skill works

The skill inspects project configuration to verify Tailwind CSS ^4 is installed and compatible with the project type. It checks Node.js and package manager expectations, validates Tailwind config and detection paths, and recommends configuration changes for responsive design, dark mode, theming, and custom utilities. When installed, it provides concrete rules and patterns to guide component development and CSS organization.

When to use it

Starting a new project that needs Tailwind CSS ^4 support
Auditing or upgrading a project that already uses Tailwind CSS
Configuring Tailwind for Vite, PostCSS, Tailwind CLI, or framework integrations (Next, SvelteKit, Nuxt)
Implementing or refactoring UI components to follow utility-first patterns
Ensuring consistent theming, dark mode, and responsive behavior across a codebase

Best practices

Prefer Tailwind ^4 utility classes instead of creating new custom CSS unless necessary
Use arbitrary values for one-off needs and centralize repeated styles with @utility directives
Keep custom CSS and variables centralized in a root stylesheet to simplify overrides and theming
Use hsl() color formats by default; adopt oklch() for specific libraries that document it (e.g., shadcn-svelte)
Verify Tailwind detection paths include all source files and templates to avoid missing classes in builds
Test layouts across breakpoints and implement dark mode variants explicitly

Example use cases

Set up a new SvelteKit app with pnpm, Tailwind ^4, and a centralized theme file
Audit an existing Next.js site to confirm Tailwind ^4 compatibility and update detection paths
Create a component library using utility-first classes and @utility for shared patterns
Add robust dark mode support using Tailwind dark utilities and theme tokens
Migrate custom CSS into Tailwind utilities and arbitrary values to reduce stylesheet complexity

FAQ

What if my project uses Tailwind ^3?

This skill targets Tailwind ^4. If your project is on ^3, follow the official upgrade guide and migrate to ^4 before applying these rules.

Which package manager is required?

pnpm ^10 is preferred for consistency and performance, but npm or yarn can be used if pnpm cannot be adopted.