@nerds-with-charisma/ui

React UI kit for Nerds With Charisma. Radix primitives, Tailwind v4, and shared design tokens.

Requirements

• React 18 or 19
• Tailwind CSS v4 (tailwindcss + @tailwindcss/vite for Vite apps)
• A bundler that supports ESM (import)

Install

npm install @nerds-with-charisma/ui

Peer dependency (your app should already have these):

npm install react react-dom

Tailwind v4 (if not already in the app):

npm install -D tailwindcss @tailwindcss/vite

1. Design tokens (CSS)

Import token variables before Tailwind in your global stylesheet (e.g. src/index.css):

@import '@nerds-with-charisma/ui/tokens.css';
@import 'tailwindcss';
@config "../tailwind.config.ts";

tokens.css defines --nwc-* variables (colors, semantic aliases, component tokens). Components expect these to be present.

Optional: runtime theme (Sapphire example)

Pass a merged token object; components and CSS variables update without a separate theme build.

import { NwcTokensProvider, mergeTokens, nwcDefaultTokens } from '@nerds-with-charisma/ui';
import sapphirePatch from './sapphire-docs.patch.json';

const tokens = mergeTokens(nwcDefaultTokens, sapphirePatch);

export function App() {
  return (
    <NwcTokensProvider tokens={tokens}>
      <YourApp />
    </NwcTokensProvider>
  );
}

Copy src/config/themes/sapphire-docs.patch.json (or edit sapphire-docs.jsonc and export a patch). Palette-only tweaks can still use examples/sapphire-docs-theme.css on :root.

Playground: Sapphire theme section → toggle Sapphire.

Optional: Roboto

The kit’s default font-sans stack starts with Roboto. Load it in CSS or your HTML shell:

@import url('https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;600;700;900&display=swap');

2. Tailwind preset

@nerds-with-charisma/ui ships a Tailwind preset with theme extensions (magentas, darks, text-md, accordion animations, etc.). Your app must use it and scan the library so utility classes inside components are not purged.

tailwind.config.ts

import type { Config } from 'tailwindcss';
import nwcPreset, { nwcUiContentGlobs } from '@nerds-with-charisma/ui/tailwind';

export default {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}', ...nwcUiContentGlobs],
  presets: [nwcPreset]
} satisfies Config;

nwcUiContentGlobs points at ./node_modules/@nerds-with-charisma/ui/dist/**/*.{js,mjs} (the published bundle).

Vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [react(), tailwindcss()]
});

Monorepo / npm link (source)

If you depend on the package from source (workspace path, not built dist), also scan the kit source and token JSON:

content: [
  "./src/**/*.{ts,tsx}",
  "./node_modules/@nerds-with-charisma/ui/src/**/*.{ts,tsx}",
  "./node_modules/@nerds-with-charisma/ui/src/config/**/*.json",
  "./node_modules/@nerds-with-charisma/ui/src/components/modalLayout.ts",
],

3. Use components

import {
  Button,
  Modal,
  ModalContent,
  ModalHeader,
  ModalTitle,
  ModalTrigger
} from '@nerds-with-charisma/ui';

export function Example() {
  return (
    <Modal>
      <ModalTrigger asChild>
        <Button copy="Open" />
      </ModalTrigger>
      <ModalContent>
        <ModalHeader>
          <ModalTitle>Hello</ModalTitle>
        </ModalHeader>
      </ModalContent>
    </Modal>
  );
}

Tooltips

Wrap part of your tree (or the app root) in TooltipProvider:

import { TooltipProvider } from '@nerds-with-charisma/ui';

<TooltipProvider>
  <App />
</TooltipProvider>;

Overlays + mask

Modal / AlertDialog accept mask on content for the branded overlay. See modalAlertConfig in the package API.

Package exports

| Import | Purpose | | ------------------------------------ | ------------------------------------- | | @nerds-with-charisma/ui | React components + types | | @nerds-with-charisma/ui/tokens.css | CSS variables | | @nerds-with-charisma/ui/tailwind | Tailwind preset + nwcUiContentGlobs |

Changelog

We use Changesets.

| Command | Purpose | | ----------------------------- | ---------------------------------------------------------------------------- | | npm run changeset | Add a changeset file after a user-facing src/ change (commit with your PR) | | npm run changeset:status | Local: changes since main need a changeset | | npm run changeset:status:ci | Same check CI uses (origin/main on PRs) | | npm run version:pkg | Release prep: bump version + update CHANGELOG.md | | npm run release:publish | Build and publish to npm |

History and conventions: CHANGELOG.md. Pending notes live in .changeset/.

CI (GitHub Actions)

On pull requests and pushes to main:

| Workflow | Check | | -------------------------------------------------- | --------------------------------------------------- | | ci.yml | npm run typecheck + npm run test (Vitest + RTL) | | changeset.yml | Changeset required for user-facing src/ changes |

Local development (this repo)

npm install
npm run dev          # playground at http://localhost:5173
npm run build        # library → dist/
npm run typecheck
npm run test         # Vitest component tests (src/**/*.test.tsx)
npm run lint         # ESLint (src, playground, scripts)
npm run format:check # Prettier (fails if unformatted)

After npm install, Husky runs lint-staged on commit (ESLint + Prettier on staged files). JSONC sources (tokens.jsonc, themes/*.jsonc) are linted by ESLint (jsonc/comma-dangle, syntax) and validated by scripts/validate-jsonc.mjs — Prettier alone does not catch invalid JSONC.

Accessibility baseline: docs/ACCESSIBILITY.md (WCAG-oriented patterns, useFieldIds, jsx-a11y in npm run lint).

Troubleshooting

Components render but look unstyled

1. Confirm @import "@nerds-with-charisma/ui/tokens.css" runs before @import "tailwindcss".
2. Confirm presets: [nwcPreset] from @nerds-with-charisma/ui/tailwind.
3. Confirm content includes ...nwcUiContentGlobs (or monorepo source paths above).
4. Rebuild the app so Tailwind rescans files.

Unknown utility class in app code

Use theme tokens from the preset (text-darks-900, bg-magentas-50, etc.). Arbitrary values work, but the kit is built around the exported scale.

Duplicate React / invalid hook call

Ensure a single react / react-dom version in the app (check with npm ls react). The kit lists React as a peer dependency.

TypeScript cannot find @nerds-with-charisma/ui/tailwind

Ensure tailwindcss is installed in the app and your moduleResolution supports package exports (Node16 / Bundler).

Playground

The playground/ app runs the component demos and token swatches. Use npm run dev to open it.