Installation

Generate GitHub Token

1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens
2. Create a new token with read:packages scope
3. Copy the token (starts with ghp_...)

Configure .npmrc

Create .npmrc in your project root and commit it to your repository:

@tilt-legal:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GH_NPM_TOKEN}

An .npmrc file is required by Vercel/CI to locate and authenticate with the package registry. Installing packages will fail without it.

Set Environment Variable

To permanently set the environment variable, add it to your .zshrc or .bashrc file.

export GH_NPM_TOKEN=ghp_your_token_here

Install Cubitt Packages

pnpm add @tilt-legal/cubitt-icons @tilt-legal/cubitt-components @tilt-legal/cubitt-logos tailwindcss

Cubitt's styles.css export is authored for Tailwind CSS, so consumer apps need tailwindcss installed for their Tailwind pipeline to process Cubitt styles and source scanning directives.

Import Styles

Import Cubitt styles once from your app root, route shell, or global CSS entrypoint:

import "@tilt-legal/cubitt-components/styles.css";

These styles define Cubitt's Tailwind utilities, CSS variables, surface tokens, shadows, frosted utilities, and brand themes.

Add Surface Context

Wrap only app-owned painted boundaries in SurfaceProvider. Most apps set one provider at the root shell, then add a nested provider only where app-owned content resets to a different surface.

import { SurfaceProvider } from "@tilt-legal/cubitt-components/utilities";

export function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <SurfaceProvider level={3}>
      <div className="min-h-screen bg-surface-3">
        <aside>App chrome</aside>

        <main className="bg-surface-1">
          <SurfaceProvider level={1}>{children}</SurfaceProvider>
        </main>
      </div>
    </SurfaceProvider>
  );
}

SurfaceProvider does not paint a background. It tells Cubitt components what surface has already been painted by your app. You do not need providers around normal Cubitt nesting; Cubitt-owned containers advance or reset context internally.

Configure TanStack Router URL State

If you plan to use Cubitt's built-in URL state props, follow the URL State Management Guide to ensure your app is wrapped in RouterProvider and your router registration is available for type-safe paramName keys.