How to Make Block Themes Better with Theme JSON

Why theme.json Matters for Modern Development Understanding the Structure of theme.json Schema Declaration Version Specification Settings Configuration Global Styles How to Work with theme.json Using ACF Blocks with theme.json Performance Optimization Techniques Advanced Configuration Examples Best Practices and Common Pitfalls Future-Proofing Your Theme Frequently Asked Questions For years, WordPress theme development meant juggling configuration across multiple files. Whether you’re a seasoned WordPress developer transitioning from classic themes or a newcomer exploring modern WordPress development , understanding theme.json is essential for building performant, maintainable, and user-friendly themes in 2025. 💡 Quick Takeaway: Theme.json consolidates theme configuration into a single JSON file, enabling visual customization through the Site Editor while improving performance and maintainability. It’s the foundation of modern WordPress block theme development.

What is theme.json in WordPress? Theme.json is WordPress’s answer to scattered theme configuration – a single JSON file that centralizes all theme settings, design tokens, and editor features. Instead of hunting through functions.php, style.css, and various PHP hooks, developers now have one declarative source of truth .

Introduced in WordPress 5.8 and continuously enhanced through subsequent releases, theme.json represents a fundamental shift in how we approach theme development. It bridges the gap between developer control and user customization, providing structure without sacrificing flexibility. 🎯 Single Source of Truth All theme configuration in one place – colors, typography, spacing, layout, and more. 🎨 Powers Global Styles Enables visual customization through the Site Editor without touching code. ⚡ Optimized Output Generates only necessary CSS with correct cascade order, eliminating bloat. 🔧 Developer Control Define what users can and cannot change while maintaining design consistency. For agencies and developers working on professional WordPress projects , theme.json provides a standardized approach that improves collaboration, reduces technical debt, and accelerates development timelines.

The shift from traditional theme development to theme.json-powered workflows represents more than a technical change – it’s a paradigm shift that affects developers, designers, and site owners alike. Aspect Before (Traditional Approach) After (With theme.json) Configuration Location Scattered across functions.php, style.css, and custom PHP files Centralized in one theme.json file Design Tokens CSS variables or PHP constants, no standard approach Structured JSON with automatic CSS custom property generation Editor Integration Complex add_theme_support() calls and custom implementations Automatic Global Styles interface with visual controls Performance Often includes unnecessary CSS, specificity conflicts common Lean output with optimized cascade, only needed styles generated User Customization Limited to Customizer or custom options pages Full visual editing through Site Editor with granular control Key Benefits for Different Stakeholders For Developers Version-controlled configuration: JSON format integrates seamlessly with Git workflows Predictable theme behavior: Standardized structure reduces debugging time Reduced custom CSS needs: Built-in utilities handle most styling requirements Easier theme portability: Self-contained configuration simplifies migrations IDE autocompletion support: Schema validation catches errors before deployment For Designers Visual style editing without code: Direct manipulation through Site Editor Consistent design token system: Colors and typography remain uniform across the site Real-time preview of changes: Immediate visual feedback during customization Safe experimentation environment: Test styles without breaking production Export and share configurations: Package design systems for reuse across projects For Site Owners Faster page load times: Optimized CSS output improves Core Web Vitals Easier brand updates: Change colors and fonts site-wide from one location No risk of breaking layouts: Controlled customization prevents accidental damage Professional design consistency: Automatic enforcement of design standards Lower maintenance costs: Reduced need for developer intervention on styling tasks ⚠️ Important Note: While theme.json works with classic themes, it truly shines in Full Site Editing (FSE) block themes. If you’re still maintaining a classic theme, consider migrating to a block theme architecture to unlock the full potential of modern WordPress development.

The theme.json file follows a specific structure with several key components. Understanding each section is crucial for effective theme development and optimization. 1.

Schema Declaration The $schema key enables IDE features like autocompletion and validation, dramatically improving the developer experience: { "$schema": "https://schemas.wp.org/trunk/theme.json", "version": 3 } 💡 Pro Tip: Always include the schema declaration. It provides real-time error checking and documentation directly in your code editor, preventing deployment issues before they happen. 2.

Version Specification The version determines available features and backward compatibility: Version 1 WordPress 5.8+ Basic global styles and settings Version 2 WordPress 5.9+ Block-specific settings, layout presets Version 3 WordPress 6.6+ Custom CSS variables, enhanced inheritance For new projects in 2025, version 3 is recommended to access the latest features and performance optimizations. If you need to support older WordPress installations, start with version 2 and progressively enhance. 3.

Settings Configuration Define your theme’s design system and editor features. This is where you establish the building blocks that power your entire theme: { "settings": { "color": { "palette": [ { "slug": "primary", "color": "#194A9A", "name": "Primary Blue" }, { "slug": "secondary", "color": "#2F62AD", "name": "Secondary Blue" }, { "slug": "accent", "color": "#F59E0B", "name": "Accent Gold" } ], "custom": false, "customGradient": false, "defaultPalette": false }, "typography": { "fontFamilies": [ { "slug": "system", "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif", "name": "System Font" }, { "slug": "heading", "fontFamily": "'Inter', sans-serif", "name": "Heading Font" } ], "fontSizes": [ { "slug": "small", "size": "0.875rem", "name": "Small" }, { "slug": "medium", "size": "1rem", "name": "Medium" }, { "slug": "large", "size": "1.25rem", "name": "Large" }, { "slug": "x-large", "size": "2rem", "name": "Extra Large" } ], "fluid": true }, "spacing": { "units": ["px", "rem", "vh", "vw", "%"], "padding": true, "margin": true, "blockGap": true }, "layout": { "contentSize": "720px", "wideSize": "1200px" } } } 🎨 Design Token Strategy: Notice how we disable custom and customGradient options. This constraint improves performance by reducing CSS output and maintains design consistency by limiting user choices to your curated palette.

Key Settings Categories Color: Define color palettes, enable/disable custom colors, configure gradient options, and set duotone filters for images Typography: Register font families, establish font size scales, enable fluid typography, control text decoration and letter spacing Spacing: Set available units (px, rem, vh, etc.), enable spacing controls for padding, margin, and block gap Layout: Define content width constraints, set wide alignment limits, configure content and wide sizes Border: Control border radius, width, color, and style options available to users For comprehensive SEO optimization , proper layout configuration ensures your content maintains optimal reading widths, which positively impacts user engagement metrics and Core Web Vitals scores. 4. Global Styles Apply default styles across your theme using the styles object.

These become your theme’s base styling that users can override through the Site Editor: { "styles": { "color": { "background": "var(--wp--preset--color--base)", "text": "var(--wp--preset--color--contrast)" }, "typography": { "fontFamily": "var(--wp--preset--font-family--system)", "fontSize": "var(--wp--preset--font-size--medium)", "lineHeight": "1.6" }, "spacing": { "blockGap": "1.5rem", "padding": { "top": "0", "right": "2rem", "bottom": "0", "left": "2rem" } }, "elements": { "link": { "color": { "text": "var(--wp--preset--color--primary)" }, ":hover": { "color": { "text": "var(--wp--preset--color--secondary)" } } }, "heading": { "typography": { "fontWeight": "700", "lineHeight": "1.2" } }, "h1": { "typography": { "fontSize": "var(--wp--preset--font-size--x-large)" } }, "button": { "color": { "background": "var(--wp--preset--color--primary)", "text": "#ffffff" }, "border": { "radius": "8px" }, "spacing": { "padding": { "top": "0.75rem", "right": "1.5rem", "bottom": "0.75rem", "left": "1.5rem" } } } } } } ✅ Global Elements Style links, headings, buttons, and lists site-wide ✅ Pseudo States Define hover, focus, and active states declaratively ✅ Block-Specific Override styles for individual block types Global styles cascade intelligently. Block-specific styles override element styles, which override root styles. This hierarchy gives you precise control while maintaining simplicity.

There are two primary methods for working with theme.json, each with specific use cases and benefits. Understanding when to use each approach will optimize your workflow. Method 1: Visual Customization via Site Editor Perfect for designers, theme authors offering user customization, and rapid prototyping.

This method provides a visual interface without requiring JSON knowledge. Customizing Typography Navigate to Appearance → Editor from your WordPress dashboard Click on Styles in the top toolbar (icon looks like a paint palette) Select Typography from the style options panel Click the settings icon next to Fonts Use the Install Fonts tab to add Google Fonts or upload custom font files Select font variants (regular, italic, bold) and weights you need Apply fonts to different elements (headings, body text, buttons) Customizing Colors Go to Styles → Colors in the Site Editor Click Edit palette to modify existing colors Add custom colors by entering specific hex values Set color relationships (background, text, accents, borders) Preview changes in real-time on your site Save to automatically update theme.json in the background Exporting Your Changes After making visual customizations through the Site Editor: Click the three dots menu (⋮) next to the Save button Select Export to download your complete theme The downloaded zip file contains your updated theme.json with all changes Extract and commit the theme.json file to version control for team collaboration Deploy to production or share with other developers Method 2: Advanced Customization with Code Ideal for developers needing precise control, performance optimization, complex configurations, and integration with build processes. Direct JSON editing provides maximum flexibility.

Performance Optimization Examples Restrict Color Options for Lighter CSS { "settings": { "color": { "custom": false, "customGradient": false, "defaultPalette": false } } } Impact: Reduces generated CSS by ~15KB by limiting color customization options to your defined palette only. Enable Fluid Typography { "settings": { "typography": { "fluid": true, "fontSizes": [ { "slug": "large", "size": "clamp(1.75rem, 1.75rem + 1vw, 2.25rem)", "name": "Large" } ] } } } Impact: Creates responsive typography with a single CSS rule instead of multiple media queries, improving rendering performance and reducing CSS size. Block-Specific Overrides { "settings": { "blocks": { "core/paragraph": { "color": { "palette": [ { "slug": "muted", "color": "#6b7280", "name": "Muted Text" } ] }, "typography": { "fontSizes": [ { "slug": "small", "size": "0.875rem", "name": "Small" } ] } }, "core/heading": { "typography": { "fontWeight": false } } } } } Impact: Provides different options for specific blocks without affecting global settings.

Useful for constraining design choices on a per-block basis. ⚡ Performance Tip: Every disabled feature in theme.json reduces CSS output. For production sites targeting optimal Core Web Vitals scores , disable any features you don’t actively use. This can reduce your stylesheet size by 30-40%.

When to Use Each Method Use Visual Editor When: Prototyping design concepts quickly Non-technical users need customization access Testing color and typography combinations Creating child theme variations You want visual feedback immediately Use Code Editor When: Optimizing for performance metrics Implementing complex configurations Working with version control systems Need block-specific overrides Integrating with build tools

Advanced Custom Fields (ACF) Blocks can inherit your theme.json styles, creating a seamless integration between custom blocks and your theme’s design system. This approach eliminates style inconsistencies and reduces development time. 🎯 Why This Matters: When ACF blocks inherit theme.json settings, users get familiar controls in the block sidebar, custom blocks automatically match your design system, and you write significantly less custom CSS. For agencies managing multiple client sites, this consistency is invaluable.

Enabling Theme Style Support in ACF Blocks Add a block.json file alongside your ACF block template: { "name": "acf/custom-hero", "title": "Custom Hero Block", "description": "A hero section with ACF fields", "category": "design", "icon": "cover-image", "keywords": ["hero", "banner", "acf"], "acf": { "mode": "preview", "renderTemplate": "template.php" }, "supports": { "color": { "background": true, "text": true, "link": true, "gradients": false }, "spacing": { "margin": true, "padding": true, "blockGap": true }, "typography": { "fontSize": true, "lineHeight": true, "fontFamily": true, "fontWeight": false }, "align": ["wide", "full"], "anchor": true } } Benefits of ACF + theme.json Integration ✅ Custom blocks automatically inherit your theme’s color palette ✅ Typography settings apply consistently across ACF blocks ✅ Spacing scales remain uniform throughout the site ✅ Users get familiar controls in the block sidebar ✅ Reduced custom CSS requirements ✅ Faster development with reusable design tokens 💡 Pro Integration Tip: When building custom WordPress solutions with ACF, always start by defining your theme.json design system first. Then configure your ACF blocks to inherit these tokens. This “design system first” approach ensures consistency from day one and prevents style drift as the project grows.

Theme.json isn’t just about organization – it’s a powerful tool for improving site performance. Strategic configuration can dramatically reduce CSS output, improve rendering speed, and boost Core Web Vitals scores. 🚀 Reduce CSS Output { "settings": { "color": { "custom": false, "defaultPalette": false }, "spacing": { "customSpacingSize": false } } } Impact: Disable unnecessary features to minimize generated CSS by ~15-20KB 📐 Set Content Widths { "settings": { "layout": { "contentSize": "720px", "wideSize": "1200px" } } } Impact: Prevent layout shift and optimize image loading for better CLS scores 📱 Use Fluid Typography { "settings": { "typography": { "fluid": { "minViewportWidth": "320px", "maxViewportWidth": "1600px" } } } } Impact: Single clamp() rule instead of multiple media queries saves ~8KB 🎨 Limit Color Variations { "settings": { "color": { "duotone": [], "gradients": [] } } } Impact: Remove unused color features for ~20KB cleaner output Impact on Core Web Vitals Optimization LCP Impact CLS Impact File Size Reduction Disable custom colors -200ms No change ~15KB Set fixed layouts -150ms -0.05 ~5KB Fluid typography -100ms No change ~8KB Remove gradients -50ms No change ~20KB 📊 Real-World Results: Sites implementing these optimizations typically see 30-40% reduction in CSS file size, 200-400ms improvement in LCP, and better mobile performance scores. For comprehensive website speed optimization , theme.json configuration is foundational.

Beyond basic settings, theme.json supports sophisticated configurations for templates, patterns, and custom CSS properties. These advanced features unlock powerful capabilities for theme developers. Custom Templates Registration { "customTemplates": [ { "name": "page-landing", "title": "Landing Page", "postTypes": ["page"] }, { "name": "page-sales", "title": "Sales Page", "postTypes": ["page", "product"] }, { "name": "single-case-study", "title": "Case Study", "postTypes": ["post", "portfolio"] } ] } Template Parts Configuration { "templateParts": [ { "name": "header", "title": "Site Header", "area": "header" }, { "name": "footer", "title": "Site Footer", "area": "footer" }, { "name": "sidebar", "title": "Sidebar", "area": "uncategorized" } ] } Custom CSS Properties (Version 3+) { "version": 3, "settings": { "custom": { "spacing": { "small": "0.5rem", "medium": "1rem", "large": "2rem", "x-large": "4rem" }, "border": { "radius": "0.375rem", "width": "2px" }, "transition": { "duration": "0.3s", "timing": "ease-in-out" } } }, "styles": { "css": "body { --custom-shadow: 0 4px 6px rgba(0,0,0,0.1); }" } } Access custom properties in your CSS using var(--wp--custom--spacing--small) 🔥 Advanced Use Case: Custom properties are perfect for creating design tokens that need to be accessed in both theme.json and custom CSS.

This is particularly powerful when building custom WordPress themes with complex design systems that span multiple contexts.

✅ Do’s Version Control: Always commit theme.json to your repository for team collaboration Use Schema: Include $schema for IDE support and real-time validation Progressive Enhancement: Start simple, add complexity as needed Test Across Versions: Verify compatibility with target WordPress version Document Custom Properties: Comment unusual configurations for maintainability Optimize for Performance: Disable unused features to reduce CSS output Use Semantic Naming: Choose clear, descriptive slugs (primary, secondary, not color1, color2) Leverage Inheritance: Let blocks inherit global styles when possible ❌ Don’ts Don’t Over-Configure: Avoid setting every possible option unnecessarily Don’t Ignore Validation: Fix JSON syntax errors immediately before deployment Don’t Mix Versions: Keep version consistent with WordPress requirements Don’t Duplicate Styles: Avoid redundant declarations that bloat CSS Don’t Forget Mobile: Test responsive behavior thoroughly on devices Don’t Skip Documentation: Document complex configurations for future maintainers Don’t Override Everything: Respect user customization needs and preferences Don’t Neglect Backwards Compatibility: Consider fallbacks for older versions Common Issues and Solutions 🐛 Styles Not Applying Problem: Changes to theme.json don’t appear on the frontend. Solution: Clear all caches (browser, WordPress, CDN), verify JSON syntax with a validator, check WordPress version compatibility, and ensure no conflicting CSS with higher specificity. 🐛 Site Editor Not Loading Problem: Site Editor shows errors or fails to load completely. Solution: Validate JSON syntax using JSONLint or VS Code, check for missing required fields like version, verify theme support declaration in functions.php, temporarily revert to default theme.json to isolate the issue. 🐛 Custom Blocks Not Inheriting Styles Problem: ACF or custom blocks don’t use theme styles from theme.json.

Solution: Add proper supports declaration in block.json, ensure blocks use theme CSS variables (var(–wp–preset–color–primary)), verify block registration includes apiVersion 2 or higher, check that theme has FSE support enabled. 🐛 Performance Degradation Problem: Site loads slowly after implementing theme.json. Solution: Disable unused features (custom colors, gradients, duotones), optimize color palette to essential colors only, reduce custom properties to what’s actually used, implement asset loading optimization strategies.

WordPress theme development continues to evolve rapidly. Building themes with longevity requires staying current with theme.json specifications and planning for future enhancements. 📅 Track WordPress Updates Monitor WordPress development for new theme.json features. Each major release typically introduces enhancements to the specification. 🔄 Progressive Enhancement Structure your theme.json to gracefully handle newer features while maintaining backwards compatibility. 🧪 Test in Staging Always test theme.json changes in staging before production, especially when updating version numbers. 📚 Follow Best Practices Stay updated with WordPress coding standards and theme.json documentation.

Join developer communities. Migration Path for Classic Themes Start Small: Create a basic theme.json with essential settings (colors, fonts, spacing) Map Existing Styles: Convert CSS variables and PHP constants to theme.json properties Enable Gradually: Add block support incrementally, testing thoroughly after each addition Test Thoroughly: Verify all functionality remains intact across different page templates Optimize: Remove redundant PHP configurations once theme.json equivalents are working Document: Update theme documentation for users explaining new customization options 🚀 Migration Success Tip: When migrating classic themes to block themes with theme.json, consider working with experienced WordPress development professionals who specialize in modern theme architecture. A well-planned migration prevents technical debt and unlocks powerful new capabilities.