Overview

The Cerberus Panda CSS Preset adds a set of core features to the Cerberus Design System.

Note

This guide assumes you are familiar with Panda CSS. If you are not, please take a moment to familiarize yourself with the framework.

Step 1 - Install Panda CSS

If you have not already installed Panda CSS, you can do so by following the Panda CSS installation guide.

If you have not added any custom presets to your Panda configuration, install the required Panda preset:

1
pnpm add -D @pandacss/preset-panda

Install Cerberus core packages

Install the Cerberus core packages, with the package manager of your choice:

1
pnpm dlx jsr add @cerberus/panda-preset
2
pnpm add @cerberus/styled-system@npm:@cerberus-design/styled-system

Step 2 - Setup Cerberus

Update the Panda Configuration

Once you have installed and setup Panda CSS and added the Cerberus Panda Preset, you need to update your Panda configuration to include the Cerberus Panda Preset.

1
import { defineConfig } from '@pandacss/dev'
2
import pandaPreset from '@pandacss/preset-panda'
3
import { cerberusPreset, cerberusConfig } from '@cerberus/panda-preset'
4

5
export default defineConfig({
6
  ...cerberusConfig,
7

8
  include: [
9
    './node_modules/@cerberus/react/src/**/*.{ts,tsx,js,jsx}',
10
    './app/**/*.{ts,tsx}', // <- Make sure this path is to your project
11
  ],
12
  exclude: [],
13

14
  presets: [pandaPreset, cerberusPreset],
15
})

Update your local styles

Now that you have extended Panda, you need to update your local styles by running the prepare script.

1
pnpm run prepare

Note

Adding Cerberus will add add a new importMap pointing to '@cerberus/styled-system'. This is the new path you will need to use for all your Panda references.

Step 4 - Connect the Cerberus Theme

To connect the Cerberus theme, you need to add the required data attributes to your html tag.

1
function Layout({ children }) {
2
  return (
3
    <html lang="en" data-theme="cerberus" data-color-mode="light">
4
      <body>{children}</body>
5
    </html>
6
  )
7
}

Step 5 - Setup Cerberus Fonts (optional)

If you would like to use the Brand font associated with Cerberus, we recommend Poppins. Unfortunately, it is not a variable font, so another great solution which is, is the Inter font (comes pre-configured in NextJS apps).

NextJS usage:

1
import { Poppins } from 'next/font/google'
2

3
const poppins = Poppins({
4
  display: 'swap',
5
  subsets: ['latin'],
6
  weight: ['400', '600', '700'],
7
})

Using Cerberus React (Not JSR compatible yet)

If you are interested in using the Cerberus React, install it now:

1
pnpm add @cerberus/react@npm:@cerberus-design/react

Using the Cerberus Icons (optional)

If you are interested in using the Cerberus Icons, install it now:

1
pnpm dlx jsr add @cerberus/icons

Note

The Cerberus React library is icon-agnostic which means you can combine any icon library with it.

Add a Cerberus script

To help make maintaining a breeze, add this new script to your package.json to use when you are ready to upgrade Cerberus:

1
"scripts": {
2
  "up:cerberus": "pnpm up @cerberus/{styled-system,react}@latest && pnpm dlx jsr add @cerberus/{panda-preset,icons}"
3
}

FAQ

What are the weird version paths for when I install the Cerberus packages?

The Cerberus packages are published under the @cerberus-design organization in NPM (due to the name cerberus being taken). However, in JSR, we use the @cerberus organization. We eventually plan on fully migrating to JSR when there is better support for the features we need.

The version paths are simply creating an alias to the @cerberus-design organization so that you can have consistent package naming across your project.

Everything should use the @cerberus organization in your code.

Why do I need to add the `@cerberus/styled-system` package?

The @cerberus/styled-system package is a dependency of the Cerberus Panda Preset. It is a styled-system that is pre-configured to work with the Cerberus Design System and creates a single source of truth for our UI related packages.