Wp Block Themes

What Is This?

Overview

WP Block Themes is a development skill focused on building and maintaining WordPress block themes using the Full Site Editing (FSE) architecture introduced in WordPress 5.9 and refined through subsequent releases. This skill targets WordPress 6.9 and later, providing structured guidance for working with the core components of modern theme development: theme.json configuration, block templates, template parts, patterns, and style variations.

Block themes represent a fundamental shift from classic PHP-based themes. Instead of relying on functions.php hooks and template hierarchy files written in PHP, block themes use HTML files containing block markup, a centralized theme.json file for global design tokens, and the Site Editor as the primary interface for layout customization. Understanding how these components interact is essential for producing maintainable, performant themes.

This skill operates in a filesystem-based environment with bash and Node.js available, and some workflows require WP-CLI for cache management, block registration, and database-level operations. Developers working in this environment can automate repetitive tasks, validate configuration files, and troubleshoot style hierarchy issues directly from the command line.

Who Should Use This

• WordPress theme developers migrating from classic themes to the block theme architecture
• Frontend developers building custom block patterns and reusable template parts
• Agency developers maintaining multiple client sites that require consistent design systems
• Plugin authors who need to ensure compatibility with FSE-based themes
• DevOps engineers managing WordPress deployments where theme configuration is version-controlled
• Technical leads reviewing theme architecture decisions for scalability and long-term maintainability

Why Use It?

Problems It Solves

• Eliminates inconsistency between global styles defined in theme.json and inline block styles applied through the Site Editor by establishing a clear style hierarchy
• Reduces the complexity of managing typography, color palettes, and spacing scales across a theme by centralizing all design tokens in a single configuration file
• Addresses caching issues that cause stale styles to persist after theme updates, particularly when working with style variations
• Simplifies the creation of reusable layout components through registered block patterns, replacing fragile shortcode-based or widget-based approaches
• Provides a structured method for supporting multiple visual styles from a single theme codebase using style variations

Core Highlights

• Centralized design token management through theme.json for colors, typography, spacing, and layout
• HTML-based templates and template parts that are fully editable in the Site Editor
• Block pattern registration for reusable, pre-designed content sections
• Style variations that allow multiple visual themes within a single theme directory
• WP-CLI integration for cache flushing, block registration verification, and database operations
• Compatibility with WordPress 6.9 and PHP 7.2.24 or higher
• Full support for global styles overrides and per-block style configuration
• Filesystem-based workflow suitable for version control and CI/CD pipelines

How to Use It?

Basic Usage

Define global color palettes and typography in theme.json at the theme root:

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#1a1a2e", "name": "Primary" },
        { "slug": "accent", "color": "#e94560", "name": "Accent" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ]
    }
  }
}

Flush the style cache after changes using WP-CLI:

wp cache flush
wp theme activate your-theme-slug

Specific Scenarios

Registering a block pattern: Place a PHP registration call in functions.php and store the pattern HTML in patterns/hero-section.php. Use the Inserter header comment to control visibility in the block inserter.

Creating a style variation: Add a JSON file to the styles/ directory within your theme folder. WordPress automatically detects files in this directory and presents them as selectable variations in the Site Editor under Styles.

Real-World Examples

A portfolio theme can define a dark variation by placing styles/dark.json with overridden color values, allowing clients to switch palettes without editing the base theme. An e-commerce theme can register product card patterns that editors insert consistently across landing pages, reducing layout drift between team members.

When to Use It?

Use Cases

• Building a new block theme from scratch for a client project
• Migrating an existing classic theme to the FSE architecture
• Defining a design system with consistent tokens across a multisite network
• Creating a theme with multiple purchasable style variations
• Troubleshooting unexpected style overrides introduced by the Site Editor
• Registering curated block patterns for a content team with limited technical knowledge
• Auditing theme performance by reviewing registered block assets and enqueue behavior

Important Notes

Requirements

• WordPress 6.9 or later installed and active
• PHP 7.2.24 or higher on the server
• WP-CLI installed for cache management and automation workflows
• Bash and Node.js available in the development environment for filesystem-based operations