theme.json

The file has a version, a settings object for what the editor allows, and a styles object for the defaults. Entries such as settings.color.palette generate CSS custom properties like --wp--preset--color--primary on the front end. Settings.layout.contentSize sets the width of the content column, and wideSize sets wide alignment.

Validate it against the schema at https://schemas.wp.org/trunk/theme.json by adding a $schema line. A JSON syntax error causes the whole file to be ignored, so you notice that the editor falls back to defaults.

A design studio defines a palette of five colors and a font size scale of 14, 18, 24, and 40 px in theme.json. An editor opens the Site Editor and sees only those five swatches and four sizes in the pickers. A client who used to pick any hex value can no longer do so.

The studio sets settings.color.custom to false on purpose. Later a trailing comma after the last palette entry breaks the file, and the pickers show WordPress defaults until a developer finds the line.

theme.json is the file of design rules, while a block theme is the full set of template files that use them. A classic theme can include a theme.json to control the block editor without becoming a block theme. The file does not replace style.css; custom CSS still goes there.

Trailing commas and other JSON errors. Using the wrong version number for the features you want. Locking down colors and forgetting to include a color the brand needs. Editing the file and not seeing a change because a user customization in Global Styles overrides it. Duplicating values in style.css and theme.json.

Add the $schema line so your editor flags mistakes. Define your palette and sizes once in theme.json and use the generated custom properties in your CSS. Check the Site Editor Styles panel to see if user changes override your defaults.