Guide
WordPress Block Theme Explained for Lovable Users
A WordPress block theme is a folder of HTML files, a theme.json design-token file and a set of patterns. The HTML files hold block markup, which is plain HTML with comment tags that tell WordPress which block is which. If you came from Lovable, the mapping is close: templates are your route layouts, template parts are your header and footer components, patterns are your page sections, and theme.json is your Tailwind config. Everything is edited in the browser under Appearance → Editor, not in code.
What a block theme actually is
A block theme is a theme where every visible part of the site is made of blocks. Blocks are WordPress's building units: heading, paragraph, image, group, columns, buttons, query loop. A block theme stores them as HTML files on disk.
Open one and you see ordinary HTML wrapped in comments. A heading looks like <!-- wp:heading --> followed by an <h2> tag. WordPress reads the comment to know it is a heading block, then renders the HTML. There is no PHP templating to learn for the common cases.
The older style, now called a classic theme, used PHP files like header.php and single.php plus a Customizer panel. Block themes replace both with HTML templates and the Site Editor. A theme is a block theme if it ships a templates/ folder and a theme.json file.
The four pieces, in Lovable terms
Four things make up a block theme. Each one has a close equivalent in the React project Lovable gave you.
Nothing here is hidden. You can unzip a block theme and read every file with a text editor.
- templates/ — the HTML files that decide the shape of a page type:
index.html,page.html,single.html,404.html. This is your route layout. A template says "header, then the content, then footer". - parts/ — reusable chunks shared across templates, normally
header.htmlandfooter.html. These are your shared React components. - patterns/ — ready-made block markup you can insert into a page. One pattern per page section is the usual shape. These are the JSX bodies of your Lovable pages.
- theme.json — colors, font families, font sizes, spacing scale, layout widths. This is your
tailwind.configand your CSS variables, in one file. - assets/ — images, fonts and any extra CSS the theme needs, copied into the theme folder.
How theme.json replaces your Tailwind config
In Lovable your design tokens live in the Tailwind config and in CSS variables set by shadcn/ui. A utility class like text-slate-900 points at a value in that config. WordPress does the same job with theme.json.
theme.json declares a palette, font families, font sizes and spacing steps. WordPress turns each entry into a CSS custom property and into a preset class. It also puts them in the editor sidebar, so an editor picks "Primary" from a swatch instead of typing a hex code.
That is the main practical difference. Tailwind classes live on every element; block theme tokens live in one file and are referenced by name. Change a palette value in theme.json and every block using that preset changes with it.
Blocks can still carry one-off styles. Those are written as inline styles in the block markup, so they survive a theme token change. Use them sparingly, for the same reason you would avoid arbitrary values in Tailwind.
Editing a block theme without touching code
The Site Editor is where a block theme is edited. Go to Appearance → Editor in the WordPress admin. You get Navigation, Styles, Pages, Templates and Patterns in the sidebar.
Styles opens the same values theme.json holds: palette, typography, layout. Edits made there are saved to the database, not the file, so the theme files stay as shipped. Templates and Patterns let you edit the HTML files visually.
Pages are separate from templates. A page holds its own content; the template says what surrounds it. Edit a headline on the About page and only that page changes. Edit page.html and every page changes.
- Open Appearance → Editor and pick Styles to change colors and fonts site-wide.
- Pick Templates and open
page.htmlto change the frame around every page. - Pick Patterns → Template parts → Header to edit the header once for the whole site.
- Use Pages to edit the words and images of a single page.
- Click Save and choose which items to save; WordPress lists templates and parts separately.
What a converted Lovable site looks like inside
Our converter outputs a block theme, so the folder follows the structure above. Your Lovable header and footer become template parts. Each page becomes a pattern, and a WordPress page is created on activation that inserts it. The Tailwind type scale, colors and Google Fonts land in theme.json, and images are copied into the theme.
Install it the normal way: Appearance → Themes → Add New → Upload Theme → Activate. The pages are created and the front page is set for you. From there it is an ordinary block theme, editable by anyone who has used WordPress.
The review screen shows the converted theme next to your original site in WordPress Playground, in the browser, before you download anything. For the file-by-file tour of what we generate, see Lovable WordPress theme and the supported features list.
Some things do not become blocks at all. Custom React state, event handlers, API calls, canvas, Lottie and third-party widgets have no block equivalent. They need a plugin or a developer, whichever theme you use.
Where block themes are strict
Block markup is validated. If the HTML inside a block comment does not match what the block expects, WordPress shows a "this block contains unexpected content" warning in the editor. Hand-editing theme HTML in a text editor is possible but easy to break.
Layout is also opinionated. Columns blocks stack on mobile by default. That covers most responsive behaviour but not everything a Tailwind grid can express. Fixed-height cropped boxes and absolutely positioned decorations usually need extra CSS.
Dynamic content comes from the query loop block, not from a data array in your source. Posts, categories and product listings are rendered by WordPress from the database. That is why a blog built as a React array has to become real posts before it looks right.
Finally, per-page titles and descriptions are not a theme feature. They come from an SEO plugin: Yoast, Rank Math or SEOPress. Install one before launch and check Settings → Reading, where "Discourage search engines from indexing this site" must be unchecked.
FAQ
What is the difference between a block theme and a classic theme?
A classic theme uses PHP template files and the Customizer for design settings. A block theme uses HTML files full of block markup, a theme.json file for design tokens, and the Site Editor for all editing. If a theme has a templates folder and a theme.json file, it is a block theme.
Do I need to know PHP to use a block theme?
No. Templates, template parts and patterns are HTML with block comments, and most editing happens visually in Appearance → Editor. PHP is only needed for custom blocks or functionality that no existing block or plugin covers.
Does a block theme replace my Tailwind classes?
Yes, in effect. Colors, font sizes and spacing move into theme.json as named presets, and WordPress turns them into CSS variables and preset classes. One-off values are kept as inline styles on the individual block.
Can I edit the theme files directly instead of using the Site Editor?
You can, since templates and parts are plain HTML files in the theme folder. Be careful, because block markup is validated and a mismatch between the comment and the HTML triggers a block error in the editor. Changes made in the Site Editor are saved to the database and override the files.
Does the IQDesk converter produce a block theme?
Yes. It outputs a WordPress block theme with templates, header and footer template parts, one pattern per page, a theme.json carrying your palette and fonts, and your images copied in. Conversion, review in WordPress Playground and the theme download are free.