Design System Theming in WordPress 7.1

WordPress 7.1 will include foundational support for theming design aspects of adminadmin (and super admin) 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. This post aims to provide information about what is included with WordPress 7.1.

Design Tokens in the wp-theme stylesheet

A new wp-theme 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) that can be referenced in WordPress or pluginPlugin 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. 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 User interface components, for aspects such as color, typography, spacing, and more. When paired with the ThemeProvider, design tokens automatically inherit aspects of color and roundness for that area of a page.

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’s unique use-cases so that styles can be applied consistently.

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

.card {
	background-color: var(--wpds-color-background-surface-neutral-strong);
	color: var(--wpds-color-foreground-content-neutral);
	border: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral-weak);
	border-radius: var(--wpds-border-radius-lg);
	padding: var(--wpds-dimension-padding-2xl);
}

To learn more about design tokens, refer to the “Design Tokens” section of the @wordpress/theme package documentation.

For more information about the available token options, a design system token reference describes the structure, purpose, and name of each token.

Design tokens are used as the basis for all components in the @wordpress/ui React component library, and is used in applying the user’s preferred color scheme to the Site Editor in WordPress 7.1. 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.

ThemeProvider ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org component in the wp-theme script handle

A new wp-theme JavaScriptJavaScript 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 script handle will be registered by default and is available as a dependency for plugins. The wp-theme script provides a single ThemeProvider 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 stylesheet.

import { ThemeProvider } from '@wordpress/theme';
import { Card } from '@wordpress/ui';

function Application() {
	return (
		<ThemeProvider
			color={ { primary: '#3858e9', background: '#11004d' } }
			cornerRadius="pronounced"
		>
			<Card.Root>
				<Card.Content>
					WordPress is designed for everyone. We believe great
					software should work with minimum set up,
					emphasizing accessibility, performance, security,
					and ease of use.
				</Card.Content>
			</Card.Root>
		</ThemeProvider>
	);
}

Given a pair of primary and background 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.

ThemeProvider currently includes five options for customizing the behavior of a themed section of a page:

Prop	Description
color.primary	The primary seed color to use for the theme. Accepts a fully opaque sRGB-parseable string: a hex value (e.g. #3858e9), an rgb()/rgba() string, or a CSSCSS Cascading Style Sheets. named color (e.g. 'blue').
color.background	The background seed color to use for the theme. Accepts a fully opaque sRGB-parseable string: a hex value (e.g. #f8f8f8), an rgb()/rgba() string, or a CSS named color (e.g. 'blue').
cursor.control	The cursor style for interactive controls that are not links (e.g. buttons, checkboxes, and toggles). By default, it inherits from the parent ThemeProvider, and falls back to the prebuilt default (pointer).
cornerRadius	Overall roundness preset for the theme subtree: none (square corners), subtle, moderate, or pronounced (most rounded). By default, it inherits from the parent ThemeProvider, and falls back to the prebuilt default (subtle).
isRoot	When a ThemeProvider is the root provider, it will apply its theming settings also to the root document element (e.g. the html element). Render at most one root provider per document.

ThemeProvider can be used by plugin authors to express their unique brand identity while appearing consistent within the broader WordPress admin interface.

To learn more about using the ThemeProvider component, refer to the “Theme Provider” section of the @wordpress/theme package documentation.

Further Reading

• Merge Proposal: Design System Theming (Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. post)
• Design System: Support for admin redesign (GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ issue)
• A themeable and scalable primitive system (GitHub issue)

Props to @wildworks and @tyxla for reviewing this post’s content.

#dev-notes, #dev-notes-7-1