Tailwind CSS

Use Vortex tokens with Tailwind CSS utilities. Works with bundled themes or a custom theme; this guide uses acme.

Configure Tailwind

For the PostCSS setup from Quick Start, install Tailwind and its PostCSS plugin:

bun add -d tailwindcss @tailwindcss/postcss

Keep Vortex's PostCSS plugins and add Tailwind before them:

import { config } from "@vortexlabs/vortex/config/postcss";

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

If you use getConfig for custom breakpoints, spread that result's plugins instead. For other build tools, follow Tailwind's installation guide.

Load your theme

This setup uses two theme files. globals.css loads token values and typography. tailwind.css maps those values to utilities and must be compiled by Tailwind; it does not replace globals.css.

The theme's tailwind.css resets Tailwind's default token namespaces, so classes such as bg-blue-500, font-sans, and text-xl stop working. Use Vortex token utilities, or define the Tailwind theme values your app still needs.

Declare the layer order first. Vortex components use the vortex layer; utilities after it lets utilities override component styles. Unlayered app styles override both.

Create your app stylesheet:

@layer theme, base, vortex, components, utilities;

@import "tailwindcss";
@import "./themes/acme/globals.css";
@import "./themes/acme/tailwind.css";

For a bundled theme, import both files from the package instead, such as @vortexlabs/vortex-themes/themes/vortex/globals.css and @vortexlabs/vortex-themes/themes/vortex/tailwind.css.

Replace your globals.css import with src/app.css in your app entry or root layout. Keep <VortexProvider defaultTheme="acme"> around your app.

Use token utilities

Inside your provider, use semantic names for custom UI:

<section className="bg-surface-default text-default rounded-md p-md">
  <p className="text-body-md-regular-mobile md:text-body-md-regular-desktop">
    Your project is ready.
  </p>
</section>

Typography utilities apply a complete style: font family, size, weight, line height, and letter spacing. Each style has -mobile and -desktop variants; switch with responsive prefixes.

Follow themes and color modes

Utilities reference Vortex CSS variables, so they follow the active theme and ThemeScope. Load the override's styles after the base theme CSS and apply both names as shown in that guide.

Semantic colors already switch between light and dark. Use dark: only for additional mode-specific changes; the generated variant matches data-vortex-color-mode="dark" and excludes nested light scopes.

When users switch themes:

• Import one theme's tailwind.css in your app stylesheet.
• Load each theme's globals.css separately.
• Use the same breakpoints in every theme. Responsive variants use breakpoint values fixed at build time.