How to Convert PSD to WordPress: Step-by-Step Guide

Converting a PSD design to a fully functional WordPress theme is a core web development skill I’ve performed hundreds of times. While Figma has largely replaced Photoshop for new design work, PSD files remain common in enterprise workflows, agency handoffs, and legacy projects. This step-by-step guide walks through the complete conversion process — from opening the PSD in Photoshop to a live, editable WordPress site.

PSD to WordPress conversion is the process of taking a static Photoshop design file and turning it into a dynamic, content-managed WordPress website. The designer creates the visual mockup in Photoshop — defining layouts, typography, colors, and imagery. The developer’s job is to transform that static image into working HTML, CSS, and PHP code that WordPress can execute.

The process involves several distinct phases: analyzing the PSD structure, exporting assets, writing markup, applying styles, and integrating with WordPress’s PHP architecture. Each phase requires different skills and tools. A developer who cuts corners at the analysis stage will encounter problems at every subsequent step.

Modern PSD to WordPress conversion also requires going beyond pixel-perfect replication. You must decide how each design element maps to WordPress’s content model — what’s editable via the Gutenberg editor, what’s controlled through theme settings, and what’s hardcoded. Making these decisions correctly is what separates a professional conversion from an amateur one.

Before writing a single line of code, ensure you have the right toolkit assembled:

• Adobe Photoshop CC — for opening PSD files, inspecting layers, and exporting assets. The “Export As” and “Generate Image Assets” features are essential.
• A local WordPress environment — I use LocalWP. It spins up a complete LAMP stack in minutes with no configuration.
• Code editor — VS Code with the PHP Intelephense, WordPress Snippets, and Prettier extensions installed.
• Node.js and npm — for running build tools. I use a Gulp or Webpack setup for compiling Sass and bundling JS.
• Browser DevTools — Chrome DevTools for CSS inspection, layout debugging, and performance profiling.
• A version control system — Git with GitHub or GitLab. Non-negotiable even for solo projects.
• WP-CLI — WordPress command line interface for installing plugins, managing users, and running database operations without leaving the terminal.

Optionally, tools like Zeplin, Avocode, or Adobe XD’s “Inspect” panel can help extract measurements, colors, and CSS values from PSD files if Photoshop’s built-in tools aren’t enough.

Before touching code, spend focused time inside the PSD. Turn on all layers, expand every group, and build a mental model of the design’s component structure. How many unique sections are there? What elements repeat across pages? What images are decorative (CSS background) vs. content images (HTML img tags)?

Look for patterns: if the same card design appears in the blog listing, team page, and case studies, that’s a single component you’ll build once and reuse. Identify your global elements — header, footer, sidebar — and note exactly which layers belong to each.

Use Photoshop’s ruler guides to verify spacing and layout grid. Most PSD designs are built on a 12-column grid (often 1200px wide with 20px gutters). Confirming the grid system before you write CSS saves enormous amounts of guesswork later.

Export images, icons, and graphics from the PSD. Rules I follow: raster images (photos, complex illustrations) export as JPEG at 85% quality. Icons and simple graphics export as SVG where possible — SVGs scale infinitely and are far smaller than PNG equivalents. Logos always export as SVG. Repeat background textures and patterns export at 1x (non-retina) and 2x (retina) sizes.

Use Photoshop’s “Export As” dialog (File > Export > Export As) rather than “Save for Web” — it offers better compression controls and supports modern formats. Name files systematically: hero-background.jpg, icon-arrow-right.svg, team-alex-chen.jpg.

Semantic HTML is the foundation of accessible, SEO-friendly WordPress themes. Every PSD element maps to an appropriate HTML element — not just a generic <div>. The header section uses <header>. Navigation uses <nav>. Main content uses <main>. Articles use <article>. Sidebar uses <aside>. Footer uses <footer>.

<!-- Semantic WordPress theme header -->
<header class="site-header">
  <div class="container">
    <a href="<?php echo esc_url( home_url('/') ); ?>" class="site-logo">
      <?php bloginfo('name'); ?>
    </a>
    <nav class="primary-nav" aria-label="Primary Navigation">
      <?php wp_nav_menu(['theme_location' => 'primary', 'container' => false]); ?>
    </nav>
  </div>
</header>

Write the HTML for one complete page template first — typically the homepage. Validate it with the W3C HTML Validator before proceeding. Fixing semantic issues at the HTML stage is ten times faster than hunting them down after PHP integration.

With valid HTML in place, translate the PSD’s visual styles into CSS. Extract typography values from Photoshop’s character panel: font family, weight, size, line height, letter spacing. Extract colors from the swatches panel. Extract spacing from layer alignment and guides.

I structure CSS using a modular approach with CSS custom properties for design tokens:

:root {
  --color-primary: #3b5bdb;
  --color-text: #1a1a2e;
  --color-bg: #ffffff;
  --font-heading: 'Inter', sans-serif;
  --font-body: 'Inter', sans-serif;
  --spacing-base: 8px;
  --border-radius: 8px;
  --max-width: 1100px;
}

.site-header {
  background: var(--color-bg);
  border-bottom: 2px solid var(--color-primary);
  position: sticky;
  top: 0;
  z-index: 100;
}

.container {
  max-width: var(--max-width);
  margin: 0 auto;
  padding: 0 24px;
}

Use Sass/SCSS for complex projects — partials for each component, variables for the design token system, mixins for responsive breakpoints. The compiled output should be production-optimized: minified, autoprefixed, with unused rules purged.

This is where your static HTML/CSS becomes a real WordPress theme. Create the mandatory theme file structure: style.css (with theme headers), index.php, functions.php, and template parts. At minimum, you also need: header.php, footer.php, single.php, page.php, archive.php, and 404.php.

The functions.php file is where theme support, widget areas, menus, and scripts are registered:

function mytheme_setup() {
    add_theme_support( 'title-tag' );
    add_theme_support( 'post-thumbnails' );
    add_theme_support( 'html5', ['search-form', 'gallery', 'caption'] );
    register_nav_menus([
        'primary' => __( 'Primary Menu', 'mytheme' ),
        'footer'  => __( 'Footer Menu', 'mytheme' ),
    ]);
}
add_action( 'after_setup_theme', 'mytheme_setup' );

function mytheme_scripts() {
    wp_enqueue_style( 'mytheme-style', get_stylesheet_uri(), [], '1.0.0' );
    wp_enqueue_script( 'mytheme-main', get_template_directory_uri() . '/assets/js/main.js', [], '1.0.0', true );
}
add_action( 'wp_enqueue_scripts', 'mytheme_scripts' );

Modern WordPress development requires thinking about how PSD components become Gutenberg blocks. Not every section needs to be a custom block — WordPress’s core blocks handle many common patterns. But unique design components that content editors need to add to pages should be implemented as custom blocks.

For most PSD-to-WordPress projects, I use the Advanced Custom Fields (ACF) Blocks API for custom block development. It allows building blocks with PHP and familiar ACF field groups rather than learning the full React/JSX Block API — which is overkill for most conversion projects. For projects requiring full custom block architecture, see my Gutenberg block development guide.

Register custom ACF blocks in functions.php, then create block templates in a /blocks/ directory. Each block template is a PHP file that outputs the block’s HTML using ACF field values — giving content editors full control over the component’s content while locking down its structure and styling.

After reviewing dozens of PSD-to-WordPress projects done by junior developers, these are the most common and costly mistakes:

• Using pixel units for all sizing: Use rem for font sizes and spacing. Pixel-based layouts break user accessibility settings and responsive scaling.
• Hardcoding text content: Every user-facing string should be output through WordPress functions (the_title(), the_content(), custom fields) — never hardcoded in template files.
• Ignoring the mobile design: If the PSD only shows desktop, you must design the mobile experience yourself. This requires judgment, not just media queries.
• Skipping accessibility: Alt text on images, aria-labels on icon buttons, keyboard-navigable menus, and sufficient color contrast are not optional.
• Not using child themes for customization: If building on top of any existing theme framework, always use a child theme. Direct parent theme edits are lost on updates.
• Missing WordPress coding standards: Unescaped output, direct database queries, non-prefixed function names — these create security vulnerabilities and conflicts.