SWELL holds an overwhelming share of Japan's WordPress market, but as WordPress core evolves toward FSE (Full Site Editing), more creators are considering a move to block themes. This article explains the concrete steps for migrating from SWELL to a block theme, how to use theme.json, and the points to watch out for during migration.
What Is FSE (Full Site Editing)?
FSE is a mechanism introduced in WordPress 5.9 and later for editing the entire site in the block editor. With traditional classic themes, site layout was controlled by PHP templates and the Customizer, but with FSE-ready block themes you can visually edit every part of the site — header, footer, sidebar, archive listings, and more — in the block editor.
At the core of a block theme is the theme.json file. It centrally manages design tokens such as colors, fonts, spacing, and layout widths in JSON format, applying them automatically to both the editor and the front end. Because you can control most of the design without writing PHP, the barrier to theme development drops dramatically.
Cases Where You Should Consider Migrating from SWELL
Not every SWELL user should migrate to a block theme. It is worth considering migration if you fall into the following cases.
- You want complete control over your site's design: If you need a custom layout or design that the SWELL Customizer cannot achieve, a block theme offers more freedom.
- You want to optimize performance to the limit: Being feature-rich, SWELL also loads CSS/JS for features you don't use. A block theme implements only the features you need, significantly reducing page size.
- You want to follow WordPress core's roadmap: FSE is the very direction of WordPress's future. Migrating early lets you benefit directly from upcoming updates.
- You want to cut the theme's annual cost: Developing your own block theme eliminates licensing fees. However, this is a trade-off against development and maintenance costs.
Conversely, on sites that heavily use SWELL's decorative features (step blocks, accordions, banner links, etc.), the migration effort becomes enormous, so decide carefully.
Concrete Migration Steps
Migrate in stages. Rather than switching all at once, migrate safely with the following steps.
Stage 1 is a content inventory. Identify pages that use SWELL's proprietary blocks (steps, tabs, accordions, rating stars, etc.). By combining WP-CLI's wp post list with grep, you can list posts that contain SWELL-specific block markup (swell/step, swell/tab, etc.). Since this content requires manual conversion during migration, it becomes the basis for estimating effort.
Stage 2 is designing theme.json. Port the values you set in SWELL's Customizer into theme.json. Define the main color, sub color, text color, and background color in settings.color.palette, and define font sizes in settings.typography.fontSizes. Refer to SWELL's defaults while accurately reflecting your site's current customized values.
Stage 3 is creating templates. Create HTML templates such as index.html, single.html, page.html, archive.html, and 404.html in the block theme's /templates directory. Build them with block markup so they reproduce SWELL's layout (presence of a sidebar, article width, spacing). Also create template parts (/parts/header.html, /parts/footer.html).
Key Points for Using theme.json
theme.json is the heart of a block theme. Here are the points for using it effectively.
Define the content width and wide width in settings.layout. SWELL's default content width is around 900px, but in a block theme you set it explicitly as contentSize and wideSize. This way, the editor also previews at the same width as the front end.
In settings.spacing, define a spacing scale. Using spacingScale to set t-shirt-sizing (S/M/L/XL) spacing values makes them appear as choices in the editor's block-gap dropdown. Be sure to configure this to unify the spacing rules across your entire site.
In styles.blocks, you can define default styles for individual blocks. For example, set the font size and margins of the core/heading block, or the border-radius and hover color of the core/button block. This setting is invaluable when reproducing SWELL's heading design.
Pitfalls and Risk Mitigation During Migration
Here is a summary of the most important points to watch when migrating from SWELL.
- Data loss in SWELL's proprietary blocks: SWELL's proprietary blocks (steps, tabs, FAQ, etc.) remain as HTML comments when switching themes, but their display breaks. You need to replace these blocks with combinations of core blocks before migrating.
- Shortcode compatibility: SWELL's shortcodes (ad tags, blog cards, etc.) stop working after switching themes. List where they are used in advance and prepare alternatives before migrating.
- Porting custom CSS: CSS added in SWELL's Customizer is theme-specific, so port it into the destination theme's style.css or theme.json custom settings.
- Carrying over SEO settings: SWELL's SEO settings (meta descriptions, OGP settings, etc.) are managed by SWELL, so migrate them to an SEO plugin (Yoast, SEO SIMPLE PACK, etc.) before migrating.
As a risk-mitigation measure, always perform migration work in a staging environment. Create a clone of production with Docker or Local by Flywheel, try the migration there, and then apply it to production. A complete backup (files + database) before migration is also essential.
Migrating from SWELL to a block theme is not easy, but it is an unavoidable path to making the most of FSE's potential. The realistic approach is to first try a block theme on a new project, accumulate know-how, and then tackle migrating existing sites.