Modern WordPress block development and Full Site Editing with theme.json, block themes, and custom blocks for WordPress 6.7+

WordPress Block Editor & Full Site Editing Overview Full Site Editing (FSE) is production ready (since WP 6.2) and treats everything as blocks—headers, footers, templates, not just content. Block themes use HTML templates + theme.json instead of PHP files + style.css. Key Components: theme.json : Centralized colors, typography, spacing, layout HTML Templates : Block based files (index.html, single.html) Template Parts : Reusable components (header.html, footer.html) Block Patterns : Pre designed block layouts Site Editor : Visual template customization When to Use: ✅ New themes, consistent design systems, non technical user customization ❌ Complex server logic, team unfamiliar with blocks, heavy PHP dependencies Full Site Editing Architecture Block Themes vs Classic Themes Block Themes Classic Themes HTML files with blocks PHP files with template tags theme.json + CSS functions.php + style.css Site Editor (visual) Customizer (settings) User edits templates Limited customization Site Editor Capabilities Template editing (pages, posts, archives) Template parts (header/footer variations) Global styles (colors, typography site wide) Pattern library (save/reuse block compositions) Navigation menus (block based) Style variations (alternate design presets) theme.json Configuration theme.json v3 (WP 6.7) provides centralized design control. WordPress auto generates CSS custom properties. Production Example CSS Custom Properties Auto Generated Colors: var( wp preset color primary) Fonts: var( wp preset font family system) Sizes: var( wp preset font size large) Spacing: var( wp preset spacing 50) Fluid Typography Font sizes with fluid: { min, max } auto scale using clamp() : Block Theme Architecture Required Files style.css Metadata HTML Template Structure templates/single.html: templates/index.html (with query loop): Template Parts parts/header.html: Block Patterns patterns/hero.php: Register pattern categories: Custom Block Development block.json Metadata (Block API v3) blocks/testimonial/block.json: Attribute Sources Different ways to extract data from HTML: Server Side Rendering (render.php) blocks/testimonial/render.php: Client Side Rendering (React) blocks/testimonial/index.js: Block Registration functions.php: InspectorControls (Settings Sidebar) Common controls for block settings: Block Supports Enable WordPress features: Custom Post Types with Block Editor Template Locking false : No restrictions 'all' : Cannot modify structure 'insert' : Cannot add/remove, can reorder 'contentOnly' : Content edits only Register in theme.json Development Workflow @wordpress/scripts package.json: Commands: wp env Setup .wp env.json: Usage: Migration from Classic Themes Template Tag to Block Mapping Classic Block Equivalent the title() <! wp:post title / the content() <! wp:post content / the post thumbnail() <! wp:post featured image / the date() <! wp:post date / wp nav menu() <! wp:navigation / get header() <! wp:template part {"slug":"header"} / get footer() <! wp:template part {"slug":"footer"} / get sidebar() <! wp:template part {"slug":"sidebar"} / Migration Steps 1. Extract design tokens from style.css → theme.json 2. Convert PHP templates to HTML block templates 3. Add block support in functions.php: 4. Test thoroughly with real content Block Validation WordPress validates block markup against registered block definitions. Invalid blocks show errors in the editor: Common validation errors: Attribute type mismatch (string vs number) Missing required attributes Incorrect HTML structure Changed attribute names Fix validation errors: Performance & Best Practices Performance ✅ Use server side rendering (render.php) when possible ✅ Leverage block supports (reduces custom CSS) ✅ Disable unused features: "defaultPalette": false ✅ Use CSS custom properties for consistency ❌ Avoid client side rendering for static content ❌ Don't override core blocks with !important Accessibility ✅ Semantic HTML ( <header , <main , <footer ) ✅ Keyboard navigation for custom blocks ✅ WCAG AA color contrast (4.5:1 minimum) ✅ Alt text for all images ❌ Don't assume FSE = accessible (test required) Anti Patterns ❌ Mixing classic and block approaches ❌ Hardcoding colors (use CSS variables) ❌ Reinventing block supports ❌ Skipping accessibility testing ❌ Using get header() in HTML templates Related Skills wordpress plugin fundamentals : Hook system, CPTs react : Block editor components typescript : Type safe block development php security : Sanitize block attributes Key Reminders 1. theme.json is mandatory for block themes 2. HTML templates replace PHP in FSE 3. Server side rendering often better than client side 4. Block supports reduce custom code 5. Accessibility requires testing Red Flags More than 5 CSS files → Use theme.json PHP tags in HTML templates → Use blocks Client rendering for static content → Use render.php No keyboard testing → Accessibility issues Hardcoded values → Use CSS custom properties WordPress: 6.7+ PHP: 8.1+ Tools: @wordpress/scripts, wp env

wordpress-block-editor-fse