I reproduced this in a clean project with MoonUI, a React component library on Radix and Tailwind. The component was fine. Tailwind just hadn't been told enough. Here are the gaps and how to close them. Everything below uses the Tailwind v3 config format. I ran each step in a clean Vite 5 project with Tailwind 3.4 and @moontra/moonui 6.30.0.

1. Tailwind can't see classes inside node_modules

Tailwind v3 doesn't ship every utility. It scans the files listed in content and generates only the classes it finds. If a component library is published with Tailwind class names in its JavaScript, those names sit in node_modules, which your config doesn't scan by default.

The fix is one more glob:

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/@moontra/moonui/dist/**/*.{js,mjs}",
  ],
};

Point it at the built output (dist), not the source, because that's what your bundler imports.

Why not put this glob inside the library's preset? We decided against it. content paths depend on the consumer's folder layout and package manager, and a wrong guess fails silently. It's better to ask for one explicit line.

2. The class exists, the colour doesn't

Libraries that support theming usually don't hardcode colours. A button uses bg-primary, and primary has to mean something in your Tailwind theme. That takes two parts:

• a preset that maps theme keys to CSS variables, such as primary: "hsl(var(--primary) / <alpha-value>)"
• a token stylesheet that defines --primary and friends for light and dark mode

// tailwind.config.js
module.exports = {
  presets: [require("@moontra/moonui/tailwind-preset")],
  // ...content from step 1
  plugins: [require("tailwindcss-animate")],
};

/* globals.css */
@import "@moontra/moonui/tokens.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

With the preset alone, Tailwind generates bg-primary, but the variable is undefined and the declaration does nothing. With the tokens alone, the variables exist but nothing uses them. You need both.

The animate plugin is there because Radix-based components use classes like animate-in and fade-in-0 for open and close states.

3. Import the tokens by their exports path

The token file is published under a short exports subpath, so import it by that name, from CSS or from JavaScript:

/* from CSS */
@import "@moontra/moonui/tokens.css";

// or from JS, e.g. main.jsx or app/layout.tsx
import "@moontra/moonui/tokens.css";

Use one of the two; there is no reason to import both. In my Vite 5 run, the longer physical path (@moontra/moonui/src/styles/tokens.css) failed to resolve, because the package's exports map doesn't list it. If your setup resolves CSS imports differently, check the error message first.

What each step looked like

I started from an empty Vite + React project and added one step at a time. The same <Button>Hello</Button> rendered like this:

1. Package installed, nothing else: no background, no padding, a plain text button.
2. Plus the content glob: padding and rounded corners appear, but the background is still transparent.
3. Plus the preset and animate plugin: same result. bg-primary is generated, but --primary is undefined.
4. Plus the token import: the primary blue background and light text appear.

A quick checklist

If a component from npm renders unstyled under Tailwind v3:

1. Is the package's dist folder in content?
2. Is the library's preset (or an equivalent theme mapping) in presets?
3. Are the CSS variables defined, by importing the token file once?
4. Are any plugins the components need (like tailwindcss-animate) installed?

The code is from MoonUI's free package, which is MIT: https://github.com/moonuidotdev/moonui. If you maintain a Tailwind-based library, I'm curious how you handle this. Do you ship compiled CSS instead?

Disclosure: I wrote this with help from an AI assistant. I ran the four steps above in a clean project and checked the results myself.