WordPress Analyzer

Analyze WordPress block theme projects to generate comprehensive technical requirements, block/pattern inventories, and performance budgets for FRDs.

Philosophy

WordPress block theme development in 2026 requires strategic decisions about blocks vs patterns vs custom development, aggressive performance optimization for Core Web Vitals, and careful plugin selection to avoid performance degradation.

Core Beliefs

1. Pattern-First Development: Core blocks + patterns should be tried before custom blocks (3-5x faster)
2. Performance is Non-Negotiable: 56% of WordPress sites fail Core Web Vitals - performance budget is mandatory
3. Plugin Justification Required: Every plugin must justify its existence (target < 15 plugins)
4. FSE is the Future: Block themes with Full Site Editing are the standard, not classic themes

Why WordPress Analysis Matters

• Cost Control: Prevents 3-5x budget overruns from unnecessary custom block development
• Performance: Core Web Vitals directly impact SEO and user experience
• Editor Experience: Pattern-based approach makes content management easier for non-technical editors
• Maintainability: Fewer custom blocks = less technical debt

When to Use This Skill

Activate this skill when:

• User is planning a WordPress block theme project
• FRD generation detects WordPress platform (wp-config.php, style.css)
• User mentions WordPress blocks, patterns, or Gutenberg
• User asks about WordPress performance or Core Web Vitals
• User needs plugin recommendations or justifications
• User asks "should I build a custom block or use a pattern?"

Decision Framework

Block vs Pattern vs ACF vs Custom Block

Use this decision tree for every UI component:

UI Component Requirement
    ↓
Can core blocks achieve this? (Cover, Group, Columns, Query Loop, etc.)
    YES → Use core blocks
    NO ↓
Can core blocks be composed into a pattern?
    YES → Create pattern (2-8 hours)
    NO ↓
Do you have ACF PRO? Are fields simple?
    YES → Use ACF block (4-20 hours)
    NO ↓
Is complex interactivity or state management required?
    YES → Build custom Gutenberg block (12-120 hours)
    NO → Reconsider: probably should be pattern

Decision Criteria:

Use Core Blocks When:

• Standard content layout (headings, paragraphs, images, buttons)
• Lists, galleries, media embeds
• Forms (with Contact Form 7 or Gravity Forms plugin)
• Query loops for post listings

Use Patterns When:

• Combining 3+ core blocks into reusable layout
• Hero sections, CTAs, testimonials, feature grids
• Repeated layout sections across pages
• Editorial teams need consistent layouts without code

Use ACF Blocks When:

• Repeating fields (team members, locations, products)
• Conditional field logic
• Relationship fields or post object selections
• PHP template approach faster than React build process

Build Custom Gutenberg Blocks When:

• Interactive UI requiring state management
• REST API integration with dynamic data
• Complex nested InnerBlocks patterns
• Third-party API integrations
• No suitable core block or pattern exists

Plugin Justification Framework

For every plugin, document:

1. Purpose: What specific need does this plugin solve? 2. Alternatives: Could this be achieved without a plugin? 3. Performance Impact: Lighthouse score before/after, added KB 4. Maintenance Risk: Last update, active installs, support quality 5. Cost: One-time, annual, or monthly 6. Justification: Why is this plugin worth the trade-offs?

Red Flags (Consider Alternatives):

• Plugin adds > 200KB assets
• Last updated > 1 year ago
• < 10K active installs
• Poor support forum response rate
• Overlapping functionality with another plugin

Plugin Budget:

• Target: < 15 plugins total
• Maximum: 20 plugins (requires strong justifications)
• Essential Only: Security, performance, SEO, forms, backups

Core Web Vitals Performance Budget

Mandatory Targets (Google Search Ranking Factor):

• LCP (Largest Contentful Paint): < 2.5s
• INP (Interaction to Next Paint): < 200ms
• CLS (Cumulative Layout Shift): < 0.1

Asset Budget:

• JavaScript: < 300KB (gzipped)
• CSS: < 100KB (gzipped)
• Images: WebP format, < 200KB per image, lazy loaded
• Fonts: < 100KB total, preloaded critical fonts

Performance Optimization Strategies:

• Critical CSS inlining for above-the-fold content
• JavaScript deferral and code splitting
• Image optimization (WebP, responsive images, lazy loading)
• Font optimization (subsetting, preload, font-display: swap)
• Object caching (Redis, Memcached)
• Page caching (WP Rocket, W3 Total Cache)
• CDN for static assets

Performance Enforcement:

• Lighthouse audits every sprint
• Real-world Core Web Vitals monitoring on staging
• Performance gate before production deployment
• Reject features that degrade Core Web Vitals > 10%

theme.json Configuration Analysis

Required theme.json Sections:

1. Version (use v3 for WordPress 6.8+)

{
  "version": 3
}

2. Settings

• Color palette: 6-8 colors (brand, accents, grays)
• Typography: Font families, sizes (5-7 presets), line heights, letter spacing
• Spacing: Scale (8-10 presets), padding, margin, gap
• Layout: contentSize (720px), wideSize (1200px)
• Custom: Border radius, shadows, gradients (if needed)

3. Styles

• Global: Background, text color, link color, font family
• Elements: Headings, paragraphs, buttons, links
• Blocks: Block-specific styling overrides

4. Template Parts

• Header, footer, sidebar (if applicable)

5. Custom Templates

• Page templates with specific layouts (full-width, no-sidebar, etc.)

Story Point Estimates for theme.json Work:

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

WordPress-Specific Analysis Steps

When analyzing a WordPress project for FRD generation:

1. Block/Pattern Inventory

For each UI component identified in discovery:

| Component | Core Blocks | Pattern | ACF | Custom | Justification | Points |
|-----------|-------------|---------|-----|--------|---------------|--------|
| Hero      | ✓           | ✓       | -   | -      | Core sufficient | 2      |
| Products  | Query Loop  | ✓       | -   | -      | Core + CPT      | 3      |
| Team      | -           | -       | ✓   | -      | Repeating fields| 5      |
| Pricing   | -           | -       | -   | ✓      | Interactivity   | 13     |

2. Plugin Analysis

List proposed plugins with justifications:

**Performance Plugins:**
- WP Rocket ($59/year) - Page cache, critical CSS, lazy load - Justified by LCP target
- Imagify ($10/month) - WebP conversion, compression - Justified by image-heavy site

**SEO Plugins:**
- Yoast SEO (Free) - Meta tags, schema markup - Justified by SEO requirements

**Form Plugins:**
- Gravity Forms ($59/year) - Complex multi-step form - Justified by form complexity

**Total: 4 plugins, $128/year + $120/year**

3. Performance Budget Definition

**Core Web Vitals Targets:**
- LCP: < 2.5s (3G), < 1.5s (4G)
- INP: < 200ms
- CLS: < 0.1

**Asset Budget:**
- JS: 280KB (current) → < 300KB (target)
- CSS: 85KB (current) → < 100KB (target)
- Images: WebP, < 200KB each, lazy loaded

**Story Points for Optimization:**
- Initial optimization: 5 points (20 hours)
- Ongoing monitoring: 2 points/sprint (8 hours)

4. theme.json Specification

**theme.json Requirements:**
- Color palette: 6 colors (primary, secondary, accent, 3 grays)
- Typography: 2 fonts (heading, body), 5 sizes (12px-48px)
- Spacing: 8 presets (0.25rem-4rem)
- Layout: contentSize 720px, wideSize 1200px

**Story Points:** 5 points (12-16 hours)

5. Risk Assessment

**WordPress-Specific Risks:**

1. **Performance Degradation Risk**
   - Likelihood: High
   - Mitigation: Performance budget, Lighthouse audits
   - Contingency: +5-8 points

2. **Custom Block Scope Creep**
   - Likelihood: Medium-High
   - Mitigation: Pattern-first framework
   - Prevention: "Could this be a pattern?" code review

3. **Editor Training Gap**
   - Likelihood: Medium
   - Mitigation: Pattern library, video training
   - Contingency: +2-3 points

Output Format

When providing WordPress analysis for FRDs, structure output as:

## WordPress Block Theme Analysis

### Block/Pattern Inventory
[Table with component decisions]

### theme.json Configuration
[Detailed specifications]

### Plugin Ecosystem
[Justified plugin list with costs]

### Performance Budget
[Core Web Vitals targets and enforcement]

### Risk Assessment
[WordPress-specific risks and mitigation]

### Success Criteria
[Technical and functional gates]

Related Templates

• templates/block-inventory-template.md - Standard block analysis matrix
• templates/themejson-spec.md - Complete theme.json specification guide
• templates/plugin-justification.md - Plugin decision framework
• templates/performance-budget.md - Core Web Vitals targets and enforcement

WordPress Estimation Quick Reference

• Block Pattern (simple): 1-2 points (2-4 hours)
• Block Pattern (complex): 3-5 points (8-20 hours)
• ACF Block (simple): 2-3 points (4-8 hours)
• ACF Block (complex): 3-5 points (12-20 hours)
• Custom Block (static): 3-5 points (12-20 hours)
• Custom Block (dynamic): 13-21 points (80-120 hours)
• theme.json (basic): 3-5 points (6-20 hours)
• theme.json (advanced): 5-8 points (20-32 hours)
• Performance optimization: 5-8 points (20-32 hours)
• Plugin setup & configuration: 1-2 points per plugin (2-4 hours)

---

Skill Version: 1.0.0 (Phase 2 v0.3.0) Last Updated: 2026-03-16 Platform: WordPress 6.8+, PHP 8.1+