Get started

bambiui is a CLI-first, source-distributed UI toolkit. The CLI copies framework-specific component files and design tokens directly into your project, so your app owns the source it runs.

Prerequisites

Node.js 22.12.0+
A project using React, Svelte, Vue, or Astro

1. Initialize

Run the CLI package from your project root. It exposes the bambiui executable, auto-detects your framework, creates bambiui.config.json, and writes the global design token file.

npx bambiui init

What it creates:

File	Purpose
`bambiui.config.json`	Stores your framework, component directory, and token file path
`src/styles/bambi.css`	Global design tokens as CSS custom properties

You can skip the interactive prompts with --yes to accept detected defaults:

npx bambiui init --yes

Or override specific values:

npx bambiui init --framework react --component-dir src/ui --tokens-file src/styles/tokens.css

2. Import the token file

Import bambi.css once in your app’s global stylesheet or entry point. All component CSS depends on these tokens being present.

// src/main.tsx or src/App.tsx
import './styles/bambi.css';

<script>
  import '../styles/bambi.css';
</script>

import './styles/bambi.css';

---
import '../styles/bambi.css';
---

Or via customCss in astro.config.mjs:

export default defineConfig({
  integrations: [starlight({
    customCss: ['./src/styles/bambi.css'],
  })],
});

3. Add a component

Add the Button component to your project:

npx bambiui add button

The CLI installs the following self-contained files into your component directory (default: src/components/ui/button/):

File	Purpose
`Button.astro` / `button.tsx` / `Button.svelte` / `Button.vue`	Component source
`recipe.ts`	Style recipe — maps props to CSS data attributes
`types.ts`	Shared TypeScript types
`button.css`	Component CSS and component-local token defaults
`index.ts`	Re-exports `Button`, recipe helpers, defaults, and types

The installed files do not import @bambiui/components, @bambiui/core, or @bambiui/tokens at runtime.

4. Use the component

import { Button } from './components/ui/button';

export default function App() {
  return (
    <Button intent="primary" size="md">
      Get started
    </Button>
  );
}

<script>
  import { Button } from './components/ui/button';
</script>

<Button intent="primary" size="md">Get started</Button>

<script setup>
import { Button } from './components/ui/button';
</script>

<template>
  <Button intent="primary" size="md">Get started</Button>
</template>

---
import { Button } from './components/ui/button';
---

<Button intent="primary" size="md">Get started</Button>

Updating a component

Re-run add with --force to overwrite existing files with the latest source:

npx bambiui add button --force

bambiui.config.json

The config file is created by init and read by every subsequent add command. You can edit it manually.

{
  "framework": "react",
  "componentDir": "src/components/ui",
  "tokensFile": "src/styles/bambi.css"
}

Field	Description	Default
`framework`	`react`, `svelte`, `vue`, or `astro`	Auto-detected
`componentDir`	Directory where components are installed	`src/components/ui`
`tokensFile`	Path for the global token CSS file	`src/styles/bambi.css`

CLI reference

bambiui init
bambiui add <component>

Options:
  --framework react|svelte|vue|astro   Override framework
  --component-dir <path>               Override component directory
  --tokens-file <path>                 Override token file path
  --registry-url <url>                 Use a custom registry (default: https://bambiui.com)
  --cwd <path>                         Run in a different directory
  --force                              Overwrite existing files
  --yes, -y                            Accept defaults without prompting

Dark mode

bambiui supports both [data-theme='dark'] and the .dark class on <html> for dark mode. Toggle both when you want the same behavior as the docs and builder:

document.documentElement.setAttribute("data-theme", "dark");
document.documentElement.classList.add("dark");

Tokens for both modes are included in bambi.css. Light semantic values are in :root, dark semantic overrides are in [data-theme='dark'], .dark. Color scales such as --bambi-primary-50 through --bambi-primary-950 stay global; dark mode changes semantic aliases like --bambi-primary, not the scale itself.