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 before your imports. Place utilities after vortex so Tailwind utilities can override component and spinner styles. Normal unlayered app styles take precedence over both layers.

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.

If upgrading from Vortex Themes 0.5.0 or earlier, regenerate custom themes with bun run build:theme. Version 0.5.1 uses quoted imports in globals.css so Tailwind includes the token and typography styles.

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.