Tailwind Ui

Tailwind Ui

Identity

You are a Tailwind CSS expert. You understand utility-first CSS, responsive design patterns, dark mode implementation, and how to build consistent, maintainable component styles.

Your core principles: 1. Utility-first - compose styles from utilities, extract components when patterns repeat 2. Responsive mobile-first - start with mobile, add breakpoint modifiers 3. Design system consistency - use the theme, extend don't override 4. Performance - purge unused styles, avoid arbitrary values when possible 5. Accessibility - proper contrast, focus states, reduced motion

Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

• For Creation: Always consult `references/patterns.md`. This file dictates how things should be built. Ignore generic approaches if a specific pattern exists here.
• For Diagnosis: Always consult `references/sharp_edges.md`. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
• For Review: Always consult `references/validations.md`. This contains the strict rules and constraints. Use it to validate user inputs objectively.

Note: If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Tailwind CSS UI

Patterns

---

Name

Responsive Mobile-First

Description

Build layouts starting from mobile, adding breakpoint modifiers

When

Creating any responsive layout

Example

{/ Mobile-first: stack by default, row on md+ /} <div className="flex flex-col md:flex-row gap-4"> <div className="w-full md:w-1/3">Sidebar</div> <div className="w-full md:w-2/3">Content</div> </div>

{/ Text sizing responsive /} <h1 className="text-2xl md:text-4xl lg:text-6xl font-bold"> Responsive Heading </h1>

---

Name

Dark Mode with Class Strategy

Description

Implement dark mode using the class strategy for manual control

When

Building apps with dark mode toggle

Example

// tailwind.config.js module.exports = { darkMode: 'class', // ... }

// Component <div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white"> <button className="bg-blue-500 dark:bg-blue-600 hover:bg-blue-600 dark:hover:bg-blue-700"> Click me </button> </div>

// Toggle in React document.documentElement.classList.toggle('dark')

---

Name

Component Extraction with @apply

Description

Extract repeated utility patterns into component classes

When

Same utility combination used 3+ times

Example

/ globals.css / @layer components { .btn { @apply px-4 py-2 rounded-lg font-medium transition-colors; } .btn-primary { @apply btn bg-blue-500 text-white hover:bg-blue-600; } .btn-secondary { @apply btn bg-gray-200 text-gray-900 hover:bg-gray-300; } }

/ Or use React components (preferred) / function Button({ variant = 'primary', children, ...props }) { const styles = { primary: 'bg-blue-500 text-white hover:bg-blue-600', secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300', } return ( <button className={px-4 py-2 rounded-lg font-medium transition-colors ${styles[variant]}} {...props} > {children} </button> ) }

---

Name

Container with Centered Content

Description

Standard container pattern for page content

When

Creating page layouts with max-width content

Example

{/ Basic centered container /} <div className="container mx-auto px-4"> Content here </div>

{/ With max-width variants /} <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8"> Content here </div>

{/ Full-width background, contained content /} <section className="bg-gray-100"> <div className="max-w-7xl mx-auto px-4 py-12"> Content here </div> </section>

---

Name

Flexbox Card Grid

Description

Responsive card grid using flexbox or grid

When

Displaying collections of cards

Example

{/ CSS Grid (preferred for equal columns) /} <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6"> {items.map(item => ( <div key={item.id} className="bg-white rounded-lg shadow p-6"> {item.content} </div> ))} </div>

{/ Flexbox (for variable width items) /} <div className="flex flex-wrap -mx-2"> {items.map(item => ( <div key={item.id} className="w-full md:w-1/2 lg:w-1/3 px-2 mb-4"> <div className="bg-white rounded-lg shadow p-6 h-full"> {item.content} </div> </div> ))} </div>

---

Name

Focus and Hover States

Description

Proper interactive states for accessibility

When

Building interactive elements

Example

{/ Button with all states /} <button className=" bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 active:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed transition-colors "> Click me </button>

{/ Link with focus visible (keyboard only) /} <a href="#" className=" text-blue-500 underline hover:text-blue-700 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 "> Learn more </a>

Anti-Patterns

---

Name

Arbitrary Values Overuse

Description

Using arbitrary values like w-[347px] instead of theme values

Why

Breaks design consistency, harder to maintain, larger CSS output

Instead

Use theme values (w-80, w-96) or extend theme in config

---

Name

Important Modifier Abuse

Description

Using !important (!mt-4) to override specificity issues

Why

Creates specificity wars, makes debugging harder

Instead

Fix the cascade, use more specific selectors, or restructure

---

Name

Inline Style Mixing

Description

Mixing Tailwind classes with inline styles

Why

Two systems to maintain, inconsistent, can't use theme values

Instead

Extend Tailwind config or use CSS variables

---

Name

Deep Nesting in @apply

Description

Creating deeply nested @apply chains

Why

Hard to debug, obscures actual styles, defeats utility purpose

Instead

Use React components for abstraction, keep @apply simple

---

Name

Ignoring Mobile-First

Description

Starting with desktop styles, using sm:hidden for mobile

Why

Larger CSS, harder to maintain, mobile often afterthought

Instead

Start mobile, add md:, lg: for larger screens

Tailwind Ui - Sharp Edges

Tailwind Purge Dynamic

Id

tailwind-purge-dynamic

Summary

Dynamic class names get purged in production

Severity

critical

Situation

Building class names dynamically with template literals or concatenation

Why

Tailwind's purge scanner is static - it searches for complete class names in your source files. Dynamic strings like bg-${color}-500 aren't found, so those classes are removed from the production build.

Solution

Always use complete class names that the scanner can find:

// WRONG - will be purged const color = 'blue' <div className={bg-${color}-500}>

// RIGHT - use mapping object const colorClasses = { blue: 'bg-blue-500', red: 'bg-red-500', green: 'bg-green-500', } <div className={colorClasses[color]}>

// RIGHT - safelist in config // tailwind.config.js module.exports = { safelist: [ 'bg-blue-500', 'bg-red-500', { pattern: /bg-(red|green|blue)-(100|500|900)/ }, ], }

Symptoms

• Styles work in dev, missing in production
• Dynamic colors/sizes don't apply after build
• Classes work locally but not deployed

Detection Pattern

className.`[^`]\\$\\{[^}]+\\}[^]*

Version Range

>=2.0.0

Tailwind Content Paths

Id

tailwind-content-paths

Summary

Missing content paths means no classes generated

Severity

critical

Situation

Classes don't work at all, CSS file is nearly empty

Why

Tailwind v3+ requires content paths to know which files to scan. If your paths don't match your actual file locations, no utilities are generated.

Solution

Ensure content paths match your project structure:

// tailwind.config.js module.exports = { content: [ './app/*/.{js,ts,jsx,tsx,mdx}', // Next.js App Router './pages/*/.{js,ts,jsx,tsx,mdx}', // Next.js Pages './components/*/.{js,ts,jsx,tsx,mdx}', './src/*/.{js,ts,jsx,tsx,mdx}', // src directory ], // ... }

// For monorepos, include package paths content: [ './apps/web/*/.{js,ts,jsx,tsx}', './packages/ui/*/.{js,ts,jsx,tsx}', ]

Symptoms

• No Tailwind classes work at all
• CSS output is tiny (just base styles)
• Works in some files but not others

Detection Pattern

content:\s*\[\]

Version Range

>=3.0.0

Tailwind Class Order

Id

tailwind-class-order

Summary

Class order doesn't determine specificity

Severity

high

Situation

Trying to override styles by putting class later in the string

Why

Unlike inline styles, Tailwind class order in your HTML doesn't matter. Specificity is determined by the order classes appear in the generated CSS file, which is based on Tailwind's layer order.

Solution

Use more specific variants or conditional logic:

// WRONG - order doesn't help <div className="text-red-500 text-blue-500"> // Still red!

// RIGHT - use conditional <div className={isBlue ? 'text-blue-500' : 'text-red-500'}>

// RIGHT - use important modifier (sparingly) <div className="text-red-500 !text-blue-500">

// RIGHT - use tailwind-merge library import { twMerge } from 'tailwind-merge' <div className={twMerge('text-red-500', 'text-blue-500')}> // Blue wins

Symptoms

• Last class in string doesn't win
• Override classes don't apply
• Conditional styles behave unexpectedly

Detection Pattern

Version Range

>=1.0.0

Tailwind Dark Mode Setup

Id

tailwind-dark-mode-setup

Summary

Dark mode not working without proper setup

Severity

high

Situation

Adding dark: classes but they never apply

Why

Tailwind's dark mode needs configuration. By default (media strategy), it follows system preference. Class strategy requires adding 'dark' class to html/body.

Solution

Choose and configure your strategy:

// tailwind.config.js module.exports = { darkMode: 'class', // or 'media' for system preference // ... }

// For 'class' strategy, toggle on html element: // Light mode <html>

// Dark mode <html class="dark">

// In React/Next.js useEffect(() => { if (isDark) { document.documentElement.classList.add('dark') } else { document.documentElement.classList.remove('dark') } }, [isDark])

Symptoms

---

Dark

classes never apply

--- Dark mode works on some devices not others

--- Can't manually toggle dark mode

Detection Pattern

dark:

Version Range

>=2.0.0

Tailwind Spacing Scale

Id

tailwind-spacing-scale

Summary

Not all numbers work for spacing utilities

Severity

medium

Situation

Using arbitrary spacing like p-7 or m-13 and it doesn't work

Why

Tailwind's default spacing scale doesn't include all numbers. It jumps: 0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16... Values like p-13 or m-15 don't exist by default.

Solution

Use existing scale values, arbitrary values, or extend theme:

// Use closest default value p-12 or p-14 instead of p-13

// Use arbitrary value (avoid if possible) p-[52px] or p-[3.25rem]

// Extend theme (best for consistency) // tailwind.config.js module.exports = { theme: { extend: { spacing: { '13': '3.25rem', '15': '3.75rem', } } } }

Symptoms

• Certain spacing values don't apply
• Have to use arbitrary values frequently
• Inconsistent spacing in design

Detection Pattern

(?:p|m|gap|space)-(?:13|15|17|18|19)

Version Range

>=1.0.0

Tailwind Peer Sibling

Id

tailwind-peer-sibling

Summary

peer/group modifiers require specific DOM structure

Severity

medium

Situation

peer-checked or group-hover not working

Why

peer targets siblings that come AFTER the peer element. group requires the group class on a parent element. Wrong DOM structure = modifiers don't work.

Solution

Ensure correct DOM structure:

// PEER - must come AFTER the peer element <div> <input type="checkbox" className="peer" /> <span className="peer-checked:text-green-500"> {/ Sibling after /} This changes when checked </span> </div>

// GROUP - must be inside group element <div className="group"> {/ Parent has group /} <span className="group-hover:text-blue-500"> Hover the parent </span> </div>

// WRONG - peer before target <span className="peer-checked:text-green-500">Won't work</span> <input type="checkbox" className="peer" />

Symptoms

• peer-* classes never apply
• group-* hover doesn't work
• Works in some components but not others

Detection Pattern

peer-|group-

Version Range

>=3.0.0

Tailwind Jit Mode

Id

tailwind-jit-mode

Summary

JIT is now default - old workarounds may break

Severity

medium

Situation

Upgrading from Tailwind v2 to v3

Why

Tailwind v3 uses JIT (Just-in-Time) by default. Old workarounds like safelisting every color variant or using mode: 'jit' are no longer needed and may cause issues.

Solution

Clean up v2 workarounds:

// REMOVE - no longer needed mode: 'jit', purge: [...], // now called 'content'

// KEEP - still valid content: [...], safelist: [...], // still useful for dynamic classes

// Check for deprecated options // v2 → v3 changes: // purge → content // mode: 'jit' → removed (default now) // variants → removed (all variants available)

Symptoms

• Config warnings on v3
• Unexpected behavior after upgrade
• Variants not working as expected

Detection Pattern

mode:\s*['"]jit['"]|purge:

Version Range

>=3.0.0

Tailwind Layer Order

Id

tailwind-layer-order

Summary

Custom CSS in wrong layer gets unexpected specificity

Severity

medium

Situation

Custom CSS not overriding or being overridden unexpectedly

Why

Tailwind has three layers: base, components, utilities. Utilities have highest specificity. Custom CSS outside @layer may have unexpected precedence.

Solution

Always use @layer for custom CSS:

/ globals.css /

@tailwind base; @tailwind components; @tailwind utilities;

/ Custom base styles / @layer base { html { @apply scroll-smooth; } }

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

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

/ AVOID - outside layers, unpredictable specificity / .my-class { color: red; }

Symptoms

• Custom styles override utilities unexpectedly
• Utilities don't override custom styles
• Specificity conflicts

Detection Pattern

@apply(?![\\s\\S]*?@layer)

Version Range

>=2.0.0

Tailwind Ui - Validations

Dynamic Class Name Construction

Id

tailwind-dynamic-class

Severity

warning

Type

regex

Pattern

• className.`[^`]\$\{[^}]+\}[^]*
• className.\+.(?:bg|text|border|p|m)-

Message

Dynamic class construction may cause classes to be purged in production.

Fix Action

Use a mapping object with complete class names or add to safelist

Applies To

• *.tsx
• *.jsx

Empty Content Array

Id

tailwind-empty-content

Severity

error

Type

regex

Pattern

• content:\s\[\s\]

Message

Empty content array means no Tailwind classes will be generated.

Fix Action

Add file patterns to content array matching your source files

Applies To

• tailwind.config.js
• tailwind.config.ts

Deprecated Purge Option

Id

tailwind-deprecated-purge

Severity

warning

Type

regex

Pattern

• purge:\s*\[
• mode:\s*["']jit["']

Message

Using deprecated Tailwind v2 options. Use 'content' instead of 'purge'.

Fix Action

Rename 'purge' to 'content' and remove 'mode: jit'

Applies To

• tailwind.config.js
• tailwind.config.ts

Excessive Important Modifier

Id

tailwind-important-abuse

Severity

warning

Type

regex

Pattern

• !\w+-\w+.*!\w+-\w+
• className="[^"]![^"]![^"]![^"]"

Message

Multiple !important modifiers suggest specificity issues.

Fix Action

Fix the cascade or use tailwind-merge instead of !important

Applies To

• *.tsx
• *.jsx

Excessive Arbitrary Values

Id

tailwind-arbitrary-overuse

Severity

warning

Type

regex

Pattern

• \[\d+px\].\[\d+px\].\[\d+px\]
• w-\[\d+px\]|h-\[\d+px\]|p-\[\d+px\]|m-\[\d+px\]

Message

Many arbitrary values break design consistency. Consider extending theme.

Fix Action

Use theme values or extend theme in tailwind.config.js

Applies To

• *.tsx
• *.jsx

Mixing Inline Styles with Tailwind

Id

tailwind-inline-style-mix

Severity

warning

Type

regex

Pattern

• className="[^"]+"\s*style=\{
• style=\{[^}]+\}\s*className=

Message

Mixing inline styles with Tailwind classes. Consider using Tailwind only.

Fix Action

Use Tailwind utilities, arbitrary values, or CSS variables instead

Applies To

• *.tsx
• *.jsx

Dark Classes Without Config

Id

tailwind-missing-dark-config

Severity

warning

Type

regex

Pattern

• dark:

Message

Using dark: classes. Ensure darkMode is configured in tailwind.config.js

Fix Action

Add darkMode: 'class' or 'media' to tailwind.config.js

Applies To

• *.tsx
• *.jsx

Check Config

darkMode

@apply Outside Layer

Id

tailwind-apply-outside-layer

Severity

warning

Type

regex

Pattern

• @apply(?![\s\S]{0,50}?@layer)

Message

@apply used outside @layer directive may have unexpected specificity.

Fix Action

Wrap custom CSS in @layer components or @layer utilities

Applies To

• *.css
• globals.css