tailwind-v4-expert

license	Apache-2.0
allowed-tools	Read,Write,Edit,Bash,Glob,Grep,WebSearch,WebFetch
name	tailwind-v4-expert
description	Use when migrating Tailwind v3 to v4, configuring CSS-first @theme tokens, debugging Oxide engine errors, dealing with the absence of tailwind.config.js, container queries (@container) usage, layer cascade problems, or "dynamic class names not generating". Triggers: switching from `@tailwind base` to `@import "tailwindcss"`, RSC/Next.js streaming + CSS ordering, dark-mode strategy choices, custom variants via @variant, content-scanning glob tuning. NOT for Tailwind v3 (different config model), CSS-in-JS frameworks, vanilla CSS architecture (BEM/SMACSS), or react-native styling.
metadata	{"category":"Frontend & UI","tags":["tailwind","css","design-tokens","oxide","container-queries","frontend"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"web-design-expert","reason":"Owns the design decisions (layout, hierarchy, visual voice) that this skill's @theme tokens and utilities implement."},{"skill":"color-contrast-auditor","reason":"The @theme color tokens defined here should pass its contrast checks in both light and dark variants."},{"skill":"ideal-web-app-builder","reason":"The app-scaffolding skill whose Next.js/globals.css setup this skill's v4 import model plugs into."}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}

Tailwind v4 Expert

Tailwind v4 is a different tool than v3. The PostCSS-based JIT engine is gone, replaced by Oxide (Rust). The JS config file is gone, replaced by CSS-first @theme blocks. Plugins from v3 mostly need rewriting. If you're migrating, expect to rebuild — not patch — your config layer.

When to use

• Migrating a v3 project (look for @tailwind base; @tailwind components; @tailwind utilities;).
• Need design tokens (colors, fonts, breakpoints) consumed by both Tailwind and raw CSS.
• Container queries — designing components that adapt to their container, not the viewport.
• Custom variants beyond what v4 ships (@variant focus-within-sibling, etc.).
• Dynamic class names disappearing from the build (Oxide can't see what isn't statically present).
• RSC + streaming + Tailwind ordering bugs.

Core capabilities

The v4 import model

/* app/globals.css */
@import "tailwindcss";

/* Optional: scan files outside the default content roots. */
@source "../../packages/ui/src/**/*.{ts,tsx}";
@source "../../node_modules/@my-org/icons/dist/**/*.js";

There is no tailwind.config.js. There is no content array. @source adds globs to the default scan root (the file's dir + project conventions). Oxide statically scans these for class strings.

@theme — design tokens are CSS now

@theme {
  --color-brand-50:  oklch(97% 0.02 250);
  --color-brand-500: oklch(60% 0.18 250);
  --color-brand-900: oklch(20% 0.10 250);

  --font-display: , , sans-serif;
  :    , ui-monospace, monospace;

  : ;

  : ;
}