Design tokens and ThemeProvider component enable consistent admin theming

As part of design systems work supporting the admin design project, the Gutenberg Components Team has been working on a foundational layer of themeability and design tokens that support consistent, accessible UI components across the admin experience. On behalf of this group, I would like to propose the initial theming capabilities for merge: a comprehensive set of design tokens and themeability enabled through the ThemeProvider React component.

Purpose and Goals

The broader design systems effort is aimed at improving consistency and accessibility of components in the WordPress admin experience. Theming and design tokens are the foundational set of styles that support this work. In practice, the net result is a set of CSS custom properties that can be used within components to apply color, typography, border, elevation, or other styling aspects.

Using design token properties instead of hard-coded values helps ensure consistency across components, while still supporting customization like user color scheme. This builds upon established shared styles like those in the @wordpress/base-styles NPM package by providing a basis that can apply to many other types of UI surfaces and controls. With this comprehensive theming approach, those established CSS colors will become aliases to tokens within the broader set of design tokens.

One particularly ambitious outcome of this project is a tool for generating color ramps from a pair of accent and background “seed” colors. This tool can create a color scale that’s configurable, visually harmonious, and provides accessible contrast between color values that are used together.

This configurability is an important aspect of theming, and it’s crucial to unlocking a number of use-cases that should be supported:

• For users, this enables more personalization over how the interface looks. WordPress can continue to provide smart defaults and support the existing set of admin color palettes, but a user could also have the option to choose whichever color combination they prefer. This can be extended later with more themeable aspects, like roundness or density.
• For plugin developers, they can express their own brand identity while still feeling authentic and consistent with the rest of the WordPress experience. Opting into WordPress theming means they benefit from future improvements automatically, without an ongoing maintenance cost. Design tokens aim to reduce confusion for developers and AI agents in choosing the best styling for a UI element by providing a comprehensive set of tokens aligned to semantic purpose.
• For WordPress development, it provides an easier pathway to extend the user color scheme consistently to more parts of the admin interface. It also unlocks the ability to more easily implement features like a true “dark mode” feature, since admin surfaces are controlled by the background seed color.

Background

The design system effort has evolved over the last several years, guided by a baseline expectation of accessibility and consistency, and a need for a strong foundation for admin innovation:

• In 2022, initial explorations around a themeable and scalable primitive system were explored, identifying challenges in managing complexity and configurability of interfaces.
• In 2023, this work picked up traction around the Admin Design roadmap project, which seeks to give plugins and users more control over the experience while ensuring it is intuitive, accessible, and delightful.
• In 2024, an initiative to better document and share the pieces of the design system resulted in improvements to the Gutenberg Components Storybook site. Later that year, a new WordPress Design System Figma library was published.
• In 2025, the limitations and high-level requirements of the design system admin design support were captured in an overview issue, which in turn prompted the initial theming work that’s now proposed to be merged.

While WordPress has had shared styles and shared componentry in many forms over the years, it has required significant ongoing effort to try to maintain consistency. WordPress 7.0’s visual refresh is one example of this (in particular, the reskin effort in #64308). A comprehensive theming system based on CSS properties should reduce this ongoing maintenance cost, in both React-based and non-React-based admin interfaces.

This also tracks with where the software industry is moving. The W3C Design Tokens Community Group published the first stable version of the Design Tokens (DTCG) specification late last year, and the WordPress theme design tokens follow this specification. This specification is seeing adoption in industry tools like Figma, which has added support for importing design tokens as variables. As the discrete foundational unit for styling UI components, a set of documented, semantic design tokens are well-understood by AI agents, which helps maintain a high standard of quality as developers adopt this technology.

What’s Proposed for Merge

For developers, the initial set of theming APIs proposed for merge are:

• A core registered stylesheet wp-theme, including a set of prebuilt CSS properties for the default WordPress theme.
• A core registered JavaScript wp-theme, including a single React ThemeProvider component for extending the default theme in an area of the admin’s user interface.

The default theme stylesheet is compiled from a set of design tokens that follow the design token specification. Developers and designers may find these tokens useful, as they can be imported directly into design tools like Figma for use in designs.

For users, the current expected impact should be minimal, aside from more UI component consistency throughout the admin interface. The default theme was intentionally designed to be largely aligned with existing styles, and not radically change the appearance of existing screens.

That being said, a noteworthy feature coming in WordPress 7.1 is the application of the user color scheme to the Site Editor, which is powered by the theming implementation.

What’s Next

While not targeted for inclusion in WordPress 7.1, the following features are being considered for future iterations:

• Better default availability of design tokens: While the new wp-theme stylesheet will be registered, it will only be enqueued by default on specific WordPress screens that use the new theming feature. As theming extends to more parts of the interface, it’s expected that the tokens would be available more universally throughout the admin interface. In the meantime, developers can enqueue the stylesheet themselves.
• Adoption and support across all screens: Since the design tokens are built on web standard technology (CSS properties) and a goal of the design system is to ensure consistency across all WordPress screens, it’s expected that these design tokens would be adopted across all admin screens, not just React-based screens such as the block and site editor. This builds on the work in #64308 in a way that is more sustainable and comprehensive.
• Enhanced user customization through theming, enabling features like “dark mode”: While this initial iteration provides a strong foundation for internal consistency, the true power of theming in providing more user expressiveness and capabilities for a “dark mode”-like experience will be explored in future releases. The theming system already supports the capability for this today.

Call for Feedback

Your feedback to this merge proposal is welcomed in the comments below. As this work is focused on the long-term sustainability of UI component development, there’s particular interest in any risks or conflicts to consider in the proposed implementation.

Props to @mciampini, @annezazu, and @0mirka00 for reviewing this post.

+make.wordpress.org/design/

#7-1, #merge-proposals