Getting Started

Set up a new project and start copying components in minutes.

Prerequisites

Make sure you have the following installed before continuing.

Node.js 18+ — node -v - to check
pnpm — npm install -g pnpm - if you don't have it
Ghostty - because it's the best

Installation

1. Create a Next.js Project

Start with a fresh Next.js app. Use the App Router, TypeScript, Tailwind, and src/ directory options when prompted.

pnpm create next-app@latest my-next-abandoned-project

2. Install Dependencies

bonk/ui relies on a few packages for accessible primitives, dark mode, and class merging.

core dependencies

pnpm add @base-ui/react next-themes class-variance-authority clsx tailwind-merge

3. Add the Utility Function

Create src/utils/utils.ts — every component uses this to merge class names.

src/utils/utils.ts

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

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

Add a barrel export so you can import from @/utils.

src/utils/index.ts

export { cn } from "./utils";

4. Set Up the Color System

Replace the contents of src/app/globals.css with the bonk/ui theme tokens. This disables all Tailwind built-in colors and defines the semantic token system. See Theming for the full token reference.

5. Copy Components

Create the folders you need and start copying. At minimum you'll want src/ui/ for the design system primitives. Add src/layout/, src/components/, and src/constants/ as needed.

src/
  ui/                     # Design system primitives
    icons/                # Icon components
    index.ts              # Barrel export
  layout/                 # Navbar, Footer, etc.
  components/             # Shared components (PageHero, etc.)
  constants/              # Brand, navigation, contact
  utils/                  # cn() utility

Browse the component pages in the sidebar, grab the source for what you need, and drop it into the matching folder. Each component page includes the full source code. See Architecture for the full folder structure and import rules.

Path Aliases

Components use @/ imports (e.g. @/ui, @/utils). Next.js sets this up automatically if you chose the src/ directory option, but double check your tsconfig.json has this:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Project Setup

A few things to configure once you have components in place.

Update Brand Constants

If you copied src/constants/brand.ts, update it with your company info:

export const BRAND = {
  name: "Your Company",
  initials: "YC",
  tagline: "Your tagline here.",
  year: 2025,
  location: "City, State",
} as const;

Update Navigation

Edit src/constants/navigation.ts to set your nav links and CTA:

export const NAV_LINKS = [
  { label: "Home", href: "/" },
  { label: "About", href: "/about" },
  { label: "Services", href: "/services" },
  { label: "Contact", href: "/contact" },
] as const;

export const NAV_CTA = {
  label: "Get in Touch",
  href: "/contact",
} as const;

Customize Colors

All colors are defined in src/app/globals.css. Update the base palette variables to match your brand:

:root {
  --light: oklch(0.97 0.008 85);  /* Page background */
  --dark: oklch(0.18 0.012 60);   /* Primary text */
}

@theme {
  --color-primary: oklch(0.46 0.09 55);           /* Your brand color */
  --color-secondary: oklch(0.46 0.04 139);        /* Secondary brand */
  --color-accent: oklch(0.54 0.21 41);            /* Accent / highlight */

  /* ...plus ghost, hover, subtle, contrast variants for each color,
     state colors (info, progress, success, warning, danger), and
     surface tokens (root, root-100, root-200, divider, overlay).
     See the Theming page for the full token reference. */
}

See Theming for the full token reference.

Tech Stack

Technology	Purpose
Next.js 16	App Router, server components
Tailwind v4	Utility CSS with @theme directive
Base UI	Accessible unstyled primitives
next-themes	Dark mode with .dark class toggle
CVA	Component variant styling
clsx + tailwind-merge	Class name merging (cn utility)
TypeScript	Type safety throughout
pnpm	Package manager