Guide

Getting started

Install the package, import one stylesheet, and use components. It works with any bundler that handles CSS imports, and with Server Components.

Install

Requires React 19. Base UI is a dependency of the package, so there is nothing else to install.

terminal

npm install @gnoud-ui/react

The package page on npm shows the README, versions and provenance exactly as users see them there.

Import the styles

Import the stylesheet once, at the root of your app. It carries the design tokens and the styles of every component.

app/layout.tsx

import "@gnoud-ui/react/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Use a component

app/page.tsx

import { Button, Card, CardHeader, CardTitle } from "@gnoud-ui/react";

export default function Page() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello</CardTitle>
      </CardHeader>
      <Button variant="primary">Continue</Button>
    </Card>
  );
}

Components that need interactivity are already marked "use client", so you can import and render them from a Server Component without wrapping them.

Tailwind CSS v4

All gnoud-ui styles live in one cascade layer named gnoud-ui. That is what lets your Tailwind utilities override a component with className="w-full" and no !important. Tailwind needs to know where that layer sits: above its base reset, below utilities.

app/globals.css

@layer theme, base, gnoud-ui, components, utilities;

@import "tailwindcss";
@import "@gnoud-ui/react/styles.css";

Declare the layer order before the imports. Without it, Tailwind's reset can flatten the components, or the components can win over your utilities.

You do not need Tailwind. Plain CSS of your own overrides the library the same way.

Fonts

The library does not load fonts for you. The tokens name three families and fall back to system fonts: Familjen Grotesk for headings, Hanken Grotesk for text and Geist Mono for labels. All three cover Vietnamese. With next/font:

app/layout.tsx

import { Familjen_Grotesk, Hanken_Grotesk, Geist_Mono } from "next/font/google";

const display = Familjen_Grotesk({ variable: "--font-display", subsets: ["latin", "vietnamese"] });
const body = Hanken_Grotesk({ variable: "--font-body", subsets: ["latin", "vietnamese"] });
const mono = Geist_Mono({ variable: "--font-mono", subsets: ["latin", "vietnamese"] });

// <html className={`${display.variable} ${body.variable} ${mono.variable}`}>

Then point the tokens at them:

app/globals.css

:root {
  --gu-font-display: var(--font-display), ui-sans-serif, system-ui, sans-serif;
  --gu-font-body: var(--font-body), ui-sans-serif, system-ui, sans-serif;
  --gu-font-mono: var(--font-mono), ui-monospace, monospace;
}