Setup & catalog

Docs

Install Tailwind CSS

Nexus UI uses Tailwind v4 with the PostCSS plugin, CSS-first configuration, and OKLCH design tokens. Follow these steps on a fresh Next.js app or compare with this repository's postcss.config and globals.

1. Create a Next.js project

If you don't have a project yet, scaffold one with TypeScript and ESLint enabled — the same flags this repo uses:

npx create-next-app@latest my-app --typescript --eslint
cd my-app

2. Install packages

From your project root, install Tailwind and its PostCSS plugin. Tailwind v4 ships the PostCSS adapter as a separate package — you do not need autoprefixer for v4 projects.

npm install tailwindcss @tailwindcss/postcss

No tailwind.config.js file is needed for v4 — all configuration moves to CSS.

3. Configure PostCSS

Create or update postcss.config.mjs at your project root (this matches postcss.config.mjs in Nexus UI):

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

4. Set up globals.css

Replace your src/app/globals.css with a Tailwind v4 import and your design token definitions. Nexus UI uses OKLCH color values for consistent perceptual luminance across light and dark themes, and a @theme inline block to map shadcn-style CSS variables to Tailwind utilities.

@import "tailwindcss";

/* Map CSS variables to Tailwind color/radius utilities */
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.4);
  --font-sans: var(--font-inter), ui-sans-serif, system-ui, sans-serif;
  --font-mono: ui-monospace, "Cascadia Code", Menlo, Monaco, Consolas, monospace;
}

/* Light mode tokens */
html {
  --background: oklch(0.99 0.002 260);
  --foreground: oklch(0.16 0.015 260);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.16 0.015 260);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.16 0.015 260);
  --primary: oklch(0.28 0.02 260);
  --primary-foreground: oklch(0.99 0 0);
  --secondary: oklch(0.96 0.006 260);
  --secondary-foreground: oklch(0.25 0.015 260);
  --muted: oklch(0.96 0.006 260);
  --muted-foreground: oklch(0.48 0.015 260);
  --accent: oklch(0.94 0.008 260);
  --accent-foreground: oklch(0.18 0.015 260);
  --destructive: oklch(0.55 0.22 25);
  --border: oklch(0.90 0.008 260);
  --input: oklch(0.90 0.008 260);
  --ring: oklch(0.38 0.02 260);
  --radius: 0.625rem;
}

/* Dark mode tokens (add class="dark" to <html>) */
html.dark {
  --background: oklch(0.09 0.008 260);
  --foreground: oklch(0.97 0.006 260);
  --card: oklch(0.13 0.006 260);
  --card-foreground: oklch(0.97 0 0);
  --popover: oklch(0.13 0.006 260);
  --popover-foreground: oklch(0.97 0 0);
  --primary: oklch(0.82 0.02 260);
  --primary-foreground: oklch(0.12 0.015 260);
  --secondary: oklch(0.20 0.006 260);
  --secondary-foreground: oklch(0.97 0 0);
  --muted: oklch(0.20 0.006 260);
  --muted-foreground: oklch(0.62 0.006 260);
  --accent: oklch(0.20 0.006 260);
  --accent-foreground: oklch(0.97 0 0);
  --destructive: oklch(0.55 0.22 25);
  --border: oklch(0.25 0.006 260);
  --input: oklch(0.25 0.006 260);
  --ring: oklch(0.55 0.015 260);
}

Import this stylesheet from your root src/app/layout.tsx:

import "./globals.css";

5. Dark mode variant

Nexus UI applies dark mode via a .dark class on the <html> element (not the media strategy). Register the custom variant once in your globals, right after the Tailwind import:

@import "tailwindcss";

@custom-variant dark (&:is(.dark *));

Then toggle dark on <html> via your theme provider (next-themes or a custom script).

6. Start the dev server

npm run dev

Open http://localhost:3000. Tailwind utilities and your OKLCH tokens should be active. Next, add the cn() utility helper so components can merge class strings safely.

Why Tailwind v4?

Nexus UI is built entirely on Tailwind v4. Here is what changed and why it matters:

—No tailwind.config.js — All configuration lives in CSS — no JavaScript config file needed.
—CSS-first tokens — @theme inline maps CSS variables directly to utilities like bg-primary and text-foreground.
—OKLCH colors — Perceptually uniform color space — light and dark tokens stay consistent across hue and brightness.
—PostCSS plugin only — @tailwindcss/postcss replaces the old tailwindcss + autoprefixer pair.
—Native CSS layers — Tailwind v4 uses @layer internally, giving you cleaner cascade control with no extra config.
—Faster builds — The new Rust-based engine makes cold builds and incremental compiles significantly faster.

← Components library

4. Set up globals.css

@import "tailwindcss";

/* Map CSS variables to Tailwind color/radius utilities */
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.4);
  --font-sans: var(--font-inter), ui-sans-serif, system-ui, sans-serif;
  --font-mono: ui-monospace, "Cascadia Code", Menlo, Monaco, Consolas, monospace;
}

/* Light mode tokens */
html {
  --background: oklch(0.99 0.002 260);
  --foreground: oklch(0.16 0.015 260);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.16 0.015 260);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.16 0.015 260);
  --primary: oklch(0.28 0.02 260);
  --primary-foreground: oklch(0.99 0 0);
  --secondary: oklch(0.96 0.006 260);
  --secondary-foreground: oklch(0.25 0.015 260);
  --muted: oklch(0.96 0.006 260);
  --muted-foreground: oklch(0.48 0.015 260);
  --accent: oklch(0.94 0.008 260);
  --accent-foreground: oklch(0.18 0.015 260);
  --destructive: oklch(0.55 0.22 25);
  --border: oklch(0.90 0.008 260);
  --input: oklch(0.90 0.008 260);
  --ring: oklch(0.38 0.02 260);
  --radius: 0.625rem;
}

/* Dark mode tokens (add class="dark" to <html>) */
html.dark {
  --background: oklch(0.09 0.008 260);
  --foreground: oklch(0.97 0.006 260);
  --card: oklch(0.13 0.006 260);
  --card-foreground: oklch(0.97 0 0);
  --popover: oklch(0.13 0.006 260);
  --popover-foreground: oklch(0.97 0 0);
  --primary: oklch(0.82 0.02 260);
  --primary-foreground: oklch(0.12 0.015 260);
  --secondary: oklch(0.20 0.006 260);
  --secondary-foreground: oklch(0.97 0 0);
  --muted: oklch(0.20 0.006 260);
  --muted-foreground: oklch(0.62 0.006 260);
  --accent: oklch(0.20 0.006 260);
  --accent-foreground: oklch(0.97 0 0);
  --destructive: oklch(0.55 0.22 25);
  --border: oklch(0.25 0.006 260);
  --input: oklch(0.25 0.006 260);
  --ring: oklch(0.55 0.015 260);
}

Import this stylesheet from your root src/app/layout.tsx:

import "./globals.css";

5. Dark mode variant

Nexus UI applies dark mode via a .dark class on the <html> element (not the media strategy). Register the custom variant once in your globals, right after the Tailwind import:

@import "tailwindcss";

@custom-variant dark (&:is(.dark *));

Then toggle dark on <html> via your theme provider (next-themes or a custom script).

Why Tailwind v4?

Nexus UI is built entirely on Tailwind v4. Here is what changed and why it matters:

—No tailwind.config.js — All configuration lives in CSS — no JavaScript config file needed.

—CSS-first tokens — @theme inline maps CSS variables directly to utilities like bg-primary and text-foreground.

—OKLCH colors — Perceptually uniform color space — light and dark tokens stay consistent across hue and brightness.

—PostCSS plugin only — @tailwindcss/postcss replaces the old tailwindcss + autoprefixer pair.

—Native CSS layers — Tailwind v4 uses @layer internally, giving you cleaner cascade control with no extra config.

—Faster builds — The new Rust-based engine makes cold builds and incremental compiles significantly faster.

Filters

1. Create a Next.js project

2. Install packages

3. Configure PostCSS

4. Set up globals.css

5. Dark mode variant

6. Start the dev server

Why Tailwind v4?

Filters

1. Create a Next.js project

2. Install packages

3. Configure PostCSS

4. Set up globals.css

5. Dark mode variant

6. Start the dev server

Why Tailwind v4?