WordPress Theme Development in 2025

The Evolving Landscape

I started building WordPress themes when you could understand the entire codebase in an afternoon. A handful of PHP files, some CSS, maybe a bit of jQuery. The Customizer was revolutionary. Page builders were emerging but optional. It was a simpler time—and honestly, a less capable one.

WordPress theme development in 2025 looks remarkably different. The block editor—what we once called Gutenberg—has matured from a controversial experiment into the foundation of modern WordPress. Full Site Editing enables visual customization of entire themes, not just post content. The patterns for building themes have shifted significantly, and developers who haven't kept up often feel lost.

I've spent the past several years navigating this transition with clients, sometimes building cutting-edge block themes, sometimes maintaining classic themes that will never be converted, often doing something in between. This article shares what I've learned about practical theme development in 2025—not theoretical best practices, but patterns that actually work in real projects.

The good news: the fundamentals of WordPress remain. Hooks, filters, the template hierarchy, the loop—these concepts still apply. The bad news: there's significantly more to learn, and some of what you knew is becoming obsolete. The honest truth: this is just how technology evolves, and adapting is part of the job.

Block Themes vs. Classic Themes

The first strategic decision in any theme project is which architecture to use. I've built both types in the past year, and the choice depends on factors that aren't always obvious.

Classic themes represent the traditional WordPress approach that most developers learned first. PHP template files like index.php, single.php, and page.php control rendering through the template hierarchy. The Customizer provides theme options. The functions.php file holds custom functionality. This pattern has a mature ecosystem of documentation, examples, and tools. Most existing WordPress themes are classic themes, and many will remain so indefinitely.

Block themes take a fundamentally different approach. Templates are HTML files containing block markup rather than PHP generating HTML. The theme.json file centralizes design configuration—colors, typography, spacing, and more. Full Site Editing lets users visually customize every part of the site, not just content areas. Block patterns and template parts provide reusable design elements. Style variations enable multiple design options without separate themes.

Hybrid approaches have emerged for sites that need both worlds. Classic themes can add block editor support and use theme.json for configuration. Block themes can include PHP for custom functionality that blocks can't handle. Progressive migration lets you convert a classic theme to blocks incrementally rather than rewriting everything at once.

My rule of thumb: if you're starting a new project with no legacy constraints, build a block theme. If you're maintaining an existing classic theme that works well, don't convert it just because blocks are newer. If you need to decide whether converting makes sense, assess the actual pain points and benefits rather than following trends.

theme.json and Design Tokens

The theme.json file has become the most important file in modern WordPress themes. When I first encountered it, I thought it was just another configuration format. Now I consider it the foundation of any theme I build.

What theme.json controls is extensive. Colors get defined as a palette available throughout the editor, with semantic names like "primary" and "background" rather than hex codes scattered through CSS. Typography settings control font families, sizes, line heights, and other properties. Spacing presets standardize margins and padding across the site. Layout settings define content widths and alignment options. Block-level settings enable or disable specific features on a per-block basis—you can allow certain blocks while restricting others. Custom CSS properties get generated automatically, creating design tokens you can use in your own CSS.

The benefits compound over time. You have a single source of truth for design decisions, which eliminates the drift that happens when colors and spacing get defined in multiple places. The editor experience matches front-end output because they're drawing from the same configuration. CSS is reduced because you're using standardized properties rather than writing custom styles for every variation. Style variations become possible without code changes—you can offer multiple design options by just providing alternative JSON files.

Practical Example

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#0066cc", "name": "Primary" },
        { "slug": "secondary", "color": "#333333", "name": "Secondary" }
      ]
    },
    "typography": {
      "fontFamilies": [
        { "slug": "system", "fontFamily": "-apple-system, BlinkMacSystemFont, sans-serif", "name": "System" }
      ],
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "medium", "size": "1rem", "name": "Medium" },
        { "slug": "large", "size": "1.25rem", "name": "Large" }
      ]
    },
    "spacing": {
      "units": ["rem", "%"],
      "spacingSizes": [
        { "slug": "40", "size": "1rem", "name": "Small" },
        { "slug": "50", "size": "2rem", "name": "Medium" }
      ]
    }
  }
}

I've started every recent theme by spending significant time on theme.json before writing any templates. Getting the foundation right makes everything that follows easier. Getting it wrong means fighting your configuration throughout the project.

Building Block Themes

Block theme development requires learning new patterns, but the concepts aren't complicated once you understand the structure. I'll walk through the key elements with enough detail to get started.

The minimum viable block theme needs only three files. The style.css provides the theme header with name, version, and other metadata—this works exactly like classic themes. A templates/index.html file serves as the main template, containing block markup instead of PHP. The theme.json file provides design configuration. That's genuinely all you need for a functioning block theme, though real projects will have more.

Template structure uses block markup instead of PHP. Where a classic single.php might have PHP calling get_header(), then the_content(), then get_footer(), a block theme's single.html contains blocks for each element. Template parts get referenced with a block that includes their slug. The post title and content use their respective blocks. The result is more declarative and more visually editable, though less flexible for complex logic.

Template Structure Example

<!-- templates/single.html -->
<!-- wp:template-part {"slug":"header"} /-->

<!-- wp:group {"tagName":"main"} -->
<div class="wp-block-group">
  <!-- wp:post-title /-->
  <!-- wp:post-content /-->
</div>
<!-- /wp:group -->

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

Template parts are reusable sections stored in a /parts directory. Headers, footers, sidebars—anything you'd want to use across multiple templates. They're editable in the Site Editor, which is powerful for clients but means you need to design them to be flexible. I typically build template parts with placeholder blocks that establish structure while allowing content customization.

Block patterns have become one of my favorite features. These are pre-designed arrangements of blocks that users can insert and then customize. A hero section pattern, a testimonial grid pattern, a call-to-action pattern—you design it once, register it, and users can drop it into their content. Patterns can be registered via PHP or as pattern files in the /patterns directory.

1. Start with theme.json

   Define your design system first. Colors, typography, spacing. This foundation shapes everything else.

2. Build template parts

   Create header, footer, and other reusable sections. Keep them flexible with placeholder blocks.

3. Create templates

   Build templates for different content types. Use template parts for consistency.

4. Add block patterns

   Create patterns for common layouts. Make content creation easy for editors.

5. Style with CSS

   Add custom CSS for refinements theme.json can't handle. Use CSS custom properties from theme.json.

The learning curve is real, but block theme development is more logical than it first appears. The concepts map to classic theme concepts—template parts are like get_template_part(), patterns are like predefined content structures. The implementation just uses different technology.

Custom Block Development

Sometimes core blocks aren't enough. When you need functionality that WordPress doesn't provide out of the box, custom block development becomes necessary. I build custom blocks regularly, but I'm increasingly careful about when they're actually needed.

Custom blocks make sense when you have unique functionality that no core block provides, when you need tight integration with custom data or external systems, when specific interaction patterns require custom JavaScript, or when you're building reusable components for multiple sites. They don't make sense when core blocks with custom styling would work, when block variations or styles could achieve the goal, or when patterns could provide the needed layout.

The block development stack has stabilized around WordPress's official tools. The @wordpress/scripts package provides build configuration based on webpack. The @wordpress/blocks package handles registration. The @wordpress/block-editor package provides editor components. The @wordpress/components package offers a UI library that matches WordPress's native appearance. React underlies the editor interface rendering, so JavaScript skills—particularly React—are essential.

Block Structure

// block.json
{
  "apiVersion": 3,
  "name": "my-theme/custom-cta",
  "title": "Custom CTA",
  "category": "design",
  "attributes": {
    "heading": { "type": "string" },
    "buttonText": { "type": "string" }
  },
  "editorScript": "file:./index.js",
  "style": "file:./style.css"
}

Server-side rendering becomes valuable when blocks need data from WordPress—posts, users, options, or computed values. The block stores its configuration as attributes, and a PHP render callback generates the actual output. This pattern is particularly useful for dynamic content that shouldn't be baked into the saved block markup.

I've seen projects with dozens of custom blocks that could have been accomplished with patterns and core blocks. Every custom block is code you maintain, and that maintenance burden compounds. Build custom blocks when you genuinely need them, not because they seem more professional than using what WordPress provides.

Build Tools and Workflow

Modern theme development benefits significantly from build tools. You can build themes without them, but you're making your life harder and your output less optimized.

The @wordpress/scripts package has become my standard starting point. It provides zero-configuration webpack setup for blocks, handling transpilation, bundling, and optimization without requiring you to understand webpack's complexity. Sass or PostCSS handle CSS preprocessing and optimization—I prefer Sass for its maturity, but PostCSS with appropriate plugins works well too. npm manages JavaScript dependencies while Composer handles PHP dependencies. Git is non-negotiable for version control; I can't imagine professional development without it.

My recommended workflow starts with a local development environment. Local by Flywheel is my usual choice for its simplicity, but wp-env, DDEV, or Docker setups work well for teams needing consistent environments. Hot reloading during development lets you see changes immediately without manual refreshing—a small thing that adds up to significant productivity gains. Linting catches code quality issues before they become problems; PHPCS for PHP and ESLint for JavaScript are standard. A build step produces optimized production assets. Automated deployment through CI/CD pipelines removes manual error from releases.

Package.json Example

{
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js"
  },
  "devDependencies": {
    "@wordpress/scripts": "^28.0.0"
  }
}

Setting up proper tooling takes time at the start of a project. That time pays back many times over in development speed, code quality, and production optimization. Skipping this setup is false economy.

Performance Considerations

Performance is non-negotiable in modern web development. Users expect fast sites, search engines reward them, and Core Web Vitals have made performance metrics explicit ranking factors. Every theme I build gets performance testing as a fundamental requirement.

Core Web Vitals provide specific metrics to target. Largest Contentful Paint (LCP) measures how quickly the main content appears—typically the hero image or headline. You optimize this by ensuring above-fold content loads immediately, images are properly sized and served in modern formats, and nothing blocks rendering. Interaction to Next Paint (INP, which replaced FID) measures responsiveness to user interaction. Minimizing blocking JavaScript is key; defer what you can, eliminate what you don't need. Cumulative Layout Shift (CLS) measures visual stability. Reserve space for dynamic content, define image dimensions, and ensure fonts load smoothly.

Theme-level performance practices make a significant difference. Scripts and styles should be enqueued conditionally, loading only on pages where they're actually used. Modern image formats like WebP and AVIF with fallbacks reduce file sizes dramatically. Lazy loading for below-fold images defers their loading until needed. Render-blocking resources should be minimized—inline critical CSS, defer non-essential scripts. Browser caching headers enable repeat visitors to load quickly. For particularly performance-sensitive sites, critical CSS extraction ensures above-fold content renders before full stylesheets load.

Block editor performance deserves specific attention. Theme.json settings affect editor performance as well as front-end rendering. Custom blocks should be built efficiently, using useSelect and useDispatch hooks appropriately to avoid unnecessary re-renders. Test editor performance with realistic content amounts, not just empty pages—a site with dozens of blocks behaves differently than one with two.

I've seen beautiful themes that were unusable on mobile networks. Performance constraints should inform design decisions, not be addressed as an afterthought.

Accessibility Requirements

Accessibility isn't optional in 2025. It's ethically required because we shouldn't exclude users with disabilities. It's increasingly legally required under regulations like the ADA, EAA, and various local laws. And it's practically beneficial because accessible sites are often better-designed sites overall.

Theme accessibility fundamentals start with semantic HTML. Use proper heading hierarchy—h1 through h6 in order, not for visual styling. Use landmark elements like main, nav, header, and footer so screen readers can navigate by region. Keyboard navigation must work throughout the site; every interactive element needs to be reachable and usable without a mouse. Focus management ensures users know where they are; visible focus indicators are essential, not optional styling. Color contrast must meet WCAG standards—typically 4.5:1 for normal text, 3:1 for large text. Screen reader compatibility requires proper ARIA labels where semantic HTML isn't sufficient and avoiding patterns that confuse assistive technology.

Block themes introduce specific considerations. Template parts need proper landmark roles—your header template part should have role="banner" or be a header element, your footer should be a footer element or have role="contentinfo". Block patterns should be accessible by default; when you create a pattern, build accessibility in rather than leaving it for content editors to figure out. Skip links for keyboard navigation let users bypass repetitive content. Form blocks need proper labels associated with inputs and accessible error handling.

Testing for accessibility requires multiple approaches. Automated testing with tools like axe or WAVE catches many issues efficiently. Keyboard-only navigation testing reveals problems that automated tools miss—try using your site without a mouse. Screen reader testing with NVDA on Windows or VoiceOver on Mac shows how real assistive technology users experience your site. Color contrast verification ensures all text is readable. Testing with reduced motion preferences ensures animations respect user settings.

I've been on projects where accessibility was treated as a final checklist item. It never works well. Accessibility needs to be considered from the beginning, baked into design decisions, and tested throughout development.

Development Strategy

Practical advice for WordPress theme development in 2025 depends on your situation. Different contexts require different approaches.

For new projects starting fresh, I recommend block themes unless you have specific reasons to choose otherwise. Invest significant time in theme.json and design tokens early—this foundation shapes everything that follows. Create patterns for common content needs; they make content creation easy for editors and ensure design consistency. Build custom blocks only when necessary, preferring core blocks with custom styling when possible.

For existing sites with classic themes, don't convert just because blocks are newer. If the current theme works well and meets needs, maintain it. When improvements are needed, add block support incrementally rather than rewriting. Use theme.json even in classic themes for editor consistency—it's not block-theme-only. If full conversion is the eventual goal, plan the migration path but don't rush it.

For your skills development, learn block development and Full Site Editing—these are the future of WordPress. Understand theme.json deeply; it's increasingly central to theme development. Keep PHP skills current because it's not going away, even as its role shifts. Add React and modern JavaScript to your toolkit for custom block development. Stay current with WordPress releases; the platform evolves faster than it used to.

WordPress theme development continues to evolve. The patterns of 2020 aren't the patterns of 2025, and 2025's patterns won't be 2030's. This is normal in technology. The developers who thrive are those who learn continuously, adapt pragmatically, and focus on building themes that serve both editors and end users well. The specific technologies matter less than understanding why they exist and when to use them.