Tailwind CSS official documentation
This skill is the contract for Tailwind CSS v4 work. It routes each task to the official documentation that governs it. Its references hold the exact page and section routes, grouped by category, each with a short reference of what it covers. Read the reference that matches the task, then read the linked sections on the live page. Trust the live page over training knowledge and over this skill. Check every decision against the Tailwind version the project resolves and its actual configuration.
When the task also designs, builds or generates an interface, also load tailwind-development:tailwind-ui-design.
When to use
- Answer any question about Tailwind CSS.
- Write, edit, review or refactor Tailwind classes, variants or CSS.
- Install, integrate or configure Tailwind in a project.
- Set up an editor, IntelliSense or class sorting for Tailwind.
- Check browser support, preprocessors, CSS modules or component styles.
- Migrate a project from v3 to v4.
- Plan any of the above, even when the user does not name Tailwind.
When not to use
- The project styles with plain CSS, CSS-in-JS or another framework, and the task does not add Tailwind.
- The task touches no styling, markup classes or Tailwind configuration.
Custom variants
Use @custom-variant when a selector pattern is truly repeated and deserves to become a styling primitive.
Good candidates:
- app theme wrappers
- data-attribute driven states
- repeated container context selectors
- CMS-specific context wrappers (e.g. dark page section, highlighted block)
Do not create custom variants for one-off selector tricks unless the repetition is real.
Generated DOM and JS-replaced markup
When styling icons or widgets that are transformed by JavaScript, target the rendered DOM, not only the placeholder markup.
Examples:
- icon libraries that replace
<i>with<svg> - component libraries that inject wrappers
- widgets that rewrite class names or structure
If a shared interaction depends on a specific child element, verify that the final rendered DOM still matches the selector.
This matters a lot for:
- transitions
- hover effects
- focus styles
- icon animation
- nested selectors in component classes
Responsive strategy
Prefer mobile-first styling:
- define the base case first
- add larger breakpoint changes progressively
Use breakpoint tokens intentionally. In v4, --breakpoint-* theme variables define which responsive variants exist.
Stylesheet structure
For a CSS-first Tailwind v4 setup, this structure is usually sensible:
- entrypoint CSS (
app.cssorsite.css) theme.cssfor tokensbase.cssfor minimal element defaultsutilities.cssfor low-level project utilities and variantscomponents.cssfor a small stable component API- Bigger components, e.g.
rich-text.cssfor scoped uncontrolled HTML
- Bigger components, e.g.
Refactor heuristics
When refactoring an existing Tailwind codebase:
- Remove dead CSS before adding new CSS.
- Remove redundant utilities before extracting abstractions.
- Normalize obvious repeated primitives first.
- Keep the number of component classes intentionally small.
- Push page structure back into markup if CSS started owning too much layout.
- Merge inconsistent implementations of the same affordance.
Watch for these smells:
- several versions of the same button or card
- repeated arbitrary shadows, radii, or spacing
- identical hover interactions implemented in different ways
- state logic split between a shared class and page-specific one-offs
- component classes that are really page fragments in disguise
Review checklist
Before finalizing a Tailwind change, check:
- Are utilities sufficient here, or did I abstract too early?
- If repetition exists, would extracting markup be better than adding CSS?
- Should repeated values become tokens?
- Are custom utilities truly low-level?
- Are component classes small, stable, and override-friendly?
- Are state and motion rules consistent across similar UI?
- Will Tailwind detect every class I used?
- Are dynamic classes mapped to full strings?
- Is uncontrolled markup scoped instead of styled globally?
- Is the responsive behavior mobile-first and intentional?
- Can any CSS be deleted now?
Practical defaults
When in doubt:
- keep styling in markup first
- reuse markup before reusing CSS
- use tokens before arbitrary repetition
- use custom utilities before semantic CSS wrappers
- keep component classes few and durable
- keep state behavior inside the shared abstraction if the abstraction exists
- verify that rendered DOM matches your selectors
- prefer deleting complexity over introducing a clever abstraction
Getting started
Installation
For any installation task (setup, fix or question), read the matching reference and the page its title links. Follow the page where they differ.
Overview: every install path at a glance → See https://tailwindcss.com/docs/installation
Vite: vite.config.*, Vite frameworks → See references/installation/using-vite.md
PostCSS: postcss.config.*, Next.js, Angular → See references/installation/using-postcss.md
Tailwind CLI: no bundler, standalone executable → See references/installation/tailwind-cli.md
Play CDN: browser prototypes, no build → See references/installation/play-cdn.md
Framework guides: Next.js, Nuxt, SvelteKit, Astro, Laravel and more → See references/installation/framework-guides.md
Read the framework's guide instead of a generic path when it has one.
Editor setup
For any editor or formatter task (setup, fix or question), read the matching reference and the page its title links. Follow the page where they differ.
Syntax support: warnings on @theme, @apply, @source → See references/editor-setup/syntax-support.md
VS Code and Cursor: IntelliSense extension, settings → See references/editor-setup/vscode-intellisense.md
Prettier: class sorting → See references/editor-setup/prettier-class-sorting.md
Zed: built-in language server → See references/editor-setup/zed.md
JetBrains: WebStorm, PhpStorm → See references/editor-setup/jetbrains.md
Compatibility
For any compatibility task (setup, fix or question), read the matching reference and the page section its title links. Follow the page where they differ.
Browsers: browser floor, project targets → See references/compatibility/browser-support.md
Preprocessors: Sass, Less, Stylus → See references/compatibility/preprocessors.md
CSS modules: @reference, @apply in modules → See references/compatibility/css-modules.md
Component styles: <style> in Vue, Svelte, Astro → See references/compatibility/component-style-blocks.md
Upgrade guide
To migrate a project, read every reference below in order, with the upgrade-guide sections each one links. For one v3 habit or a question, read only the matching reference. Follow the page where they differ.
- Upgrade tool: run it first → See references/upgrade-guide/upgrade-tool.md
- Manual upgrade: when the tool cannot run → See references/upgrade-guide/manual-upgrade.md
- Utilities: removed, renamed, defaults → See references/upgrade-guide/utilities.md
- Syntax: directives, prefix, important, variants → See references/upgrade-guide/syntax.md
- Preflight: base style changes → See references/upgrade-guide/preflight.md
- Configuration: JS config,
theme(), browsers → See references/upgrade-guide/config.md - Report every section with its verdict: changed, not present, kept, or needs a decision.
Core concepts
For any work, knowledge or guidance on a core concept, read the matching reference. Then read the linked page sections for your topic.
Utility classes: composition, arbitrary values, conflicts, important, prefix → See references/core-concepts/styling-with-utility-classes.md
States: hover, focus, group, peer, pseudo-elements, ARIA, data, custom variants → See references/core-concepts/hover-focus-and-other-states.md
Responsive design: breakpoints, ranges, container queries → See references/core-concepts/responsive-design.md
Dark mode: dark:, class or data-attribute toggle, system theme → See references/core-concepts/dark-mode.md
Theme variables: @theme, namespaces, tokens in CSS and JS → See references/core-concepts/theme.md
Colors: palette, opacity, custom colors → See references/core-concepts/colors.md
Custom styles: arbitrary values, custom CSS, @utility, custom variants → See references/core-concepts/adding-custom-styles.md
Class detection: dynamic class names, @source, safelisting → See references/core-concepts/detecting-classes-in-source-files.md
Functions and directives: @import, @apply, @reference, --alpha(), @config → See references/core-concepts/functions-and-directives.md
Base styles
Preflight resets, extending or disabling Preflight → See references/base-styles.md
Layout
aspect-ratio, columns, display, float, object-fit, overflow, position, inset, z-index → See references/layout.md
Flexbox & Grid
flex, grid columns and rows, gap, justify, align, place, order → See references/flexbox-and-grid.md
Spacing
padding, margin → See references/spacing.md
Sizing
width, height, min and max sizes, logical inline and block sizes → See references/sizing.md
Typography
font family, size and weight, line height, text color, decoration, wrapping, lists → See references/typography.md
Backgrounds
background color, image, gradients, position, size, clip → See references/backgrounds.md
Borders
border radius, width, color, style, outlines → See references/borders.md
Effects
box and text shadows, opacity, blend modes, masks → See references/effects.md
Filters
blur, brightness, contrast, drop shadow, backdrop filters → See references/filters.md
Tables
border collapse and spacing, table layout, caption side → See references/tables.md
Transitions & Animation
transition property, duration, easing, delay, animation → See references/transitions-and-animation.md
Transforms
rotate, scale, skew, translate, perspective, transform origin → See references/transforms.md
Interactivity
accent and caret color, cursor, field sizing, pointer events, scrolling, scroll snap, touch, user select → See references/interactivity.md
SVG
fill, stroke, stroke width → See references/svg.md
Accessibility
forced colors adjustment → See references/accessibility.md
Agents
Before the first delegation of the session, run the link check yourself, never in an agent:
python3 "${CLAUDE_SKILL_DIR}/scripts/check-links.py"
Where ${CLAUDE_SKILL_DIR} is not replaced, run scripts/check-links.py from this skill's folder.
It checks every URL in this skill's references and prints only the problems, each with its file and line.
- Exit 0: delegate.
- Exit 1: tell the user each broken URL with its file and line.
- Exit 1: give the agent that list, and tell it to reach those sections from the live site's navigation.
- Unverified lines: tell the user which URLs the check could not confirm, then delegate.
- Exit 2, no command runner or no network: say the check did not run, then delegate.
Delegate to the matching agent when the session can run agents. Give it the task, the project root and the files involved.
Documentation: syntax, behaviour, versions → tailwind-development:tailwind-docs
Audit: review code or a change → tailwind-development:tailwind-auditor
Refactor: clean up existing code → tailwind-development:tailwind-refactorer
Migration: v3 to v4 → tailwind-development:tailwind-migrator
Workflow
Follow these steps yourself when no agent fits or agents cannot run.
- Read the resolved Tailwind version, not the declared range.
- Read the integration, the CSS entry, the
@themetokens and the project's conventions. - Split the task into utilities, conditions, customization and compilation.
- Read the matching references and their live sections.
- Read sources as
references/retrieval.mdsays → See references/retrieval.md - Pick between similar pages with the disambiguation list → See references/disambiguation.md
- Implement with complete, statically detectable classes and existing tokens.
- Run the project's lint, type-check, tests and build.
- Check the result in a browser when one is available.
Completion report
- What changed.
- The resolved Tailwind version, or why it is unresolved.
- The docs section URL behind each decision.
- The checks run and their results.
- What you could not verify.
- Never cite this skill as evidence of Tailwind behaviour.