Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
jezweb avatar

Tailwind Theme Builder

jezweb/claude-skills

  • 2.9k installs
  • 946 repo stars
  • Updated July 2, 2026
  • jezweb/claude-skills

This agent skill configures Tailwind v4 plus shadcn/ui with @theme inline variables, semantic colours, and a working dark mode toggle.

About

This Tailwind v4 theme skill configures shadcn/ui with CSS variable theming and dark mode for React Vite projects. It follows a mandatory four-step pattern: define semantic variables in :root and .dark with hsl wrappers, map them through @theme inline to generated utilities such as bg-background, apply base styles without double hsl wrapping, and wire a ThemeProvider that toggles the .dark class on html. Workflow steps install tailwindcss and @tailwindcss/vite, remove legacy tailwind.config.ts, configure the Vite plugin, copy theme-provider and mode-toggle components, and set components.json with an empty tailwind config path for v4. Critical rules forbid nesting :root inside @layer base, nested @theme blocks, double hsl(var(...)) usage, and @apply on base layer classes. Documentation includes eighteen gotchas with symptom-cause-fix tables covering tw-animate-css imports, WCAG contrast pairing for foreground tokens, and chart color variables. Developers reach for it when setting up Tailwind v4 theming, fixing colours after upgrade, or troubleshooting shadcn dark mode and @theme inline conflicts.

  • Implements mandatory four-step CSS variable to @theme inline to utility class architecture.
  • Uses @tailwindcss/vite plugin and deletes tailwind.config.ts for Tailwind v4 projects.
  • Provides ThemeProvider and ModeToggle patterns for class-based dark mode switching.
  • Documents eighteen gotchas including double hsl wrapping and @layer base placement errors.
  • Configures components.json with empty tailwind config path and cssVariables enabled.

Tailwind Theme Builder by the numbers

  • 2,871 all-time installs (skills.sh)
  • +43 installs in the week ending Jul 29, 2026 (Skillselion tracking)
  • Ranked #183 of 2,244 Frontend Development skills by installs in the Skillselion catalog
  • Security screen: MEDIUM risk (skills.sh audit)
  • Data as of Jul 31, 2026 (Skillselion catalog sync)
At a glance

tailwind-theme-builder capabilities & compatibility

Capabilities
css variable token setup · @theme inline mapping · dark mode provider wiring · vite tailwind plugin config · v3 to v4 migration troubleshooting
Use cases
frontend · ui design
npx skills add https://github.com/jezweb/claude-skills --skill tailwind-theme-builder

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs2.9k
repo stars★ 946
Security audit3 / 3 scanners passed
Last updatedJuly 2, 2026
Repositoryjezweb/claude-skills ↗

How do I set up Tailwind v4 theming with shadcn/ui colours and dark mode without breaking @theme inline or @apply after upgrade?

Set up Tailwind v4 with shadcn/ui theming, @theme inline CSS variables, dark mode toggle, and v3 migration troubleshooting.

Who is it for?

Developers migrating to Tailwind v4 or wiring shadcn/ui CSS variable theming with class-based dark mode in Vite React apps.

Skip if: Skip when the stack is Tailwind v3 with tailwind.config.ts theming or a non-React framework without the documented pattern.

When should I use this skill?

User mentions Tailwind v4 setup, shadcn colours, dark mode toggle, tw-animate-css errors, or v3 to v4 migration issues.

What you get

Configured index.css, Vite plugin, ThemeProvider, mode toggle, and components.json with semantic utilities like bg-background working in light and dark modes.

  • Configured `src/index.css` theme file
  • Light and dark CSS variable token set
  • shadcn-compatible `components.json` settings

By the numbers

  • Follows the official shadcn/ui Tailwind v4 documentation pattern with 3-step CSS variable setup

Files

SKILL.mdMarkdownGitHub ↗

Tailwind Theme Builder

Set up a fully themed Tailwind v4 + shadcn/ui project with dark mode. Produces configured CSS, theme provider, and working component library.

Architecture: The Four-Step Pattern

Tailwind v4 requires a specific architecture for CSS variable-based theming. This pattern is mandatory -- skipping or modifying steps breaks the theme.

How It Works

CSS Variable Definition --> @theme inline Mapping --> Tailwind Utility Class
--background           --> --color-background     --> bg-background
(with hsl() wrapper)      (references variable)     (generated class)

Dark mode switching:

ThemeProvider toggles .dark class on <html>
  --> CSS variables update automatically (.dark overrides :root)
  --> Tailwind utilities reference updated variables
  --> UI updates without re-render

Best Practices

  • Semantic names: Use --primary not --blue-500
  • Foreground pairing: Every background colour needs a foreground (--primary + --primary-foreground)
  • WCAG contrast: Normal text 4.5:1, large text 3:1, UI components 3:1
  • Chart colours: Use separate variables with @theme inline mapping, reference via var(--chart-1) in style props

---

Workflow

Step 1: Install Dependencies

pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node tw-animate-css
pnpm dlx shadcn@latest init

# Delete v3 config if it exists
rm -f tailwind.config.ts

Step 2: Configure Vite

Copy assets/vite.config.ts or add the Tailwind plugin:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: { alias: { '@': path.resolve(__dirname, './src') } }
})

Step 3: Four-Step CSS Architecture (Mandatory)

This exact order is required. Skipping steps breaks the theme.

src/index.css:

@import "tailwindcss";
@import "tw-animate-css";

/* 1. Define CSS variables at root (NOT inside @layer base) */
:root {
  --background: hsl(0 0% 100%);
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  --primary-foreground: hsl(210 40% 98%);
  /* ... all semantic tokens */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  --primary-foreground: hsl(222.2 47.4% 11.2%);
}

/* 2. Map variables to Tailwind utilities */
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

/* 3. Apply base styles (NO hsl() wrapper here) */
@layer base {
  body {
    background-color: var(--background);
    color: var(--foreground);
  }
}

Result: bg-background, text-primary etc. work automatically. Dark mode switches via .dark class -- no dark: variants needed for semantic colours.

Step 4: Set Up Dark Mode

Copy assets/theme-provider.tsx to your components directory, then wrap your app:

import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
    <App />
  </ThemeProvider>
)

Add a theme toggle -- install the dropdown menu then use the ModeToggle component below:

pnpm dlx shadcn@latest add dropdown-menu
// src/components/mode-toggle.tsx
import { Moon, Sun } from "lucide-react"
import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { useTheme } from "@/components/theme-provider"

export function ModeToggle() {
  const { setTheme } = useTheme()

  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="outline" size="icon">
          <Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
          <Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
          <span className="sr-only">Toggle theme</span>
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end">
        <DropdownMenuItem onClick={() => setTheme("light")}>Light</DropdownMenuItem>
        <DropdownMenuItem onClick={() => setTheme("dark")}>Dark</DropdownMenuItem>
        <DropdownMenuItem onClick={() => setTheme("system")}>System</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

Step 5: Configure components.json

{
  "tailwind": {
    "config": "",
    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true
  }
}

"config": "" is critical -- v4 doesn't use tailwind.config.ts.

---

Critical Rules

Always:

  • Wrap colours with hsl() in :root/.dark
  • Use @theme inline to map all CSS variables
  • Use @tailwindcss/vite plugin (NOT PostCSS)
  • Delete tailwind.config.ts if it exists

Never:

  • Put :root/.dark inside @layer base
  • Use .dark { @theme { } } (v4 doesn't support nested @theme)
  • Double-wrap: hsl(var(--background))
  • Use @apply with @layer base classes (use @utility instead)

---

All 18 Gotchas

Quick Diagnosis

#SymptomCauseFix
1Variables ignored / theme broken:root inside @layer baseMove :root and .dark to root level
2Dark mode colours not switching.dark { @theme { } }Use CSS variables + single @theme inline
3Colours all black/whiteDouble hsl() wrappingUse var(--background) not hsl(var(...))
4bg-primary not generatedColours in tailwind.config.tsDelete config, use @theme inline
5bg-background class missingNo @theme inline blockAdd @theme inline mapping variables
6shadcn components breakcomponents.json has config pathSet "config": "" (empty string)
7Tailwind not processingUsing PostCSS pluginSwitch to @tailwindcss/vite plugin
8@/ imports failMissing path aliasesAdd paths to tsconfig.app.json
9Redundant dark: variantsUsing dark:bg-primary-darkJust use bg-primary -- variables handle it
10Hardcoded colours everywhereUsing bg-blue-600 dark:bg-blue-400Use semantic tokens: bg-primary
11Class merging bugsString concatenation for classesUse cn() from @/lib/utils
12Radix Select crashesEmpty string value value=""Use value="placeholder"
13Wrong Tailwind versionInstalled tailwindcss@^3Install tailwindcss@^4.1.0 + @tailwindcss/vite
14Missing peer depsOnly installed tailwindcssAlso install clsx, tailwind-merge, @types/node
15Broken in dark modeOnly tested light modeTest light, dark, system, and toggle transitions
16Fails WCAG contrastLooks fine visuallyCheck ratios: 4.5:1 normal text, 3:1 large/UI
17Build fails on animation importUsing tailwindcss-animate (deprecated)Use tw-animate-css or native CSS animations
18CSS priority issuesDuplicate @layer base after shadcn initMerge into single @layer base block

Gotcha Details with Code Examples

#1 -- :root inside @layer base

Tailwind v4 strips CSS outside @theme/@layer, but :root must be at root level to persist. This is the most common setup failure.

WRONG:

@layer base {
  :root { --background: hsl(0 0% 100%); }
}

CORRECT:

:root { --background: hsl(0 0% 100%); }
@layer base {
  body { background-color: var(--background); }
}

#2 -- Nested @theme

Tailwind v4 does not support @theme inside selectors. Use CSS variables in :root/.dark with a single @theme inline block.

WRONG:

@theme { --color-primary: hsl(0 0% 0%); }
.dark { @theme { --color-primary: hsl(0 0% 100%); } }

CORRECT:

:root { --primary: hsl(0 0% 0%); }
.dark { --primary: hsl(0 0% 100%); }
@theme inline { --color-primary: var(--primary); }

#3 -- Double hsl() wrapping

Variables already contain hsl(). Double-wrapping creates hsl(hsl(...)).

WRONG: background-color: hsl(var(--background)); CORRECT: background-color: var(--background);

#4 -- Colours in tailwind.config.ts

Tailwind v4 completely ignores theme.extend.colors in config files. Delete the file or leave it empty. Set "config": "" in components.json.

#5 -- Missing @theme inline

Without @theme inline, Tailwind has no knowledge of your CSS variables. Utility classes like bg-background simply won't be generated.

WRONG:

:root { --background: hsl(0 0% 100%); }
/* No @theme inline block -- bg-background won't exist */

CORRECT:

:root { --background: hsl(0 0% 100%); }
@theme inline { --color-background: var(--background); }

#7 -- PostCSS vs Vite plugin

WRONG:

export default defineConfig({
  css: { postcss: './postcss.config.js' }  // Old v3 way
})

CORRECT:

import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
  plugins: [react(), tailwindcss()]  // v4 way
})

#8 -- Path aliases

Add to tsconfig.app.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  }
}

#11 -- cn() utility for class merging

WRONG: ` className={base ${isActive && 'active'}} CORRECT: className={cn("base", isActive && "active")}`

cn() from @/lib/utils properly merges and deduplicates Tailwind classes.

#12 -- Radix Select empty value

Radix UI Select does not allow empty string values. Use value="placeholder" instead of value="".

#14 -- Required dependencies

{
  "dependencies": {
    "tailwindcss": "^4.1.0",
    "@tailwindcss/vite": "^4.1.0",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1"
  },
  "devDependencies": {
    "@types/node": "^24.0.0"
  }
}

#17 -- tw-animate-css

tailwindcss-animate is deprecated in Tailwind v4. shadcn/ui docs may still reference it. Causes build failures and import errors. Use tw-animate-css or @tailwindcss/motion instead.

#18 -- Duplicate @layer base after shadcn init

shadcn init adds its own @layer base block. Check src/index.css immediately after running init and merge any duplicate blocks into one.

WRONG:

@layer base { body { background-color: var(--background); } }
@layer base { * { border-color: hsl(var(--border)); } }  /* duplicate from shadcn */

CORRECT:

@layer base {
  * { border-color: var(--border); }
  body { background-color: var(--background); color: var(--foreground); }
}

Prevention Checklist

  • [ ] No tailwind.config.ts file (or it's empty)
  • [ ] components.json has "config": ""
  • [ ] All colors have hsl() wrapper in :root
  • [ ] @theme inline maps all variables
  • [ ] @layer base doesn't wrap :root
  • [ ] Theme provider wraps app
  • [ ] Tested in light, dark, and system modes
  • [ ] All text has sufficient contrast

---

Dark Mode Testing Checklist

  • [ ] Light mode displays correctly
  • [ ] Dark mode displays correctly
  • [ ] System mode respects OS setting
  • [ ] Theme persists after page refresh
  • [ ] Toggle component shows current state
  • [ ] All text has proper contrast
  • [ ] No flash of wrong theme on load
  • [ ] Works in incognito mode (graceful fallback)

---

Asset Files

Copy from assets/ directory:

  • index.css -- Complete CSS with all colour variables
  • components.json -- shadcn/ui v4 config
  • vite.config.ts -- Vite + Tailwind plugin
  • theme-provider.tsx -- Dark mode provider
  • utils.ts -- cn() utility

Reference Files

  • references/migration-guide.md -- v3 to v4 migration

Official Documentation

  • shadcn/ui Tailwind v4 Guide: https://ui.shadcn.com/docs/tailwind-v4
  • shadcn/ui Dark Mode (Vite): https://ui.shadcn.com/docs/dark-mode/vite
  • shadcn/ui Theming: https://ui.shadcn.com/docs/theming
  • Tailwind v4 Docs: https://tailwindcss.com/docs
  • Tailwind Dark Mode: https://tailwindcss.com/docs/dark-mode

Related skills

vercel-labsVercel React Best PracticesAutomatically apply Vercel’s official React and Next.js performance rules during code generation and review.576k29.4kvercel-labsVercel Composition PatternsGenerate and refactor React components that stay maintainable as complexity grows without boolean prop explosion.261k29.4kshadcnShadcnAdd, compose, search, fix, and style production-grade React components directly from source without leaving their editor.249k120kxixu-meDevelop UserscriptsCorrectly write, debug, and package userscripts for Tampermonkey and ScriptCat with proper metadata, GM APIs, and runtime decisions.224k72leonxlnxMinimalist UiGenerate clean, editorial-style web interfaces with warm monochrome palettes, typographic hierarchy, bento grids and flat components that feel premium and utilita201k66.9kvercel-labsVercel React Native SkillsEnsure AI agents generate and refactor React Native code that follows performance best practices without common rendering and list pitfalls.173k29.4k

How it compares

Use tailwind-theme-builder instead of manual Tailwind config editing when shadcn/ui cssVariables and v4 `@theme inline` conventions must align.

FAQ

Where should :root and .dark variables be defined?

Define them at the root level, not inside @layer base, with hsl() wrappers on colour values.

Which Vite integration does v4 require?

Use the @tailwindcss/vite plugin instead of PostCSS and remove tailwind.config.ts.

How does dark mode switch semantic colours?

ThemeProvider toggles the .dark class on html so variables update and utilities like bg-background follow automatically.

Is Tailwind Theme Builder safe to install?

skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

Frontend Developmentui
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.