wordpress-block-theming

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

<main class="wp-block-group">  </main>

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 */ ?>  ...

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()
URL context: esc_url()
Never use eval() , create_function() , shell_exec() , exec() , or system() in generated theme code
Static block themes with hardcoded content (the default) do not need escaping — WordPress core blocks handle this. Escaping matters only if generating PHP that renders dynamic data.

style.css

The style.css file contains theme metadata and custom CSS. ** Important ** Always bring across custom CSS from the design into style.css that is not achievable via theme.json, especially for layout and composition techniques that are critical to the design's aesthetics such as animation/motion.

/* Theme Name: Theme Name Theme URI: https://example.com Author: Author Name Author URI: https://example.com Description: A beautiful WordPress block theme Version: 1.0.0 Requires at least: 6.0 Tested up to: 6.7 Requires PHP: 7.4 License: GNU General Public License v2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html Text Domain: theme-slug */

Animation & Motion in Block Themes

Animation brings life to block themes, but WordPress block markup requires a specific pattern to connect CSS animations to blocks.

The className Pattern

Add animation classes to blocks via the className JSON attribute. WordPress renders this as a class on the wrapper div:

<div class="wp-block-group alignfull fade-up">  </div>

This works on any block — groups, columns, headings, paragraphs, buttons, images:

<h2 class="wp-block-heading slide-in-left">Features</h2>

<div class="wp-block-columns alignwide stagger-children"> ... </div>

Animation Classes in style.css

Generate and adapt these classes (these are examples only, do not limit yourself to these) in each theme's style.css :

Entrance animations:

.fade-up { opacity: 0; transform: translateY(30px); animation: fadeUp 0.6s ease forwards; } .fade-in { opacity: 0; animation: fadeIn 0.6s ease forwards; } .slide-in-left { opacity: 0; transform: translateX(-40px); animation: slideIn 0.7s ease forwards; } .slide-in-right { opacity: 0; transform: translateX(40px); animation: slideIn 0.7s ease forwards; }

@keyframes fadeUp { to { opacity: 1; transform: translateY(0); } } @keyframes fadeIn { to { opacity: 1; } } @keyframes slideIn { to { opacity: 1; transform: translateX(0); } }

Staggered children — delays applied via nth-child:

.stagger-children > * { opacity: 0; transform: translateY(20px); animation: fadeUp 0.5s ease forwards; } .stagger-children > *:nth-child(1) { animation-delay: 0.1s; } .stagger-children > *:nth-child(2) { animation-delay: 0.2s; } .stagger-children > *:nth-child(3) { animation-delay: 0.3s; } .stagger-children > *:nth-child(4) { animation-delay: 0.4s; }

Interactive transitions:

.hover-lift { transition: transform 0.2s ease, box-shadow 0.2s ease; } .hover-lift:hover { transform: translateY(-4px); box-shadow: 0 12px 24px rgba(0,0,0,0.15); } .hover-glow { transition: box-shadow 0.3s ease; } .hover-glow:hover { box-shadow: 0 0 20px rgba(var(--wp--preset--color--accent-rgb, 0,0,0), 0.3); }

Continuous ambient motion:

.float { animation: float 3s ease-in-out infinite; } @keyframes float { 0%, 100% { transform: translateY(0); } 50% { transform: translateY(-10px); } } .pulse-subtle { animation: pulse 2s ease-in-out infinite; } @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.7; } }

Scroll-Triggered Reveals via functions.php

The most impactful animation pattern — sections revealing as the user scrolls — requires a small IntersectionObserver script. Add this to functions.php :

// Enqueue scroll animation observer function theme_slug_scroll_animations() { wp_add_inline_script( 'theme-slug-style', " document.addEventListener('DOMContentLoaded', function() { var els = document.querySelectorAll('.animate-on-scroll'); if (!els.length) return; var observer = new IntersectionObserver(function(entries) { entries.forEach(function(entry) { if (entry.isIntersecting) { entry.target.classList.add('is-visible'); observer.unobserve(entry.target); } }); }, { threshold: 0.15 }); els.forEach(function(el) { observer.observe(el); }); }); " ); } add_action( 'enqueue_block_assets', 'theme_slug_scroll_animations' );

Note: wp_add_inline_script requires an existing registered script handle. Since block themes may not always have a script registered, a more reliable approach is to output the script directly:

// Scroll animation observer — outputs inline script function theme_slug_scroll_animations() { ?> <script> document.addEventListener('DOMContentLoaded', function() { var els = document.querySelectorAll('.animate-on-scroll'); if (!els.length) return; var observer = new IntersectionObserver(function(entries) { entries.forEach(function(entry) { if (entry.isIntersecting) { entry.target.classList.add('is-visible'); observer.unobserve(entry.target); } }); }, { threshold: 0.15 }); els.forEach(function(el) { observer.observe(el); }); }); </script> <?php } add_action( 'wp_footer', 'theme_slug_scroll_animations' );

Then in style.css , pair with CSS that starts elements hidden and animates them when .is-visible is added:

.animate-on-scroll { opacity: 0; transform: translateY(30px); transition: opacity 0.6s ease, transform 0.6s ease; } .animate-on-scroll.is-visible { opacity: 1; transform: translateY(0); }

Use className: "animate-on-scroll" on section-level Group blocks:

<div class="wp-block-group alignfull animate-on-scroll">  </div>

prefers-reduced-motion (Required)

Every theme MUST include this in style.css :

@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }

How Much Animation

Not every element needs animation. Prioritize:

Hero section entrance — the first impression (fade-up, scale, or slide)
Section reveals on scroll — major content blocks with animate-on-scroll
Interactive elements — cards with hover-lift , buttons with transitions
1-2 decorative ambient animations — a floating shape, gradient shift, or pulsing accent

Avoid animating every heading, paragraph, and button individually — it creates visual noise rather than delight.

Card layouts in rows

For equal-height, equal-width cards ( with optional bottom-aligned CTAs ), use this structure unless the user specifies otherwise:

Columns (className: "equal-cards") └── Column verticalAlignment: "stretch" width: "X%" where X = 100 / number_of_cards (e.g., 2 cards = 50%, 3 cards = 33.33%, 4 cards = 25%) └── Group [card wrapper] └── [content: headings, paragraphs, images*, lists] └── (optional) Buttons (className: "cta-bottom")

Width rule: All cards in a row MUST have equal width. Calculate each column's width as 100% / number_of_cards (e.g., 3 cards = 33.33% each). The sum of all column widths must equal exactly 100% - never exceed the parent element width.

*Images in cards: style="height:200px;object-fit:cover;width:100%"

Required CSS (style.css):

.equal-cards > .wp-block-column { display: flex; flex-direction: column; flex-grow: 0; } .equal-cards > .wp-block-column > .wp-block-group { display: flex; flex-direction: column; flex-grow: 1; }

If present, ensure bottom-aligned CTAs unless otherwise specified:

.equal-cards .cta-bottom { margin-top: auto; justify-content: center; }

Always add the following CSS to reset the footer top margin:

.wp-site-blocks > footer { margin-block-start: 0; }

Landing Page Composition

When generating homepage block markup, think like a landing page designer, not a template assembler. Every section should be a visually distinct, full-width band that creates rhythm and visual impact as the user scrolls.

Section Architecture

Section margin reset: Add "style":{"spacing":{"margin":{"top":"0"}}} to every top-level Group block that wraps a landing page section. This overrides WordPress's default top margin on direct children of .wp-site-blocks and can be easily adjusted by users in the editor.
Section layout widths: Hero sections, header groups, cover blocks, and feature grids should use "align":"wide" or "align":"full" rather than defaulting to narrow content width. Only use default (content) alignment for text-heavy reading sections.
Do not use <inner-blocks> ; output the full expanded markup inside each block.
Columns alignment: ALWAYS set "align":"wide" on wp:columns blocks (and add the alignwide class on the wrapper div) unless specifically instructed otherwise.
No decorative HTML comments: Never insert section-labeling comments like  or  in templates, template parts, or patterns. Only WordPress block comments ( ) are allowed.

Every major homepage section must be alignfull — edge-to-edge across the viewport. Content inside can be constrained, but the section wrapper fills the screen width. This is the full-bleed wrapper, constrained content pattern:

Never use bare {"layout":{"type":"constrained"}} without "align":"full" for homepage sections. Without alignfull , sections render at contentSize (800px) and the page looks narrow and lifeless.

YOU DECIDE which sections best serve this specific site. Do not follow a rigid template. Consider the site type, audience, and primary goal:

A portfolio needs a full-bleed project gallery
A SaaS needs feature grids with clear value props
A restaurant needs appetizing imagery and menu sections
An agency needs case study cards and social proof
An escape room needs atmosphere and immersion

Visual Rhythm

Alternate between visual treatments to create rhythm as the user scrolls:

Technique WordPress Implementation

Alternating backgrounds Alternate backgroundColor between background and surface (or primary /secondary for bold sections)

Full-bleed imagery Cover blocks with "align":"full" and overlayColor from the brand palette

Edge-to-edge media-text wp:media-text with "align":"full" for alternating image/content sides

Bold CTA bands Full-width group with primary or accent background, centered text

Spacer breaks wp:spacer between sections for breathing room

Every section should feel visually distinct from its neighbors. If two adjacent sections have the same background color and layout pattern, the page feels monotonous — change the background, flip the image side, switch from grid to single-column, or add a cover block break.

Image Handling

ONLY add user provided images/image URLs to the initial site build. Stock image urls often fail to load in the block editor and break the design. Look at any user supplies images carefully and include them in the design if appropriate, but do not force them in if they do not fit the design.

Creating Visual Richness Without Images

Since only user provided images/image URLs can be used, if none are available convey atmosphere and visual interest through:

CSS Gradients: Linear, radial, and conic gradients for depth and color
Color Blocks: Bold use of background colors to create visual hierarchy
Typography as Design: Large, distinctive headings; creative font pairing; varied text sizes and weights
CSS Patterns: Repeating backgrounds using CSS gradients (stripes, dots, grids)
Shadows & Depth: Box-shadow, text-shadow, and drop-shadow for dimension
Borders & Frames: Creative use of borders, outlines, and decorative frames
Spacing & Layout: Generous whitespace or controlled density to create mood
CSS Pseudo-elements: ::before and ::after for decorative visual elements
Color Overlays: Layered divs with transparency for atmospheric effects

wordpress-block-theming

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

design-systems

site-specification

wordpress-router