# Use raft-ui
> How to install raft-ui, set up its stylesheets, Tailwind CSS v4 and dark mode, render a first component, upgrade between versions, and where the tokens and the agent entry points are.
Source: https://raft-design.botiverse.build/about/use-raft-ui. Generated from the current release; where it differs from what you remember, this page is right.
raft-ui is the React implementation of the Raft Design System, published as `@botiverse/raft-ui`. It contains the CSS foundations (the tokens as CSS variables), which work in plain HTML, and React components built on Base UI and Tailwind CSS v4. Product code uses raft-ui instead of its own copies of these components.
## Install
raft-ui needs React 19 and, for the components, Tailwind CSS v4.
```bash
pnpm add @botiverse/raft-ui
```
The package's entry points:
| Import | Contains |
| --- | --- |
| `@botiverse/raft-ui` | Stable components, providers and hooks |
| `@botiverse/raft-ui/wip` | Experimental components; their API can change in any release |
| `@botiverse/raft-ui/cn` | The class merger, `cn` |
| `@botiverse/raft-ui/styles.css` | The Tailwind CSS v4 integration; it imports `foundation.css` |
| `@botiverse/raft-ui/foundation.css` | The theme variables alone, for pages without React or Tailwind |
| `@botiverse/raft-ui/fonts.css` | Optional web fonts: Space Grotesk and Space Mono |
| `@botiverse/raft-ui/tokens.json` | Every token in the Design Tokens Community Group format |
## Set up the styles
### With React and Tailwind CSS v4
Import Tailwind and raft-ui's styles in your global stylesheet, and point Tailwind at the installed package so it generates the utilities the components use:
```css
@import "tailwindcss";
@import "@botiverse/raft-ui/styles.css";
@source "../node_modules/@botiverse/raft-ui/dist/**/*.{js,mjs}";
```
`@source` is relative to this CSS file and must resolve to the installed package.
Import the fonts from the app entry:
```ts
import "@botiverse/raft-ui/fonts.css";
```
`fonts.css` starts with a web-font `@import`. If you import it from a stylesheet instead, put it first in that file, because a CSS `@import` must come before other rules. To use other fonts, set `--heading-font`, `--sans-font` and `--mono-font`.
### Without React or Tailwind
Link `foundation.css`, or copy it beside your HTML. It defines the same theme variables the components use, without component markup, interactions or a CSS reset:
```html
```
## Theme and dark mode
Raft has one visual language, in light and dark mode; components adapt to the mode themselves. Pick the mode with a class on the root: `class="light"` or `class="dark"`. Without either, the page follows the system setting.
In a React app, wrap the app in `ThemeProvider`. It sets the mode class and `color-scheme` on `document.documentElement`.
```tsx
import { ThemeProvider } from "@botiverse/raft-ui";
export function AppProviders({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
- `mode` or `defaultMode` is `light`, `dark` or `system`; the default is `light`. `onModeChange` reports changes, and `storageKey` keeps an uncontrolled mode in `localStorage`.
- `useTheme()` returns `mode`, `resolvedMode` (`light` or `dark`, with `system` resolved) and `setMode`.
- A nested scope, such as a preview, uses `syncDom={false}` and puts the matching `light` or `dark` class on its own root.
- An app rendered on the server that keeps the mode has to restore it before the first paint, or the page flashes the other mode.
Two more providers are needed only with their components: `TooltipProvider` for tooltips and `ToastProvider` for the toast API ([Toast](https://raft-design.botiverse.build/components/toast.md)).
Base UI overlays portal to `document.body`. Give the app root `isolation: isolate` so its stacking contexts stay below them.
## A first component
```tsx
import { Button } from "@botiverse/raft-ui";
export function CreateTaskButton() {
return ;
}
```
`variant="primary"` is the pink sticker for the one action a screen exists for; every other action uses the default variant. Each component's page lists its variants, parts and props, generated from the code, and its rules. Check a prop there or in `node_modules/@botiverse/raft-ui/dist/index.d.mts` rather than guessing it: names differ between components (the negative intent is `danger` on Button and `destructive` on Banner).
Two rules hold for everything you build with raft-ui:
- Use real elements. Anything clickable is a `