name: tailwind-css description: Use when working with Tailwind CSS configuration, custom classes, theme customization, or CSS architecture. Guides proper use of @theme, @layer, @apply, and component class extraction. allowed-tools: Read, Edit, Write, Grep, Glob, Bash

Tailwind CSS Architecture Skill

You are working on a project using Tailwind CSS v4.1.17. This skill guides you when working with Tailwind configuration, custom classes, and CSS architecture.

Project CSS Architecture

Configuration Files

1. •tailwind.config.ts: v3-style config (content paths, theme extensions)
2. •src/app/globals.css: v4-style CSS config (preferred)

Current Setup

The project uses both old and new config styles:

• •✅ v4 @theme directive for CSS variables
• •✅ v4 @plugin for loading plugins
• •✅ @apply for component classes
• •⚠️ Still has tailwind.config.ts (can be migrated to CSS)

Core Principles

1. Read Config Files First

Before any Tailwind work:

Read tailwind.config.ts
Read src/app/globals.css

2. Prefer v4 CSS-First Approach

When adding new theme values, prefer @theme in CSS over JS config:

Preferred (v4):

/* globals.css */
@theme {
  --color-accent: #f9a825;
  --spacing-section: 4rem;
}

Acceptable (v3):

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: { accent: '#f9a825' },
      spacing: { section: '4rem' },
    },
  },
};

3. Extract Repeated Patterns

When you see the same utility combinations 3+ times, extract to a component class:

Before:

<button className="inline-flex items-center rounded-md bg-indigo-600 px-3 py-2 text-sm font-semibold text-white hover:bg-indigo-500">
  Click
</button>

After:

/* globals.css */
@layer components {
  .btn-primary {
    @apply inline-flex items-center rounded-md bg-indigo-600 px-3 py-2 text-sm font-semibold text-white hover:bg-indigo-500;
  }
}

<button className="btn-primary">Click</button>

4. Use Appropriate @layer

@layer base {
  /* Reset styles, base element styles */
  body { @apply antialiased; }
}

@layer components {
  /* Reusable component classes */
  .btn { }
  .card { }
}

@layer utilities {
  /* Custom utility classes */
  .text-balance { text-wrap: balance; }
}

Current Component Classes

The project already has these in globals.css:

Layout:

• •.container-max: Max-width container with padding

Cards:

• •.card: Card wrapper
• •.card__body: Card content area

Buttons:

• •.btn: Base button
• •.btn--primary: Primary button
• •.btn--ghost: Ghost button

Navigation:

• •.navbar: Navigation wrapper
• •.navbar__inner: Navigation container
• •.nav-link: Desktop nav link
• •.nav-mobile-link: Mobile nav link

Tables:

• •.table, .th, .td, .tbody: Table components

Check these before creating new similar patterns!

Tailwind v4 Directives

@theme - Custom Design Tokens

@theme {
  --color-brand: #0d47a1;
  --spacing-card: 1.5rem;
  --font-heading: "Georgia", serif;
  --radius-button: 0.375rem;
}

/* Use as: bg-brand, p-card, font-heading, rounded-button */

@layer - Organize CSS

@layer components {
  .my-component {
    @apply /* utilities here */;
  }
}

@apply - Extract Utilities

.button {
  @apply px-4 py-2 rounded-md font-medium;
}

Warning: Don't overuse @apply. Consider:

• •Is this pattern repeated 3+ times? → Extract
• •Is it used once? → Keep inline utilities
• •Is it a simple wrapper? → Might not need extraction

@plugin - Load Plugins

@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/typography";

When to Extract Component Classes

Extract when:

• •Pattern appears 3+ times
• •Complex utility combination (10+ classes)
• •Semantic meaning (e.g., "card", "button", not "blue-box")
• •Need to maintain consistency

Keep inline when:

• •Used only once or twice
• •Simple (2-3 utilities)
• •Layout-specific (unique to one component)
• •Needs to be dynamic/conditional

Common Tasks

Task: Add Custom Color

/* globals.css */
@theme {
  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-danger: #ef4444;
}

/* Use as: bg-success, text-warning, border-danger */

Task: Add Custom Spacing

@theme {
  --spacing-section: 6rem;
}

/* Use as: py-section, mt-section */

Task: Create Component Class

@layer components {
  .alert {
    @apply rounded-lg border p-4;
  }

  .alert--success {
    @apply border-green-500 bg-green-50 text-green-800;
  }

  .alert--danger {
    @apply border-red-500 bg-red-50 text-red-800;
  }
}

Task: Add Custom Utility

@layer utilities {
  .text-balance {
    text-wrap: balance;
  }

  .scrollbar-hide {
    scrollbar-width: none;
  }
  .scrollbar-hide::-webkit-scrollbar {
    display: none;
  }
}

Naming Conventions

BEM for components:

.card { }           /* Block */
.card__header { }   /* Element */
.card--featured { } /* Modifier */

Utility-style for simple variants:

.btn { }
.btn-primary { }
.btn-secondary { }
.btn-lg { }

Semantic names (what it is, not how it looks):

• •✅ .hero-section, .product-card, .cta-button
• •❌ .blue-box, .big-text, .rounded-div

Testing Changes

After making Tailwind changes:

1. •Build check:

pnpm build

1. •

   Look for:

   • •No CSS errors
   • •Classes are being generated
   • •No purged classes still in use
2. •

   Visual check:

   • •Components look correct
   • •Responsive behavior works
   • •Hover/focus states work

When to Delegate

For complex CSS architecture work, delegate to the tailwind-css-expert subagent:

• •Systematic refactoring (removing dark mode, etc.)
• •Adding new breakpoints project-wide
• •Migrating v3 config to v4 @theme
• •Extracting component patterns from entire codebase
• •Major CSS reorganization

For simple tasks, use this skill (do it yourself):

• •Adding single custom color/spacing
• •Creating one component class
• •Adding a custom utility
• •Small theme adjustments

Quality Checklist

Before completing Tailwind CSS work:

• • Read both config files first
• • Used v4 @theme for new theme values (preferred)
• • Component classes in appropriate @layer
• • Naming is semantic and clear
• • Not overusing @apply
• • Build succeeds
• • Visually tested changes
• • Updated documentation (if significant)

Important Reminders

1. •v4 preferred - Use @theme over JS config when possible
2. •Check existing patterns - Review globals.css before creating new classes
3. •Extract thoughtfully - 3+ uses, complex patterns, semantic meaning
4. •Layer correctly - base/components/utilities
5. •Name semantically - What it is, not how it looks
6. •Don't overuse @apply - Balance with regular CSS
7. •Test builds - Ensure no errors
8. •Document significant changes - Help future developers

Resources

• •Config: tailwind.config.ts (v3-style)
• •CSS Config: src/app/globals.css (v4-style, preferred)
• •Component classes: See globals.css @layer components
• •Tailwind v4 docs: Focus on new CSS-first features