WordPress Block Themes Guide¶

CMS Planner provides specialized support for WordPress block theme projects with Full Site Editing (FSE). This guide covers architecture patterns, block vs pattern decisions, performance optimization, and story point estimation for WordPress 6.8+ projects.

What are WordPress Block Themes?¶

Block themes are the modern WordPress theme architecture introduced in WordPress 5.9 (2022) and matured in WordPress 6.8+ (2026). They use the block editor (Gutenberg) for all site content, including templates, template parts, and page layouts.

Key Characteristics:¶

Full Site Editing (FSE): Edit headers, footers, and templates in the block editor
theme.json: Centralized configuration for colors, typography, spacing, and layout
Block-based templates: HTML templates composed of blocks, not PHP code
Pattern-driven: Reusable block combinations for consistent layouts
No traditional PHP templates: index.html instead of index.php

Why Block Themes Matter (2026):¶

WordPress Default: Classic themes deprecated, block themes are the standard
Editor Experience: Non-technical editors can customize layouts without code
Performance: Lighter and faster than classic themes with page builders
Maintainability: Less custom code, more reliance on WordPress core
Future-Proof: All new WordPress features built for block themes

Block Theme Architecture¶

Directory Structure¶

my-theme/
├── style.css                  # Theme metadata (required)
├── functions.php              # Theme setup and enqueuing (optional)
├── theme.json                 # Global settings and styles (required)
├── templates/
│   ├── index.html             # Main template (required)
│   ├── single.html            # Single post template
│   ├── page.html              # Page template
│   ├── archive.html           # Archive template
│   ├── 404.html               # 404 error template
│   └── home.html              # Blog homepage template
├── parts/
│   ├── header.html            # Site header
│   ├── footer.html            # Site footer
│   └── sidebar.html           # Sidebar (if needed)
├── patterns/
│   ├── hero-section.php       # Hero block pattern
│   ├── feature-grid.php       # Feature grid pattern
│   └── testimonial.php        # Testimonial pattern
├── styles/
│   ├── blue.json              # Style variation (blue theme)
│   └── dark.json              # Style variation (dark mode)
├── assets/
│   ├── css/
│   │   └── custom.css         # Additional custom styles
│   ├── js/
│   │   └── main.js            # Custom JavaScript
│   └── images/
│       └── logo.svg           # Theme assets
└── README.md                  # Theme documentation

Required Files¶

Minimum viable block theme: - style.css - Theme metadata and basic styles - theme.json - Settings and styles configuration - templates/index.html - Main template (fallback for all pages)

Production-ready block theme adds: - parts/header.html, parts/footer.html - Reusable template parts - templates/single.html, templates/page.html - Specific templates - patterns/*.php - Reusable block patterns - functions.php - Custom functionality and asset enqueuing

theme.json: The Heart of Block Themes¶

theme.json is a configuration file that controls colors, typography, spacing, and layout for the entire theme.

theme.json v3 Structure (WordPress 6.8+)¶

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#0066cc", "name": "Primary" },
        { "slug": "secondary", "color": "#ff6600", "name": "Secondary" },
        { "slug": "dark", "color": "#1a1a1a", "name": "Dark" },
        { "slug": "light", "color": "#f5f5f5", "name": "Light" },
        { "slug": "white", "color": "#ffffff", "name": "White" }
      ]
    },
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
          "slug": "sans",
          "name": "Sans Serif"
        }
      ],
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "normal", "size": "1rem", "name": "Normal" },
        { "slug": "large", "size": "1.5rem", "name": "Large" },
        { "slug": "xlarge", "size": "2.5rem", "name": "Extra Large" }
      ]
    },
    "spacing": {
      "spacingSizes": [
        { "slug": "30", "size": "0.5rem", "name": "Small" },
        { "slug": "40", "size": "1rem", "name": "Medium" },
        { "slug": "50", "size": "2rem", "name": "Large" }
      ]
    },
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  },
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#1a1a1a"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--sans)",
      "fontSize": "var(--wp--preset--font-size--normal)"
    }
  }
}

theme.json Benefits¶

Centralized Configuration: All design tokens in one file
CSS Custom Properties: Automatically generates CSS variables
Editor Integration: Settings available in block editor UI
No CSS Required: Basic themes need minimal or no custom CSS
Style Variations: Create multiple color schemes from one theme.json

Story Point Estimate: theme.json¶

Basic theme.json (colors, typography, spacing): 3 points (6-8 hours)
Complete theme.json (+ layout, custom settings, element styles): 5 points (12-16 hours)
Advanced theme.json (+ style variations, complex presets, block styles): 8 points (24-32 hours)

Core Blocks vs Patterns vs Custom Blocks¶

The most critical decision in WordPress block theme development is when to use core blocks, patterns, ACF blocks, or custom Gutenberg blocks. This decision can make a 3-10x difference in development time and cost.

The Decision Framework¶

UI Component Requirement
    ↓
Can this be built with core blocks? (90+ blocks available)
    YES → Use core blocks (fastest, free, maintained by WordPress core)
    NO ↓
Can core blocks be composed into a pattern?
    YES → Create pattern (2-8 hours, reusable, easy for editors)
    NO ↓
Do you have ACF PRO? Are fields simple/repeating?
    YES → Use ACF block (4-20 hours, PHP template, faster than React)
    NO ↓
Is complex interactivity or state management required?
    YES → Build custom Gutenberg block (12-120 hours, React + build tooling)
    NO → Reconsider: probably should be a pattern

Core Blocks (WordPress 6.8+)¶

WordPress 6.8 ships with 90+ core blocks:

Layout Blocks: - Group, Row, Stack, Columns, Spacer, Separator

Content Blocks: - Paragraph, Heading, List, Quote, Code, Preformatted, Verse, Table

Media Blocks: - Image, Gallery, Video, Audio, File, Media & Text, Cover

Interactive Blocks: - Button, Buttons, Search, Social Icons

Design Blocks: - Site Logo, Site Title, Site Tagline, Navigation, Query Loop, Post Template, Post Title, Post Excerpt, Post Featured Image, Post Date, Post Author, Post Categories, Post Tags

Embed Blocks: - YouTube, Twitter, Instagram, Vimeo, Spotify, etc.

When to Use Core Blocks: - Standard content layouts (text, images, headings, buttons) - Blog post layouts - Simple landing pages - Media galleries - Social media embeds - Navigation menus

Story Point Estimate: Core Block Layouts - Simple layout (3-5 blocks): 1 point (2 hours) - Moderate layout (6-10 blocks): 2 points (4 hours) - Complex layout (10+ blocks, nested): 3 points (6-8 hours)

Block Patterns¶

Block patterns are reusable combinations of core blocks saved as templates. They're the secret weapon of efficient block theme development.

Pattern Example: Hero Section

<?php
/**
 * Title: Hero Section
 * Slug: mytheme/hero-section
 * Categories: featured
 */
?>
<!-- wp:cover {"url":"<?php echo esc_url( get_template_directory_uri() ); ?>/assets/images/hero.jpg","dimRatio":50} -->
<div class="wp-block-cover">
  <span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span>
  <img class="wp-block-cover__image-background" alt="" src="<?php echo esc_url( get_template_directory_uri() ); ?>/assets/images/hero.jpg" />
  <div class="wp-block-cover__inner-container">
    <!-- wp:group {"layout":{"type":"constrained"}} -->
    <div class="wp-block-group">
      <!-- wp:heading {"level":1} -->
      <h1>Welcome to Our Site</h1>
      <!-- /wp:heading -->

      <!-- wp:paragraph -->
      <p>Your journey starts here with amazing content and services.</p>
      <!-- /wp:paragraph -->

      <!-- wp:buttons -->
      <div class="wp-block-buttons">
        <!-- wp:button -->
        <div class="wp-block-button"><a class="wp-block-button__link">Get Started</a></div>
        <!-- /wp:button -->
      </div>
      <!-- /wp:buttons -->
    </div>
    <!-- /wp:group -->
  </div>
</div>
<!-- /wp:cover -->

When to Use Patterns: - Repeating layout sections (hero, features, testimonials, CTAs) - Page templates (about page, services page, contact page) - Multi-section layouts requiring consistent structure - Content that editors should reuse but customize

Pattern Benefits: - Fast Development: 2-8 hours vs 12-80 hours for custom blocks - Easy for Editors: Insert pattern, edit content, done - Maintained by Core: Core blocks updated by WordPress, not you - No Build Tools: No React, no webpack, no npm

Story Point Estimate: Block Patterns - Simple pattern (3-5 core blocks, single section): 1-2 points (2-4 hours) - Moderate pattern (6-10 core blocks, multi-section): 2-3 points (4-8 hours) - Complex pattern (10+ blocks, nested groups, advanced styling): 3-5 points (8-20 hours / 1-2 days)

ACF Blocks¶

Advanced Custom Fields (ACF) PRO adds the ability to create blocks using PHP templates and custom fields, without writing React code.

When to Use ACF Blocks: - Repeating structured content: Team members, locations, services, products - Complex field types: Relationship fields, post objects, conditional logic - Rapid development: PHP template faster than React for field-heavy blocks - ACF PRO available: Requires ACF PRO license ($49-249/year)

ACF Block Example: Team Member

<?php
/**
 * Team Member Block Template
 *
 * @param   array $block The block settings and attributes.
 * @param   string $content The block inner HTML (empty).
 * @param   bool $is_preview True during AJAX preview.
 * @param   (int|string) $post_id The post ID this block is saved to.
 */

$name = get_field('name');
$title = get_field('title');
$bio = get_field('bio');
$photo = get_field('photo');
$linkedin = get_field('linkedin_url');
?>

<div class="team-member">
  <?php if( $photo ): ?>
    <img src="<?php echo esc_url($photo['url']); ?>" alt="<?php echo esc_attr($name); ?>" />
  <?php endif; ?>

  <h3><?php echo esc_html($name); ?></h3>

  <?php if( $title ): ?>
    <p class="team-member__title"><?php echo esc_html($title); ?></p>
  <?php endif; ?>

  <?php if( $bio ): ?>
    <p class="team-member__bio"><?php echo esc_html($bio); ?></p>
  <?php endif; ?>

  <?php if( $linkedin ): ?>
    <a href="<?php echo esc_url($linkedin); ?>" target="_blank" rel="noopener">LinkedIn</a>
  <?php endif; ?>
</div>

ACF Block Benefits: - Faster than Custom Blocks: 2-3x faster development (PHP vs React) - Field Management: Visual field builder in ACF UI - Conditional Logic: Show/hide fields based on selections - No Build Tools: No React, webpack, or npm required

ACF Block Limitations: - Requires ACF PRO: $49-249/year cost - Less Interactive: Not suitable for complex JavaScript interactions - Backend Dependency: Requires ACF plugin (vendor lock-in)

Story Point Estimate: ACF Blocks - Simple ACF block (basic fields, PHP template): 2-3 points (4-8 hours) - Complex ACF block (repeaters, conditional logic, relationships): 3-5 points (12-20 hours / 1-2 days)

Custom Gutenberg Blocks¶

Custom Gutenberg blocks are React-based blocks built with the WordPress block editor API. Reserve these for truly interactive or complex UI components.

When to Use Custom Blocks: - Interactive UI: State management, dynamic updates, complex user interactions - REST API Integration: Fetching dynamic data from WordPress or external APIs - Complex InnerBlocks: Nested block patterns with strict validation - Third-Party Integration: Payment gateways, maps, booking systems - No Alternative: Core blocks, patterns, and ACF truly insufficient

Custom Block Example: Interactive Pricing Calculator

import { registerBlockType } from '@wordpress/blocks';
import { useState } from '@wordpress/element';
import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody, RangeControl } from '@wordpress/components';

registerBlockType('mytheme/pricing-calculator', {
  title: 'Pricing Calculator',
  icon: 'calculator',
  category: 'widgets',

  edit: (props) => {
    const [users, setUsers] = useState(10);
    const [storage, setStorage] = useState(100);

    const basePrice = 29;
    const userPrice = 5;
    const storagePrice = 0.10;

    const totalPrice = basePrice + (users * userPrice) + (storage * storagePrice);

    return (
      <>
        <InspectorControls>
          <PanelBody title="Settings">
            <RangeControl
              label="Number of Users"
              value={users}
              onChange={setUsers}
              min={1}
              max={100}
            />
            <RangeControl
              label="Storage (GB)"
              value={storage}
              onChange={setStorage}
              min={10}
              max={1000}
            />
          </PanelBody>
        </InspectorControls>

        <div className="pricing-calculator">
          <h3>Pricing Calculator</h3>
          <p>Users: {users}</p>
          <p>Storage: {storage} GB</p>
          <h4>Total: ${totalPrice.toFixed(2)}/month</h4>
        </div>
      </>
    );
  },

  save: (props) => {
    return null; // Dynamic block, rendered via PHP
  }
});

Custom Block Challenges: - High Development Cost: 12-120 hours (3-21 points) - Build Tooling Required: React, webpack, npm, @wordpress/scripts - Testing Complexity: Editor UI, frontend rendering, block validation - Maintenance Burden: Updates required for WordPress core changes

Story Point Estimate: Custom Gutenberg Blocks - Simple static block (no backend, basic UI): 3-5 points (12-20 hours / 1-2 days) - Block with InnerBlocks (nested content, container pattern): 8-13 points (32-80 hours / 3-5 days to 1-2 weeks) - Dynamic block with REST API (backend logic, data fetching): 13-21 points (80-120 hours / 1-3 weeks)

Decision Matrix: Real-World Examples¶

UI Component	Core Blocks	Pattern	ACF	Custom	Best Approach	Points	Time
Hero Section	Cover, Group, Heading, Button	✓	-	-	Pattern	2	4h
Feature Grid	Columns, Image, Heading, Paragraph	✓	-	-	Pattern	2	4h
Testimonial Slider	Quote, Image	-	-	✓	Custom (needs JS state)	13	1-2 weeks
Team Directory	-	-	✓	-	ACF (repeating fields)	5	2 days
Product Showcase	Query Loop, Post Template	✓	-	-	Pattern (WooCommerce CPT)	3	1 day
Pricing Calculator	-	-	-	✓	Custom (interactivity)	13	1-2 weeks
FAQ Accordion	List, Details/Summary	✓	-	-	Pattern (HTML5 details)	2	4h
Contact Form	-	-	-	Plugin	Gravity Forms / CF7	2	4h setup

Key Insight: In most projects, 80-90% of UI components should be patterns or core blocks. Only 10-20% require ACF or custom blocks.

Performance Optimization for Block Themes¶

Performance is critical for WordPress sites. As of 2026, 56% of WordPress sites fail Core Web Vitals, directly impacting Google search rankings.

Core Web Vitals: Mandatory Targets¶

Largest Contentful Paint (LCP): - Target: < 2.5 seconds - Measures: Loading performance - Common issues: Unoptimized images, render-blocking CSS/JS

Interaction to Next Paint (INP): - Target: < 200ms - Measures: Responsiveness - Common issues: Heavy JavaScript, blocking event handlers

Cumulative Layout Shift (CLS): - Target: < 0.1 - Measures: Visual stability - Common issues: Images without dimensions, dynamic content insertion

Asset Budget¶

JavaScript: - Target: < 300KB (gzipped) - Maximum: 400KB (requires justification)

CSS: - Target: < 100KB (gzipped) - Maximum: 150KB (requires justification)

Images: - Target: < 200KB per image - Format: WebP with JPEG/PNG fallback - Strategy: Lazy loading for below-the-fold

Fonts: - Target: < 100KB total - Recommended: System fonts (0 KB) - If web fonts: WOFF2, preload critical, font-display: swap

Optimization Strategies¶

Level 1: Quick Wins (1-2 points, 2-4 hours) - Enable caching (WP Rocket, W3 Total Cache) - Optimize images (Imagify, ShortPixel) - Enable lazy loading - Minify CSS/JS - Use system fonts or preload web fonts

Level 2: Standard (3-5 points, 6-20 hours / 1-2 days) - Critical CSS inlining - Remove unused CSS/JS (PurgeCSS) - Optimize web fonts (subsetting, WOFF2) - Implement responsive images (srcset) - Object caching (Redis, Memcached)

Level 3: Advanced (8-13 points, 24-80 hours / 3-5 days to 1-2 weeks) - Service workers for offline support - HTTP/2 or HTTP/3 - CDN implementation (Cloudflare) - Advanced image formats (AVIF) - Edge caching

Performance Gate Enforcement¶

Every Sprint: - [ ] Run Lighthouse audit on staging - [ ] Verify Core Web Vitals targets met - [ ] Check asset budget not exceeded - [ ] Review performance report

Before Production Deploy: - [ ] Lighthouse Performance > 90 (desktop), > 70 (mobile) - [ ] Core Web Vitals pass (LCP < 2.5s, INP < 200ms, CLS < 0.1) - [ ] No performance budget violations - [ ] Real-world monitoring enabled

Story Point Estimate: Performance Work¶

Initial optimization: 5-8 points (20-32 hours / 3-4 days)
Ongoing monitoring: 2 points/sprint (4-8 hours)
Budget violation fix (minor): 1-2 points (2-4 hours)
Budget violation fix (major): 8-13 points (24-80 hours / 3-5 days to 1-2 weeks)

Plugin Ecosystem¶

WordPress has 60,000+ plugins, but most projects should use < 15 plugins to maintain performance.

Plugin Decision Framework¶

For every plugin, document: 1. Purpose: What need does this solve? 2. Alternatives: Could this be manual code? 3. Performance Impact: Asset size, HTTP requests 4. Cost: One-time, annual, monthly 5. Justification: Why is this worth it?

Essential Plugins (Most Projects)¶

Performance (1-2 plugins): - WP Rocket ($59/year) - Cache, critical CSS, lazy load - Imagify ($10/month) - Image optimization

SEO (1 plugin): - Yoast SEO (Free) - Meta tags, schema markup - Rank Math (Free) - Alternative to Yoast

Security (1-2 plugins): - Wordfence (Free) - Firewall, malware scanner - iThemes Security (Free) - Hardening, 2FA

Forms (1 plugin): - Gravity Forms ($59/year) - Complex forms - WPForms ($49/year) - Simpler, good UX - Contact Form 7 (Free) - Basic contact forms

Backups (1 plugin): - UpdraftPlus (Free) - Scheduled backups

Plugins to Avoid¶

Performance Impact > 200KB: - Jetpack (280 KB, feature bloat) - Revolution Slider (550 KB, outdated) - Visual Composer (600+ KB, deprecated)

Better Alternatives: - Page builders → Block theme patterns (0 KB, native) - Slider plugins → Core Gallery block with CSS (10 KB) - Multiple SEO plugins → One SEO plugin (avoid conflicts)

Story Point Estimate: Plugin Work¶

Plugin research and selection: 1 point (2 hours)
Simple plugin setup: 1 point per plugin (2 hours)
Complex plugin (e.g., WooCommerce): 8-13 points (24-80 hours / 3-5 days to 1-2 weeks)

Common Pitfalls and Mitigation¶

Pitfall #1: Building Custom Blocks When Patterns Suffice¶

Problem: Developers default to custom blocks for everything, causing 3-10x cost overruns.

Cost Impact: - Pattern: 2-8 hours (1-3 points) - ACF block: 4-20 hours (2-5 points) - Custom block: 12-120 hours (3-21 points)

Mitigation: 1. Pattern-First Framework: Try core → pattern → ACF → custom (in that order) 2. Require Justification: Written rationale for any custom block 3. Code Review Checkpoint: "Could this be a pattern instead?" 4. Client Education: Explain cost implications of custom vs pattern

Story Points: +5-8 points contingency if not enforced

Pitfall #2: Performance Degradation from Heavy Block Usage¶

Problem: 56% of WordPress sites fail Core Web Vitals. Block themes can be heavy if not optimized.

Impact: Google SEO penalty, poor user experience, high bounce rates.

Mitigation: 1. Performance Budget at Kickoff: LCP < 2.5s, INP < 200ms, CLS < 0.1 2. Lighthouse Audits Every Sprint: Catch issues early 3. Asset Budget Enforcement: JS < 300KB, CSS < 100KB 4. Performance Gate: Block deploys that degrade metrics > 10%

Story Points: +5-8 points contingency for remediation

Pitfall #3: Editor Training Gap¶

Problem: Block themes more complex than classic themes. Editors accidentally break layouts.

Impact: Support burden, incorrect content, site breakage.

Mitigation: 1. Pattern Library with Screenshots: Visual guide for editors 2. Video Training: Editor walkthrough, 15-30 minutes 3. Lock Critical Blocks: Prevent accidental layout changes 4. Editor Style Guide: Do's and don'ts, troubleshooting

Story Points: +2-3 points for training materials

Pitfall #4: Plugin Bloat¶

Problem: Adding plugins without justification. 20+ plugins common, causing performance issues.

Impact: Each plugin adds 10-50 HTTP requests, 50-200 KB assets.

Mitigation: 1. Plugin Budget: < 15 plugins target, < 20 maximum 2. Justification Required: Document why each plugin is essential 3. Quarterly Plugin Audit: Remove unused plugins 4. Performance Testing: Before/after plugin install

Story Points: +2-5 points for plugin audit and optimization

Pitfall #5: Inadequate theme.json Planning¶

Problem: Rushed theme.json causes inconsistent design tokens, requiring rework.

Impact: Editors use hex codes instead of theme colors, breaking consistency.

Mitigation: 1. theme.json First: Define tokens before building patterns/templates 2. Design System Sync: Match Figma/design tool tokens to theme.json 3. Lock Custom Values: Disable custom colors/font sizes if consistency critical 4. Document Tokens: Explain when to use each color/size/spacing

Story Points: 3-8 points for theme.json (invest upfront to save later)

Best Practices¶

Development Workflow¶

Start with theme.json: Define design tokens first (colors, typography, spacing)
Build Core Layouts as Patterns: Hero, features, CTAs as reusable patterns
Test with Real Content: Don't use "lorem ipsum", use actual expected content length
Lock Critical Layout Blocks: Prevent editors from breaking structure
Performance Test Every Sprint: Lighthouse audits, Core Web Vitals monitoring

Pattern Organization¶

Group patterns by category:

patterns/
├── hero-section.php              # Hero patterns
├── hero-section-video.php
├── feature-grid-3col.php         # Feature patterns
├── feature-grid-4col.php
├── testimonial-single.php        # Testimonial patterns
├── testimonial-slider.php
├── cta-banner.php                # CTA patterns
├── cta-boxed.php
└── footer-3col.php               # Footer patterns

Pattern Naming: - Descriptive: hero-section, not pattern1 - Specific: feature-grid-3col, not grid - Categorized: Prefix by type if helpful (e.g., hero-*, cta-*)

Documentation¶

For Developers: - README with setup instructions - theme.json documentation (what each token is for) - Pattern usage guide (when to use which pattern) - Custom block documentation (if any)

For Editors: - Pattern library with screenshots - Video walkthrough (15-30 minutes) - Common tasks guide (add a page, add a post, etc.) - Troubleshooting section

Story Point Estimation Cheat Sheet¶

Theme Foundation: - theme.json (basic): 3 points (6-8 hours) - theme.json (complete): 5 points (12-16 hours) - Basic templates (index, single, page, 404): 2-3 points (4-12 hours) - Header/footer parts: 1-2 points (2-8 hours)

Patterns: - Simple (3-5 blocks): 1-2 points (2-4 hours) - Moderate (6-10 blocks): 2-3 points (4-8 hours) - Complex (10+ blocks): 3-5 points (8-20 hours / 1-2 days)

ACF Blocks: - Simple: 2-3 points (4-8 hours) - Complex: 3-5 points (12-20 hours / 1-2 days)

Custom Gutenberg Blocks: - Static: 3-5 points (12-20 hours / 1-2 days) - With InnerBlocks: 8-13 points (32-80 hours / 3-5 days to 1-2 weeks) - Dynamic with REST API: 13-21 points (80-120 hours / 1-3 weeks)

Performance: - Initial optimization: 5-8 points (20-32 hours / 3-4 days) - Ongoing monitoring: 2 points/sprint (4-8 hours)

Plugins: - Setup per plugin: 1 point (2 hours) - Complex plugin (WooCommerce): 8-13 points (24-80 hours / 3-5 days to 1-2 weeks)

Testing & QA: - Browser testing (Chrome, Firefox, Safari, Edge): 2 points (4 hours) - Accessibility testing (WCAG AA): 3 points (6-8 hours) - Performance testing (Lighthouse, Core Web Vitals): 2 points (4 hours)

Example Project: Marketing Site¶

Project: Marketing site for SaaS product Requirements: Homepage, about page, services page, blog, contact form Target: Core Web Vitals pass, < 15 plugins, WCAG AA compliant

FRD Breakdown¶

FR-001: Homepage Hero Pattern [MUST HAVE] - Cover block + Group + Heading + Paragraph + Buttons - Story Points: 2 points (4 hours) - Justification: Core blocks sufficient

FR-002: Feature Grid Pattern [MUST HAVE] - Columns + Image + Heading + Paragraph (repeat 3x) - Story Points: 2 points (4 hours) - Justification: Core blocks sufficient

FR-003: Testimonial ACF Block [SHOULD HAVE] - Repeating fields: name, title, quote, photo - Story Points: 3 points (6-8 hours / 1 day) - Justification: Repeating content, ACF faster than custom block

TR-001: theme.json Configuration [MUST HAVE] - Colors (6), typography (2 fonts, 5 sizes), spacing (8 presets) - Story Points: 5 points (12-16 hours / 2 days)

NFR-001: Performance Budget [MUST HAVE] - LCP < 2.5s, INP < 200ms, CLS < 0.1 - Story Points: 8 points (24-32 hours / 3-4 days)

NFR-002: Accessibility [MUST HAVE] - WCAG 2.1 Level AA compliance - Story Points: 3 points (6-8 hours / 1 day)

Total: 23 points (~46 hours, 6 days for 1 developer)

Plugin List¶

WP Rocket ($59/year) - Performance
Imagify ($10/month) - Image optimization
Yoast SEO (Free) - SEO
Wordfence (Free) - Security
Gravity Forms ($59/year) - Contact form
UpdraftPlus (Free) - Backups

Total: 6 plugins, $178/year (well under 15-plugin budget)

Summary¶

WordPress block themes in 2026 are powerful, performant, and pattern-driven. The key to success is:

Pattern-First: Use core blocks and patterns for 80-90% of UI
Performance Budget: LCP < 2.5s, INP < 200ms, CLS < 0.1 (mandatory)
Plugin Discipline: < 15 plugins with documented justifications
Editor-Friendly: Pattern library, training, locked layouts
Accurate Estimation: Pattern = 2-8h, ACF = 4-20h, Custom = 12-120h

When planning your next WordPress project, use the decision frameworks in this guide to: - Choose the right approach for each UI component - Estimate story points accurately - Avoid common pitfalls (custom block overuse, performance issues) - Deliver on time and on budget

Guide Version: 1.0.0 (Phase 2 v0.3.0) Last Updated: 2026-03-16 Target: WordPress 6.8+, Block Themes, Full Site Editing Related: Story Points Guide, Quick Start Guide