Getting Started

Installation

Get BlackBoard set up in your project. Currently supports manual installation — CLI coming soon.

Prerequisites

A React project with Tailwind CSS v4 configured
TypeScript (recommended but not required)

1. Install Dependencies

BlackBoard components use a few peer dependencies. Install them first:

npm install clsx tailwind-merge class-variance-authority lucide-react radix-ui

2. Add the `cn` utility

Create a utility file for merging Tailwind classes:

lib/utils.ts

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

3. Add CSS Design Tokens

Add the BlackBoard design tokens to your global CSS file. These CSS custom properties power theming, density presets, and glow effects:

globals.css

@theme inline {
  /* Semantic color tokens — reference CSS variables */
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);

  /* Radius — bridged from density preset */
  --radius-sm: var(--bb-radius-sm);
  --radius-md: var(--bb-radius-md);
  --radius-lg: var(--bb-radius-lg);
}

/* Light mode (default) — customize these colors freely */
:root {
  --background: #F8F6F0;
  --foreground: #1A1F1C;
  --card: #FFFFFF;
  --card-foreground: #1A1F1C;
  --primary: #E0A420;
  --primary-foreground: #1A1F1C;
  --secondary: #EBE8E0;
  --secondary-foreground: #1A1F1C;
  --muted: #F3F0E8;
  --muted-foreground: #8A8E8B;
  --destructive: #D04A5E;
  --destructive-foreground: #FFFFFF;
  --border: #D6D2C8;
  --input: #FFFFFF;
  --ring: #E0A420;
  --glow-sm: 0 1px 3px rgba(0,0,0,0.04), 0 1px 2px rgba(0,0,0,0.06);
  --glow-md: 0 4px 12px rgba(0,0,0,0.06), 0 1px 3px rgba(0,0,0,0.04);
  --glow-focus: 0 0 0 3px rgba(224,164,32,0.18);
  --accent-hover: #C89010;
  --accent-ghost: rgba(224,164,32,0.06);
  --accent-border: rgba(224,164,32,0.25);
}

/* Dark mode — customize these colors independently */
.dark {
  --background: #0B1210;
  --foreground: #EBE6DB;
  --card: #17231D;
  --card-foreground: #EBE6DB;
  --primary: #F0C554;
  --primary-foreground: #0B1210;
  --secondary: #1F2E27;
  --secondary-foreground: #EBE6DB;
  --muted: #111B16;
  --muted-foreground: #ADA89D;
  --destructive: #ED6B7E;
  --destructive-foreground: #EBE6DB;
  --border: #2B3C33;
  --input: #111B16;
  --ring: #F0C554;
  --glow-sm: 0 0 12px -2px rgba(240,197,84,0.10);
  --glow-md: 0 0 24px -4px rgba(240,197,84,0.16);
  --glow-focus: 0 0 0 3px rgba(240,197,84,0.14);
  --accent-hover: #F5D174;
  --accent-ghost: rgba(240,197,84,0.06);
  --accent-border: rgba(240,197,84,0.25);
}

Components reference these tokens via var(--btn-h), rounded-md, etc. Switching density is a single class — all components adapt automatically.

4. Add Components

Start adding components to your project. You can use the CLI or manually copy the source:

npx blackboard-ui@latest add button

The CLI will automatically install dependencies, create the component file, and add the cn utility if needed.

CLI Coming Soon

The blackboard-ui CLI is under active development. In the meantime, you can manually copy components from the docs pages.

5. Density Presets

BlackBoard ships with two density presets that control sizing, spacing, and border-radius across all components. No prop changes needed — it's a single class on the root element.

defaultSlate

Ultra-compact. 32px buttons, tight gaps, sharp radius. Built for dashboards, data tables, and power-user interfaces.

Button height32px

Radius (md)6px

Body font13px

Canvas

Spacious and relaxed with rounder corners. Great for marketing sites, landing pages, and content-first apps.

Button height40px

Radius (md)10px

Body font14px

Slate is the default. To switch to Canvas, add the class to your root element:

layout.tsx

<!-- Slate + Light (default — no class needed) -->
<html lang="en">

<!-- Canvas + Light -->
<html lang="en" class="canvas">

<!-- Slate + Dark -->
<html lang="en" class="dark">

<!-- Canvas + Dark -->
<html lang="en" class="canvas dark">

Try the Slate / Canvas toggle in the top navigation bar to see the difference live.