How to Make Block Themes Better with Theme JSON

Why AI search visibility wins cases

What How to Make Block Themes Better with Theme JSON covers

Dashboards & results

Blog — answered

Top 5 Generative Engine Optimization Agencies for Law Firms How to Make Block Themes Better with Theme JSON Law Firm Marketing Strategies for Lawyers in 2026 AI Overview & AI Mode Optimization (AIO) for Law Firms AI Visibility Optimization Checklist for Law Firms Family law digital marketing Turning Semantic Insights Into Video Search Advantage llms.txt – in Legal Practice: A Game Changer for Law Firms Evolution of Digital Marketing Strategies for Law Firms in 2025 FindLaw’s PPC Threshold: Impact on Small Law Firms GEO (Generative Engine Optimization) Audit for Law Firms Google Ads for Law Firms: Costs, Strategies, and ROI in 2025 Google Ads vs. Facebook Ads: Best ROI for Law Firms in 2025? Law Firm Content Marketing Strategies for 2025 – Intercore Technologies The New Playbook for Rankings and Citations Child custody lawyers digital marketing agency Law Firm Lead Generation: How to Grow Your Practice in 2025 PPC and LSA For Lawyers – Paid Search Advertising in 2025 Most Effective Advertising Strategies for Law Firms in 2025 PPC, LSA, and SEO – A Combined Approach for Law Firms Semantic SEO With AI Vectors: Boosting AI Search Rankings SEO Audit vs.

GEO Audit for Law Firms – Intercore Technologies TOFU AI, MOFU AI, and BOFU AI Law Firm Sales Funnels SEO for Generative AI Engines – Boost Visibility – Intercore Technologies Technical SEO for AI Visibility (Google AI & ChatGPT) Top Ways to Adapt Your Law Firm Website for LLM Traffic Top 4 Workers’ Comp Lawyer Marketing Agencies in 2026 How to Become an Authority That Gets Cited in Google AI Overviews Advanced Prompt Engineering Techniques for 2026 How Often Should I Publish Content to Improve AI Visibility? LLM Context Windows A Comparison October 14, 2025 Scott Wiseman For years, WordPress theme development meant juggling configuration across multiple files. Settings lived in functions.php, styles were hardcoded in CSS, and editor support required complex PHP hooks.

Theme.json changed everything by bringing these scattered pieces into one structured file. Whether How to Make Block Themes Better with Theme JSON: Complete Guide for 2025 Transform your WordPress theme development with theme.json – the single configuration file that brings order to chaos, centralizes design tokens, and powers the modern editing experience. Table of Contents What is theme.json in WordPress?

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.

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. Why theme.json Matters for Modern Development 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. Understanding the Structure of theme.json The theme.json file follows a specific structure with several key components.

Understanding each section is crucial for effective theme development and optimization. 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.

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. 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.

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. How to Work with theme.json 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.

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 Using ACF Blocks with theme.json 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.

Performance Optimization Techniques 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.

Advanced Configuration Examples 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. Best Practices and Common Pitfalls ✅ 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.

Future-Proofing Your Theme 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.

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. Frequently Asked Questions What is theme.json in WordPress?

Theme.json is a configuration file that centralizes theme settings and styles in WordPress. It defines global settings, design tokens, and editor features in a single JSON file, replacing scattered PHP configurations and making theme development more maintainable. Introduced in WordPress 5.8, it has become the foundation of modern block theme development.

Theme.json was introduced in WordPress 5.8 with version 1 of the specification. WordPress 5.9 brought version 2 with enhanced features including block-specific settings and layout presets. WordPress 6.6 and later supports version 3 with advanced capabilities like custom CSS variables and enhanced style inheritance.

For new projects in 2025, version 3 is recommended. Yes, theme.json works with both classic and block themes, though it’s technically optional for classic themes. While you can add theme.json to a classic theme to enable Global Styles and centralize configuration, the full power of theme.json is best experienced in Full Site Editing (FSE) block themes where it provides comprehensive control over design tokens and editor features.

You can add custom fonts through two methods: Visual Method: Navigate to Styles > Typography > Fonts in the Site Editor, then use the Install Fonts tab to add Google Fonts or upload custom font files. Code Method: Define fonts directly in theme.json under settings.typography.fontFamilies with appropriate font-face declarations, then reference them using CSS custom properties throughout your theme. Yes, theme.json can significantly improve performance when configured strategically.

By generating only necessary CSS, eliminating redundant styles, and providing optimized cascade order, properly configured theme.json reduces stylesheet size by 30-40%. Disabling unused features like custom colors, gradients, and duotones further reduces file sizes and improves Core Web Vitals scores, particularly LCP (Largest Contentful Paint). Theme.json primarily works with the native WordPress block editor (Gutenberg).

While some page builders may respect certain theme.json settings, full integration varies significantly by builder. Theme.json is best suited for native block development and Full Site Editing themes. If you’re using popular page builders like Elementor or Divi, their proprietary theming systems may override or bypass theme.json configurations.

Use the $schema declaration at the top of your file (https://schemas.wp.org/trunk/theme.json) for real-time validation in code editors with JSON schema support like VS Code. Additionally, online JSON validators like JSONLint can catch syntax errors. WordPress also provides built-in error reporting – the Site Editor will show specific error messages if theme.json contains invalid JSON or missing required fields.

WordPress will fall back to default behavior if theme.json contains syntax errors. The Site Editor may display error messages or fail to load entirely. Minor configuration errors might be silently ignored while critical syntax errors break the interface completely.

Always validate your JSON syntax before deployment and test changes in a development or staging environment. Keep backups of working configurations to quickly revert if issues arise. Transform your WordPress projects with modern development practices and expert guidance from InterCore Technologies. 🎨 Custom Theme Development Block themes built with theme.json best practices ⚡ Performance Optimization Core Web Vitals improvements through theme.json 🔧 ACF Integration Custom blocks that inherit your design system Get Expert WordPress Development 📞 Call us at 213-282-3001 or visit our Marina Del Rey office About InterCore Technologies Since 2002, InterCore Technologies has been a Los Angeles technology staple, pioneering innovative solutions for prestigious clients including The Cochran Firm, Marriott International, and the New York Police Department.

Our expertise in WordPress development, AI-powered marketing, and cutting-edge technology solutions has made us the trusted partner for law firms and enterprises seeking exceptional digital experiences. Specializing in attorney SEO , Generative Engine Optimization (GEO), and modern WordPress development, we deliver results-driven solutions that combine technical excellence with strategic insight. Our team of experts is dedicated to transforming your online presence into a revenue-generating powerhouse, ensuring your business stays ahead of the competition in today’s rapidly evolving digital ecosystem.

Trustpilot 📅 Book Now Free AI Audit × Ready to dominate AI search? Get My Free Audit → 🔒 We respect your privacy.

Ready to turn AI search into signed cases?

Get your free 23-point AI visibility report — delivered in 24 hours. No credit card.