Tailwind CSS
Knowledge base from the official Tailwind CSS v4 (tailwindcss.com) documentation — utility-first CSS framework. Use when writing or debugging Tailwind classes, customizing the theme (@theme, colors, spacing, breakpoints), choosing a variant (hover/focus/dark/container-query/has-*/group-*/peer-*), building responsive or state-driven UI, or migrating a project from Tailwind v3 to v4.
Tailwind CSS
Package: tailwindcss v4 | Chapters: 29 (14 Core Concepts + 15 utility categories) | Generated: 2026-08-25
How to Use This Skill
- Without arguments — load Core Patterns below for the mental model shared across every utility
- With a utility/class name — ask about
justify-content,grid-cols-*,backdrop-blur-*-style topics; I find and read the matching chapter - With a chapter — ask for
ch011; I load that specific chapter - With a v3→v4 migration question — check
ch014-upgrade-guide.mdfirst - Browse — ask "what chapters do you have?" to see the full index
When you ask about a topic not covered in Core Patterns below, I will read the relevant chapter file before answering.
Core Patterns & Conventions
Everything is CSS-first since v4. There is no tailwind.config.js by default — design tokens live in @theme { } blocks in your CSS entry file, and a token's namespace (--color-*, --spacing, --breakpoint-*, ...) determines what utility/variant it generates.
One value grammar reused everywhere. Numeric suffixes resolve against --spacing (p-4 = calc(var(--spacing) * 4)); fractions resolve to percentages; -px/-full/-auto are literal keywords; (<custom-property>) and [<value>] cover custom-property references and fully arbitrary values. This single grammar spans margin/padding/width/height/gap/inset — learn it once.
Variants are class prefixes, always additive, never bundling both states. hover:bg-sky-700 only contains hover styles — the unprefixed class is always the default/base state. Variants stack in any order (dark:lg:hover:bg-red-600) and cover pseudo-classes, pseudo-elements, media/container queries, attribute selectors, and parent/sibling/descendant relationships (group-*, peer-*, has-*).
Composable utility families share a CSS variable, not a literal property. filter, background-image (gradients), box-shadow, mask, and individual transform properties (rotate/scale/translate) each let multiple utilities combine (blur-sm grayscale, from-red-500 to-yellow-400) because each utility only sets its own variable — never assume combining two utilities on the same literal CSS property (e.g. two bg-* classes) will merge; the later one in the generated stylesheet always wins outright.
Mobile-first, container-aware. Unprefixed = every size; sm:/md:/etc. = that breakpoint and up; @sm:/@md:/etc. = that container size and up (needs an ancestor marked @container). Stack a breakpoint with its max-* counterpart to scope a range instead of "and up."
Reach for a variant before JS state. hover:, focus:, has-*:, group-*:, peer-*:, aria-*:, data-*: cover almost every "style differently when X" need — especially for headless UI libraries that expose state via attributes.
Never apply two utilities to the same literal CSS property on one element. Cascade/generation order (not class-attribute order) decides the winner — branch the class string instead.
Chapter Index
Core Concepts — System
| # | Title | Key Concepts |
|---|---|---|
| ch001 | Adding Custom Styles | @theme, arbitrary values/properties/variants, @utility, @custom-variant |
| ch002 | Compatibility | Browser floor, Sass/Less/Stylus, CSS Modules, @reference |
| ch003 | Dark Mode | dark: variant, manual class/data-attribute toggling |
| ch004 | Detecting Classes in Source Files | Plain-text scanning, @source, safelisting |
| ch005 | Editor Setup | IntelliSense, Prettier plugin |
| ch006 | Functions and Directives | @theme/@utility/@variant/@apply/@reference reference, --alpha()/--spacing() |
| ch007 | Preflight | Base-style reset, extending/disabling |
| ch008 | Responsive Design | Breakpoints, mobile-first, custom breakpoints |
| ch009 | Container Queries | @container, named containers, size containers |
| ch010 | Styling with Utility Classes | Composition, duplication management, style conflicts |
| ch011 | Hover, Focus & Other States | Full variant system: pseudo-classes/elements, media queries, group/peer/has |
| ch012 | Colors | Default palette, customizing/disabling colors |
| ch013 | Theme Variables | @theme namespaces, extending/overriding, inline/static |
| ch014 | Upgrade Guide (v3→v4) | Upgrade tool, renamed utilities, breaking changes |
Utilities — Layout & Box Model
| # | Title | Key Concepts |
|---|---|---|
| ch015 | Layout | display, position, overflow, float/clear, columns, z-index |
| ch016 | Flexbox & Grid | flex-, grid-, justify/align/place, order |
| ch017 | Spacing | margin, padding, space-between |
| ch018 | Sizing | width, height, min/max, size-* |
Utilities — Typography & Visuals
| # | Title | Key Concepts |
|---|---|---|
| ch019 | Typography — Fonts & Sizing | font-family/size/weight, tracking, leading, line-clamp |
| ch020 | Typography — Text, Decoration & Wrapping | text-align, decoration, transform, text-wrap, white-space |
| ch021 | Backgrounds | background-color/image (gradients), position/size/repeat |
| ch022 | Borders | border-width/color/style, radius, divide-*, outline, table-layout |
| ch023 | Effects | box-shadow, opacity, mix-blend-mode, mask-* |
| ch024 | Filters | filter-/backdrop-filter- (blur, brightness, drop-shadow, ...) |
Utilities — Motion & Interaction
| # | Title | Key Concepts |
|---|---|---|
| ch025 | Transitions & Animation | transition-, animate-, @starting-style |
| ch026 | Transforms | rotate/scale/translate/skew, perspective, 3D |
| ch027 | Interactivity | cursor, scroll-snap, scrollbar-*, touch-action, will-change |
| ch028 | SVG | fill, stroke, stroke-width |
| ch029 | Accessibility | forced-color-adjust |
Topic Index
- Alignment (flex/grid) → ch016
- Arbitrary values/properties/variants → ch001, ch010
- Breakpoints (viewport) → ch008, ch013
- Breakpoints (container) → ch009, ch013
- Colors (palette, customizing) → ch012
- Composable CSS-variable utilities (filter/gradient/shadow/transform) → ch021, ch023, ch024, ch026
- Dark mode → ch003
- Duplication management → ch010
- Forced colors / high contrast → ch029, ch011
group/peer/has-*→ ch011- Gradients → ch021
- Masking → ch023
- Preflight / base styles → ch007
- Responsive design (media) → ch008
- Scroll snap / scrollbars → ch027
- Spacing scale (
--spacing) → ch013, ch017, ch018 @theme/ design tokens → ch001, ch013- Transitions vs. animations → ch025
- Upgrade from v3 → ch014
- Variants (full reference) → ch011
Supporting Files
- glossary.md — key terms with definitions
- patterns.md — theming, responsive, composition, and migration techniques
- cheatsheet.md — decision tables, spacing grammar, variant reference, v3→v4 rename table
Scope & Limits
This skill covers the Tailwind CSS v4 documentation as of the fetch date in the source — the utility-first framework itself (core concepts, theme system, and every utility category). It does not cover the official plugins (@tailwindcss/typography, @tailwindcss/forms) beyond their mention in the compatibility/upgrade chapters, nor Tailwind UI (the paid component library).
Companion skills: shadcn-ui-docs, radix-primitives-docs, and base-ui-docs all describe component libraries that are typically styled with Tailwind — consult those for component behavior/anatomy/props, and this skill for the styling layer underneath. aceternity-docs (if present) is a copy-paste animated-component library also built with Tailwind.
The 197 individual utility-class source pages (one CSS property per page in the raw docs) were consolidated into 15 dense category chapters rather than reproduced 1:1 — near-identical utility families (the 9 backdrop-filter-* variants, the 9 filter-* variants, the 9 mask-* sub-properties, the width/height/min/max sizing family) are presented as single reference tables per family rather than one thin chapter each.