Skip to content
CFA Design System

Tailwind v4

When integrating Tailwind with @cfa/react-core, import order matters. Tailwind’s global resets can clash with our styles if utilities load before component CSS.

Import @cfa/react-core/index.css in your global stylesheet.

Setup

Install Tailwind using the official Tailwind installation documentation for your bundler or framework.

Then structure your global stylesheet so Tailwind utilities load after @cfa/react-core:

globals.css
@layer theme, base, components, utilities;


@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "@cfa/react-core/index.css" layer(components);
@import "tailwindcss/utilities.css" layer(utilities);

Choose an integration

Recommended for new work: @cfa/design-tokens-core — semantic utilities (bg-brand, text-default, type-body-default, etc.) backed by CFA tokens.

Legacy: @cfa/tailwind-utils — only if you already depend on the older theme-mapped classes (bg-brand-red, etc.).

Terminal window
npm install @cfa/design-tokens-core

Add these imports to globals.css:

@import "@cfa/design-tokens-core/css/tailwind-theme.css" layer(theme);
@import "@cfa/design-tokens-core/css/tailwind-utilities.css";

tailwind-theme.css resets Tailwind’s default color scale. Use CFA semantic utilities (for example, bg-brand, text-on-brand) rather than stock Tailwind color classes.

Import tailwind-utilities.css as a plain CSS import — not inside layer(utilities).

function Page() {
  return (
    <section className="rounded-lg bg-surface p-6 shadow-raised">
      <p className="type-label-small text-subtle">Tailwind v4</p>
      <h1 className="mt-2 type-header-2 text-default">Hello World</h1>
      <button className="mt-4 rounded-round bg-brand px-4 py-2 type-label-small text-on-brand">
        Continue
      </button>
    </section>
  );
}

Switch themes by setting data-theme on a root or scoped element (for example, data-theme="experimental-navy").

For setup without @cfa/react-core, import cautions, and generated file details, see TAILWIND-V4.md in @cfa/design-tokens-core.

Legacy: @cfa/tailwind-utils

Terminal window
npm install @cfa/tailwind-utils

Add the legacy theme import to globals.css:

@import "@cfa/tailwind-utils/v4-theme.css" layer(theme);
function Page() {
  return (
    <div className="bg-brand-red">
      <h1 className="text-brand-blue">Hello World</h1>
    </div>
  );
}