The theme.json file is the central configuration file that controls DigiFlash’s design system, defining colors, typography, spacing, and layout settings available in the Site Editor.
What is theme.json
theme.json is a JSON-formatted configuration file that WordPress block themes use to define their design tokens and editor settings. This file determines what options appear in the Site Editor and sets the default values for your website’s visual appearance.
DigiFlash uses theme.json to provide all the color palettes, font options, spacing scales, and style presets you see when customizing your site through the Site Editor.
Locating theme.json
The theme.json file is located in the root directory of the DigiFlash theme folder. You can access it through:
FTP or File Manager – Navigate to /wp-content/themes/digiflash/theme.json
WordPress Theme File Editor – Go to Appearance → Theme File Editor and select theme.json from the file list
Code Editor – Open your WordPress installation in any code editor and locate the file in the DigiFlash theme directory
The file contains all design system definitions in structured JSON format.
Structure of theme.json
The theme.json file organizes settings into several main sections:
version – Specifies which theme.json schema version DigiFlash uses
settings – Defines available options in the Site Editor, including color palettes, font families, spacing scales, and custom features
styles – Sets default visual styles for elements, blocks, and typography
customTemplates – Registers custom page templates available in the template selector
templateParts – Defines reusable template parts like headers and footers
Each section uses nested objects to organize related settings hierarchically.
Settings Section
The settings section controls what customization options appear in the Site Editor. Key subsections include:
color – Defines color palettes, gradients, duotone filters, and custom color controls
typography – Specifies available font families, font sizes, line heights, and typographic features
spacing – Sets spacing scale values and padding/margin options
layout – Configures content width, wide width, and layout-related settings
border – Controls border radius, width, and style options
shadow – Defines shadow presets like Natural, Deep, Sharp, Outlined, and Crisp
When you add or modify options in the settings section, those changes appear as available choices in the Site Editor interface.
Styles Section
The styles section sets default values for how elements appear on your website. This section includes:
elements – Default styles for HTML elements like links, buttons, headings, and text
blocks – Default styles for specific WordPress blocks like paragraphs, images, and groups
typography – Global font family, size, and line height defaults
color – Default background and text colors for the entire site
spacing – Default padding, margin, and gap values
Values defined in the styles section serve as starting points that users can override through the Site Editor.
Color Palette Definition
Within the settings.color section, DigiFlash defines its color palette using an array of color objects. Each color includes:
slug – Internal identifier used in CSS classes and style variations
color – Hexadecimal color value
name – Human-readable label displayed in the Site Editor
The color palette determines which colors appear in color pickers throughout the Site Editor interface.
Typography Configuration
The settings.typography section defines available font families and sizes. Font families include:
fontFamily – The actual font stack or web font URL
slug – Internal identifier for the font
name – Display name shown in font selectors
fontFace – Optional array defining custom font file locations and weights
Font size presets follow a similar structure, with slugs, sizes, and names defining each available size option.
Spacing Scale
DigiFlash’s spacing scale is defined in settings.spacing.spacingScale. This creates the consistent spacing values (20, 30, 40, 50, 60, 70) available throughout the Site Editor.
The spacing scale ensures visual consistency by limiting spacing options to predefined, harmonious values rather than allowing arbitrary numbers.
Custom Settings
DigiFlash can define custom settings beyond WordPress defaults. These appear in settings.custom and can include:
Theme-specific options – Unique features or controls specific to DigiFlash
Performance settings – Configuration for optimization features
Layout presets – Custom layout configurations
Custom settings extend DigiFlash’s capabilities beyond standard WordPress block theme features.
How Changes Propagate
When you modify settings through the Site Editor, WordPress stores your customizations in the database as user style variations. These database values override the defaults defined in theme.json.
The theme.json file provides the foundation and available options, while the database stores user-specific customizations. This separation allows DigiFlash to update default values without overwriting your custom settings.
Block-Specific Settings
Within the settings section, DigiFlash can define block-specific options using the blocks subsection. This allows different customization options for different block types.
For example, buttons might have specific color options not available to other blocks, or headings might have unique typography controls.
Template Configuration
The customTemplates section registers page templates that appear in the template selector when creating pages. Each template includes:
name – Internal identifier for the template
title – Display name shown in the template picker
postTypes – Which post types can use the template
DigiFlash uses this section to provide templates like Blank, No Title, and No Title & Spacing.
Child Theme Considerations
When using a child theme with DigiFlash, you can include a theme.json file in the child theme folder. The child theme’s theme.json merges with the parent theme.json, allowing you to override specific settings without modifying the original DigiFlash files.
Child theme theme.json files typically include only the sections you want to modify, inheriting everything else from the parent theme.
Validation and Errors
WordPress validates theme.json structure when the theme loads. Invalid JSON syntax or incorrect property names prevent the theme from functioning correctly.
If theme.json contains errors, DigiFlash falls back to default WordPress block theme settings, and your custom design system settings won’t apply. Always validate JSON syntax using a JSON validator before saving changes.
Relationship with Global Styles
The Global Styles feature in the Site Editor reads from and writes to theme.json settings. When you customize colors, fonts, or spacing through the interface, you’re indirectly working with theme.json configuration.
Understanding theme.json structure helps you comprehend how Site Editor changes affect your website and what options are available for customization.