# How Design Tokens Are Identified and Applied to a Next.js Project's globals.css

> Learn how design tokens are identified and applied to a Next.js project's globals.css. This guide explains automatic theme generation using OKLCH colors and Tailwind.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-06-23

---

**The AI Website Cloner extracts visual styles from target sites and maps them to CSS custom properties in [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css), enabling automatic theme generation through OKLCH color values and Tailwind utility classes.**

The `JCodesMore/ai-website-cloner-template` repository automates design system extraction by identifying **design tokens** from any target website and injecting them into a Next.js application's global stylesheet. This process bridges the gap between visual inspection and code implementation, using AI-driven analysis to populate CSS custom properties that power the entire UI through shadcn UI conventions.

## How Design Tokens Are Identified

The identification process relies on an automated inspection workflow that analyzes computed styles from live websites and translates them into a standardized token system.

### Site Inspection and Style Extraction

The AI-driven `clone-website` workflow initiates a headless browser session to crawl the target URL. During this phase, it collects computed styles, screenshots, and layout data from every DOM element. This raw data feeds into the color extraction pipeline, where the system reads specific CSS values including `color`, `background-color`, and related properties to build a comprehensive palette.

### Color Aggregation and OKLCH Conversion

Once extracted, the color values undergo aggregation to eliminate duplicates and identify the core palette. The system converts these colors into **OKLCH** format—a perceptual color space that ensures consistent lightness across hues and is fully supported by Tailwind CSS v4. This conversion preserves color fidelity while enabling semantic organization of the design tokens.

### Mapping to shadcn UI Token Standards

The aggregated palette maps against default shadcn UI token names including `background`, `foreground`, `primary`, and `muted`. When an extracted color lacks a direct counterpart in the standard token set, the workflow generates a custom property to accommodate the unique brand color. This mapping ensures compatibility with shadcn UI components while preserving the original site's visual identity. The complete extraction logic is documented in the workflow configuration at [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md).

## Token Application in globals.css

After extraction, the design tokens are injected into [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css) where they become available to the entire component tree through CSS custom properties.

### Declaring Light and Dark Mode Variables

The stylesheet defines tokens within two distinct scopes to support automatic theme switching. The `:root` selector establishes the light-mode defaults, while the `.dark` class provides dark-mode overrides that Tailwind's `dark:` variant activates when applied to the `<html>` element.

```css
/* src/app/globals.css – token definitions */
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  /* …other tokens… */
}

/* Dark-mode token overrides */
.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  /* …other overrides… */
}

```

### Connecting Tokens to Tailwind Utilities

The tokens are wired into Tailwind's utility layer through the `@layer base` directive. This approach allows components to reference semantic classes like `bg-background` and `text-foreground`, which resolve to the underlying CSS variables.

```css
@layer base {
  body {
    @apply bg-background text-foreground;  /* uses the custom properties */
  }
}

```

Because Tailwind's `bg-<color>` and `text-<color>` utilities read these CSS variables, any component using semantic token classes automatically reflects the extracted design system without hardcoded values.

## Project Architecture and File Dependencies

The token system relies on specific configuration files that wire the CSS custom properties into the Next.js runtime environment.

[`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css) serves as the central registry for design tokens, importing Tailwind directives and shadcn utilities while declaring the OKLCH color variables. This file is imported at line 3 of [`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx), ensuring the tokens are available to the entire application during server-side rendering and hydration.

[`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts) provides the `cn()` utility function that merges Tailwind class strings, enabling components to reference token-based classes cleanly while handling conditional styling logic. The `postcss.config.mjs` file configures the PostCSS pipeline to process Tailwind directives, ensuring the `@apply` rules and CSS variables compile correctly for production.

## Summary

- The AI inspection workflow extracts computed styles from target websites using a headless browser, then aggregates colors into an OKLCH palette.
- Design tokens map to shadcn UI naming conventions and generate CSS custom properties in [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css) within `:root` and `.dark` scopes.
- The `@layer base` directive in [`globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/globals.css) connects these variables to Tailwind utilities via `@apply`, enabling semantic classes like `bg-background`.
- File dependencies include [`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx) (CSS import), [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts) (class merging), and `postcss.config.mjs` (build pipeline configuration).

## Frequently Asked Questions

### What color format does the AI Website Cloner use for design tokens?

The system converts extracted colors to **OKLCH**, a perceptual color space that maintains consistent lightness across different hues. This format is natively supported by Tailwind CSS v4 and provides better color fidelity than RGB or HSL for design system automation.

### How does the template support both light and dark modes?

The template declares design tokens twice in [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css): once within the `:root` selector for light mode defaults, and again within the `.dark` class for dark mode overrides. When Tailwind applies the `dark` class to the HTML element, the CSS variables automatically switch values, enabling instant theme toggling without JavaScript color manipulation.

### Where is the design token extraction logic documented?

The extraction workflow is documented in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md), which describes the headless browser inspection process, color aggregation algorithms, and the mapping strategy that aligns extracted values with shadcn UI token names like `primary` and `muted`.

### How do components access the design tokens defined in globals.css?

Components access tokens through Tailwind utility classes generated from the CSS variables. The `cn()` utility in [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts) merges these classes, allowing components to use semantic references like `bg-background` and `text-foreground`. These utilities resolve to the CSS custom properties defined in [`globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/globals.css), ensuring consistent styling across the application.