Skip to content

Refactor admin-ui Page component to use @wordpress/theme tokens and @wordpress/ui layout primitive#75963

Merged
jameskoster merged 7 commits intotrunkfrom
update/admin-ui-page
Mar 6, 2026
Merged

Refactor admin-ui Page component to use @wordpress/theme tokens and @wordpress/ui layout primitive#75963
jameskoster merged 7 commits intotrunkfrom
update/admin-ui-page

Conversation

@jameskoster
Copy link
Copy Markdown
Contributor

What

Refactors the admin-ui Page and Header components to use @wordpress/theme design tokens and the Stack component from @wordpress/ui.

Why

The Page component relied on experimental @wordpress/components abstractions (__experimentalHeading, __experimentalHStack, __experimentalVStack) and Sass variables from @wordpress/base-styles. Migrating to @wordpress/theme tokens and the Stack layout primitive aligns this component with the design system's token-based approach, making it easier to maintain and ensuring it benefits from theme-level features.

How

  • header.tsx: Replaced Heading with a plain <h2> styled via a new CSS class. Replaced all HStack and VStack instances with Stack from @wordpress/ui — the outer VStack uses render={ <header /> } to preserve the semantic <header> element while leveraging Stack's layout.
  • style.scss: Removed all @wordpress/base-styles Sass imports and replaced every variable/mixin usage with --wpds-* CSS custom properties (colors, spacing, typography, borders). Added a new .admin-ui-page__header-title rule with heading font tokens and text truncation.
  • package.json: Added @wordpress/ui as a dependency.

Token mapping

Before (Sass) After (CSS custom property)
$white --wpds-color-bg-surface-neutral-strong
$gray-800 --wpds-color-fg-content-neutral
$gray-100 --wpds-color-stroke-surface-neutral-weak
$gray-700 --wpds-color-fg-content-neutral-weak
$grid-unit-20 / $grid-unit-30 --wpds-dimension-padding-lg / --wpds-dimension-padding-2xl
$grid-unit-10 --wpds-dimension-padding-xs
@include body-medium() --wpds-font-size-md / --wpds-font-line-height-md
$helptext-font-size --wpds-font-size-sm

Testing

  • Enable the Extensible Site Editor experiment and navigate to Appearance -> Editor
  • Check for any visual regressions

Screenshots

Before After
Screenshot 2026-02-26 at 14 28 49 Screenshot 2026-02-26 at 14 23 11

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Backported to WP Core Pull request that has been successfully merged into WP Core Design System Issues related to the system of combining components according to best practices. [Type] Enhancement A suggestion for improvement.

Projects

Status: 💫 Done

Development

Successfully merging this pull request may close these issues.

6 participants