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

The AI Website Cloner extracts visual styles from target sites and maps them to CSS custom properties in 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.

Token Application in globals.css

After extraction, the design tokens are injected into 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.

/* 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.

@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 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, ensuring the tokens are available to the entire application during server-side rendering and hydration.

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 within :root and .dark scopes.
• The @layer base directive in globals.css connects these variables to Tailwind utilities via @apply, enabling semantic classes like bg-background.
• File dependencies include src/app/layout.tsx (CSS import), 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: 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, 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 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, ensuring consistent styling across the application.

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