Tailwind CSS

Writes and debugs Tailwind CSS: utility classes, theme config, dark mode, variants, plugins, and build setup. Not for CSS mechanics themselves — stacking contexts, flex sizing, and cascade behavior belong to the css skill. Use when a class produces no CSS, when dynamically built names (bg-${color}-500) never render, when styles work in dev but vanish after deploy, when your own CSS beats a utility or can't override one, when @apply breaks inside a Vue, Svelte, or CSS-module file, when hover:, group-hover:, peer-*, has-[…], or dark: won't fire, when upgrading v3 to v4 (@tailwind directives, tailwind.config.js → @theme, renamed utilities), when adding custom colors, spacing, breakpoints, fonts, or keyframes, when wiring Tailwind into Vite, Next.js, Astro, SvelteKit, Rails, or Laravel, when the CSS bundle is huge or rebuilds crawl, when Preflight flattens third-party widgets, or when choosing between @apply, a component, and tailwind-merge.

User preferences and memory live in ~/Clawic/data/tailwindcss/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/tailwindcss/ or ~/clawic/tailwindcss/), move it to ~/Clawic/data/tailwindcss/.

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/tailwindcss/config.yaml.

Variable	Type	Default	Effect
tailwind_version	3 | 4	4	Selects the config surface of every answer: 4 emits @import "tailwindcss", @theme, @source, @utility, suffix !; 3 emits tailwind.config.js, @tailwind directives, content, safelist, prefix !
build_integration	vite | postcss | cli | browser	vite	Which install steps and config files installation.md emits, and where the scan root sits
dark_mode_strategy	media | class | data-attribute	media	The variant definition emitted in CSS, and whether toggle code plus the paint-blocking script ships with it (dark-mode.md)
component_syntax	jsx | vue-sfc | svelte | astro | html	jsx	Markup language of every emitted example, and which @apply/@reference rules apply (frameworks.md)
merge_helper	cn | clsx | tailwind-merge | none	cn	Helper wrapped around conditional or overridable class props in emitted components (components.md)
rem_base	number px (10-16)	16	Every px↔rem conversion for utilities in Utility Scale Math (p-4 = 4 × 0.25rem = 1rem = rem_base px). Breakpoints are exempt — see that section
token_threshold	number (2-5)	3	Uses of the same value before it must become a theme token: gates Core Rule 2, the promotion rules in arbitrary-values.md and variants.md, and the second Output Gate
text_direction	ltr | rtl | both	ltr	ltr emits physical utilities (ml-4, text-left, border-l); rtl and both emit logical ones (ms-4, text-start, border-s) everywhere and add dir to example markup (variants.md)
a11y_target	aa | aaa	aa	Which contrast and target-size rows gate output: AA = 4.5:1 body and size-6; AAA = 7:1 body and size-11 (accessibility.md)

Preference areas to record as the user reveals them:

• tooling — formatter and lint stack (prettier-plugin-tailwindcss, ESLint class rules), IntelliSense regex for custom helpers, how eagerly to adopt new majors
• conventions — theme namespace naming, CSS entrypoint layout, where component classes are allowed to live
• design system — palette source (default palette, brand tokens, an imported token pipeline), spacing and type scale overrides, multi-brand or white-label needs
• integrations — UI kit in play (shadcn/ui, Headless UI, Radix, daisyUI, Flowbite): decides the variant idiom (data-[state=…]) and the class-merging strategy
• risk posture — appetite for arbitrary values and the ! modifier, whether Preflight may be dropped, tolerance for features above the v4 browser floor
• constraints — banned techniques (@apply, browser build, runtime class construction), legacy stylesheets that must keep winning, email or WebView targets
• output — whether to show the generated CSS, and whether to name the mechanism before giving the fix

When To Use

• Writing or reviewing Tailwind markup, @theme/tailwind.config.js, custom utilities, or plugins
• Debugging: a class emits nothing, emits but loses, works in dev and not in production, or fires in the wrong state
• Setting up or migrating: first install, framework wiring, v3 → v4, adding Tailwind to a codebase that already has CSS
• Design-system work in Tailwind: tokens, dark mode, multi-brand theming, component variant APIs
• Build health: rebuild speed, CSS bundle size, monorepo and library scanning
• Not for CSS mechanics or taste — why a flex child overflows belongs to css, palette and scale choices to design-system

Quick Reference

Situation	Play
Class is in the markup, no CSS in the output	The scanner never saw the string (→ Class Detection); dynamic name or unscanned file → missing-styles.md
Works in dev, gone after build	Same scanner problem, plus config drift between dev and build → missing-styles.md
CSS is generated but the element ignores it	Cascade And Conflicts below, then debugging.md symptom chains
Your own CSS silently beats every utility	Unlayered author CSS outranks every cascade layer in v4 (→ Cascade And Conflicts)
Two utilities of the same property fight (px-4 px-6)	Sheet order decides, not attribute order; runtime merging → components.md
hover:, group-hover:, peer-*, has-[…], data-[…] won't fire	variants.md
dark: does nothing, or the theme flashes on load	dark-mode.md
Custom color, spacing step, font, breakpoint, or keyframe	theming.md
A one-off value the theme has no token for	arbitrary-values.md
space-x gaps wrong, truncate won't truncate, w-screen overflows	layout.md
A breakpoint fires at the wrong width, a range needs both bounds, or one component must respond to its own width	responsive.md
The same 14 classes repeated in 30 places	components.md — component boundary, cva, cn, and where @apply is still correct
prose, form-control resets, or writing a custom utility/variant	plugins.md
Transitions, keyframes, enter/exit animation, reduced motion	animations.md
Focus rings, sr-only, contrast of the default palette	accessibility.md
Next.js, Nuxt, Astro, SvelteKit, Rails, Laravel, Storybook, email, React Native	frameworks.md
First install, Vite plugin vs PostCSS vs CLI, editor IntelliSense	installation.md
Slow rebuilds, huge CSS file, monorepo or library scanning	performance.md
Upgrading v3 → v4, or an error naming @tailwind, content, or corePlugins	v4-migration.md
Adding Tailwind to a codebase that already has CSS, Bootstrap, or a UI kit	adoption.md
Anything else	Put the single class on a bare <div> in isolation: if it works there the fault is scanning or cascade, not the utility

Core Rules

1. A class only exists if its complete string exists in a scanned file. The scanner is a text matcher, not a JS evaluator: bg-${tone}-500, 'text-' + size, and `p-${n}` produce zero CSS and zero errors. Write a lookup of whole classes — const tone = { danger: 'bg-red-500', ok: 'bg-green-500' } — and index into it.
2. Theme first, arbitrary second, @apply last. A value used ≥ token_threshold times (default 3) becomes a token (--color-brand-500: oklch(0.62 0.19 259)); below that, bg-[#1da1f2]. The legitimate uses of @apply are exactly three, and this list is closed: third-party HTML, ::-webkit-* pseudo-elements, print sheets. Anything else you were about to @apply is a component you haven't written yet.
3. Conflicts resolve by generated-sheet order, never by attribute order. Tailwind sorts by property group then by scale ascending, so px-6 is emitted after px-4 and wins — class="px-6 px-4" still renders 1.5rem. To resolve at runtime, twMerge('px-4','px-6') → px-6; string concatenation just ships both.
4. A manual dark toggle needs three things or it fails silently. Default dark: follows prefers-color-scheme. Manual toggling requires (a) the strategy — v4 @custom-variant dark (&:where(.dark, .dark *));, v3 darkMode: 'class'; (b) the class on <html>, not on a component; (c) a blocking inline script that sets it before first paint, or every reload flashes the wrong theme.
5. Preflight is take-it-or-leave-it: never fork or edit the reset itself. It removes heading sizes and list markers and makes img display: block; max-width: 100% — which is why CMS HTML and third-party widgets go flat the day Tailwind lands. Three sanctioned exits, in order: wrap unowned content in prose (typography plugin); restore the handful of defaults you need in your own @layer base (an explicit short list, never a copy of the old reset); or drop Preflight whole by importing the layers individually (adoption.md). What is forbidden is a patched Preflight — a vendored copy with rules commented out drifts from the framework on every upgrade with no error.
6. Mobile-first: unprefixed applies everywhere, md: means ≥768px and up. A range needs two utilities (md:flex lg:hidden = 768–1023px) or one max-* variant (max-lg:flex). "Only on tablets" written as md:block is the classic responsive bug in Tailwind markup.
7. Repetition is a component problem, not an @apply problem. A component with a variant map (cva) plus a mergeable className prop keeps variants, IntelliSense, and the scanner working. @apply does support variants (@apply hover:bg-blue-500 compiles fine) — what it costs you is discoverability and override order, and inside a Vue <style> or CSS module it needs @reference to see the theme at all.
8. Never remove a focus affordance without replacing it in the same rule. focus:outline-none alone is the classic Tailwind accessibility regression. Canonical replacement, used verbatim everywhere in this skill: focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-offset-2 (add a focus-visible:ring-* color where the default currentColor is wrong). Two reasons for every token in it: outline-hidden keeps the outline under forced colors where outline-none deletes it, and focus-visible: on both halves means a mouse click shows no ring while keyboard focus does — focus:outline-hidden would strip the native outline on click too.
9. Read the rename list before bumping the major. v4 renamed shadow→shadow-sm, shadow-sm→shadow-xs, rounded→rounded-sm, outline-none→outline-hidden, dropped bg-opacity-* for bg-black/50, and changed ring from 3px blue to 1px currentColor. The build succeeds and the design shifts quietly (v4-migration.md).

Utility Scale Math

Canonical home for these numbers; other files point here.

• Utilities — px = rem × rem_base. Step n = n × 0.25rem. p-4 = 1rem = 16px at the default rem_base 16, and 10px at rem_base 10, because a utility's rem resolves against html { font-size }. Fractional steps 0.5/1.5/2.5/3.5 exist; px = 1px. v4 derives every step from --spacing: 0.25rem, so any multiple works (p-13 = 3.25rem); v3 only ships the listed steps.
• Breakpoints — rem_base does not apply. sm 640px/40rem · md 768/48 · lg 1024/64 · xl 1280/80 · 2xl 1536/96, identical in both majors. A media query resolves rem against the browser's initial font-size, always 16px, ignoring html { font-size } (CSS Media Queries Level 4, "Evaluating Media Features"). So sm: is 640px even in a project with rem_base: 10 — computing 40 × 10 = 400px there is wrong. This is the one exception to the row above.
• Container scale is not the breakpoint scale. max-w-* and container-query sizes share --container-*: xs 20rem · sm 24 · md 28 · lg 32 · xl 36 · 2xl 42 · 3xl 48 · 4xl 56 · 5xl 64 · 6xl 72 · 7xl 80. So max-w-sm = 24rem while sm: = 40rem — the pair most often misread in the framework.
• Type (size/line-height, rem): text-sm 0.875/1.25 · text-base 1/1.5 · text-lg 1.125/1.75 · text-xl 1.25/1.75 · text-2xl 1.5/2.
• Target sizes: size-6 = 1.5rem = 24px = WCAG 2.2 AA floor (2.5.8); size-11 = 2.75rem = 44px = AAA and Apple HIG. a11y_target picks the row. The floor is specified in CSS px, so under rem_base 10 those same classes render 15px and 27.5px and fail it — size hit areas in px or raise the step.
• Opacity modifier: bg-blue-500/50 is the color at 50% alpha. v4 computes it with color-mix(), so it also works on currentColor and on a CSS variable; v3 required a color defined with the <alpha-value> placeholder.

Class Detection

The mental model that explains most Tailwind bugs: the build reads your source files as plain text and extracts every substring shaped like a utility. It does not parse, does not resolve imports, and does not run your code.

• A class inside a comment or a dead branch is generated. A class assembled at runtime is not. A class that lives only in a database row, CMS field, or API response is never seen.
• v4 scans from the project root automatically, skipping .gitignored paths, binaries, and node_modules. Widen with @source "../packages/ui/src";, narrow with @source not "./legacy";, force with @source inline("bg-red-500 bg-green-500");.
• v3 scans exactly the content globs and nothing else. A new top-level directory, or an index.html missing from the array, yields silence — not an error.
• Classes shipped inside a dependency's compiled files are invisible in both majors until you point a source at them (missing-styles.md).
• Verify, don't hope: after a production build, grep -c 'bg-brand-500' dist/**/*.css. Either the class is in the artifact or the scan configuration is wrong.

Cascade And Conflicts

• v4 emits into cascade layers (theme, base, components, utilities). Author CSS written outside any layer beats every layer regardless of specificity — one stray unlayered .card { padding: 0 } disables p-4 on every card, and DevTools shows the utility struck through with no specificity explanation. Move that rule into @layer base and the utility wins again.
• v3 output has no layers: plain specificity and source order decide, so .card p { margin: 0 } (0,2,0) beats mt-4 (0,1,0). Same symptom, opposite mechanism — check tailwind_version before diagnosing.
• Same-property utilities never "override" each other in the attribute; both are generated and the sheet decides (→ Core Rule 3).
• Override across a component boundary with twMerge, which knows the conflict groups. Custom utilities need extendTailwindMerge or the merge silently keeps both (components.md).
• Escape hatch: the important modifier — v4 suffix bg-red-500!, v3 prefix !bg-red-500. Reserve it for CSS you don't own; important: true project-wide trades one problem for a permanent one.
• Custom CSS placement: @layer components for anything a utility should be able to override, @utility (v4) for anything that must sort with utilities and accept variants.

Output Gates

Before emitting Tailwind markup or config, verify:

• Every class a complete literal string in a scanned file — no interpolation, no concatenation?
• Any value repeated ≥ token_threshold times (default 3) promoted to a theme token instead of repeated arbitrary syntax?
• Interactive elements carry the canonical focus-visible ring of rule 8 and meet the target-size row?
• Directional utilities match text_direction — logical (ms-*, text-start) whenever it is not ltr?
• Every color set has its dark: counterpart, if the project themes?
• Layout read at the smallest width first — unprefixed is mobile, not desktop?
• Text colors pass the contrast floor (text-gray-400 on white is ≈2.5:1 and fails)?
• Syntax matches tailwind_version — no @tailwind directive in a v4 project, no @theme block in a v3 one?

Traps

Trap	Why it fails	Do instead
bg-${color}-500, 'text-' + size	The scanner is a text matcher; that string never exists in the source	Lookup map of complete classes (→ Class Detection)
class="px-4 px-6" to override	Both are generated; the stylesheet decides, not the attribute	twMerge, or don't emit both (→ Cascade And Conflicts)
focus:outline-none with nothing after it	Deletes the only affordance keyboard users have	focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-offset-2 (→ Core Rule 8)
important: true in the config	Every utility becomes !important: third-party CSS dies and your own overrides need escalation	Per-class ! on the few that need it; layer your CSS instead (→ adoption.md)
@apply in a Vue <style> or a CSS module	That file compiles in its own context with no theme loaded	v4 @reference "../app.css"; first — better, move the classes to the markup (→ frameworks.md)
h-screen for a full-height mobile section	100vh ignores the browser chrome that collapses on scroll	h-dvh, or h-svh when live resizing would be jumpy
w-screen for a full-bleed row	100vw includes the scrollbar width → horizontal scroll on desktop	w-full, or w-dvw
space-x-4 on a wrapping or reversed row	The sibling selector skips wrapped rows and inverts under flex-row-reverse	gap-4 (→ layout.md)
truncate with no width constraint	text-overflow needs a resolvable width; a flex child defaults to min-width: min-content	min-w-0 on the flex child, or an explicit max-w-*
safelist: [{ pattern: /bg-.*/ }]	Emits the whole palette across every variant — bundle explodes, tree-shaking gone	Enumerate the real classes (→ missing-styles.md)
Adding dark: to background only	Half the component follows the theme; the bug is invisible in the mode you develop in	Set foreground and background as a pair, every time
Browser build (<script src=…tailwindcss">) in production	Compiles on every page load, no scanning discipline, no plugin parity	A real build step (→ installation.md)
Pasting v3 snippets into a v4 project	@tailwind, content, corePlugins, and safelist are gone; the error names the directive, never the cause	Mapping table in v4-migration.md
rounded-full on an element without overflow-hidden	Absolutely positioned children paint over the rounded corner	overflow-hidden on the rounded parent (→ layout.md)

Where Experts Disagree

• @apply. Tailwind's own maintainers argue against it; design-system teams shipping a class API to templates they don't control use it deliberately. Boundary: @apply is right when the markup isn't yours to edit — otherwise it's a component you haven't written yet.
• Arbitrary values vs a closed theme. One camp treats [...] as a design-system leak; the other as the reason Tailwind survives real designs. Boundary: escapes are fine at the leaf, harmful in shared components — those pull from tokens so a rebrand is one file.
• CSS config (@theme) vs JS config (@config). JS is programmable — loops, imports from a token package, generated scales — and v4 still loads it. Boundary: generated token pipelines stay in JS; hand-maintained themes move to @theme and get CSS variables for free.
• Class sorting. Automated (prettier-plugin-tailwindcss, canonical order, zero diff noise) vs hand-grouped by concern (layout, then color, then state) for readability. Boundary: any repo with more than one author takes the automated order; the argument only survives in solo codebases.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/tailwindcss (install if the user confirms):

• css — the mechanics underneath the utilities: stacking contexts, flex sizing, cascade
• react — component architecture, props, and state around the class strings
• nextjs — App Router, fonts, and build integration specifics
• design-system — tokens, scales, and multi-product theming above the config file
• accessibility-audit — full WCAG review beyond the floor enforced here

Feedback

• If useful, star it: https://clawic.com/skills/tailwindcss
• Latest version: https://clawic.com/skills/tailwindcss

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/tailwindcss.