Customizing Typography

1. Navigate to Appearance → Editor from your WordPress dashboard
2. Click on Styles in the top toolbar (icon looks like a paint palette)
3. Select Typography from the style options panel
4. Click the settings icon next to Fonts
5. Use the Install Fonts tab to add Google Fonts or upload custom font files
6. Select font variants (regular, italic, bold) and weights you need
7. Apply fonts to different elements (headings, body text, buttons)

Customizing Colors

1. Go to Styles → Colors in the Site Editor
2. Click Edit palette to modify existing colors
3. Add custom colors by entering specific hex values
4. Set color relationships (background, text, accents, borders)
5. Preview changes in real-time on your site
6. Save to automatically update theme.json in the background

Exporting Your Changes

After making visual customizations through the Site Editor:

1. Click the three dots menu (⋮) next to the Save button
2. Select Export to download your complete theme
3. The downloaded zip file contains your updated theme.json with all changes
4. Extract and commit the theme.json file to version control for team collaboration
5. Deploy to production or share with other developers

Performance Optimization Examples

{
  "settings": {
    "color": {
      "custom": false,
      "customGradient": false,
      "defaultPalette": false
    }
  }
}

{
  "settings": {
    "typography": {
      "fluid": true,
      "fontSizes": [
        {
          "slug": "large",
          "size": "clamp(1.75rem, 1.75rem + 1vw, 2.25rem)",
          "name": "Large"
        }
      ]
    }
  }
}

{
  "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
        }
      }
    }
  }
}

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

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

✅ 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

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.

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.

What version of WordPress supports theme.json?

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.

Can theme.json work with classic themes?

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.

How do I add custom fonts to theme.json?

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.

Does theme.json improve website performance?

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

Can I use theme.json with page builders?

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.

How do I validate my theme.json file?

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.

What happens if theme.json has errors?

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.

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