I’ve struggled in numerous ways to understand, to get to know, to be kind to the WordPress Full Site editor experience, but it has frustrated me at every turn. Can I please just see what code I’m changing, please? Oh, there’s a Create Block Theme plugin, that should fix all of my problems! Wait — oh god, why did saving my styles overwrite the color palette I so lovingly input into the Global Styles UI. A synced pattern can be saved into php, but an unsynced pattern can only be exported to json and downloaded? And so on…

Learning from my mistakes, here is a workflow I have landed on that is, so far, making a Block Theme actually enjoyable:

1. Create a fresh new theme with Create Block Theme

First step is to add the Create Block Theme plugin. Click on Appearance -> Create Block Theme in the sidebar, and create a new theme. Input the name, etc. and activate your new theme.

2. Initialize a git repository and watch for changes

Next, git init your new theme folder. This is the best way to understand what’s happening when creating your theme. Always commit your hand-coded changes before saving your theme through Create Block Theme. Always commit the new code generated by Create Block Theme. I use lazygit to have a nice UI to look at and see new changes appear.

3. Disable default color palette in theme.json

I want my code to be the single source of truth, not the database. Originally, I tried making my own color palette in Global Styles, but when I saved the theme, it got overwritten. To avoid this, in theme.json disable the default color palette:

"settings": {
    ...
    "color": {
        "defaultPalette": false
    }
}

4. Add and save your custom color palette

Now with the default palette disabled, head over to Global Styles in the Editor and add your colors. Afterwards, click the Create Block Theme wrench icon in the top-right toolbar and click Save Changes To Theme. As a safety precaution, I only leave checked what I know I’m trying to save. In this case, have ‘Save Style Changes’ selected. Click ‘Save Changes’ and look at your git diff for theme.json. You should see your color palette appear. Commit these changes.

5. Understand what just happened – code vs. database

The preceeding steps should paint a good overview for the workflow. Your theme.json and hardcoded template files are the main source of truth, until they aren’t. This happens when an update is made to the database. So now WordPress loads your theme.json configuration and slaps database changes on top of it. Once you save these changes with Create Block Theme, your code is in charge once again.

It is good to know that if you make changes to something like Global Styles and want to revert back to what is in theme.json, these is a ‘Reset Styles’ button in the Styles sidebar, as well as ‘Reset’ for templates. It is disabled unless a change has been made from the code.

6. Do the same for the rest of the Global Styles

Add fonts, set body and link text defaults, update layout width defaults, and update global styles for blocks. Save these with Create Block Theme and commit the code changes.

7. Do the same for Templates and Patterns

I use patterns for things like button variations. I tried overwriting the default style variations for the core button, or registering my own custom style variations and that just didn’t work like I wanted it to, so this is what I landed on.

Create a synced pattern. Why not unsynced? Because there isn’t the option to save it, for reasons unknown. So ok, let’s make a button pattern – add a buttons block and change the background color. Add a custom class name. Save editor changes and from the Create Block Theme wrench, make sure to check Save Synced Patterns and save changes. Check your git diff and wow! – we have a php file!

But, it’s mostly WordPress template markup. Maybe I can edit it from here, at least add custom classes? Nope, that causes an error. Ok, good thing I added that class before saving. Let me change something in the Editor… oh, it’s unsynced and no longer editable? Why would that be…? Guess I’ll duplicate it, make changes, save it, and delete the old one. Ok. Sure, that’s it.

Templates work like patterns but without the syncing/unsyncing stuff. Make and save changes to a template, save the changes with Create Block Theme, and voila! a real life html file.