TL;DR
- Theme switches break because the previous theme had been carrying things nobody had cataloged: theme-bundled shortcodes, widget areas, customizer CSS, menu locations, and page-builder bundles. The new theme cannot warn you about any of it.
- Six places tend to break across a switch — homepage layout, shortcodes, widgets and sidebars, menu locations, custom CSS, and WooCommerce template hooks. Read all six before activation.
- The four-step workflow: inventory what the current theme is carrying, pull the target theme’s documentation, feed both to an AI chat with a tight prompt asking for a six-section verdict, build a manual punch list from the verdict.
- Three traps to avoid: skipping the staging copy, trusting a vendor compatible badge in place of comparison work, and treating theme-bundled page-builder content as something that will transfer.
- Thirty minutes of pre-switch audit replaces three days of post-switch firefighting — pick the one you would rather spend.
A small-business owner I know nearly switched themes on a Tuesday afternoon. The new theme demo looked perfect. The activation button was sitting right there. The only thing between her and a three-day rebuild was the unsaved coffee meeting that pulled her away from her laptop.
By Thursday morning her staging copy had told the rest of the story. The theme she had been about to activate could not render the shortcodes her old theme had quietly registered. Three sidebars would have emptied themselves on the first refresh. Twelve hundred lines of customizer CSS would have lived inside an unrendered tab.
Theme switches break for predictable reasons. The reasons are visible in advance if you go looking. AI just makes the looking fast enough that you actually do it.
This post is about a thirty-minute audit you run before you click activate. The audit asks one question, in six places: what does the new theme not know how to render?
Why does a theme switch go wrong on a live site?
The Tuesday-afternoon owner had run her site for three years on the same classic theme. She had never thought about it. The theme came with a contact form widget and a testimonial slider. It also bundled two custom widgets she had never heard of. And a customizer panel where her front-end designer had dropped twelve hundred lines of CSS over time.
She had also never opened the wp-admin menu in the theme settings. Two custom post types fired tracking events through her tag manager. She had no idea any of this was attached to the theme.
When she found the new theme she liked, she searched the vendor’s site for “is it compatible.” The vendor said yes. She almost trusted that.
Most theme switches go sideways for the same reason. The owner did not catalog what the current theme was secretly carrying. The new theme could not have warned her, because it does not know what was in the previous one’s basement.
Reading the house-inspection report before you sign on the new roof is the closest analogy. The roof is fine. The roof was never the question. The question is what the house already has, and what the new roof will not understand.
A pre-switch audit lists what is in the basement. Then it asks the new roof which of those things it does not know how to handle.
What does the audit actually check?
Six places tend to break when WordPress themes change hands. The list is older than the AI workflow that reads it — the workflow just makes the reading fast.
The first is homepage layout. A homepage built inside the previous theme’s customizer or page builder will not survive the switch. The blocks that defined the layout were theme-bundled, and the new theme does not know to load them.
The second is shortcodes. A theme can register its own shortcodes — a vendor button, a styled accordion, a testimonial card. When you switch themes, those shortcodes stop rendering. Posts that used them now display the raw bracketed text on the page.
The third is widgets and sidebars. Widget areas are theme-defined. When you switch, widgets fall into an Inactive Widgets pile. They wait for a new home that may or may not have a slot in the same shape.
The fourth is menu locations. Menus survive the switch, but their assignment to specific theme regions does not. The new theme may have three menu slots where the old had five.
The fifth is custom CSS. CSS pasted into a theme settings panel goes with the theme. CSS pasted into the WordPress Customizer’s Additional CSS section is portable. Older sites mix both, and the audit has to find the theme-bundled half.
The sixth is WooCommerce template hooks, if the site sells anything. Themes inject hooks at specific spots in the product page. Switching themes can move those hooks without warning.
Read those six places before you click activate, and the surprise rate drops to nearly zero.
How do you actually run the audit?
The workflow is four steps. The reader does not need to write code.
Step 1. Inventory what the current theme is carrying. From wp-admin: open Appearance > Widgets and copy the list of every active widget per area. Open Appearance > Customize > Additional CSS and copy the contents into a text file. Search your post and page content for any text matching [shortcode_name]-style brackets. Note your menu locations and which menu lives in each.
Step 2. Pull the target theme’s documentation. Open the new theme’s documentation page. Copy its widget areas, its shortcode list, its supported menu locations, its custom-CSS handling notes, and its WooCommerce hook list if the site sells anything. Save all of this in the same text file as Step 1.
Step 3. Feed both halves to an AI chat with one prompt.
You are auditing the risk of a WordPress theme switch.
Below is the current theme's inventory and the target theme's
documentation. The inventory covers widgets, custom CSS, shortcodes
in posts, menu locations, and WooCommerce hook touches.
Return a six-section verdict:
1. Homepage: what will survive, what needs a manual rebuild.
2. Shortcodes: which still render, which will display as raw text.
3. Widgets and sidebars: which area maps cleanly, which fall into
Inactive Widgets.
4. Menus: which assignments survive, which need re-mapping.
5. Custom CSS: which lines are portable, which are theme-bundled.
6. WooCommerce: which hooks remain, which move position or vanish.
Current theme: <name>
Target theme: <name>
Inventory: <paste>
Target documentation: <paste>
Step 4. Read the verdict and build the punch list. For each line that says needs a manual rebuild, write the edit you will make on staging. The AI does the diagnosis. You do the fixing. The list keeps the fix-work bounded.
The audit takes about thirty minutes. The post-switch firefighting it replaces takes anywhere from a Friday afternoon to a long weekend.
What can go wrong even with the workflow?
Three traps catch operators who run the audit on the live site instead of staging.
Trap 1: skipping the staging copy. A staging copy is a private mirror of the live site that nobody visits. Every reputable WordPress host offers one in the dashboard. Run the new theme there first. The audit catches the visible breaks. Staging catches the surprises that only show up when something runs.
Trap 2: trusting a “compatible” badge on the theme page. Theme vendors say compatible to mean their theme renders correctly with current WordPress core. Compatible does not promise that the previous theme’s customizations carry forward. The vendor cannot promise that. They have never seen the previous theme’s basement.
Trap 3: ignoring page-builder dependencies. Layouts built with theme-bundled builders — Divi Builder, Avada Builder, Elementor Pro — live inside the theme. They do not transfer. The audit must check whether the current site has any builder-locked content. If it does, that content is rebuild work, not migration work.
The honest disconfirming voice is WordPress.com’s own classic-to-block migration guide. Even after a clean automated migration, the guide names manual testing as the next step. Test on multiple devices. Test on multiple browsers. The audit is the desk work. The staging visit is the field work. Both belong in the plan.
How do you turn the audit into a thirty-minute pre-switch habit?
A pre-switch audit is two artifacts. One is the prompt template above, saved once and reused for every theme switch the site will ever do. The other is the inventory file you build each time, listing what the current theme has been carrying. A longer-term variant is the child-theme override plan workflow that keeps customizations outside the parent theme entirely.
Pick the candidate theme you have been considering. Run the audit on it now, against a copy of your current site’s inventory. See what surfaces. Maybe it is clean and you can switch. Maybe the page-builder report is heavy and the switch becomes a rebuild project. Either answer is better than the surprise on Tuesday afternoon.
Thirty minutes of audit replaces three days of firefighting. The math is the same as every pre-flight check. The companion verifying your WordPress backups workflow is the other pre-flight you run before activating a new theme.
Theme switches do not break because the new theme is bad. They break because the previous theme had been carrying things nobody had cataloged. The AI audit is a catalog tool. It surfaces what was already there. You do not need to be a developer to run it. You need to know which six places to read, and the patience to read them before you click activate.
Other questions worth answering
What’s special about classic-to-block WordPress migrations?
Five extra reconstruction areas show up in classic-to-block migrations. WordPress.com’s 2025 migration guide names them: widgets, menu styling, homepage design, Customizer settings, and classic content. Even a clean automated migration leaves all five for manual rebuild.
The body’s six audit places still apply, but the rebuild side gets heavier. Plan an extra day for it.
What WooCommerce-specific tests belong on staging?
Three end-to-end checks belong on staging before activation. WooCommerce template hooks fire at specific spots — single product, cart, checkout. A redesign can break the styling around them. Jetpack’s 2026 theme-switch guide names them as the sixth risk area.
Three staging checks:
- Walk a real order through coupon and payment.
- Compare the product page against three live listings.
- Spot-check the cart on mobile.
How do you handle a WordPress redesign without staging access?
Three options exist when staging is off the table. Ask the managed host first — most include it for free. If not, WPBeginner’s 2025 checklist names maintenance mode as the fallback.
Put the site in maintenance mode, switch themes, then walk the six audit places. WordPress.com’s 2025 guidance adds multi-device and multi-browser testing as verification.
What happens to tracking codes during a WordPress redesign?
WPBeginner’s 2025 WordPress pre-switch checklist names tracking-code preservation as a separate failure point alongside the body’s six. Analytics, ad pixels, and tag-manager snippets pasted into theme files travel with the theme. Move them out before activation.
The safest home in 2026 is a tracking-code plugin or the tag manager container itself — not the new theme’s footer.php. The audit verdict then captures whether tracking survives.
How should you audit your next theme switch before activating?
Have a theme switch on your calendar and feel the unsaved-coffee-meeting kind of nerves? You can contact me here. Tell me your current theme, the target theme, and a sentence or two about what the site does. I will walk through the six places with you and tell you what I see. There is no pitch, no upsell, and the conversation is free.