Design tokens and ThemeProvider ship for wp-admin theming

WordPress 7.1 will include foundational support for theming design aspects of 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 plugin 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 UI 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 block 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);
}

An example card component inheriting ThemeProvider settings with a light gray background

An example card component inheriting ThemeProvider settings with a dark blue background and a more pronounced border radius

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 React component in the wp-theme script handle

A new wp-theme JavaScript 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 CSS 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/Core post)
• Design System: Support for admin redesign (GitHub 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