Skip to main content

Unblock Theme

This page shows you how to install the Unblock Theme, the optional blank companion theme, and how to decide where your design tokens live.

What is the Unblock Theme​

The Unblock Theme is a blank block theme. It ships almost no CSS: no typography scale, no color palette, no layout opinions. You get a minimal theme.json and a clean HTML shell.

It's a starting point, not a requirement. Unblock renders real HTML and reads styles from the same places every WordPress block does, so it works with any block theme.

Do you need it?​

No. If you already have a block theme you like and your styles render as expected, keep it.

The blank theme isn't about avoiding conflicts. A well-built theme won't fight you. It's about keeping the number of places your styles come from small. Start from blank and everything you set in the editor is the whole story, with nothing in the theme to trace back to or work around.

If you'd rather lean on a theme's tokens, that works too. The next section covers both.

Where your design tokens live​

Your design tokens (colors, spacing, fonts) can live in two places, and both work with Unblock.

With WordPress. Your tokens can come from the theme's theme.json, from the Global Styles you edit under Appearance → Editor → Styles, or from both. Global Styles is the visual way to edit and extend what theme.json defines, and both output the same CSS variables like --wp--preset--color--primary. Unblock blocks can reference them by name, just like core blocks do. But these tokens belong to the active theme: change theme and they change with it.

With Unblock. Define your tokens in the Variables panel instead. They live with the plugin, not the theme, so they stay put when you switch themes. Your design system travels with Unblock.

That portability is the real benefit. Two common setups:

  • Variables in theme.json or Global Styles, selectors in Unblock. Each theme brings its own values, so switching theme restyles the site at once.
  • Blank theme plus a CSS framework, with variables you tweak freely (the CSS Parser imports a whole file in one paste).

New to this? Don't overthink it. Keep your tokens in the Variables panel, all in one place, and revisit theme.json later only if you need it.

Common mistake

Tokens flow one way. Unblock reads WordPress tokens, but core blocks can't read Unblock's: variables from the Variables panel won't show in a core block's color or font picker. If both kinds of block need the same tokens in those pickers, define them in theme.json or Global Styles.

Install the theme​

  1. Download the theme from your Unblock account
  2. Go to Appearance → Themes → Add New Theme
  3. Click Upload Theme
  4. Select the unblock-theme.zip file
  5. Click Install Now
  6. Click Activate

Automatic updates​

The Unblock Theme receives automatic updates through WordPress, the same way the plugin does. No extra license or configuration required: if the Unblock plugin is active and your license is valid, theme updates show up in Dashboard → Updates alongside everything else.

Next steps​