Payload CMS — Customizing CSS & SCSS

Three mechanisms to restyle the Admin Panel: global stylesheet, CSS variable overrides, and BEM class targeting.

Global CSS

Add a custom.scss file at the root of your app — it is loaded into the Admin Panel root:

.dashboard {
  background-color: red;
}

For wiki/tech-patterns/payload-cms-admin-panel-location, import styles directly into the component instead of using the global stylesheet.

All Payload styles are inside @layer payload-default. Custom CSS gets highest specificity by default.

Two layers available:

Layer	Purpose
(no layer)	Overrides everything — use for most customizations
`@layer payload`	Custom styles that respect cascade order after Payload
`@layer payload-default`	Write within Payload's own specificity (for surgical overrides)

@layer payload-default {
  /* matches Payload's own specificity level */
}

Import the UI package's SCSS utilities into your own stylesheet:

@import '~@payloadcms/ui/scss';

Payload uses BEM naming — class names are globally accessible and predictable.

Override CSS custom properties defined in @payloadcms/ui/src/scss:

Variable Group	File	Controls
Breakpoints	`queries.scss`	Responsive breakpoints
Colors	`colors.scss`	Base shades, success/warning/error, theme-specific bg/text/input
Elevation	`colors.scss`	How "bright" elements appear vs background
Sizing	`app.scss`	Gutters, transition speeds, font sizes

Color variables automatically adapt to dark/light theme. Payload inverts:

When overriding colors — always verify both dark and light themes.

Global CSS → custom.scss at app root; highest specificity wins by default
Use @layer payload-default to stay within Payload's specificity layer
Import ~@payloadcms/ui/scss to re-use Payload's SCSS variables
BEM class names are stable and globally targetable
CSS custom properties (colors, sizing, elevation) are the fastest way to retheme
Always check dark mode when touching color variables