Setup

How to quickly start using the Staffbase Design System within projects, for engineers.

Overview

The Staffbase Design System brings order and consistency to all Staffbase products through a single package of UI components, icons, and design tokens.

• Available as a private npm package found at @staffbase/design.
• Built on React 18/19
• For styling it uses Tailwind v4
• Most compound components are built using Base UI primitives.

Requirements

Before you start, make sure your project has:

• React 18 or 19 (react and react-dom) — these are peer dependencies and aren’t bundled.
• Tailwind v4 set up in your project. Follow the installation instructions from Tailwind.

Installation

Since this is a private npm package you will first need to set up your npm config so your package manager can authenticate against the registry.

Then install the design system:

pnpm install @staffbase/design

Configuration

Import the following into your application’s global stylesheet. The cascade layer order is declared up front so that rules in later layers override earlier ones — keep this order intact.

@layer theme, base, components, utilities;

@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);
@import 'tailwindcss/utilities.css' layer(utilities);

@import '@staffbase/design/fonts/inter.css' layer(base);
@import '@staffbase/design/fonts/epilogue.css' layer(base);
@import '@staffbase/design/tokens/primitive.css' layer(base);
@import '@staffbase/design/tokens/semantic.css' layer(base);
@import '@staffbase/design/tokens/component.css' layer(base);

@import '@staffbase/design/components.css' layer(components);
@import '@staffbase/design/illustrations.css' layer(components);

@import '@staffbase/design/theme.css' layer(theme);

What each import does:

• Tailwind layers — the framework’s theme, preflight reset, and utilities.
• Fonts — inter.css and epilogue.css register the Staffbase typefaces (see Fonts below).
• Token layers — primitive, semantic, and component expose the design tokens as CSS custom properties. Prefer semantic tokens in your own code; they adapt to dark mode and theming.
• components.css — the bundled component styles. Always import this single file; never import per-component CSS.
• illustrations.css — illustration styles. Only needed if your app uses @staffbase/design/illustrations.
• theme.css — the Tailwind v4 theme bridge that maps tokens onto Tailwind utilities.

You can now use Tailwind classes in your markup 🎉

<div class="text-neutral-strong p-1">Hello World</div>

Fonts

The design system ships with copies of the Staffbase typefaces, Inter and Epilogue. These are registered by the @staffbase/design/fonts/inter.css and @staffbase/design/fonts/epilogue.css imports in the CSS block above, so you don’t need to preload or serve the font files separately.

CSS reset

Tailwind’s preflight.css (imported above) acts as the CSS reset, normalizing native browser styling to avoid conflicts with component styles. If your project already ships its own reset, keep the cascade layer order intact so design system styles win where expected.

Usage

Import the component you need directly from the package:

import {Button} from '@staffbase/design';

And use it as you would any React component:

<Button>Hello World</Button>

Icons

Icon components are exported from the same entry point as components:

import {CheckIcon} from '@staffbase/design';

Hooks

Hooks live behind a separate entry point:

import {useFormatDateTime} from '@staffbase/design/hooks';

Editor support

VS Code

If you’re using VS Code, we recommend installing the Tailwind CSS IntelliSense extension. This provides code completion for Tailwind classes.

IntelliJ IDEA

If you’re using IntelliJ IDEA, there’s nothing you need to do. The IDE will automatically pick up the Tailwind classes and provide code completion.