ThemeProvider from the WordPress Theme package

The team is working on theme package as part of the new UI package. It’s in activem early development and won’t come to WordPress Core anytime soon. However, developers building on top of WordPress can already use it.

This has nothing to do with WordPress Themes. The Theme package is for the inner workings of WordPress, in side the WP-Admin, after logging into the site. It’s also for plugin developers providing add-ons for WordPress users.

The documentation is available on WordPress Developer site

A summary of the current status of the package:

The @wordpress/theme package provides the design-token foundation for the WordPress design system and is a prerequisite for the forthcoming @wordpress/ui components package. It ships a ThemeProvider component that outputs CSS custom properties derived algorithmically from a seed color — a single base color from which an entire palette is generated.

The color generation algorithm adjusts the seed as needed to meet contrast requirements, so output hex values may shift as the algorithm is refined. Developers should rely on semantic token names rather than specific color values.

A developer would initiate the Theme provider like this:

You wrap your app in ThemeProvider and pass seed colors via the color prop:

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

function App() {
    return (
        <ThemeProvider color={ { primary: '#3858e9', bg: '#f8f8f8' } }>
            { /* Your app content */ }
        </ThemeProvider>
    );
}

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

function App() {
    return (
        <ThemeProvider color={ { primary: '#3858e9', bg: '#f8f8f8' } }>
            { /* Your app content */ }
        </ThemeProvider>
    );
}

From those two seeds — primary for the accent color and bg for the background — the package automatically generates full color ramps for surfaces, text, borders, and three graduated semantic severity levels: caution, warning, and error, each perceptually distinct, following patterns seen in design systems like IBM Carbon. The system also determines light or dark mode from the background seed. A density prop ('default', 'compact', or 'comfortable') controls spacing tokens for different interface contexts. All values are optional and fall back to sensible defaults.

The generated tokens are exposed as CSS custom properties following a consistent naming pattern such as

• --wpds-color-bg-surface-neutral or
• --wpds-color-fg-interactive-brand-strong.

Developers should rely on these semantic token names rather than specific hex values, since the color generation algorithm is actively being refined and output values may shift between releases.

The Design Tokens Reference document (docs/ds-tokens.md within the package) lists all available tokens. Looking at the list, I realized how much of a saving it will be to use this package for any apps inside of WordPress. It lists 133 tokens in five categories, Border, Color, Dimension, Elevation and Typography.

Decision making is delegated to the system that makes app development consistent and inline with the rest of the WordPress admin, even if WordPress core isn’t adopting things yet.

primary and bg are the only two properties within the color prop. The other prop on ThemeProvider itself is density, which we already mention in the description. So the full API surface is:

• color — object with primary (accent color, default '#3858e9') and bg (background color, default '#f8f8f8')
• density — string: 'default', 'compact', or 'comfortable'

As this is a package in the early stages on development, I would think that the props surface will grow, and things get fleshed out. I could for instance see that typography needs initiale values as well as border presets. An maybe a couple more colors. Anyway.

I’ll try to find the time to experiment with this some more, when building plugins for WordPress in the future.