Get started with bbb-design

BBB is the design system I use as a starting point for my interfaces. The @beepboopbit/ui installer copies React components, styles, and supporting files into your app. You edit and own that source.

The intended setup uses npx from your app’s root. The installer reads the deployed source registry by default. You do not need to clone the BBB repository or build a local registry.

Publication status: The Gallery and source registry are live. The npm CLI is not published yet, so the npx commands below become available after @beepboopbit/ui is published. An npm E404 currently means publication is still pending. Gallery’s View code offers source bundle downloads in the meantime.

Prepare a React app

Use Node.js 24 and npm. The supported app setup is React and React DOM 19.2.x, TypeScript 6.x, Vite, and plain CSS. BBB initializes an existing app.

If you need a new app:

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install

Check the generated React and TypeScript versions against the supported versions above. If you already have a compatible app, open a terminal in its root instead. Run the remaining commands there.

Initialize BBB with npx

Preview the setup, then apply it:

npx @beepboopbit/ui@latest init --dry-run
npx @beepboopbit/ui@latest init

init copies foundations and ThemeProvider, adds the component stylesheet import to your app’s detected CSS entrypoint, installs missing dependencies, and prints a provider snippet for you to place in your app.

The default keeps your app’s existing page styling. For BBB’s whole-app typography and baseline, choose --baseline on first initialization:

npx @beepboopbit/ui@latest init --baseline

Choose either the default initialization or the baseline option for your first setup. If the installer cannot detect your imported stylesheet, select it explicitly with --stylesheet src/index.css.

Add components

List the available components, then add what you need:

npx @beepboopbit/ui@latest list
npx @beepboopbit/ui@latest add button text-field dialog

The installer copies complete component bundles, including their styles and supporting files, into src/bbb/. It installs missing runtime dependencies and preserves existing edits. npx runs the installer without adding the CLI itself to your app’s dependencies.

To preview another batch before copying:

npx @beepboopbit/ui@latest add button text-field dialog --dry-run

Use your first component

In src/App.tsx, import the copied Button and wrap it in ThemeProvider:

import { Button } from './bbb/components/Button/Button';
import { ThemeProvider } from './bbb/components/ThemeProvider/ThemeProvider';

export default function App() {
  return (
    <ThemeProvider mode="system" locale="en-US">
      <Button onPress={() => console.log('Saved')}>Save changes</Button>
    </ThemeProvider>
  );
}

The initialization step adds the required stylesheet import. If you maintain styles manually, ensure ./bbb/foundations/styles.css is imported once from your app’s entrypoint or stylesheet.

Start the app:

npm run dev

Open the URL printed by Vite. ThemeProvider supplies appearance and locale settings. You can edit the copied components, CSS, and shared --bbb-* tokens directly.

Choose the registry or app directory

The public registry is already the default. To select it explicitly during initialization:

npx @beepboopbit/ui@latest init --registry https://ui.beepboopbit.com/r/

To initialize an app from another directory, use --cwd:

npx @beepboopbit/ui@latest init --cwd /path/to/my-app

These are alternatives to the earlier initialization command. The installer saves the registry URL in bbb.json and records the source release in src/bbb/.bbb-source.json. Later add commands use the saved registry and recorded release.

Keep your changes

Commit bbb.json, the copied source directory, its .bbb-source.json record, and license notices. Differing files are preserved; the installer does not automatically merge or overwrite your customizations.

For upgrades, compare a newer source release in a separate directory and apply the changes you choose. Your app owns its copied source, dependency updates, and regression checks.

Browse the deployed Gallery for working examples, source files, and component APIs.