[RFC] Modernize @payloadcms/ui: Tailwind CSS, Base UI Primitives, and a Mantine-inspired Styles API

[michaelcamper]

Some context first

I genuinely love Payload. It's become my go-to CMS, and I've been actively developing and publishing plugins for it. Every time I build something new, I'm reminded of how well-thought-out the core architecture is.

That said, there's one area where the developer experience breaks down significantly: making custom components visually indistinguishable from Payload's native admin UI. After building several plugins, I've run into the same walls repeatedly, and I believe a set of coordinated changes to @payloadcms/ui would solve these problems not just for me, but for the entire plugin ecosystem.

This RFC is intentionally ambitious. I know it touches a lot of surface area, but I think the pieces fit together as a coherent vision. I'm also offering my time and effort to help implement this — more on that at the end.

---

The problem

1. Many internal components aren't exported as decoupled primitives

Many of the components used inside the admin panel (Input, Select, Tabs, DropdownMenu, etc.) are tightly coupled to internal wiring and either aren't exported or aren't usable in isolation. Plugin developers end up in one of two situations:

• Copy-pasting internal component code into their plugin, which breaks on Payload upgrades
• Writing custom components from scratch that inevitably look and behave differently from the native admin UI

Related discussions: #9794, #4820, #293

2. The SCSS + BEM + CSS variables approach creates friction

The current styling system (SCSS with BEM naming, CSS layers, and --theme-* custom properties) works well internally, but it creates a steep learning curve for anyone building on top of Payload:

• Plugin authors must learn Payload's variable naming conventions (--theme-elevation-500, --base, etc.)
• BEM class names provide targeting, but offer no structured API for customizing inner elements of a component — you're always one internal refactor away from your selectors breaking
• There's no way for an app developer to theme the admin panel through a single configuration point

Related discussion: #5028

3. No component documentation

As noted in the roadmap discussion (#293), the component library is marked "Done. Only missing docs." In practice, the lack of documentation makes @payloadcms/ui very difficult to use without cloning the repo and reading source code. Community members have resorted to writing their own unofficial glossaries.

---

Proposed solution

I'm proposing four coordinated changes that work together as a system:

1. Replace src/elements primitives with Base UI

Base UI reached v1.0 in February 2026 with 35 headless components. It's built by the creators of Radix UI and covers exactly the primitives Payload currently maintains in-house: Select, Tabs, Menu, Dialog, Combobox, Switch, Checkbox, Input, Field, and more.

Why Base UI specifically:

• Truly headless — zero default styles, works perfectly with any styling solution
• Slot-based architecture — every inner element is a named slot that can be targeted, replaced, or styled independently
• Accessibility built in — WAI-ARIA compliant keyboard navigation, focus management, screen reader support — all maintained by a dedicated team
• data-* attributes for state — components expose data-disabled, data-selected, data-open, etc., which are perfect for Tailwind's attribute selectors
• Active, funded maintenance — backed by a full-time team with long-term commitment

This would let Payload's team stop maintaining low-level interaction logic (keyboard handling, focus traps, ARIA attributes, portal management) and focus on the CMS-specific composition layer on top.

Before (current internal primitive):

// Payload maintains its own Select with custom keyboard handling,
// portal logic, accessibility, and styling

After (Base UI primitive, styled by Payload):

import { Select } from '@base-ui-components/react/select';


  
    
  
  
    
      
        {options.map(opt => (
          
             {opt.label}
          
        ))}
      
    
  

2. Switch entirely to Tailwind CSS

Drop the SCSS + BEM + CSS variables approach and adopt Tailwind CSS as the sole styling system for the admin panel.

Why this makes sense now:

• Ecosystem alignment — Payload runs on Next.js. Tailwind is the default styling choice in the Next.js ecosystem. Every Payload app already has a tailwind.config for the frontend. Having the admin panel speak the same language removes a major integration pain point.
• Tailwind v4's CSS-first config — With v4, Tailwind moved to @theme blocks in CSS, which maps cleanly to a theming system that app developers can override without touching JavaScript configs.
• CSS layers are already in use — Payload already wraps styles in @layer payload-default. Tailwind v4 also uses CSS layers natively. The mental model aligns.
• Dark mode — Tailwind's dark: variant with a class-based toggle replaces the current approach of mirrored CSS variables. The theme's CSS custom properties can be swapped under a .dark selector, and Tailwind picks them up automatically — no need to maintain two parallel sets of variables.
• LLM-friendly — Tailwind is one of the most well-represented libraries in LLM training data. AI coding tools (Copilot, Cursor, Claude, etc.) generate accurate Tailwind markup out of the box. This directly improves the developer experience for anyone using AI-assisted development to build Payload plugins or custom admin components — which is increasingly the norm.

3. Mantine-inspired classNames prop for inner element customization

This is the replacement for BEM targeting. Instead of relying on CSS class name conventions that can break between versions, every @payloadcms/ui component would expose a typed classNames prop that maps named inner elements to CSS classes.

How it works:

Every component defines its internal structure as a set of named selectors (root, label, input, error, description, icon, etc.). The consumer passes an object mapping those selectors to class strings.

// Plugin author customizing a Payload Select component
<PayloadSelect
  classNames={{
    root: 'my-4',
    trigger: 'bg-pl-surface border-pl-border rounded-pl-md',
    popup: 'shadow-lg border border-pl-border',
    option: 'px-3 py-2 hover:bg-pl-primary/10',
    optionSelected: 'bg-pl-primary text-white',
  }}
/>

Why this beats BEM:

• Typed and versioned — the selector names are part of the component's public API. TypeScript catches typos. Breaking changes show up in changelogs.
• Framework-agnostic — works with Tailwind classes, CSS modules, vanilla CSS, or any string
• Composable — a plugin can partially override selectors while inheriting defaults for the rest
• Conditional styling — classNames can also accept a function that receives the component's state and props:

<PayloadSelect
  classNames={(theme, props) => ({
    trigger: clsx(
      'border rounded-pl-md',
      props.error ? 'border-pl-error' : 'border-pl-border'
    ),
  })}
/>

4. App-level Tailwind config overrides for theming

As a nice side-effect of switching to Tailwind, theming the admin panel becomes straightforward for app developers. Payload would define its design tokens as CSS custom properties, and the app developer overrides them in the existing src/app/(payload)/custom.scss:

/* src/app/(payload)/custom.scss */
:root {
  --pl-primary: #your-brand-color;
  --pl-bg: #fafafa;
  --pl-radius-md: 0.75rem;
}

.dark {
  --pl-bg: #0a0a0a;
  --pl-surface: #1a1a1a;
}

This isn't a plugin developer concern — it's simply a cleaner theming story for anyone deploying a Payload app who wants the admin panel to match their brand.

---

Documentation: Storybook + AI-ready markdown

Storybook with autodocs

Every component in @payloadcms/ui should ship with a Storybook story. Using Storybook's autodocs feature, JSDoc comments on component props automatically generate interactive documentation:

/**
 * A dropdown select component built on Base UI.
 * Supports single and multi-select modes with search filtering.
 *
 * @example
 * <PayloadSelect
 *   options={[{ label: 'Draft', value: 'draft' }, { label: 'Published', value: 'published' }]}
 *   value="draft"
 *   onChange={(val) => console.log(val)}
 * />
 */
export interface PayloadSelectProps {
  /** The available options to choose from */
  options: Option[]
  /** Currently selected value(s) */
  value?: string | string[]
  /** Callback fired when selection changes */
  onChange?: (value: string | string[]) => void
  /** Override classes for inner elements */
  classNames?: PayloadSelectClassNames
  /** Whether the select is in an error state */
  error?: boolean
  /** Placeholder text when no value is selected */
  placeholder?: string
}

Developers see this rendered as an interactive playground with a controls panel — they can toggle props, see variants, and copy code. No separate documentation site to maintain.

Auto-generated markdown for AI agents

As a build step, JSDoc + Storybook metadata can be extracted into structured markdown files:

# PayloadSelect

A dropdown select component built on Base UI.

## Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| options | `Option[]` | required | The available options |
| value | `string \| string[]` | — | Currently selected value(s) |
| onChange | `(value) => void` | — | Selection change callback |
| classNames | `PayloadSelectClassNames` | — | Override classes for inner elements |

## classNames selectors
| Selector | Element |
|----------|---------|
| root | Outermost wrapper |
| trigger | The button that opens the dropdown |
| popup | The dropdown panel |
| option | Individual option row |

## Usage
\`\`\`tsx

\`\`\`

These files can live alongside the source and be consumed by AI coding agents (Copilot, Cursor, Claude, etc.) as context, making it dramatically easier to generate correct Payload admin components.

---

Migration path

I'm not suggesting this happens overnight. A realistic migration could look like:

1. Phase 1 — Infrastructure: Set up Storybook and Tailwind inside @payloadcms/ui. No migration yet — just the tooling foundation to develop against.
2. Phase 2 — New components: Build new decoupled components using Base UI + Tailwind + classNames, developed in Storybook. Ship them alongside existing ones. Plugins can start adopting them immediately. Nothing breaks.
3. Phase 3 — Internal migration: Progressively replace Payload's internal usage of old primitives with the new ones. Deprecate BEM class targeting.
4. Phase 4 — Cleanup: Remove SCSS and old primitives. The Tailwind + classNames API becomes the official styling contract.

Phases 1–2 are purely additive — existing components keep working unchanged. Breaking changes only land in phases 3–4, giving the ecosystem time to migrate.

---

I'd like to help

I'm not just filing a feature request. I actively develop Payload plugins and run into these problems on every project. I'm willing to contribute to the implementation.

If the team is open to this direction, I'd love to start a conversation about where to begin and how to coordinate.

[magicspon]

Baseui would be great.
Tailwind, less so.

[michaelcamper]

Thank you for your feedback!

Would you mind elaborate why not tailwind?

[magicspon]

Modern css is incredibly powerful. I feel like tailwind is stuck in the past. I say that as an avid tailwind user. Just look at the markup shadcn and friends spit out, it's starting to get a bit ridiculous. Look at the catalyst button, it's insane! I still use tailwind but I'm starting to impose a rule, if it needs more than three classes, create a css module.

[michaelcamper]

Fair point, tailwind is definitely not a dealbreaker for this proposal.

I mainly proposed it because many people in the community a familiar with a shadcn-like design system so theming would be intuitive. But for the theming, I simple doc page explaining the design tokens and exposing the css variables to plugin creates would surely be sufficient for an improved DX.

[tsemachh]

I approach many organization with payload , and the one thing that usually stops them is the branding ,
most of the organizations used figma generated ui components and integrating it in payload as a custom component is a pain in the ass ,
as it usually comes as base ui + tailwind components , I do believe that this will help us to integrate payload in more organizations.
So +1 for the entire RFC from us

[michaelcamper]

Thank you for your feedback!

I believe a shadcn or daisy ui inspired design token system based on CCS variables would enable full visual customization.

[shaadcode]

I don't agree with tailwind css!
But the idea you presented was great because it makes the project more cohesive.
I think what payload should do is provide a set of pre-made components or use a UI library like Mantine (because maintaining components is hard and payload is not built for that).

[HarleySalas]

For the last year I have joked multiple times that, if I had all the money in the world, I would offer Vitaly (creator of Mantine) a blank check to adapt, or build a new version of Mantine, specially for making the entire payload admin and all of it's components themed and completely reusable.

If I could only give one suggestion to Payload for the rest of my life, it would be to consider Mantine, or something custom inspired by it for Payload v4.

[michaelcamper]

Word! Mantine's component API's and "ecosystem" are amazing.
I used it for years, but I switched to base ui some time ago because it allowed me to achieve superior web core vitals in nextjs apps.

[LeonGatt]

I totally agree with the idea of making the Payload UI a bit more visually customizable by default.
It would be awesome to have the project driven by a set of design system variables with the ability to make some tweaks.

But overall, I have to say that working with Payload Admin is by far the best experience I've had with a CMS, and I've worked with dozens of them.

So +1 from our team. We’re not just watching, we’re happy to contribute and help with the work. We've built a few custom UI libraries so far.