Identify the Tailwind surface:
- Read the nearest project guidance and package manifests.
- Check installed versions of tailwindcss, @tailwindcss/vite, @tailwindcss/postcss, @tailwindcss/cli, @tailwindcss/webpack, @tailwindcss/turbopack, prettier-plugin-tailwindcss, and framework packages.
- Inspect CSS entry files, vite.config.*, PostCSS config, framework config, tailwind.config.*, and class composition helpers.
Refresh docs when the user asks for latest/current behavior, when versions differ from the captured snapshot, or when touching v4 migration/configuration:
- Use source-map.md for the captured latest-version snapshot and official source links.
Load the focused reference file:
- setup-and-migration.md: installation paths, package split, v3-to-v4 upgrade, browser support, and migration hazards.
- core-utilities.md: utility-class composition, source detection, responsive design, dark mode, variants, arbitrary values, Preflight, and accessibility.
- css-directives-and-theme.md: @theme, @source, @utility, @variant, @custom-variant, @apply, @reference, @config, @plugin, and Tailwind CSS functions.
Implement in the existing project style:
- Prefer the project's current Tailwind major version and integration package.
- Use complete, statically detectable class names. Map props or states to full class strings instead of interpolating fragments.
- Prefer design-token utilities and theme variables over one-off arbitrary values.
- Add custom CSS only when utilities, theme variables, variants, or component composition are not the right fit.
- Do not migrate a v3 project to v4 unless the user asks or the task requires it.
Verify the smallest meaningful surface:
- Run the relevant style build, framework build, typecheck, lint, tests, Storybook, or browser check.
- For visible UI changes, inspect the actual rendered state when feasible.
- Report any verification you could not run.

Tailwind Judgment

Treat Tailwind v4 as CSS-first: @import "tailwindcss";, theme variables in CSS, and dedicated Vite/PostCSS/CLI/webpack/Turbopack integration packages.
Use @source for monorepos, ignored external packages, multiple stylesheets, safelisting, and source exclusions.
Keep responsive styles mobile-first: unprefixed utilities target all sizes, breakpoint prefixes apply at that breakpoint and above.
Keep dark mode explicit: use default prefers-color-scheme behavior or define a project selector with @custom-variant dark.
Treat Preflight as active when Tailwind is imported. Account for reset margins, unstyled headings/lists, border reset, block images, responsive media, and hidden attributes.
Prefer official framework guides when a framework owns the CSS pipeline.
If the project must support Safari below 16.4, Chrome below 111, or Firefox below 128, do not choose Tailwind v4 without an explicit compatibility decision.

tailwind

Tailwind

Workflow