How Tailwind CSS v4 Is Configured with oklch Design Tokens in the AI Website Cloner Template

This template configures Tailwind CSS v4 using CSS custom properties with oklch color notation, eliminating the need for a tailwind.config.js file while supporting light and dark modes through the shadcn/ui preset.

The JCodesMore/ai-website-cloner-template demonstrates a modern approach to styling by combining Tailwind CSS v4 with a token-based design system. Instead of relying on JavaScript configuration files, the setup leverages native CSS variables defined in oklch color space to drive the entire visual theme.

Installation and Build Integration

Tailwind CSS v4 operates differently from previous versions by integrating deeply with the CSS processing pipeline rather than using a JavaScript configuration object.

Package Dependencies

The template declares Tailwind v4 as a development dependency in package.json. This version introduces a new architecture where the compiler runs as a PostCSS plugin rather than a standalone utility.

{
  "devDependencies": {
    "tailwindcss": "^4"
  }
}

According to the source code at package.json lines 56-58, this dependency enables the CSS-first configuration approach.

PostCSS Configuration

The build process is configured in postcss.config.mjs to process styles through Tailwind's new PostCSS plugin. This setup handles the @import directives and variable substitution at build time.

export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

This configuration appears at lines 1-4 of postcss.config.mjs, establishing the compilation pipeline that processes the oklch-based design tokens.

Global Styles and Token Definition

The heart of the configuration lives in the global stylesheet, where oklch color values are defined as CSS custom properties and mapped to semantic design tokens.

Importing Tailwind v4

The root stylesheet at src/app/globals.css begins by importing Tailwind's base layers and the shadcn/ui preset. This single import statement activates the entire utility-first framework.

@import "tailwindcss";

This import appears at lines 1-4 of src/app/globals.css, replacing the traditional @tailwind directives used in v3.

Defining oklch Color Variables

The template defines two distinct color palettes using oklch notation within CSS variables. The :root selector establishes the light mode values, while the .dark class selector overrides these for dark mode.

In src/app/globals.css lines 52-84, the light mode tokens are declared:

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  /* additional tokens... */
}

For dark mode, lines 86-118 provide the contrasting values:

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  /* additional tokens... */
}

The oklch color space provides perceptually uniform colors, ensuring that lightness adjustments appear consistent to human vision across different hues.

Shadcn/ui Preset Integration

The shadcn/ui preset bridges the CSS variables with Tailwind's utility class system. It automatically maps the custom properties to standard Tailwind color utilities like bg-background, text-foreground, and border-border.

This integration eliminates the need for a tailwind.config.js file entirely. The preset reads the -- prefixed variables from the CSS and exposes them as first-class Tailwind colors, allowing developers to use familiar utility classes while the actual values resolve to the oklch variables at runtime.

Practical Usage Examples

Components in the template consume these tokens through standard Tailwind utility classes. The values automatically adapt based on the presence of the .dark class on parent elements.

Basic Background and Text Colors

To apply the semantic background and foreground colors:

<div className="bg-background text-foreground p-4">
  This box uses the light-mode background token.
</div>

Dark Mode Variants

For explicit dark mode styling, the template uses the dark: prefix modifier:

<div className="dark:bg-background dark:text-foreground p-4">
  Dark-mode colors are applied via the .dark selector.
</div>

Interactive Components

The button component at src/components/ui/button.tsx demonstrates complex state handling with these tokens. Line 15 shows how hover states and dark mode adaptations combine:

<button
  className={cn(
    "border-border bg-background hover:bg-muted hover:text-foreground",
    "dark:border-input dark:bg-input/30 dark:hover:bg-input/50"
  )}
>
  Click me
</button>

The cn() utility merges these classes, allowing the component to respond to both user interactions and theme changes without JavaScript state management for colors.

Summary

• Tailwind CSS v4 runs as a PostCSS plugin configured in postcss.config.mjs, removing the need for a JavaScript configuration file.
• oklch color values are stored in CSS custom properties within src/app/globals.css, providing perceptually uniform colors for both light and dark modes.
• The shadcn/ui preset automatically maps these variables to Tailwind utility classes like bg-background and text-foreground.
• Theme switching occurs through the .dark class selector, which overrides the :root variables with dark mode equivalents.
• Components reference these tokens directly in their className props, enabling automatic adaptation to theme changes without prop drilling or context providers.

Frequently Asked Questions

Why does this template use oklch instead of hex or rgb colors?

The oklch color space provides perceptual uniformity, meaning that changing the lightness value produces consistent visual results regardless of the hue. This ensures that the template's gray scales and colored accents maintain predictable contrast ratios across light and dark modes, improving accessibility and visual consistency compared to sRGB-based formats.

Is a tailwind.config.js file required for this setup?

No explicit tailwind.config.js file is necessary. Tailwind CSS v4 is designed to work with CSS-based configuration, and the shadcn/ui preset handles the mapping of CSS variables to utility classes automatically. All design tokens reside in src/app/globals.css as standard CSS custom properties.

How do I add a new color token to the design system?

Define the new variable in both the :root and .dark selectors within src/app/globals.css using oklch notation. For example, add --accent: oklch(0.6 0.2 250); to the light theme and a corresponding dark variant. The shadcn/ui preset will automatically expose this as bg-accent, text-accent, and border-accent utilities without additional JavaScript configuration.

Where does the dark mode class get applied in the application?

The .dark class is typically applied to the root HTML or body element to trigger the dark mode variable overrides defined in src/app/globals.css lines 86-118. All child components then automatically receive the dark mode color values through the CSS variable cascade, enabling instant theme switching without re-rendering React components for color changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}