@nvidia/foundations-react-core

Kaizen UI Foundations — React Core

Core React components for Kaizen UI Foundations, NVIDIA's design system. Styles available from CDN.

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

pnpm add @nvidia/foundations-react-core

Styles

Kaizen UI publishes pre-built stylesheets to the NVIDIA web assets CDN. Pin the version to the @nvidia/foundations-react-core version you have installed.

File	Description
base-external.css	Base theme for external projects: CSS reset, design tokens, light/dark/density themes, MIT-compatible icon set, web-safe fallback fonts.
base.css	Same as base-external.css but with NVIDIA proprietary icons and NVIDIA Sans. Only use this in NVIDIA-licensed projects.
components.css	Default component styles. Requires base-external.css (or base.css) to be loaded first.

CDN URL pattern:

https://webassets.nvidia.com/kaizen-ui-foundations/<version>/<file>

Option 1 — Load directly from the CDN

Simplest approach. Add <link> tags to your HTML or @import them from your CSS, replacing <version> with the version of @nvidia/foundations-react-core you have installed:

<link
  rel="stylesheet"
  href="https://webassets.nvidia.com/kaizen-ui-foundations/<version>/base-external.css"
/>
<link
  rel="stylesheet"
  href="https://webassets.nvidia.com/kaizen-ui-foundations/<version>/components.css"
/>

Option 2 — Bundle the CSS with your app

Download the CSS at build time so your app stays self-contained and works offline. Add a prebuild/predev script that fetches the stylesheets for the version of @nvidia/foundations-react-core you have installed, writes them to a local file, and imports that file from your CSS.

A minimal example:

// scripts/fetch-kui-styles.mjs
import { mkdir, readFile, writeFile } from "node:fs/promises";

const { version } = JSON.parse(
  await readFile(
    "./node_modules/@nvidia/foundations-react-core/package.json",
    "utf8",
  ),
);
const CDN = `https://webassets.nvidia.com/kaizen-ui-foundations/${version}`;
const FILES = ["base-external.css", "components.css"];

const parts = await Promise.all(
  FILES.map(async (file) => {
    const res = await fetch(`${CDN}/${file}`);
    if (!res.ok) throw new Error(`${file}: ${res.status}`);
    return `/* --- ${file} --- */\n${await res.text()}`;
  }),
);

await mkdir("src/generated", { recursive: true });
await writeFile(`src/generated/kui-styles.css`, parts.join("\n\n"));

Wire it into package.json:

{
  "scripts": {
    "predev": "node scripts/fetch-kui-styles.mjs",
    "prebuild": "node scripts/fetch-kui-styles.mjs"
  }
}

Then import the generated file from your CSS:

/* src/index.css */
@import "./generated/kui-styles.css";

Bump the @nvidia/foundations-react-core version, re-run the script, and your CSS is back in lockstep.

Usage

import { Button } from "@nvidia/foundations-react-core";

export default function Home() {
  return <Button onClick={() => alert("Hello!")}>Click me</Button>;
}

Types are exported alongside their components:

import type { ButtonProps } from "@nvidia/foundations-react-core";

Framework notes

Next.js

For App Router projects, import the base CSS from your root app/layout.tsx (or a stylesheet imported there). If Next.js complains about CSS imports from node_modules, add the package to transpilePackages:

// next.config.mjs
const nextConfig = {
  transpilePackages: ["@nvidia/foundations-react-core"],
};
export default nextConfig;

TypeScript

Requires TypeScript 5.0+ with moduleResolution set to bundler:

// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
  },
}

See the TypeScript docs for context.

AI skills

KUI ships agent skills that give LLMs full context on our components and design patterns. Sync them into your project:

pnpm exec kui-sync-skills

By default this writes to .agents/skills/kaizen-ui/. If the skill already exists in .agents/, .claude/, or .cursor/, it updates in place.

Options:

• --dir <path> — write to a specific directory (e.g. --dir .claude)
• --dry-run — preview what would change without writing
• --force — overwrite even if the installed version already matches

To keep skills up-to-date as the package version changes, add the sync to your prepare script:

{
  "scripts": {
    "prepare": "kui-sync-skills"
  }
}

If your project uses TanStack Intent, KUI skills are also discoverable directly from node_modules via npx @tanstack/intent list.

Documentation

1. Bundled AI skills. Run pnpm exec kui-sync-skills (above) and let your editor's agent / LLM pull in component and pattern 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

• @nvidia/foundations-tailwind-plugin — Tailwind plugin for NVIDIA design tokens