npm.io
1.7.0 • Published 3d ago

@nvidia/foundations-tailwind-plugin

Licence
Apache-2.0
Version
1.7.0
Deps
0
Size
587 kB
Vulns
0
Weekly
0
SummaryDependencyVersions

Kaizen UI Foundations — Tailwind Plugin

The Tailwind CSS plugin for Kaizen UI Foundations, NVIDIA's design system. Drops NVIDIA design tokens — colors, typography, spacing, radii, shadows, breakpoints — into your Tailwind theme, alongside density variants and a .nv-dark dark-mode class. Supports Tailwind 4 (recommended) and Tailwind 3.

About this package

This package is published under the Apache 2.0 License to support NVIDIA products and projects that are distributed as open source. It is not intended for general public consumption, and we do not recommend adopting it outside of NVIDIA-affiliated projects.

Installation (Tailwind 4)

pnpm add -D tailwindcss @tailwindcss/postcss postcss @nvidia/foundations-tailwind-plugin
pnpm add @nvidia/foundations-react-core

The plugin pairs with the Kaizen UI base CSS, which is loaded from the NVIDIA CDN (pin <version> to your installed @nvidia/foundations-react-core version):

https://webassets.nvidia.com/kaizen-ui-foundations/<version>/base-external.css

Add id="style-root" to your <html> element (see Why style-root?), then configure your global CSS:

/* src/global.css */
#style-root {
  @tailwind utilities;
}

@import url("https://webassets.nvidia.com/kaizen-ui-foundations/<version>/base-external.css");
@import "@nvidia/foundations-tailwind-plugin";

And configure PostCSS:

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

What each piece does:

  • #style-root { @tailwind utilities; } — emits every Tailwind utility wrapped in #style-root, giving them specificity (1,0,0) so they win over component CSS without needing !important.
  • base-external.css from the CDN — design tokens, CSS variables, light + dark + density themes, MIT-compatible icons, web-safe fallback fonts, and a preflight-based CSS reset.
  • @nvidia/foundations-tailwind-plugin — the Tailwind theme and variants.

Want to bundle the CSS instead of loading it from the CDN at runtime? See the styles guide in the @nvidia/foundations-react-core README for a build-time fetch pattern.

See Tailwind's installation guide for framework-specific notes (Vite, Next.js, React Router, …).

Why style-root?

Wrapping utilities in #style-root { @tailwind utilities; } and setting <html id="style-root"> makes every Tailwind utility render as #style-root .bg-red-500 { … }, giving utilities specificity (1,0,0) so they always win against component CSS without !important.

Anchor the ID to <html> rather than <body>: React frequently portals content (dialogs, tooltips, toasts, dropdowns) out of <body>, so a <body> selector loses its Tailwind overrides on portaled content. <html> guarantees every rendered node is inside the selector.

Installation (Tailwind 3)

For new projects, use Tailwind 4. For existing TW3 projects, install the JS plugin:

// tailwind.config.js
import foundations from "@nvidia/foundations-tailwind-plugin";

export default {
  content: ["./src/**/*.{html,js,ts,jsx,tsx}"],
  plugins: [
    foundations({
      // Strip NVIDIA-proprietary icons/fonts from the generated CSS
      external: true,
      // Pair with <html id="style-root"> to raise utility specificity
      important: "#style-root",
    }),
  ],
};
Plugin options

In Tailwind 3, theme configuration flows through the plugin. Pass options to the factory call above; string keys work as-is ("log-level": "debug").

Options also work in Tailwind 4 via the @plugin "..." { … } directive, but most TW4 users won't need them.

Option Type Default Purpose
themes string | string[] nv-light --default, nv-dark, nv-dark --prefersdark, nv-density-standard --default, nv-density-compact, nv-density-spacious Theme strategy. Theme names with optional --default, --prefersdark, and --exclude flags.
default-themes string | string[] — Replaces the built-in default theme set entirely (advanced).
external boolean false Strips NVIDIA-proprietary icons/fonts from the generated CSS. TW4 users: load base-external.css from the CDN instead — this option doesn't apply.
important string | boolean — Forwarded to Tailwind. Pass a selector to prefix all utilities, or true to emit !important everywhere. TW4 users: prefer #style-root { @tailwind utilities; }.
log-level "silent" | "info" | "debug" "info" Plugin log verbosity.
debug boolean false Shortcut for log-level: "debug".

Documentation

The full Kaizen UI documentation site is internal to NVIDIA. Externally, we recommend two sources:

  1. Bundled AI skills. Install @nvidia/foundations-react-core and run pnpm exec kui-sync-skills to drop Kaizen UI agent skills into your project. Your editor's agent / LLM can then pull in component, theming, and plugin context directly from node_modules.
  2. IntelliSense in your editor. Every component and prop is documented inline with JSDoc, so hovering, autocomplete, and inline type signatures surface the same information you'd find on a docs site.

Related packages