tailwind-theme-builder

intent

build a fully themed tailwind v4 + shadcn/ui project with dark mode support. this skill sets up css variable-based theming via @theme inline mapping, installs the tailwind vite plugin, configures a theme provider for dark mode toggling, and validates the setup works across light/dark/system modes. use this when starting a new react + tailwind v4 project that needs semantic color tokens, dark mode, and shadcn/ui components working out of the box.

inputs

• node 18+ with pnpm installed
• existing react project (vite-based)
• write access to: vite.config.ts, src/index.css, tsconfig.app.json, components.json, src/ directory
• no existing tailwind.config.ts (if one exists, you will delete it)
• env or config: none required (this is local setup only)

procedure

step 1: install dependencies

run these commands in order:

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

after shadcn init completes, delete any v3 config:

rm -f tailwind.config.ts

input: project root with package.json and src/ directory. output: tailwindcss@^4.1.0, @tailwindcss/vite installed; shadcn/ui initialized; no tailwind.config.ts file.

step 2: configure vite

update vite.config.ts to include the tailwind plugin and path alias:

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') } }
})

also update tsconfig.app.json to enable path aliases:

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

input: vite.config.ts, tsconfig.app.json. output: vite configured with @tailwindcss/vite plugin; @ alias resolves to src/.

step 3: configure css architecture (mandatory order)

create or replace src/index.css with this exact structure. order matters: variables first, then @theme inline, then @layer base.

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

/* 1. define css variables at root level (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%);
  --secondary: hsl(210 40% 96%);
  --secondary-foreground: hsl(222.2 47.4% 11.2%);
  --destructive: hsl(0 84.2% 60.2%);
  --destructive-foreground: hsl(210 40% 98%);
  --muted: hsl(210 40% 96%);
  --muted-foreground: hsl(215.4 16.3% 46.9%);
  --accent: hsl(217.2 91.2% 59.8%);
  --accent-foreground: hsl(222.2 47.4% 11.2%);
  --border: hsl(214.3 31.8% 91.4%);
  --input: hsl(214.3 31.8% 91.4%);
  --ring: hsl(221.2 83.2% 53.3%);
  --chart-1: hsl(12 76% 61%);
  --chart-2: hsl(173 58% 39%);
  --chart-3: hsl(197 37% 24%);
  --chart-4: hsl(43 74% 66%);
  --chart-5: hsl(27 87% 67%);
}

.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%);
  --secondary: hsl(217.2 32.6% 17.5%);
  --secondary-foreground: hsl(210 40% 98%);
  --destructive: hsl(0 62.8% 30.6%);
  --destructive-foreground: hsl(210 40% 98%);
  --muted: hsl(217.2 32.6% 17.5%);
  --muted-foreground: hsl(215 20.2% 65.1%);
  --accent: hsl(217.2 91.2% 59.8%);
  --accent-foreground: hsl(222.2 47.4% 11.2%);
  --border: hsl(217.2 32.6% 17.5%);
  --input: hsl(217.2 32.6% 17.5%);
  --ring: hsl(212.7 26.8% 83.9%);
  --chart-1: hsl(12 76% 61%);
  --chart-2: hsl(173 58% 39%);
  --chart-3: hsl(197 37% 24%);
  --chart-4: hsl(43 74% 66%);
  --chart-5: hsl(27 87% 67%);
}

/* 2. map variables to tailwind utilities via @theme inline */
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);
}

/* 3. apply base styles (use var() not hsl() here) */
@layer base {
  * {
    border-color: var(--border);
  }

  body {
    background-color: var(--background);
    color: var(--foreground);
  }
}

input: src/index.css path, semantic color palette (hsl tuples for light and dark). output: src/index.css with :root/.dark at root level, @theme inline block present, @layer base applied to body.

step 4: set up dark mode provider

create src/components/theme-provider.tsx:

import { createContext, useContext, useEffect, useState } from "react"

type Theme = "light" | "dark" | "system"

interface ThemeContextType {
  theme: Theme
  setTheme: (theme: Theme) => void
}

const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

export function ThemeProvider({
  children,
  defaultTheme = "system",
  storageKey = "vite-ui-theme",
}: {
  children: React.ReactNode
  defaultTheme?: Theme
  storageKey?: string
}) {
  const [theme, setThemeState] = useState<Theme>(
    () => (localStorage.getItem(storageKey) as Theme) || defaultTheme
  )

  useEffect(() => {
    const root = document.documentElement
    const systemTheme = window.matchMedia("(prefers-color-scheme: dark)").matches
      ? "dark"
      : "light"
    const activeTheme = theme === "system" ? systemTheme : theme

    root.classList.remove("light", "dark")
    root.classList.add(activeTheme)
    localStorage.setItem(storageKey, theme)
  }, [theme, storageKey])

  const setTheme = (newTheme: Theme) => setThemeState(newTheme)

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

export function useTheme() {
  const context = useContext(ThemeContext)
  if (!context) {
    throw new Error("useTheme must be used within ThemeProvider")
  }
  return context
}

wrap your app with ThemeProvider in main.tsx or your entry point:

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

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

input: src/components/ directory, main.tsx or entry point. output: theme-provider.tsx created; app wrapped with ThemeProvider; localStorage persists theme choice.

step 5: add theme toggle component

install shadcn dropdown menu:

pnpm dlx shadcn@latest add dropdown-menu

create 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>
  )
}

input: shadcn dropdown-menu component, lucide-react icons. output: mode-toggle.tsx created and ready to drop into your navbar or header.

step 6: configure components.json

update or create components.json in your project root:

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

critical: set "config": "" (empty string). tailwind v4 does not use tailwind.config.ts.

input: components.json file. output: components.json with empty config path; shadcn add commands will reference src/index.css.

step 7: verify setup

run your dev server:

pnpm dev

test these checks in your browser:

• light mode: classes like bg-background, text-primary render with light colors
• dark mode toggle: click mode toggle, html element gains .dark class, colors switch
• system mode: set OS to dark, refresh, theme syncs
• persistence: toggle theme, refresh page, theme persists
• contrast: all text meets wcag (4.5:1 normal, 3:1 large/ui, 3:1 components)

input: running dev server, browser. output: visual confirmation of light/dark mode switching; console clear of errors; theme persists after refresh.

decision points

if you have an existing tailwind.config.ts file (from v3), delete it immediately before step 2. tailwind v4 ignores config files and uses @theme inline instead. keeping it causes confusion and potential conflicts.

if theme colors don't switch on dark mode toggle, verify:

• :root and .dark selectors are at root level in src/index.css (not inside @layer base)
• @theme inline block exists and maps all variables
• theme-provider.tsx correctly adds/removes .dark class on html element
• localStorage is not blocked by browser (test in incognito if unclear)

if @/ imports fail, check tsconfig.app.json has "paths": { "@/": ["./src/"] }. vite.config.ts alone is not enough.

if shadcn add fails or components don't work, verify components.json has "config": "" (empty string, not a path). shadcn v4 uses this to skip config file lookup.

if tailwind utilities like bg-background don't generate, ensure @theme inline block exists in src/index.css with all color mappings. missing @theme inline is the most common cause.

if you need chart colors (separate from semantic tokens), reference them via style prop: style={{ color: 'var(--chart-1)' }}. do not try to create chart-1 utilities in @theme inline; they are for inline reference only.

if a component crashes or renders incorrectly in dark mode but works in light, test wcag contrast ratios. dark colors may be too close to background color. use contrast checker tool and adjust .dark hsl() values.

output contract

success means:

• src/index.css exists with :root/.dark at root level, @theme inline mapping all variables, and @layer base applying to body
• vite.config.ts imports and uses @tailwindcss/vite plugin
• tsconfig.app.json has @ alias pointing to ./src/*
• components.json has "config": "" and "css": "src/index.css"
• src/components/theme-provider.tsx exported useTheme hook and ThemeProvider wrapper
• src/components/mode-toggle.tsx exported ModeToggle component
• no tailwind.config.ts file exists
• app wrapped with ThemeProvider in main.tsx or entry point
• tailwindcss@^4.1.0, @tailwindcss/vite, tw-animate-css, clsx, tailwind-merge installed
• pnpm dev runs without errors

data format: css variables are hsl(h s% l%) tuples; dark mode state stored in localStorage under key specified in ThemeProvider (default: "vite-ui-theme"); theme value is one of "light", "dark", or "system".

file locations:

• src/index.css (css variables and @theme inline)
• vite.config.ts (vite plugin config)
• tsconfig.app.json (path aliases)
• components.json (shadcn config)
• src/components/theme-provider.tsx (context provider)
• src/components/mode-toggle.tsx (ui toggle)

outcome signal

you know this worked when:

• dev server starts with zero tailwind warnings
• bg-background, text-foreground, bg-primary classes render correctly in light mode
• toggling dark mode via ModeToggle dropdown visibly swaps colors (no page reload, no delay)
• refreshing the page preserves the selected theme (light/dark/system)
• inspector shows .dark class on html element in dark mode, not present in light mode
• all text meets wcag contrast requirements in both light and dark
• shadcn/ui components (buttons, cards, dropdowns) inherit theme colors automatically
• no hsl(var(...)) or double-wrapped colors appear in computed styles
• switching to system dark mode in OS prefs auto-updates app theme when set to "system"
• all semantic color tokens (primary, secondary, destructive, muted, accent, border) work as utility classes (bg-primary, text-muted, border-input)