Phase A: Custom WordPress Theme Redesign

Status: Ready to start
Timeline: 2-3 months (12-13 weeks)
Risk Level: 🟢 LOW
Budget: [Budget TBD] (freelance) or team composition based on client needs

Budget & Cost Breakdown

Infrastructure costs: [Client-specific infrastructure cost]/mo (varies based on scale and requirements)

See also: Testing Strategy and Infrastructure

📋 Quick Reference

← Back to Master Roadmap | Roadmap Index | Phase Comparison

Technical Details: For comprehensive architecture, service providers, Blade templating, HMR, and development workflow documentation, see Architecture Documentation.

Table of Contents

• Executive Summary
• Phase A Overview
• Budget & Cost Breakdown
• A.1 Discovery & Planning
• A.2 Design Phase
• A.3 Theme Development
• A.4 Performance Optimization
• A.5 Testing & QA
• A.6 Deployment & Launch
• A.7 Phase A Success Metrics
• A.8 Phase A Deliverables
• Dependencies & Assumptions
• Out of Scope (Phase A)
• Risks & Mitigations (Phase A)
• Acceptance Criteria (Definition of Done)
• KPIs & Targets
• Milestones and Go/No-Go Gates
• Roles & Responsibilities (RACI)
• Document Updates

Executive Summary

Modernize the site’s user experience and performance without changing editorial workflows or backend architecture. Deliver a production-ready, accessible theme (Sage + Tailwind + Alpine) with PageSpeed ≥ 90 (mobile) and ≥ 95 (desktop), forming a stable foundation for Phase B.

Phase A Overview

Goal: Modernize the user experience while maintaining WordPress’s full functionality. This phase lays the groundwork for future decoupling without disrupting current operations.

Why Start Here?

• Immediate user-facing improvements
• No architectural changes (low risk)
• Builds foundation for Phase B
• Editorial team unaffected
• SEO improvements
• Performance gains

What Stays the Same:

• WordPress as CMS
• Existing content structure
• Editorial workflow
• Admin interface
• Hosting setup

What Changes:

• Frontend UI/UX
• Theme architecture
• Performance optimization
• Mobile responsiveness
• Accessibility

A.1 Discovery & Planning (Week 1-2)

A.1.1 Audit Current Site

• Document existing features and functionality
• Identify all custom post types
• List all plugins and their purposes
• Map out user journeys
• Performance baseline (PageSpeed, Lighthouse)
• Analytics review (top pages, user behavior)
• SEO audit (keywords, rankings, backlinks)
• Accessibility audit (WCAG compliance)

Tools:

• Google Analytics
• Google Search Console
• PageSpeed Insights
• Screaming Frog SEO Spider
• WAVE (Web Accessibility Evaluation Tool)

Deliverable: Current State Document

A.1.2 Design Requirements

• Stakeholder interviews (editorial, business, tech)
• User persona definition
• Competitor analysis
• Define design goals
• Create mood boards
• Define color palette and typography
• Component library requirements

Key Questions:

• What are user pain points?
• What do competitors do better?
• What features drive engagement?
• What content types need special treatment?

Deliverable: Design Brief

A.1.3 Technical Planning

• Choose frontend framework/build tools
  • Option 1: Vanilla JS + modern build tools
  • Option 2: Alpine.js (lightweight reactivity)
  • Option 3: React/Vue components (progressive enhancement)
• Define theme architecture
• Plan image optimization strategy
• Define caching strategy
• Choose CSS approach
• Plan for performance budgets

Recommended Stack:

- Sage (WordPress theme framework)
- Bud.js (build tool with HMR)
- TailwindCSS (utility-first CSS)
- Alpine.js (lightweight JavaScript)
- Blade (templating)

📚 Technical Reference: For detailed information about this stack, see:

• Architecture Overview
• Service Providers
• Blade Templating
• Asset Pipeline & HMR

Deliverable: Technical Specification

A.2 Design Phase (Week 3-5)

A.2.1 Wireframing

• Homepage wireframes
• Article page wireframes
• Category/archive page wireframes
• Author page wireframes
• Search results wireframes
• Mobile wireframes for all pages
• Navigation structure
• Footer structure

Tools: Figma, Sketch, Adobe XD

A.2.2 High-Fidelity Design

• Homepage design
• Article template design
  • Standard articles
  • Breaking news
  • Feature articles
  • Market data articles
• Category pages
• Author profile pages
• Search interface
• Navigation (header, mobile menu)
• Footer design
• Component library
  • Buttons
  • Cards
  • Forms
  • Modals
  • Alerts
  • Loading states

Special Considerations for Financial News:

• Stock ticker integration
• Market data widgets
• Chart displays
• Breaking news banners
• Newsletter signup forms
• Social sharing

Deliverable: Complete Design System in Figma

A.2.3 Design Review & Iteration

• Internal stakeholder review
• User testing (if possible)
• Accessibility review
• Mobile responsiveness review
• Design refinements
• Final approval

A.3 Theme Development (Week 6-10)

A.3.1 Setup Development Environment

# Current location
cd ~/Projects/roots/nairametrics.com/web/app/themes/

# Option 1: Start fresh with Sage
composer create-project [theme-framework] nairametrics-new
cd nairametrics-new
composer install
npm install

# Option 2: Upgrade existing theme
cd nairametrics
# Review composer.json and package.json
# Update dependencies

Tasks:

• Initialize Sage with recommended stack
• Set up build pipeline (Bud.js)
• Configure TailwindCSS
• Set up linting (ESLint, StyleLint)
• Configure version control
• Set up local development workflow

Note: For technical implementation details, see Architecture Documentation.

A.3.2 Component Development

Week 6: Foundation

• Base templates (layouts/app.blade.php)
• Header component
• Footer component
• Navigation (desktop & mobile)
• Typography styles
• Color system
• Grid system

Week 7: Article Components

• Article card (thumbnail, title, excerpt, meta)
• Article grid/list layouts
• Article header (title, meta, featured image)
• Article body (content, formatting)
• Article footer (tags, share, author bio)
• Related articles component
• Comments section

Week 8: Page Templates

• Homepage template
• Single article template
• Category archive template
• Tag archive template
• Author archive template
• Search results template
• 404 page

Week 9: Special Features

• Breaking news banner
• Stock ticker widget
• Market data widgets
• Newsletter signup forms
• Social sharing buttons
• Ad placement components
• Infinite scroll / Load more

Week 10: Polish & Refinement

• Loading states
• Error states
• Empty states
• Animations and transitions
• Micro-interactions
• Accessibility improvements (ARIA labels, keyboard nav)

A.3.3 WordPress Integration

• Custom post type templates
• Custom taxonomy templates
• Widget areas
• Menu locations
• Theme options (if needed)
• Customizer settings
• Block editor styles (Gutenberg)
• Custom blocks (if needed)

Example: Custom Post Type Template

// resources/views/single-breaking_news.blade.php
@extends('layouts.app')

@section('content')
  <article>
    <header class="breaking-news-header">
      <span class="breaking-badge">🔴 Breaking News</span>
      <h1>{!! $title !!}</h1>
      @include('partials.article-meta')
    </header>

    <div class="article-content">
      @php(the_content())
    </div>

    @include('partials.related-articles')
  </article>
@endsection

A.4 Performance Optimization (Week 11)

A.4.1 Image Optimization

• Install and configure image optimization plugin (ShortPixel/Imagify)
• Implement lazy loading for images
• Generate responsive image sizes
• WebP format support
• CDN integration (Cloudflare)

// Add custom image sizes
add_action('after_setup_theme', function () {
    add_image_size('article-thumb', 400, 250, true);
    add_image_size('article-large', 1200, 675, true);
    add_image_size('breaking-news', 800, 450, true);
});

A.4.2 Caching Strategy

• Configure object caching (Redis)
• Set up page caching
• Configure browser caching
• Implement fragment caching for expensive queries

// Example: Cache trending articles
function get_trending_articles($limit = 10) {
    return cache()->remember('trending_articles', 300, function () use ($limit) {
        // Expensive query here
        return get_posts([
            'posts_per_page' => $limit,
            'meta_key' => 'view_count',
            'orderby' => 'meta_value_num',
            'order' => 'DESC',
        ]);
    });
}

A.4.3 Asset Optimization

• Minify CSS and JavaScript
• Bundle and code-split JavaScript
• Remove unused CSS (PurgeCSS)
• Optimize fonts (variable fonts, font-display: swap)
• Defer non-critical JavaScript
• Critical CSS inline

Build Configuration:

// bud.config.js
export default async (bud) => {
  bud
    .entry("app", ["@scripts/app", "@styles/app"])
    .splitChunks()
    .minimize()
    .hash();
};

A.4.4 Database Optimization

• Add indexes for commonly queried fields
• Clean up post revisions
• Optimize autoloaded options
• Database query optimization

-- Add index for post views (if tracking)
ALTER TABLE wp_postmeta
ADD INDEX idx_view_count (meta_key, meta_value);

-- Add index for post date queries
ALTER TABLE wp_posts
ADD INDEX idx_post_date_status (post_date, post_status);

A.5 Testing & QA (Week 12)

A.5.1 Functional Testing

• Test all page templates
• Test navigation
• Test forms (search, newsletter, comments)
• Test responsive breakpoints
• Test browser compatibility (Chrome, Firefox, Safari, Edge)
• Test on various devices (desktop, tablet, mobile)
• Test with real content

A.5.2 Performance Testing

• PageSpeed Insights (target: 90+ mobile, 95+ desktop)
• Lighthouse audit (target: 90+ all categories)
• WebPageTest
• GTmetrix
• Core Web Vitals
  • LCP (Largest Contentful Paint) < 2.5s
  • FID (First Input Delay) < 100ms
  • CLS (Cumulative Layout Shift) < 0.1

Deliverable: Performance Report

A.5.3 SEO Testing

• Meta tags correct (title, description)
• Open Graph tags
• Twitter Card tags
• Schema.org markup (Article, Organization, Person)
• XML sitemap
• Robots.txt
• Canonical URLs
• 301 redirects for changed URLs

A.5.4 Accessibility Testing

• WAVE accessibility evaluation
• Keyboard navigation
• Screen reader testing (NVDA/JAWS)
• Color contrast ratios (WCAG AA minimum)
• Focus states visible
• ARIA labels where needed
• Alt text for all images

Target: WCAG 2.1 Level AA compliance

A.6 Deployment & Launch (Week 12-13)

A.6.1 Pre-Launch Checklist

• Backup current site (database + files)
• Final content review
• Update all plugins and WordPress core
• Configure caching
• Set up error monitoring (Sentry/Bugsnag)
• Set up uptime monitoring
• Test on staging environment
• Get stakeholder approval

A.6.2 Deployment

# Build production assets
npm run build

# Deploy via your preferred method
# Option 1: Git deployment
git push production main

# Option 2: SFTP/rsync
# Option 3: WP Pusher or similar

Deployment Steps:

1. Enable maintenance mode
2. Deploy new theme files
3. Activate new theme
4. Clear all caches
5. Test critical paths
6. Monitor error logs
7. Disable maintenance mode

A.6.3 Post-Launch

Week 1 After Launch:

• Monitor analytics (traffic, bounce rate, time on site)
• Monitor error logs
• Monitor performance metrics
• Collect user feedback
• Fix critical bugs
• Make minor adjustments

Week 2-4 After Launch:

• Analyze user behavior
• Identify optimization opportunities
• Plan iterative improvements
• Document lessons learned

A.7 Phase A Success Metrics

Performance Targets

• PageSpeed Score: 90+ (mobile), 95+ (desktop)
• LCP: < 2.5s
• FID: < 100ms
• CLS: < 0.1
• Time to Interactive: < 3s

User Experience Targets

• Bounce Rate: < 60% (improvement from baseline)
• Pages per Session: > 2.5
• Average Session Duration: > 2 minutes
• Mobile vs Desktop usage: Track trend

Business Targets

• Maintain or improve SEO rankings
• Maintain or improve ad revenue
• Increase newsletter signups
• Positive user feedback

A.8 Phase A Deliverables

✅ Design Assets

• Complete design system in Figma
• Component library
• Style guide

✅ Code

• Production-ready WordPress theme
• Optimized build pipeline
• Documentation

✅ Documentation

• Theme usage guide
• Component documentation
• Performance benchmarks
• SEO improvements

✅ Foundation for Phase B

• Clean, modular codebase
• Separation of concerns (templates vs. logic)
• API-ready structure
• Modern tooling in place

Dependencies & Assumptions

• WordPress stays as CMS; no data model changes in Phase A
• Existing hosting and CDN remain unchanged
• Editorial workflows and roles do not change
• Design approval occurs by end of Week 5

Out of Scope (Phase A)

• Headless architecture (Next.js/Expo)
• Laravel API layer
• Mobile apps
• Database schema changes or content migrations

Risks & Mitigations (Phase A)

Acceptance Criteria (Definition of Done)

• New theme activated on staging and production without critical regressions
• PSI scores ≥ 90 (mobile) and ≥ 95 (desktop) on key pages
• All primary templates validated (home, article, archive, search, author, 404)
• Accessibility checks meet WCAG 2.1 AA for key flows
• Editorial team confirms no workflow changes/blockers

KPIs & Targets

• PageSpeed (Mobile): ≥ 90
• PageSpeed (Desktop): ≥ 95
• LCP: < 2.5s; INP: < 200ms; CLS: < 0.1
• Bounce rate: < 60%
• Avg session duration: > 2 minutes

Milestones and Go/No-Go Gates

Timeline Snapshot (13 weeks)

Wk 1-2  : Discovery & Planning    [######]
Wk 3-5  : Design (wireframes→Hifi) [#########]
Wk 6-10 : Development              [###############]
Wk 11   : Performance              [###]
Wk 12   : QA                       [###]
Wk 13   : Deploy                   [##]

Go/No-Go Gates

• End of Week 2: Discovery complete (proceed to design)
• End of Week 5: Design approved (proceed to dev)
• End of Week 12: QA passes + performance targets met (go to deploy)

Roles & Responsibilities (RACI)

Document Updates

📄 Master Roadmap | 📄 Phase B →