/wordpress-block-theming

name: wordpress-block-theming
description: WordPress Full Site Editing (FSE) theme architecture. Use when generating theme.json, block templates, template parts, patterns, and functions.php for WordPress block themes.

WordPress Block Theming Skill

Comprehensive knowledge for building WordPress block themes using Full Site Editing (FSE) architecture.

Absolute Rules

• **NO EMOJIS**: Never use emojis anywhere in generated content - not in headings, paragraphs, button text, or any other text. This applies to all templates, patterns, and content.

Theme Architecture

Directory Structure

theme-slug/
├── theme.json           # Central configuration file
├── style.css            # Theme metadata + custom CSS
├── functions.php        # Asset enqueuing, pattern registration
├── templates/           # Block templates
│   ├── index.html       # Main/fallback template
│   ├── single.html      # Single post
│   ├── page.html        # Single page
│   ├── archive.html     # Archive listings
│   ├── search.html      # Search results
│   └── 404.html         # Not found
├── parts/               # Reusable template parts
│   ├── header.html      # Site header
│   └── footer.html      # Site footer
└── patterns/            # Block patterns
    ├── hero.php
    ├── features.php
    └── cta.php

theme.json Configuration

The `theme.json` file is the central configuration for block themes. It defines:

Schema and Version

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3
}

Settings

Define available options for the editor:

{
  "settings": {
    "appearanceTools": true,
    "layout": { "contentSize": "800px", "wideSize": "1280px" },
    "color": {
      "palette": [ /* 5 colors: primary, secondary, accent, light, dark */ ],
      "defaultPalette": false,
      "defaultGradients": false
    },
    "typography": {
      "fontFamilies": [ /* heading + body font families */ ],
      "fontSizes": [ /* 5-6 step scale: small through huge */ ]
    },
    "spacing": {
      "units": ["px", "em", "rem", "%", "vw", "vh"],
      "spacingSizes": [ /* 6 steps from compact to spacious */ ]
    }
  }
}

Styles

Define default styles for the site and blocks:

{
  "styles": {
    "color": { /* background + text from palette */ },
    "typography": { /* body font family, medium size, line-height 1.5-1.65 */ },
    "elements": {
      "heading": { /* heading font family, appropriate weight, line-height 1.1-1.3 */ },
      "link": { /* accent color */ },
      "button": { /* accent background, light text, border-radius */ }
    }
  }
}

Typography

• Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
• **Font size scale**: Keep sizes grounded and usable. Body: 1rem. Headings: scale modestly (h1 ≤ 2.5–3rem). Use `clamp()` for responsive display text, but cap at ~3.5rem max. Avoid "massive"/"gigantic" sizes above 4rem—they rarely improve design and often degrade it. A good 6-step scale: 0.875rem / 1rem / 1.25rem / 1.75rem / 2.25rem / clamp(2.5rem, 4vw, 3.5rem).
• **Line height**: Body text: 1.5–1.65. Headings: 1.1–1.3. Never go below 1.0 for any text. Apply via `styles.typography.lineHeight` and `styles.elements.heading.typography.lineHeight` in theme.json.

Block Templates

Templates use WordPress block markup (HTML comments with JSON attributes).

Template Structure

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- Content blocks here -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Template Parts

Header Requirements

• Constrained layout group with site-appropriate background
• Flex row: `site-title` (level:0 — renders `<p>` not `<h1>`) + `navigation`
• Appropriate padding using spacing presets

Footer Requirements

• Constrained layout group, matching or complementing header style
• Content varies by site type (copyright, social links, contact info, etc.)
• Include footer margin reset in style.css

Block Patterns

Patterns are PHP files that register reusable block content.

Pattern Registration

<?php
/**
 * Title: Hero Section
 * Slug: theme-slug/hero
 * Categories: featured
 */
?>
<!-- wp:group {"backgroundColor":"primary","textColor":"light","layout":{"type":"constrained"}} -->
...
<!-- /wp:group -->

functions.php

Keep functions.php minimal. Primary uses:

Google Fonts Enqueuing

**IMPORTANT:** Always use `enqueue_block_assets` hook (not `wp_enqueue_scripts`) to ensure fonts load in BOTH the front-end AND block editor.

<?php
/**
 * Theme functions and definitions
 */

// Enqueue Google Fonts and theme stylesheet for both front-end and block editor
function theme_slug_enqueue_assets() {
    wp_enqueue_style(
        'theme-slug-fonts',
        'https://fonts.googleapis.com/css2?family=Clash+Display:wght@400;500;600;700&family=DM+Sans:wght@400;500;600&display=swap',
        array(),
        null
    );

    wp_enqueue_style(
        'theme-slug-style',
        get_stylesheet_uri(),
        array( 'theme-slug-fonts' ),
        wp_get_theme()->get( 'Version' )
    );
}
add_action( 'enqueue_block_assets', 'theme_slug_enqueue_assets' );

// Register block patterns
function theme_slug_register_patterns() {
    register_block_pattern_category(
        'theme-slug',
        array( 'label' => __( 'Theme Patterns', 'theme-slug' ) )
    );
}
add_action( 'init', 'theme_slug_register_patterns' );

Security in Generated Code

• When `functions.php` outputs any user-derived value, use WordPress escaping functions:
• HTML context: `esc_html()`
• Attribute context: `esc_attr()`