Overview

A block theme builds every template out of blocks and configures its design in a single theme.json file, so the site owner can edit the whole site — header, footer, templates and styles — visually in the Site Editor.

The minimum block theme

gdc-blocks/
├── style.css            Theme header (same as a classic theme)
├── theme.json           Design settings and styles
├── templates/
│   └── index.html       Required: the fallback template
└── parts/
    ├── header.html
    └── footer.html

There is no index.php, no header.php, and usually only a tiny functions.php. WordPress recognises the theme as a block theme because templates/index.html exists.

theme.json

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "settings": {
        "appearanceTools": true,
        "layout": {
            "contentSize": "720px",
            "wideSize": "1200px"
        },
        "color": {
            "defaultPalette": false,
            "palette": [
                { "slug": "base",     "name": "Base",     "color": "#ffffff" },
                { "slug": "contrast", "name": "Contrast", "color": "#1e293b" },
                { "slug": "accent",   "name": "Accent",   "color": "#6c63ff" }
            ]
        },
        "typography": {
            "fluid": true,
            "fontSizes": [
                { "slug": "small",  "name": "Small",  "size": "0.9rem" },
                { "slug": "medium", "name": "Medium", "size": "1.125rem" },
                { "slug": "large",  "name": "Large",  "size": "2rem", "fluid": { "min": "1.5rem", "max": "2.5rem" } }
            ]
        },
        "spacing": {
            "units": [ "px", "rem", "%", "vw" ]
        }
    },
    "styles": {
        "color": {
            "background": "var(--wp--preset--color--base)",
            "text": "var(--wp--preset--color--contrast)"
        },
        "typography": {
            "fontSize": "var(--wp--preset--font-size--medium)",
            "lineHeight": "1.7"
        },
        "elements": {
            "link": {
                "color": { "text": "var(--wp--preset--color--accent)" }
            },
            "h1": {
                "typography": { "fontSize": "var(--wp--preset--font-size--large)" }
            }
        }
    },
    "templateParts": [
        { "name": "header", "title": "Header", "area": "header" },
        { "name": "footer", "title": "Footer", "area": "footer" }
    ]
}

settings versus styles

Every palette colour becomes a CSS custom property: accent becomes --wp--preset--color--accent. Use those variables in any extra CSS, and the whole site follows when the owner changes a colour in Styles.

Classic or block?

Tip: Classic themes can adopt theme.json too. Adding one to GDC Starter gives you the editor colour palette and font sizes without converting a single template.

Practice

• Create the gdc-blocks folder with style.css, theme.json and an empty templates/index.html, and activate it.
• Change the accent colour in theme.json and watch links update.
• Open Appearance → Editor → Styles and change the colour there — then read why it overrides your file (user changes are saved in the database).