What Is theme.json? WordPress Design Settings Explained

theme.json is a standard WordPress theme configuration file. It enables editor settings, defines design presets, applies styles, and registers selected theme features. WordPress reads it on both editor and frontend requests.

The file creates a shared design contract. Themes declare available choices. WordPress turns many declarations into controls and generated CSS.

It does not replace every stylesheet or PHP function. It handles supported design-system tasks particularly well. Custom behaviour still needs appropriate code.

What can theme.json do?

• Enable or disable block design controls.
• Define colour and gradient palettes.
• Register font sizes and font families.
• Set content and wide layout widths.
• Apply global element styles.
• Apply defaults for individual block types.
• Add custom CSS properties and values.
• Register custom templates and template parts.
• Reference patterns from the Pattern Directory.

The available properties follow a versioned schema. WordPress ignores unsupported or invalid declarations. Exact capabilities depend on the active WordPress version.

Where does theme.json live?

A theme places theme.json at its root directory. WordPress detects that conventional filename automatically. Child themes can provide their own file too.

The file uses JSON syntax. Property names and string values need double quotation marks. Trailing commas are invalid.

Developers commonly include a schema URL for editor assistance. Suitable tools can then suggest properties and flag mistakes. The schema does not run the site.

WordPress core also contains its own configuration. The theme file does not start from nothing. It participates within a larger settings hierarchy.

A minimal theme.json structure

{
  "version": 3,
  "settings": {
    "color": {
      "custom": false
    }
  },
  "styles": {
    "color": {
      "text": "#1e293b"
    }
  }
}

This example disables arbitrary custom colours and sets a default text colour. A production file usually contains more. Start small and add verified requirements.

The top-level version identifies the schema generation. It is not the theme’s release number. Consult current WordPress documentation before changing it.

The other top-level properties

The main file can contain more than settings and styles. Supported properties also register templates, template parts, and directory patterns. Metadata describes each registered object.

The customTemplates collection registers selectable templates. Entries can include names, titles, and applicable post types. Corresponding template files still provide block markup.

The templateParts collection describes reusable structural parts. It can identify areas such as headers or footers. WordPress uses that information within editing interfaces.

The patterns collection can reference slugs from the official Pattern Directory. This bundles discoverable starting designs without copying their complete markup into configuration.

The custom settings area can hold theme-specific design values. WordPress can expose them as generated custom properties. Name them consistently and document intended consumers.

Do not add arbitrary application data merely because JSON accepts it. Use established WordPress options for application settings. Keep the file focused on theme configuration.

Settings and styles are different

The settings section controls capabilities and choices. It can expose spacing controls or define a colour palette. Think about what users may choose.

The styles section defines visual defaults. It can set body text colour or Heading typography. Think about the initial visual result.

A setting can exist without a matching style. A palette may offer six colours without choosing one. A style can reference one declared preset.

This separation supports governance. Themes can provide narrow approved choices and sensible defaults. Editors then work inside a deliberate system.

How the theme.json hierarchy works

1. WordPress core provides base settings and styles.
2. The parent theme overrides relevant core values.
3. An active child theme can override its parent.
4. User Global Styles choices override theme defaults.
5. Server filters can modify data programmatically.

The official hierarchy guide documents these layers. It warns that theme declarations may not hold final priority.

This explains a common debugging surprise. A correct file change can appear ineffective. An existing user customisation may override it.

Reset the relevant user style only after confirming intent. Resets can remove valuable customisation. Backups should precede broad changes.

How WordPress turns theme.json into CSS

WordPress processes supported style declarations and generates CSS. Presets often become CSS custom properties. Block and element rules receive predictable selectors.

This generated layer can reduce theme specificity battles. User choices flow through the same system. Editor and frontend styles can align more reliably.

The official styles reference recommends supported properties when possible. Their integration lets users customise through standard WordPress interfaces.

Unsupported design needs ordinary CSS. Complex selectors, animations, and some responsive rules still live there. Use each layer for its suitable job.

What are theme.json presets?

Presets are named design choices registered by WordPress or a theme. Colours, gradients, font sizes, spacing sizes, and shadows can use presets.

Each preset usually has a human label, slug, and value. Editors choose the friendly label. Saved content can reference the stable slug.

Stable slugs help design systems evolve. A theme can adjust a preset value centrally. Blocks using that preset can follow the updated definition.

Changing a preset carelessly can alter many pages. Treat established slugs as public design contracts. Add new choices when meanings truly differ.

How settings control the editor

Settings can enable margin, padding, line height, or custom units. They can also disable arbitrary choices. Block-level settings can narrow global permissions.

Removing a control does not always remove existing saved values. Historical blocks can retain attributes. Test old content after tightening the system.

Theme support and block support interact. A block must support the relevant feature. The theme then decides whether users receive that control.

Use restrictions to protect consistency, not frustrate genuine requirements. Interview editors before disabling important tools. Offer patterns for common approved outcomes.

How styles target elements and blocks

Global styles can define the page’s general typography and colours. Element styles can target links, headings, buttons, and captions. Block styles target registered block types.

A core Button block can receive different defaults from a Paragraph. A Quote can receive its own border and typography. Local choices may override allowed values.

Avoid reproducing every CSS rule inside JSON. Use supported properties where integration matters. Keep specialised selectors inside maintainable stylesheets.

Inspect generated frontend output during development. Verify selector reach and cascade. An accepted JSON property can still create an unwanted visual result.

How theme.json supports accessibility

A controlled palette can prevent many weak colour combinations. Consistent font sizes can protect readable hierarchy. Spacing presets can support predictable focus and touch layouts.

Configuration cannot prove accessible outcomes. Local overrides can create poor contrast. Custom blocks can emit weak semantics or broken keyboard behaviour.

Test the real combinations available to editors. Include links, buttons, text, backgrounds, focus states, and error messages. Automated contrast checks cover only part.

Avoid disabling browser zoom through unrelated theme code. Do not rely on colour alone. Design tokens should support accessible components, not merely attractive screenshots.

Can classic themes use theme.json?

Yes. Classic themes can use theme.json for block settings and styles. Adding the file does not convert their PHP templates into block templates.

This makes gradual adoption practical. A classic theme can standardise palettes and typography first. Existing template logic remains unchanged.

Some Site Editor features still require a block theme. The configuration file and theme architecture are separate concepts. Test the actual available interface.

Hybrid themes use this separation deliberately. They gain modern design controls while preserving established PHP structure. That can lower migration risk.

Does theme.json improve performance?

It can consolidate supported design rules and improve style coordination. WordPress can generate only the needed standard declarations. This may simplify a theme’s CSS.

The file is not a performance guarantee. Large fonts, images, scripts, and queries remain decisive. Excessive custom CSS can still accompany it.

Measure generated CSS and complete page weight. Check cache behaviour after changes. Editor performance also deserves testing with realistic templates.

Common theme.json mistakes

• Using invalid JSON or trailing commas.
• Copying properties from a newer unsupported schema.
• Confusing settings with visual defaults.
• Changing established preset slugs casually.
• Ignoring child-theme and user override layers.
• Expecting unsupported CSS selectors to work.
• Disabling controls without testing existing content.
• Editing production without version control or backups.

Many mistakes fail silently. WordPress may ignore an invalid property instead of crashing. Visual regression tests catch more than syntax checks alone.

How to debug a theme.json change

1. Validate the file as strict JSON.
2. Confirm the declared schema version.
3. Check the property in current documentation.
4. Verify the active theme and child theme.
5. Inspect user Global Styles overrides.
6. Clear relevant caches once.
7. Check editor controls and frontend output.
8. Test a new block and historical content.
9. Reduce the change to one property.
10. Restore the last working version when necessary.

Changing one property per test reveals hierarchy problems quickly. Large copied configurations hide the responsible value. Build from a known valid base.

Moving theme.json changes between environments

Theme-file changes move through the normal code deployment. Global Styles user choices live in the database. Those two paths can produce different environment results.

Before deployment, compare user overrides on staging and production. A production override can hide the new theme default. Decide whether preserving it is intentional.

Export tools can help capture visual customisations. Review exported values before committing them. Environment-specific choices should not enter a reusable theme accidentally.

Record any required reset as a deployment step. Resets are destructive to user choices. Obtain explicit review and maintain a database backup.

After deployment, verify a new block and existing blocks. Check the editor palette and frontend output. Then confirm that caches contain the updated styles.

Can plugins change theme.json data?

Plugins can register block supports, styles, and presets through WordPress interfaces. Server filters can also modify global settings and style data. Those changes join the effective hierarchy.

This capability helps integrations provide required defaults. It can also create confusing conflicts. Disable candidate plugins on staging when values appear unexpectedly.

Do not edit plugin files to solve the conflict. Updates will replace those changes. Prefer documented filters, theme configuration, or provider support.

Record every programmatic override within project documentation. File inspection alone cannot reveal runtime filters. Future maintainers need the complete ownership chain.

A maintainable theme.json workflow

1. Define the project’s approved design tokens.
2. Map each token to a stable preset.
3. Enable only required editor controls.
4. Add broad styles before block-specific styles.
5. Validate syntax and schema properties.
6. Test editor and frontend results together.
7. Check representative historical content.
8. Review accessibility and responsive behaviour.
9. Commit the file with an explanatory change.
10. Deploy through the normal release process.

Keep comments outside JSON because standard JSON forbids comments. Explain decisions in project documentation or version-control history. Preserve the file’s readability.

When theme.json is the right tool

Use it for shared WordPress design settings and supported style defaults. It excels when editor controls and frontend results must agree.

Use ordinary CSS for specialised selectors and unsupported presentation. Use PHP for dynamic logic or server filtering. Use block metadata for block-specific capabilities.

The weak case is forcing every style into one format. Maintainability comes from clear ownership. It does not come from eliminating appropriate layers.

Frequently asked questions

The verdict

A disciplined design system makes specialised blocks easier to govern. WP Block Suite products inherit WordPress theme settings where appropriate. Try every free plugin first. Then compare the $299 lifetime suite for several Pro needs.