Tailwind, shadcn/ui and design system skills for AI agents

Ask an agent to style a page with Tailwind and it writes what it saw most of, which is Tailwind 3. It creates a tailwind.config.js, puts @tailwind base; @tailwind components; @tailwind utilities; at the top of the stylesheet, and reaches for bg-opacity-50 and bg-gradient-to-r. On a v4 project none of that is merely dated: the directives were removed, the JS config is not read unless you load it explicitly, and those utility names no longer exist. The failure is quiet — some of it compiles, some of it silently produces nothing.

So you hand the agent a skill. But a skill is a document frozen at whatever version its author had open, and the name on the tin tells you nothing about that. The most useful thing to come out of reading this material is a single sharp sort: the strong documents state which major version they target and then keep that promise line by line, and the weak ones say nothing and teach the old one anyway. A document can be literally named tailwind-4 and still not contain a single v4-only directive. That check — does it declare a version, and does the config guidance match it — is the whole game.

Top picks

Upgrading v3 to v4: parity is the pass/fail test

a-tokyo's tailwind-v3-to-v4-migration runs the official @tailwindcss/upgrade codemod first and then spends its length on what the codemod cannot decide. Its organizing claim is that "A correct migration is a visual no-op" — every renamed utility is a pure alias, so what actually moves pixels is v4's changed defaults, and each one comes with a copy-paste shim: border and divide colours now currentColor, ring now 1px instead of 3px, placeholder at 50% of text colour, buttons at cursor: default.

The detail that shows someone shipped this: it warns that two of those shims are "invisible to a screenshot harness" — the button cursor and hover-on-touch change behaviour, not painted pixels, so a visual diff cannot confirm them and you must reason about the markup instead. It also tells you when not to upgrade, naming Safari 16.4+, Chrome 111+ and Firefox 128+ as v4's floor, and requires Node 20+ for the tool. MIT, and it scopes itself out of fresh installs explicitly.

Already on v4: the rules file that names what the agent gets wrong

ofershap's tailwind-best-practices is built on the right diagnosis — it states that "AI agents are trained on Tailwind v3 data" and consistently generate outdated patterns — and answers it with twelve numbered rules in strict Wrong / Correct / Why form. The wrong side is the exact v3 output an agent produces: tailwind.config.js with theme.extend, bg-opacity-*, @layer utilities, important: true in config. The right side is the v4 replacement, down to @import "tailwindcss" important; for the global important flag.

Its same-name rival, AsyrafHussin's tailwind-best-practices, takes the opposite bet and covers v3.4+ and v4 together with 29 rules across 8 categories. Its Step 1 is the best idea in either document — settle which major version the project is on before giving any advice — and it hands the agent a signal table for reading that off the repository itself: tailwind.config.js present points to v3, while an @import "tailwindcss" line in the CSS, a @theme {} block, or @tailwindcss/vite in the dependencies point to v4. One caveat, and it is a real one: an inline example in that overview says v4 dark mode is class-based by default and needs no config, while both xobotyi's tailwindcss and the migration skill state that v4 defaults to the prefers-color-scheme media query and class toggling needs @custom-variant dark.

The v4 reference to keep loaded while writing

xobotyi's tailwindcss opens with a stance — "Utility classes are the default. Custom CSS is the escape hatch." — and then earns it. It maps the @theme namespaces to the utility families they generate, explains when to use @theme inline (a token that references another variable), and walks --value() resolution modes for functional custom utilities.

The line worth the install is buried in class authoring: conflicts resolve by "Last class in the generated stylesheet wins, not last in the HTML attribute" — so reordering a className string fixes nothing, and you need conditional rendering instead. Compare Mindrally's tailwindcss, which is a page of true-but-generic advice — leverage the responsive prefixes, "Use JIT mode for optimal performance" — with no version stated anywhere and nothing in it that would stop an agent writing v3.

When you want a position, not just syntax

rekryt's skill-tailwind is the one document here that treats utility classes in markup and BEM-plus-@apply in SCSS as two equally valid choices and gives you a decision tree instead of a preference, hung off a six-rung abstraction ladder from utilities to @apply-as-adapter. Its anti-pattern list is where it pays for itself: @screen md { @apply ... } "is v3 and was removed in v4", and the compiler "silently drops the wrapped rules" rather than erroring.

The second trap is subtler — @reference "tailwindcss" inside a Vue or Svelte <style> block exposes only the default theme and drops your custom tokens without complaint, so the reference must point at your own entry CSS. Its rival wshobson's tailwind-design-system is also honestly v4-stamped and hands you a finished OKLCH token set with @custom-variant dark wired up; take that one if you want a file to paste, and rekryt's if you want a decision.

shadcn/ui: check the install command before anything else

existential-birds' shadcn-ui is the build-time companion, and its CLI section opens by flagging that the package was renamed: npx shadcn-ui@latest add is the deprecated form and npx shadcn@latest add is current. From there it is genuinely current shadcn — data-slot on every part, asChild via @radix-ui/react-slot, CVA variants typed through VariantProps, and has-data-[slot=card-action]:grid-cols-[1fr_auto] for layout that responds to which children exist.

That opening flag matters because bobmatnyc's shadcn — same tool, longer document, no version note anywhere — teaches the deprecated npx shadcn-ui@latest throughout, ships a globals.css starting with @tailwind base;, and configures theme.container with center and padding, options v4 removed. giuseppe-trisciuoglio's shadcn-ui uses the current CLI and is the better choice if you want React Hook Form and Zod worked through, plus a Recharts wrapper.

Auditing shadcn components the agent already wrote

mattbx's shadcn-component-review exists for the pass after generation, on the premise that "Reviews catch drift" — someone copies from an older project, a model suggests space-y-4, nobody catches it. It starts by running npx shadcn@latest info --json to learn the project's framework, Tailwind version, primitive base and visual style, then audits against that rather than against a generic ideal; its universal spacing rule is gap-* in flex and grid containers, "never space-y-* / space-x-* or margins".

It is also current on shadcn's five official visual styles and on the CLI v4 presets that pack style, theme, fonts, icons and radius into one short code. Its closest rival, existential-birds' shadcn-code-review, is tuned for the opposite failure — false positives — with a "Valid Patterns (Do NOT Flag)" list and rules like "Flag accessibility issues ONLY IF not handled by Radix primitives underneath". Run mattbx's for design-token and spacing drift; run beagle's when the reviewer keeps flagging vendored shadcn internals.

Reading a skill's version stamp in thirty seconds

Open the document and look at four places. The CSS entry line: @import "tailwindcss" is v4, a bare @tailwind base; is v3 — unless it is sitting under a "wrong" or "never" label, which is exactly how the good documents teach the rename. The configuration: a @theme { --color-… } block is v4, a tailwind.config.js with theme.extend as the primary answer is v3. For anything shadcn, the install line: npx shadcn@latest is current and npx shadcn-ui@latest is the deprecated package.

Then look for the stamp itself — a sentence, front-matter field or table that names the target version. Its absence is the signal. A document that never commits to a version cannot be wrong about one, which sounds safe and means you inherit whatever its author assumed. The strongest form of the stamp is a pinned one: alecs5am's tailwind names an exact runtime, @tailwindcss/browser@4.2.4, tells the agent to "Treat that as Tailwind v4, not v3", and adds that a sibling package in the same repository "still uses Tailwind v3 internally" so the guidance does not leak across.

A skill called tailwind can be any of these

Skill names are not namespaced, so the name is the topic and the publisher plus the body are the identity. A name like tailwind, tailwindcss, tailwind-best-practices, shadcn or shadcn-ui is shared across unrelated accounts, and the documents behind it are not variants of each other — they disagree on version, scope and sometimes on the tool. The one called tailwind under alecs5am is not general Tailwind guidance at all; it is scoped to browser-runtime compositions for a specific CLI, and installing it for a Next.js app would be a category error.

The reverse trap is two names that turn out to be one document. The copy of tailwind-4 published under Gentleman-Programming and the copy published under prowler-cloud are, below the front matter, the same text — differing by a code-fence language label and a trailing keywords line, and nothing else. Both are decent on cn(), conditional classes and when to drop to the style prop, and neither contains a single v4-only directive: no @theme, no @import "tailwindcss", no bg-linear-to-*. Apply the licence check and the pair comes apart — both front matters declare license: Apache-2.0, while the repository behind the Gentleman-Programming copy carries MIT, so that one line is not by itself an answer to what you are agreeing to. Installing both buys you one skill. And look at where the version claim actually sits: each description promises "Tailwind CSS 4 patterns and best practices". The stamp is there. The body never honours it.

What to install

The problem was never that Tailwind changed — it is that your agent's default is the previous version and it fails quietly, and that a skill can carry the same staleness with a confident name. Fix it in the order the work happens. If a v3 project needs upgrading, take a-tokyo's migration skill and let visual parity, not a green build, be the test. If you are already on v4, ofershap's rules stop the agent producing v3 in the first place and xobotyi's is the reference that answers the questions the rules raise; add rekryt's if your team needs a position on component classes rather than a syntax table.

On the shadcn side, install existential-birds' skill for building and mattbx's for the review pass, and check the install command in anything else before you trust it. What you have avoided is the specific bad afternoon these documents predict: a config file the build never reads, a dark-mode toggle wired to a variant that was never registered, a stylesheet whose @screen blocks vanished without an error, and a component tree styled by whichever copy of shadcn you happened to install.