# Configuring Tailwind CSS v4 OKLCH Design Tokens for Cloned Websites

> Learn to configure Tailwind CSS v4 OKLCH design tokens for cloned websites. Achieve pixel-perfect color fidelity with perceptually uniform color space values and CSS custom properties.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: configuration
- Published: 2026-07-09

---

**The AI Website Cloner Template uses Tailwind CSS v4 with OKLCH color tokens defined as CSS custom properties in [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css), eliminating the need for [`tailwind.config.js`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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:

```tsx
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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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:

```tsx
<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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css):

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

```

Then reference the new token in components:

```tsx
<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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css)** – Central location for all OKLCH design tokens, Tailwind imports, and base layer utilities
- **[`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/tailwind.config.js) by storing OKLCH tokens as CSS custom properties in [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/tailwind.config.js) or [`tailwind.config.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/tailwind.config.ts) file optional. The AI Website Cloner Template relies entirely on [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/globals.css), while the Tailwind utilities remain unchanged (e.g., `bg-background` automatically resolves to the dark value when inside a `.dark` container).