{"id":125147,"date":"2026-07-31T12:51:45","date_gmt":"2026-07-31T12:51:45","guid":{"rendered":"https:\/\/make.wordpress.org\/core\/?p=125147"},"modified":"2026-07-31T17:58:13","modified_gmt":"2026-07-31T17:58:13","slug":"design-system-theming-in-wordpress-7-1","status":"publish","type":"post","link":"https:\/\/make.wordpress.org\/core\/2026\/07\/31\/design-system-theming-in-wordpress-7-1\/","title":{"rendered":"Design System Theming in WordPress 7.1"},"content":{"rendered":"

WordPress 7.1 will include foundational support for theming design aspects of adminadmin<\/span> (and super admin)<\/span><\/span><\/span> interface components, including color, roundness, and cursor pointers for interactive controls. The background and purpose behind these new features were shared previously in Merge Proposal: Design System Theming<\/a>. This post aims to provide information about what is included with WordPress 7.1.<\/p>\n\n\n\n

Design Tokens in the wp-theme<\/code> stylesheet<\/h2>\n\n\n\n

A new wp-theme<\/code> stylesheet will be registered by default and is available as a dependency for plugins. When enqueued, the stylesheet includes a full set of semantic design tokens formatted as CSS custom properties (variables)<\/a> that can be referenced in WordPress or pluginPlugin<\/span> 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\/<\/a> or can be cost-based plugin from a third-party.<\/span><\/span><\/span> styles that are building user interfaces for the wp-admin dashboard. Design tokens can be used in place of hard-coded values to keep styles in sync across related UIUI<\/span> User interface<\/span><\/span><\/span> components, for aspects such as color, typography, spacing, and more. When paired with the ThemeProvider<\/a>, design tokens automatically inherit aspects of color and roundness for that area of a page.<\/p>\n\n\n\n

Typically, design tokens would be used in the implementation of common WordPress UI components, and a plugin would use those components instead of interfacing with the design tokens directly in their own styles. But the design tokens are generally available for both WordPress-internal styling as well as a plugin\u2019s unique use-cases so that styles can be applied consistently.<\/p>\n\n\n\n

The following example demonstrates a hypothetical component for a simple card layout. In the blockBlock<\/span> 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> editor or site editor, you should use the Card<\/code> React component<\/a> instead.<\/p>\n\n\n\n

.card {\n\tbackground-color: var(--wpds-color-background-surface-neutral-strong);\n\tcolor: var(--wpds-color-foreground-content-neutral);\n\tborder: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral-weak);\n\tborder-radius: var(--wpds-border-radius-lg);\n\tpadding: var(--wpds-dimension-padding-2xl);\n}<\/code><\/pre>\n\n\n\n
\n
\n
\"Screenshot<\/a>
An example card component inheriting ThemeProvider settings with a light gray background<\/figcaption><\/figure>\n<\/div>\n\n\n\n
\n
\"Screenshot<\/a>
An example card component inheriting ThemeProvider settings with a dark blue background and a more pronounced border radius<\/figcaption><\/figure>\n<\/div>\n<\/div>\n\n\n\n
To learn more about design tokens, refer to the \u201cDesign Tokens\u201d section<\/a> of the @wordpress\/theme<\/code> package documentation. <\/p>\n\n\n\n
For more information about the available token options, a design system token reference<\/a> describes the structure, purpose, and name of each token.<\/p>\n\n\n\n
Design tokens are used as the basis for all components in the @wordpress\/ui<\/code> React component library<\/a>, and is used in applying the user\u2019s preferred color scheme to the Site Editor in WordPress 7.1<\/a>. As a foundational piece, this will be expanded in subsequent WordPress releases to apply to more of the admin interface, which is detailed in the merge proposal<\/a>.<\/p>\n\n\n\n
ThemeProvider ReactReact<\/span> React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces.\rhttps:\/\/reactjs.org<\/a><\/span><\/span><\/span> component in the wp-theme<\/code> script handle<\/h2>\n\n\n\n
A new wp-theme<\/code> JavaScriptJavaScript<\/span> 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.\rhttps:\/\/www.javascript.com<\/a><\/span><\/span><\/span> script handle will be registered by default and is available as a dependency for plugins. The wp-theme<\/code> script provides a single ThemeProvider<\/code> React component that can be used to wrap content in an area of the page to override the default design token values that are provide from the wp-theme<\/code> stylesheet.<\/p>\n\n\n\n
import { ThemeProvider } from '@wordpress\/theme';\nimport { Card } from '@wordpress\/ui';\n\nfunction Application() {\n\treturn (\n\t\t<ThemeProvider\n\t\t\tcolor={ { primary: '#3858e9', background: '#11004d' } }\n\t\t\tcornerRadius=\"pronounced\"\n\t\t>\n\t\t\t<Card.Root>\n\t\t\t\t<Card.Content>\n\t\t\t\t\tWordPress is designed for everyone. We believe great\n\t\t\t\t\tsoftware should work with minimum set up,\n\t\t\t\t\temphasizing accessibility, performance, security,\n\t\t\t\t\tand ease of use.\n\t\t\t\t<\/Card.Content>\n\t\t\t<\/Card.Root>\n\t\t<\/ThemeProvider>\n\t);\n}<\/code><\/pre>\n\n\n\n
Given a pair of primary<\/code> and background<\/code> seed color values, the component internally generates a color ramp which is visually harmonious and provides contrast between elements, such as between foreground and background, or between background and border. While the color algorithm aims for accessible contrast targets, it is not possible to guarantee for every color combination, so due diligence is still required to verify its outputs for a given set of colors.<\/p>\n\n\n\n
ThemeProvider<\/code> currently includes five options for customizing the behavior of a themed section of a page:<\/p>\n\n\n\n
Prop<\/strong><\/th>Description<\/strong><\/th><\/tr><\/thead>
color.primary<\/code><\/td>The primary seed color to use for the theme. Accepts a fully opaque sRGB-parseable string: a hex value (e.g.\u00a0#3858e9<\/code>), an\u00a0rgb()<\/code>\/rgba()<\/code>\u00a0string, or a CSSCSS<\/span> Cascading Style Sheets.<\/span><\/span><\/span> named color (e.g.\u00a0'blue'<\/code>).<\/td><\/tr>
color.background<\/code><\/td>The background seed color to use for the theme. Accepts a fully opaque sRGB-parseable string: a hex value (e.g.\u00a0#f8f8f8<\/code>), an\u00a0rgb()<\/code>\/rgba()<\/code>\u00a0string, or a CSS named color (e.g.\u00a0'blue'<\/code>).<\/td><\/tr>
cursor.control<\/code><\/td>The cursor style for interactive controls that are not links (e.g. buttons, checkboxes, and toggles). By default, it inherits from the parent\u00a0ThemeProvider<\/code>, and falls back to the prebuilt default (pointer<\/code>).<\/td><\/tr>
cornerRadius<\/code><\/td>Overall roundness preset for the theme subtree:\u00a0none<\/code>\u00a0(square corners),\u00a0subtle<\/code>,\u00a0moderate<\/code>, or\u00a0pronounced<\/code>\u00a0(most rounded). By default, it inherits from the parent\u00a0ThemeProvider<\/code>, and falls back to the prebuilt default (subtle<\/code>).<\/td><\/tr>
isRoot<\/code><\/td>When a ThemeProvider is the root provider, it will apply its theming settings also to the root document element (e.g. the html<\/code> element). Render at most one root provider per document.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
ThemeProvider<\/code> can be used by plugin authors to express their unique brand identity while appearing consistent within the broader WordPress admin interface.<\/p>\n\n\n\n
To learn more about using the ThemeProvider<\/code> component, refer to the \u201cTheme Provider\u201d section<\/a> of the @wordpress\/theme<\/code> package documentation.<\/p>\n\n\n\n
Further Reading<\/h2>\n\n\n\n