Skip to content
CFA Design System

TailwindCSS V3

When integrating TailwindCSS with @cfa/react-core, there are a few things that need to be considered to avoid styling conflicts — particularly with Tailwinds base layer. This layer includes global resets and defaults, which can clash with our own CSS resets and global styles.

We do not recommend using ThemeProvider in Tailwind projects. Instead, refer to the strategies below for more effective ways to apply our styles.

CSS Setup

One of the most effective ways to ensure your CSS is loading in the correct order, is to import everything manually. This requires the use of postcss-import, so to start we need to install that package.

Terminal window
npm install -D postcss-import

Then update your postcss.config.js file to ensure that it has all the correct plugins enabled. postcss-import should go at the top, the order of the plugins is important.

postcss.config.js
/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    "postcss-import": {},
    tailwindcss: {},
  },
};


export default config;

Once you have all of your plugins enabled, you can then edit your global css file. This syntax will allow you to import everything in a specific order.

We are going to update to this new configuration, which gives us more control over the order and specificity of the CSS.

Order is important! This ensures that Tailwind utilities are loaded after our custom CSS, avoiding override issues.

globals.css
@tailwind base;
@tailwind components;
@tailwind utilities;
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "@cfa/react-core/dist/index.css";
@import "tailwindcss/utilities";

One note here is that when importing our CSS into a .css file, you should use the path @cfa/react-core/dist/index.css. This is different than when you import into a JS file, which would be @cfa/react-core/index.css.

Theme Preset

We provide a helpful tailwind preset that will allow you to map all of our design tokens, which includes different values for

  • Colors
  • Sizing
  • Fonts
  • Border Radius

1. Install package

Terminal window
npm install @cfa/tailwind-utils

2. Add preset to tailwind.config

You can find the actual theme here.

tailwind.config.ts
import type { Config } from "tailwindcss";
import dsPreset from "@cfa/tailwind-utils";


const config: Config = {
  presets: [dsPreset],
  content: [
    "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {},
  plugins: [],
};
export default config;

This will extend your current theme to include all of our various tokens, you can find the full list here.

This would enable you to then use the new values as shown below.

page.tsx
function Page() {
  return (
    <div className="bg-brand-red">
      <h1 className="text-brand-blue">Hello World</h1>
    </div>
  );
}

Troubleshooting

Nested CSS Console Warnings

We are heavily utilizing nesting in @cfa/react-core and certain versions of Tailwind will have a console warning if it detects nested CSS, you can remedy this by using the following plugin that is included in tailwind. We have not noticed this console warning in more recent versions of tailwind > 3.4. If you are using an older version of Tailwind and want to get rid of those warnings. You can use the following plugin, but it should not cause any actual CSS issues.

This warning was originally intended to be used for writing nested CSS as part of Tailwind.

postcss.config.js
/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    "tailwindcss/nesting": {},
    tailwindcss: {},
  },
};