@graph8/ui

The React component kit and design tokens behind the graph8 app — the same primitives, the same tokens, extracted so you can build on the graph8 Developer API and have it look like graph8.

27 primitives. 163 design tokens, light and dark. Tailwind v4, React 18 or 19, no Next.js requirement.

npm install @graph8/ui

Getting the styles right (read this first)

This is the one step people skip, and skipping it means every component renders unstyled. graph8 is on Tailwind v4, where the theme is CSS, not a tailwind.config.js — so there is no preset object to spread into a config file. Pick the path that matches your stack.

You already use Tailwind v4

Import the preset from your CSS entry point, after Tailwind itself:

@import "tailwindcss";
@import "@graph8/ui/theme.css";

That single import brings four things:

1. the design tokens (:root and .dark)
2. the @theme inline mapping, so bg-background / text-muted-foreground compile in your markup as well as ours
3. graph8's dark and hover variant semantics
4. an @source directive pointing at the shipped components

Number 4 is not optional and is the usual cause of "it installed but everything is unstyled". Tailwind v4 is gitignore-aware and does not scan node_modules, so without @source your build never sees the class names inside this package. theme.css declares it for you.

You do not use Tailwind

Import the pre-compiled stylesheet once, at the root of your app:

import "@graph8/ui/styles.css";

It carries the tokens plus every utility the components actually use, already compiled. It deliberately excludes Tailwind's preflight reset — a component library has no business restyling every heading and form control in your app. If you want the reset, opt in yourself:

@import "tailwindcss/preflight.css";

You only want the tokens

For a design system of your own, or non-React surfaces:

@import "@graph8/ui/tokens.css";

Custom properties only — :root and .dark, nothing else. No selectors on your elements, no Tailwind, nothing that can collide with your CSS.

| Import | Gives you | Use when | |---|---|---| | @graph8/ui/theme.css | tokens + @theme inline + variants + @source | you run Tailwind v4 | | @graph8/ui/styles.css | tokens + pre-compiled utilities | you do not run Tailwind | | @graph8/ui/tokens.css | custom properties only | you want just the palette |

Dark mode

Dark mode is class-based. Put dark on <html>, or on any subtree you want inverted:

<html className={isDark ? "dark" : ""}>

Both theme.css and styles.css define @custom-variant dark (&:is(.dark *)), which is what makes dark: utilities respond to that class.

Usage

import { Button, Card, CardHeader, CardTitle, CardContent, Separator } from "@graph8/ui";

export function DealCard({ deal }) {
  return (
    <Card>
      <CardHeader>
        <CardTitle>{deal.name}</CardTitle>
      </CardHeader>
      <Separator />
      <CardContent>
        <Button variant="outline" size="sm">Open</Button>
      </CardContent>
    </Card>
  );
}

Every primitive is also importable on its own, which tree-shakes without relying on your bundler seeing through the barrel:

import { Dialog, DialogContent } from "@graph8/ui/primitives/dialog";

Sortable is the one component that needs the subpath form if you want its short aliases. They are kept out of the top-level barrel on purpose, because Item would collide with the Item primitive:

import * as Sortable from "@graph8/ui/primitives/sortable";

<Sortable.Root><Sortable.Item /></Sortable.Root>;

React Server Components

Client-only primitives keep their "use client" directive through the build, so importing <Dialog> from a Server Component works without you marking anything. Because the package is transpiled file-by-file rather than bundled into one client blob, the primitives that need no client runtime stay usable directly in a Server Component. There are seven:

Breadcrumb, Button, Card, Input, Item, Skeleton, Textarea

Everything else carries "use client", which is what makes importing <Dialog> from a Server Component work without you marking anything.

What is in the kit

Layout & surface — Card, Separator, Table, Item, Skeleton, Resizable, Sidebar, Sheet, Drawer

Input — Button, Input, Textarea, Label, Switch, Slider, Tabs, Kbd

Overlay — Dialog, AlertDialog, ContextMenu, Tooltip, Collapsible

Content — Avatar, Breadcrumb, Carousel, Chart, Sortable

Plus the helpers the primitives use: cn, composeRefs / useComposedRefs, useIsMobile / MOBILE_BREAKPOINT.

One known difference from graph8's own UI

Carousel's prev/next buttons. Inside graph8 they use the app's canonical Button wrapper; here they use this kit's Button, because the canonical wrapper is a separate component that is not part of the extracted set. The API is compatible (variant="outline" size="icon" exist on both) so nothing breaks — but the hover and cursor styling differs slightly from graph8's own carousel. Every other primitive is byte-for-byte what graph8 ships.

Not included, on purpose

Three files from graph8's internal components/ui/ are deliberately not shipped:

| | Why | |---|---| | content-state | Requires next/dynamic, lottie-react and a product-specific JSON animation. Tied to Next.js and to graph8 product code. | | confirm-dialog | An app composite, not a primitive — it wraps graph8's canonical dialog/button wrappers and ships a workflow hook. | | skeletons | App composites shaped around specific graph8 screens, and it re-declares Skeleton. |

Versioning

Semantic versioning. This package is generated from the graph8 app's own components/ui and app/globals.css, and CI fails if the two drift, so a release genuinely reflects what graph8 itself ships.

License

MIT