Configuring Tailwind CSS v4 OKLCH Design Tokens for Cloned Websites

The AI Website Cloner Template uses Tailwind CSS v4 with OKLCH color tokens defined as CSS custom properties in src/app/globals.css, eliminating the need for tailwind.config.js while enabling pixel-perfect color fidelity through perceptually uniform color space values.

The JCodesMore/ai-website-cloner-template ships with a modern styling architecture that replaces traditional JavaScript configuration with pure CSS-based design tokens. By leveraging Tailwind CSS v4's CSS-first configuration and the OKLCH color space, the template enables AI agents to extract and replicate exact color values from target websites with mathematical precision.

How the OKLCH Token System Works

The template stores all design tokens in src/app/globals.css using CSS custom properties rather than a JavaScript configuration file. This approach aligns with Tailwind CSS v4's shift toward CSS-native configuration.

Global Token Definitions

The :root selector in src/app/globals.css defines the complete color palette using OKLCH notation, which represents colors by lightness, chroma, and hue values. For example, the primary color token is defined as --primary: oklch(0.205 0 0); under the :root block. A matching dark mode set exists under the .dark class selector, automatically swapping values when the parent container has the dark class.

Tailwind v4 Runtime Imports

The global stylesheet imports the core Tailwind runtime using @import "tailwindcss"; at the top of the file. Additional imports include the animation helpers from tw-animate-css and the Shadcn UI preset via @import "shadcn/tailwind.css";. These imports establish the utility-first framework without requiring a separate tailwind.config.ts file.

Dark Mode Custom Variant

A custom variant declaration @custom-variant dark (&:is(.dark *)); enables the dark: prefix utility. This allows you to write dark:bg-background or dark:text-foreground directly in JSX components. The variant works by checking if any ancestor element has the .dark class, then applying the corresponding CSS variable values defined later in the same file.

Base Layer Utility Mapping

The @layer base section maps token variables to Tailwind utilities using @apply directives. The body element receives bg-background text-foreground through this layer, ensuring the entire page uses the OKLCH-based color system immediately. This wiring connects the CSS custom properties to standard Tailwind utility classes like bg-, text-, border-, and ring-.

Implementing OKLCH Tokens in Components

Because the tokens are plain CSS variables, components reference them through standard Tailwind utilities. The template provides the cn() utility function in src/lib/utils.ts, which wraps tailwind-merge to safely combine class strings while preserving custom token classes.

Using Standard Utility Classes

The following component demonstrates how to use the OKLCH-based destructive color token:

export function Alert({ children }: { children: React.ReactNode }) {
  return (
    <div className="rounded-md border border-destructive bg-destructive/10 p-4 text-destructive">
      {children}
    </div>
  )
}

The border-destructive, bg-destructive/10, and text-destructive classes map to the --destructive OKLCH variable defined in globals.css. The /10 opacity modifier applies after Tailwind resolves the token, preserving the original hue while adjusting transparency.

Dark Mode Implementation

Apply the dark mode variant using the standard dark: prefix:

<button className="rounded-md bg-primary text-primary-foreground dark:bg-primary dark:text-primary-foreground">
  Submit
</button>

The dark: prefix triggers the custom variant defined in globals.css, swapping the light-mode --primary and --primary-foreground tokens for their dark-mode counterparts automatically when an ancestor has the .dark class.

Extending the Token Palette

To add brand-specific colors, extend the :root block in src/app/globals.css:

:root {
  --brand-accent: oklch(0.45 0.4 250);
}

Then reference the new token in components:

<div className="border border-brand-accent text-brand-accent">
  Brand-specific callout
</div>

Because the base layer already wires utilities to CSS variables, the new token works immediately without additional JavaScript configuration.

Key Configuration Files

Several files work together to maintain the Tailwind CSS v4 OKLCH architecture:

• src/app/globals.css – Central location for all OKLCH design tokens, Tailwind imports, and base layer utilities
• src/lib/utils.ts – Exports the cn() utility that safely merges Tailwind class strings while preserving custom token classes
• postcss.config.mjs – Configures PostCSS to process Tailwind CSS v4 during the build process
• package.json – Declares Tailwind CSS v4 and related dependencies including tailwind-merge and tw-animate-css

Summary

• CSS-First Configuration: The template eliminates tailwind.config.js by storing OKLCH tokens as CSS custom properties in src/app/globals.css.
• Perceptual Color Accuracy: OKLCH values ensure cloned websites match target colors with mathematical precision across light and dark modes.
• Automatic Dark Mode: The @custom-variant dark declaration enables seamless dark: utilities that respond to the .dark class selector.
• Zero Config Extensions: Adding new colors requires only defining CSS variables in :root, as utilities are pre-wired to read from custom properties.
• Build Integration: PostCSS processes Tailwind CSS v4 through postcss.config.mjs, maintaining compatibility with the Next.js build pipeline.

Frequently Asked Questions

What is OKLCH and why does the template use it?

OKLCH is a perceptually uniform color space that represents colors using lightness, chroma, and hue components. The template uses OKLCH because it provides better color consistency across different devices and lighting conditions compared to RGB or HSL, ensuring that AI-extracted colors from cloned websites maintain their visual fidelity when converted to design tokens.

Do I need a tailwind.config.js file with this setup?

No. Tailwind CSS v4 shifts configuration to CSS, making the traditional tailwind.config.js or tailwind.config.ts file optional. The AI Website Cloner Template relies entirely on src/app/globals.css for theme configuration, using CSS imports and custom properties rather than JavaScript exports.

How do I add custom colors to the design system?

Define new CSS custom properties in the :root selector of src/app/globals.css using OKLCH notation (e.g., --custom: oklch(0.5 0.2 180);). Tailwind utilities automatically recognize these variables, allowing immediate use of classes like bg-custom, text-custom, and border-custom without restarting the development server.

How does dark mode switching work in this architecture?

Dark mode operates through a CSS class strategy. When the root HTML element or any parent container has the .dark class, the custom variant @custom-variant dark (&:is(.dark *)); activates. This swaps the CSS variable values to those defined under the .dark selector in globals.css, while the Tailwind utilities remain unchanged (e.g., bg-background automatically resolves to the dark value when inside a .dark container).

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