Tailwind CSS

---

name: Tailwind CSS description: Write Tailwind utility classes with proper responsive design, dark mode, and configuration. metadata: {"clawdbot":{"emoji":"🌊","requires":{"bins":["npx"]},"os":["linux","darwin","win32"]}}

---

Content Configuration

content array in tailwind.config.js must include ALL files with classes—missing paths = missing styles in production

Glob patterns: "./src/**/*.{js,jsx,ts,tsx,html}" covers nested directories

Dynamic class names like bg-${color}-500 won't be detected—use complete class names or safelist

Check production build size—if unexpectedly small, content paths are wrong

Responsive Prefixes

Mobile-first: unprefixed styles apply to all sizes, md: applies at medium AND above

sm:hidden md:block means hidden on small, visible on medium+—not "only on medium"

Breakpoints: sm(640px), md(768px), lg(1024px), xl(1280px), 2xl(1536px)

Custom breakpoints in config override defaults—use extend.screens to add without replacing

Dark Mode

dark: prefix requires darkMode: 'class' in config—won't work with default media strategy if you need manual toggle

Dark class on or , not on individual components

dark:bg-gray-900 only applies when ancestor has class="dark"

System preference: darkMode: 'media' uses prefers-color-scheme

State Variants

hover:, focus:, active: work as expected

group-hover: requires group class on parent—child reacts to parent hover

peer-focus: requires peer class on sibling AND sibling must come first in DOM

Stack variants: dark:hover:bg-gray-700 applies on hover in dark mode

Arbitrary Values

bg-[#1da1f2] for one-off colors—brackets for any arbitrary value

w-[calc(100%-2rem)] for calc expressions

grid-cols-[1fr_2fr_1fr] underscores for spaces in values

Arbitrary properties: [mask-type:alpha] for unsupported CSS properties

@apply Traps

@apply in component CSS loses responsive/state variants—@apply hover:bg-blue-500 doesn't work as expected

Order in @apply matters unlike HTML classes—later utilities override earlier

Prefer HTML classes over @apply—easier to maintain, better tree-shaking

If you must use @apply, keep it simple: base styles only

Configuration

extend adds to defaults: extend: { colors: { brand: '#xxx' } } keeps all existing colors

Top-level replaces defaults: colors: { brand: '#xxx' } removes all default colors

theme() function in CSS: border-color: theme('colors.gray.200')

Plugin order matters—later plugins can override earlier ones

Important Modifier

! prefix forces important: !mt-4 generates margin-top: 1rem !important

Use sparingly—usually indicates specificity battle that should be fixed

important: true in config makes ALL utilities important—avoid, breaks third-party CSS

important: '#app' scopes specificity to selector—better than global important

Common Mistakes

class="px-4 px-6" last one wins in stylesheet, not in HTML—both get applied, cascade decides

Forgetting overflow-hidden with rounded-* on parent with absolute children

h-screen doesn't account for mobile browser chrome—use h-dvh (dynamic viewport height)

truncate needs width constraint or max-w-* to actually truncate

Performance

JIT is default since v3—generates only used classes, no purge needed

Avoid safelist with patterns like bg-*—defeats tree-shaking

@layer components for reusable component styles—proper cascade order

Large arbitrary values generate unique classes—extract to config if repeated

extend adds to defaults: extend: { colors: { brand: '#xxx' } } keeps all existing colors

Top-level replaces defaults: colors: { brand: '#xxx' } removes all default colors

theme() function in CSS: border-color: theme('colors.gray.200')

Plugin order matters—later plugins can override earlier ones