Getting started

Foundations

How to install the kit, the paper and ink the crafts are printed with, one tone scale per bead, the buttons, and the theme. Set --h on anything, with tone(hue), and the tone-* colours under it take that hue. Every colour is a light and dark pair.

Install

The kit is copied into your project with the shadcn CLI, so the code is yours to change. It needs React 19 and Tailwind 4. Each component has its own command on its page, and brings what it imports with it. This one brings the whole kit, into components/orbeez:

bash

npx shadcn@latest add https://orbeez-kit.vercel.app/r/orbeez.json

Then import the stylesheet once, wrap the app in OrbeezProvider, and give the page the kit's paper, ink and rounded type. The kit takes its type and text colour from what it sits in, so without those classes it is set in whatever the page uses. To keep the rest of a page as it is, put them on an element round the kit's components and leave <body> alone.

css

/* your global stylesheet, after tailwindcss; the path is from this file to the kit */
@import "tailwindcss";
@import "../components/orbeez/orbeez.css";

tsx

// app/layout.tsx: the kit's paper, ink and rounded type on the page, and motion that honours a request for less of it
import { OrbeezProvider } from '@/components/orbeez/provider'

<body className="bg-paper font-rounded text-ink">
  <OrbeezProvider>{children}</OrbeezProvider>
</body>

The kit keeps to its own folder and its own colour names, so it sits beside shadcn components without changing them. It follows a dark or light class on <html>, as next-themes sets, as well as its own data-theme. With neither, it follows the system.

Colour

ink

mute

line

paper

panel

surface

mine

warm

Neutrals

bg-ink, text-mute, border-line, bg-paper, bg-panel, bg-surface, bg-mine, text-warm

338

142

198

264

Tones

Six bead hues, each with fill, chip, edge, ring, text and title. Status colours are tones too.

tsx

// any hue, on any element: everything under it takes it
<div style={tone(338)} className="bg-tone-fill text-tone-title gummy-tone">...</div>

// the agent colours, in order, and what colours mean
hueFor(0) // 338
STATUS.done // 142

Buttons

BeadButton squishes like gel. Button is a gummy pill; IconButton is quiet, for toolbars.

Theme

ThemeToggle

A light/dark switch whose knob is a bead: amber in light mode, violet in dark. It follows the system until someone picks.

The theme lives on data-theme on <html>, set by an inline script before anything paints, so there is no flash. The switch is drawn from that attribute alone, so it is right from the first frame and never jumps after hydration.

tsx

// app/layout.tsx: settle the theme before first paint
<html suppressHydrationWarning>
  <head>
    <script dangerouslySetInnerHTML={{ __html: THEME_SCRIPT }} />
  </head>
  ...
</html>

<ThemeToggle />

PreviousOverview NextBeads