As part of design systems work supporting the admin design project, the Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ Components Team has been working on a foundational layer of themeability and design tokens that support consistent, accessible UI User interface components across the admin (and super admin) experience. On behalf of this group, I would like to propose the initial theming capabilities A capability is permission to perform one or more types of task. Checking if a user has a capability is performed by the current_user_can function. Each user of a WordPress site might have some permissions but not others, depending on their role. For example, users who have the Author role usually have permission to edit their own posts (the “edit_posts” capability), but not permission to edit other users’ posts (the “edit_others_posts” capability). for merge: a comprehensive set of design tokens and themeability enabled through the ThemeProvider React React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org component.

Purpose and Goals

The broader design systems effort is aimed at improving consistency and accessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/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 Cascading Style Sheets. 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 A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. 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 Core is the set of software required to run WordPress. The Core Development Team builds WordPress. registered stylesheet wp-theme, including a set of prebuilt CSS properties for the default WordPress theme.
• A core registered JavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com 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 Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. 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 A capability is permission to perform one or more types of task. Checking if a user has a capability is performed by the current_user_can function. Each user of a WordPress site might have some permissions but not others, depending on their role. For example, users who have the Author role usually have permission to edit their own posts (the “edit_posts” capability), but not permission to edit other users’ posts (the “edit_others_posts” 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