{"id":124406,"date":"2026-07-07T15:31:22","date_gmt":"2026-07-07T15:31:22","guid":{"rendered":"https:\/\/make.wordpress.org\/core\/?p=124406"},"modified":"2026-07-07T15:33:06","modified_gmt":"2026-07-07T15:33:06","slug":"merge-proposal-design-system-theming","status":"publish","type":"post","link":"https:\/\/make.wordpress.org\/core\/2026\/07\/07\/merge-proposal-design-system-theming\/","title":{"rendered":"Merge Proposal: Design System Theming"},"content":{"rendered":"<p class=\"wp-block-paragraph\">As part of design systems work supporting the <a href=\"https:\/\/make.wordpress.org\/core\/2023\/07\/12\/admin-design\/\">admin design project<\/a>, the <span tabindex='0' class='glossary-item-container'>Gutenberg<span class='glossary-item-hidden-content'><span class='glossary-item-header'>Gutenberg<\/span> <span class='glossary-item-description'>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 \u2018blocks\u2019 to add richness rather than shortcodes, custom HTML etc.\r<a href=\"https:\/\/wordpress.org\/gutenberg\/\">https:\/\/wordpress.org\/gutenberg\/<\/a><\/span><\/span><\/span> Components Team has been working on a foundational layer of themeability and design tokens that support consistent, accessible <span tabindex='0' class='glossary-item-container'>UI<span class='glossary-item-hidden-content'><span class='glossary-item-header'>UI<\/span> <span class='glossary-item-description'>User interface<\/span><\/span><\/span> components across the <span tabindex='0' class='glossary-item-container'>admin<span class='glossary-item-hidden-content'><span class='glossary-item-header'>admin<\/span> <span class='glossary-item-description'>(and super admin)<\/span><\/span><\/span> experience. On behalf of this group, I would like to propose the initial theming <span tabindex='0' class='glossary-item-container'>capabilities<span class='glossary-item-hidden-content'><span class='glossary-item-header'>capability<\/span> <span class='glossary-item-description'>A\u00a0<strong>capability<\/strong>\u00a0is permission to perform one or more types of task. Checking if a user has a capability is performed by the <code>current_user_can<\/code> function. Each user of a WordPress site might have some permissions but not others, depending on their\u00a0role. For example, users who have the Author role usually have permission to edit their own posts (the \u201cedit_posts\u201d capability), but not permission to edit other users\u2019 posts (the \u201cedit_others_posts\u201d capability).<\/span><\/span><\/span> for merge: a comprehensive set of design tokens and themeability enabled through the <a href=\"https:\/\/wordpress.github.io\/gutenberg\/?path=\/docs\/design-system-theme-introduction--docs#theme-provider\">ThemeProvider<\/a> <span tabindex='0' class='glossary-item-container'>React<span class='glossary-item-hidden-content'><span class='glossary-item-header'>React<\/span> <span class='glossary-item-description'>React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces.\r<a href=\"https:\/\/reactjs.org\/\">https:\/\/reactjs.org<\/a><\/span><\/span><\/span> component.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Purpose and Goals<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The broader design systems effort is aimed at improving consistency and <span tabindex='0' class='glossary-item-container'>accessibility<span class='glossary-item-hidden-content'><span class='glossary-item-header'>Accessibility<\/span> <span class='glossary-item-description'>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 \u201cdirect access\u201d (i.e. unassisted) and \u201cindirect access\u201d meaning compatibility with a person\u2019s assistive technology (for example, computer screen readers). (https:\/\/en.wikipedia.org\/wiki\/Accessibility)<\/span><\/span><\/span> 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 <a href=\"https:\/\/developer.mozilla.org\/en-US\/docs\/Web\/CSS\/Guides\/Cascading_variables\/Using_custom_properties\">CSS custom properties<\/a> that can be used within components to apply color, typography, border, elevation, or other styling aspects.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">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 <a href=\"https:\/\/github.com\/WordPress\/gutenberg\/tree\/trunk\/packages\/base-styles\">@wordpress\/base-styles<\/a> 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 <span tabindex='0' class='glossary-item-container'>CSS<span class='glossary-item-hidden-content'><span class='glossary-item-header'>CSS<\/span> <span class='glossary-item-description'>Cascading Style Sheets.<\/span><\/span><\/span> colors will become aliases to tokens within the broader set of design tokens.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">One particularly ambitious outcome of this project is a tool for <a href=\"https:\/\/wordpress.github.io\/gutenberg\/?path=\/docs\/design-system-theme-theme-provider-color-scales--docs\">generating color ramps<\/a> from a pair of accent and background \u201cseed\u201d colors. This tool can create a color scale that\u2019s configurable, visually harmonious, and provides accessible contrast between color values that are used together.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">This configurability is an important aspect of theming, and it\u2019s crucial to unlocking a number of use-cases that should be supported:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>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.<\/li>\n\n\n\n<li>For <span tabindex='0' class='glossary-item-container'>plugin<span class='glossary-item-hidden-content'><span class='glossary-item-header'>Plugin<\/span> <span class='glossary-item-description'>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 <a href=\"https:\/\/wordpress.org\/plugins\/\">https:\/\/wordpress.org\/plugins\/<\/a> or can be cost-based plugin from a third-party.<\/span><\/span><\/span> 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.<\/li>\n\n\n\n<li>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 \u201cdark mode\u201d feature, since admin surfaces are controlled by the background seed color.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Background<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">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:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>In 2022, initial explorations around a <a href=\"https:\/\/github.com\/WordPress\/gutenberg\/issues\/42388\">themeable and scalable primitive system<\/a> were explored, identifying challenges in managing complexity and configurability of interfaces.<\/li>\n\n\n\n<li>In 2023, this work picked up traction around the <a href=\"https:\/\/make.wordpress.org\/core\/2023\/07\/12\/admin-design\/\">Admin Design roadmap project<\/a>, which seeks to give plugins and users more control over the experience while ensuring it is intuitive, accessible, and delightful.<\/li>\n\n\n\n<li>In 2024, an <a href=\"https:\/\/make.wordpress.org\/design\/2024\/09\/05\/advancing-the-wordpress-design-system\/\">initiative to better document and share<\/a> the pieces of the design system resulted in improvements to <a href=\"https:\/\/wordpress.github.io\/gutenberg\/?path=\/docs\/introduction--page\">the Gutenberg Components Storybook site<\/a>. Later that year, a new <a href=\"https:\/\/make.wordpress.org\/design\/2024\/11\/07\/announcing-the-new-wordpress-design-system-figma-library\/\">WordPress Design System Figma library<\/a> was published.<\/li>\n\n\n\n<li>In 2025, the <a href=\"https:\/\/github.com\/WordPress\/gutenberg\/issues\/71196\">limitations and high-level requirements of the design system admin design support<\/a> were captured in an overview issue, which in turn prompted the initial theming work that\u2019s now proposed to be merged.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">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\u2019s visual refresh is one example of this (in particular, the reskin effort in <a href=\"https:\/\/core.trac.wordpress.org\/ticket\/64308\">#64308<\/a>). A comprehensive theming system based on CSS properties should reduce this ongoing maintenance cost, in both React-based and non-React-based admin interfaces.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">This also tracks with where the software industry is moving. The <a href=\"https:\/\/www.w3.org\/community\/design-tokens\/\">W3C Design Tokens Community Group<\/a> published the first stable version of the <a href=\"https:\/\/www.designtokens.org\/\">Design Tokens (DTCG) specification<\/a> 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 <a href=\"https:\/\/www.figma.com\/blog\/schema-2025-design-systems-recap\/#importing-and-exporting-variables\">importing design tokens as variables<\/a>. 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.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">What\u2019s Proposed for Merge<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">For developers, the initial set of theming APIs proposed for merge are:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>A <span tabindex='0' class='glossary-item-container'>core<span class='glossary-item-hidden-content'><span class='glossary-item-header'>Core<\/span> <span class='glossary-item-description'>Core is the set of software required to run WordPress. The Core Development Team builds WordPress.<\/span><\/span><\/span> registered stylesheet <code>wp-theme<\/code>, including a set of <a href=\"https:\/\/github.com\/WordPress\/gutenberg\/blob\/trunk\/packages\/theme\/src\/prebuilt\/css\/design-tokens.css\">prebuilt CSS properties<\/a> for the default WordPress theme.<\/li>\n\n\n\n<li>A core registered <span tabindex='0' class='glossary-item-container'>JavaScript<span class='glossary-item-hidden-content'><span class='glossary-item-header'>JavaScript<\/span> <span class='glossary-item-description'>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\u2019s browser.\r<a href=\"https:\/\/www.javascript.com\/\">https:\/\/www.javascript.com<\/a><\/span><\/span><\/span> <code>wp-theme<\/code>, including a single React <a href=\"https:\/\/wordpress.github.io\/gutenberg\/?path=\/docs\/design-system-theme-introduction--docs#theme-provider\">ThemeProvider component<\/a> for extending the default theme in an area of the admin\u2019s user interface.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">The default theme stylesheet is compiled from a <a href=\"https:\/\/github.com\/WordPress\/gutenberg\/tree\/trunk\/packages\/theme\/tokens\">set of design tokens<\/a> 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.\u00a0<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">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.\u00a0<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">That being said, a noteworthy feature coming in WordPress 7.1 is the application of the user color scheme to the <a href=\"https:\/\/wordpress.org\/documentation\/article\/site-editor\/\">Site Editor<\/a>, which is powered by the theming implementation.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">What\u2019s Next<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">While not targeted for inclusion in WordPress 7.1, the following features are being considered for future iterations:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Better default availability of design tokens:<\/strong> While the new <code>wp-theme<\/code> 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\u2019s expected that the tokens would be available more universally throughout the admin interface. In the meantime, developers can enqueue the stylesheet themselves.<\/li>\n\n\n\n<li><strong>Adoption and support across all screens:<\/strong> 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\u2019s expected that these design tokens would be adopted across all admin screens, not just React-based screens such as the <span tabindex='0' class='glossary-item-container'>block<span class='glossary-item-hidden-content'><span class='glossary-item-header'>Block<\/span> <span class='glossary-item-description'>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.<\/span><\/span><\/span> and site editor. This builds on the work in <a href=\"https:\/\/core.trac.wordpress.org\/ticket\/64308\">#64308<\/a> in a way that is more sustainable and comprehensive.<\/li>\n\n\n\n<li><strong>Enhanced user customization through theming, enabling features like \u201cdark mode\u201d:<\/strong> 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 \u201cdark mode\u201d-like experience will be explored in future releases. The theming system already supports the <span tabindex='0' class='glossary-item-container'>capability<span class='glossary-item-hidden-content'><span class='glossary-item-header'>capability<\/span> <span class='glossary-item-description'>A\u00a0<strong>capability<\/strong>\u00a0is permission to perform one or more types of task. Checking if a user has a capability is performed by the <code>current_user_can<\/code> function. Each user of a WordPress site might have some permissions but not others, depending on their\u00a0role. For example, users who have the Author role usually have permission to edit their own posts (the \u201cedit_posts\u201d capability), but not permission to edit other users\u2019 posts (the \u201cedit_others_posts\u201d capability).<\/span><\/span><\/span> for this today.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Call for Feedback<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">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,\u00a0there\u2019s particular interest in any risks or conflicts to consider in the proposed implementation.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Props to <a href=\"https:\/\/profiles.wordpress.org\/mciampini\/\" class=\"mention\"><span class=\"mentions-prefix\">@<\/span>mciampini<\/a>, <a href=\"https:\/\/profiles.wordpress.org\/annezazu\/\" class=\"mention\"><span class=\"mentions-prefix\">@<\/span>annezazu<\/a>, and <a href=\"https:\/\/profiles.wordpress.org\/0mirka00\/\" class=\"mention\"><span class=\"mentions-prefix\">@<\/span>0mirka00<\/a> for reviewing this post.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><a href=\"\/\/make.wordpress.org\/design\/\" class=\"po-xpost\"><\/a><a href=\"\/\/make.wordpress.org\/design\/\" class=\"po-xpost\">+make.wordpress.org\/design\/<\/a><\/p>\n<p class=\"o2-appended-tags\"><a href=\"https:\/\/make.wordpress.org\/core\/tag\/7-1\/\" class=\"tag\"><span class=\"tag-prefix\">#<\/span>7-1<\/a>, <a href=\"https:\/\/make.wordpress.org\/core\/tag\/merge-proposals\/\" class=\"tag\"><span class=\"tag-prefix\">#<\/span>merge-proposals<\/a><\/p><nav class='o2-post-footer-actions'><ul class='o2-post-footer-action-row'><li class='o2-post-footer-action'><a href=\"https:\/\/login.wordpress.org\/?redirect_to=https%3A%2F%2Fmake.wordpress.org%2Fcore%2F2026%2F07%2F07%2Fmerge-proposal-design-system-theming%2F%23respond&#038;locale=en_US\" title=\"Login to Reply\"  class=\"genericon  genericon-reply\"  data-action=\"login-to-reply\"  data-actionstate=\"default\" >Login to Reply<\/a><\/li><\/ul><div class='o2-post-footer-action-likes'><\/div><ul class='o2-post-footer-action-row'><\/ul><\/nav>","protected":false},"excerpt":{"rendered":"<p>As part of design systems work supporting the admin design project, the GutenbergGutenberg 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 \u2018blocks\u2019 to add richness rather than shortcodes, custom HTML etc. https:\/\/wordpress.org\/gutenberg\/ Components Team [&hellip;]<\/p>\n","protected":false},"author":13655154,"featured_media":0,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"advanced_seo_description":"","jetpack_seo_html_title":"","jetpack_seo_noindex":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_post_was_ever_published":false},"categories":[1174],"tags":[5885,1522],"class_list":["post-124406","post","type-post","status-publish","format-standard","hentry","category-proposals","tag-7-1","tag-merge-proposals","mentions-0mirka00","mentions-annezazu","mentions-mciampini","author-aduth"],"revision_note":"","jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p2AvED-wmy","_links":{"self":[{"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/posts\/124406","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/users\/13655154"}],"replies":[{"embeddable":true,"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/comments?post=124406"}],"version-history":[{"count":14,"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/posts\/124406\/revisions"}],"predecessor-version":[{"id":124445,"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/posts\/124406\/revisions\/124445"}],"wp:attachment":[{"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/media?parent=124406"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/categories?post=124406"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/tags?post=124406"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}