feat(ui): add CSS variable theming system for fields, buttons, controls, and popups

[JarrodMFlesch]

Summary

This PR introduces a comprehensive CSS variable theming system for the Payload admin panel, enabling users to deeply customize the UI through CSS custom properties — no !important needed, since all Payload component styles are inside @layer payload-default.

---

What's new

packages/ui/src/css/theme.css (new file)

Central location for all component-level override variables. Imported by styles.css.

Variable	Purpose
--field-min-height	Minimum height of form field inputs
--field-padding-inline	Inline padding for form fields
--field-border-radius	Border radius for form fields
--button-height	Height for standard buttons
--button-radius	Border radius for buttons and interactive elements
--control-height	Height for compact toolbar controls (search bar, paginator)
--popup-radius	Border radius for popup containers
--popup-item-radius	Border radius for popup list items
--popup-item-bg-hover	Background color for hovered popup items
--popup-item-color-hover	Text color for hovered popup items
--popup-item-bg-selected	Background color for selected popup items

Field color variables (colors.css)

27 --field-color-* variables wired through all field CSS files for consistent field appearance customization.

Button sizing fix

Buttons now use box-sizing: content-box so the Figma spec of 24px content + 1px border × 2 = 26px total is correct. Large button height also updated accordingly.

SearchBar / Hierarchy search fix

• Changed from outline to border — so the border participates in height calculation like all other inputs
• Applied --control-height + content-box to SearchBar, Hierarchy search, and Pagination inputs
• This fixes the height mismatch between the search input and adjacent buttons

Popup background fix

Root cause: Popup uses createPortal and sets data-theme directly on the .popup__content element itself. Descendant selectors like [data-theme='dark'] .popup__content never matched.

Fix: Use a CSS variable fallback evaluated in the element's own context:

background: var(--popup-bg, var(--color-bg-elevated));

This correctly resolves --color-bg-elevated in the popup's own data-theme context. --popup-bg becomes a pure user override hook (not defined in defaults).

Localizer renderButton refactor

Localizer now accepts a renderButton prop (same signature as Popup.renderButton). AppHeader passes a custom renderButton that owns the button appearance, removing a CSS hack that was targeting .btn inside .app-header__localizer.

Focus rings

Added a global :focus-visible rule in utilities.css and replaced --radius-medium with --button-radius on ~25 interactive/focusable elements for consistency.

---

How users can customize

All Payload styles are in @layer payload-default. Plain (unlayered) CSS in :root automatically wins — no !important required:

:root {
  /* Buttons */
  --button-height: 32px;
  --button-radius: 6px;

  /* Form fields */
  --field-min-height: 40px;
  --field-border-radius: 6px;

  /* Popup menus */
  --popup-bg: #1e2130;
  --popup-item-bg-hover: rgba(255, 255, 255, 0.08);
  --popup-item-bg-selected: rgba(255, 255, 255, 0.12);
}

[github-actions]

📦 esbuild Bundle Analysis for payload

This analysis was generated by esbuild-bundle-analyzer. 🤖

Meta File	Out File	Size (raw)	Note
packages/next/meta_index.json	esbuild/index.js	1.03 MB	🆕 Added
packages/payload/meta_index.json	esbuild/index.js	1.41 MB	🆕 Added
packages/payload/meta_shared.json	esbuild/exports/shared.js	192.51 KB	🆕 Added
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	304.12 KB	🆕 Added
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.28 MB	🆕 Added
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	18.64 KB	🆕 Added

Largest paths

These visualization shows top 20 largest paths in the bundle.

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████████▉ }}}$ 83.9%, 861.10 KB
dist/views/Version	${{\color{Goldenrod}{ █▎ }}}$ 5.3%, 54.61 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▌ }}}$ 2.1%, 21.85 KB
dist/views/Document	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 16.76 KB
dist/views/List	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 15.96 KB
dist/views/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 10.01 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.48 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.13 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 5.74 KB
dist/views/Login	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 4.64 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.4%, 3.61 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 3.22 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.3%, 3.02 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.2%, 2.46 KB
dist/views/Logout	${{\color{Goldenrod}{ }}}$ 0.2%, 1.96 KB
dist/views/Verify	${{\color{Goldenrod}{ }}}$ 0.1%, 1.35 KB
dist/utilities/initReq.js	${{\color{Goldenrod}{ }}}$ 0.1%, 1.15 KB
dist/views/NotFound	${{\color{Goldenrod}{ }}}$ 0.1%, 1.04 KB
dist/adapters/router.js	${{\color{Goldenrod}{ }}}$ 0.1%, 659 B
dist/adapters/server.js	${{\color{Goldenrod}{ }}}$ 0.1%, 531 B
(other)	${{\color{Goldenrod}{ ████ }}}$ 16.1%, 164.75 KB

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████ }}}$ 68.4%, 959.52 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.1%, 44.07 KB
dist/collections/operations	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 40.23 KB
dist/versions/migrations	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 18.50 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 15.63 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.58 KB
dist/fields/config	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.40 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.40 KB
dist/queues/operations	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 12.63 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.57 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.53 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.44 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.92 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.80 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.77 KB
dist/hierarchy/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.65 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.54 KB
dist/collections/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 6.23 KB
dist/auth/strategies	${{\color{Goldenrod}{ }}}$ 0.4%, 5.43 KB
dist/queues/config	${{\color{Goldenrod}{ }}}$ 0.4%, 5.31 KB
(other)	${{\color{Goldenrod}{ ███████▉ }}}$ 31.6%, 443.83 KB

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████████████▉ }}}$ 79.5%, 150.12 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▍ }}}$ 5.6%, 10.57 KB
dist/config/orderable	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 3.13 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 2.54 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.42 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 1.29 KB
dist/utilities/getVersionsConfig.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 1.04 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 943 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ }}}$ 0.4%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.4%, 713 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 651 B
dist/collections/config	${{\color{Goldenrod}{ }}}$ 0.3%, 570 B
dist/bin/generateImportMap	${{\color{Goldenrod}{ }}}$ 0.3%, 561 B
dist/auth/sessions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 525 B
dist/fields/getFieldPaths.js	${{\color{Goldenrod}{ }}}$ 0.3%, 485 B
dist/utilities/appendDateTimezoneSelectFields.js	${{\color{Goldenrod}{ }}}$ 0.2%, 451 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.2%, 423 B
dist/utilities/deepMerge.js	${{\color{Goldenrod}{ }}}$ 0.2%, 413 B
(other)	${{\color{Goldenrod}{ █████▏ }}}$ 20.5%, 38.61 KB

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
dist/features/blocks	${{\color{Goldenrod}{ ███ }}}$ 12.4%, 37.36 KB
dist/lexical/ui	${{\color{Goldenrod}{ ██▊ }}}$ 11.4%, 34.16 KB
dist/lexical/plugins	${{\color{Goldenrod}{ ██▋ }}}$ 10.9%, 32.88 KB
dist/features/experimental_table	${{\color{Goldenrod}{ ██▎ }}}$ 9.0%, 27.16 KB
dist/packages/@lexical	${{\color{Goldenrod}{ █▌ }}}$ 6.3%, 18.99 KB
dist/features/link	${{\color{Goldenrod}{ █▌ }}}$ 6.3%, 18.81 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 16.58 KB
dist/features/upload	${{\color{Goldenrod}{ █▏ }}}$ 4.7%, 14.09 KB
dist/features/textState	${{\color{Goldenrod}{ ▉ }}}$ 3.7%, 11.08 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.1%, 9.39 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 8.79 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.8%, 8.36 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.40 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 7.29 KB
dist/lexical/config	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 5.08 KB
dist/features/lists	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 5.00 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 3.46 KB
dist/lexical/LexicalEditor.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.23 KB
dist/features/horizontalRule	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.18 KB
dist/field/Field.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.84 KB
(other)	${{\color{Goldenrod}{ █████████████████████▉ }}}$ 87.6%, 263.53 KB

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████▍ }}}$ 45.6%, 579.79 KB
dist/elements/Hierarchy	${{\color{Goldenrod}{ ▊ }}}$ 3.4%, 43.08 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 28.07 KB
dist/views/HierarchyList	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 20.43 KB
dist/elements/Table	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 19.28 KB
dist/views/Edit	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 17.57 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 17.34 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 15.87 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 15.47 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 15.11 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 14.40 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.22 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.66 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 8.26 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.83 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.76 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.75 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.54 KB
dist/elements/RelationshipTable	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.69 KB
(other)	${{\color{Goldenrod}{ █████████████▌ }}}$ 54.4%, 691.31 KB

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ ███████▋ }}}$ 30.9%, 5.57 KB
../../node_modules	${{\color{Goldenrod}{ ███▋ }}}$ 14.7%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▏ }}}$ 8.5%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ █▊ }}}$ 7.4%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▏ }}}$ 4.8%, 866 B
dist/utilities/getGlobalData.js	${{\color{Goldenrod}{ █ }}}$ 4.2%, 762 B
dist/utilities/api.js	${{\color{Goldenrod}{ █ }}}$ 4.2%, 756 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █ }}}$ 4.1%, 745 B
dist/elements/Translation	${{\color{Goldenrod}{ ▋ }}}$ 2.7%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 440 B
dist/utilities/traverseForLocalizedFields.js	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 399 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 339 B
dist/utilities/getNavGroups.js	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 338 B
dist/utilities/getVisibleEntities.js	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 329 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 180 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 157 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 152 B
dist/forms/Form	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 148 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 146 B
(other)	${{\color{Goldenrod}{ █████████████████▎ }}}$ 69.1%, 12.45 KB

Details

Next to the size is how much the size has increased or decreased compared with the base branch of this PR.

• ‼️: Size increased by 20% or more. Special attention should be given to this.
• ⚠️: Size increased in acceptable range (lower than 20%).
• ✅: No change or even downsized.
• 🗑️: The out file is deleted: not found in base branch.
• 🆕: The out file is newly found: will be added to base branch.

Addressed feedback.