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:
1pnpm add -D @pandacss/preset-panda
Install Cerberus core packages
Install the Cerberus core packages, with the package manager of your choice:
1pnpm dlx jsr add @cerberus/panda-preset2pnpm 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.
1import { defineConfig } from '@pandacss/dev'2import pandaPreset from '@pandacss/preset-panda'3import { cerberusPreset, cerberusConfig } from '@cerberus/panda-preset'4
5export 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 project11 ],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.
1pnpm 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.
1function 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:
1import { Poppins } from 'next/font/google'2
3const 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:
1pnpm add @cerberus/react@npm:@cerberus-design/react
Using the Cerberus Icons (optional)
If you are interested in using the Cerberus Icons, install it now:
1pnpm 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.