Updates to experimental-theme.json

[oandregal]

Part of #20331

There's been good feedback and experimentation in the past months regarding the experimental-theme.json approach with some themes being built on top of it. This issue is to consolidate conversations that are scattered through many issues and pull requests. @jorgefilipecosta @youknowriad @ItsJonQ provided thoughts to put this together.

• The need for theme metadata (in progress)
• Controlling the visibility of UI controls (in progress)
• The difference between the root/site block VS defaults that are inherited (done)
• How to express hierarchy: flat vs nested (need to develop the idea further)
• Everything together

The need for theme metadata

theme.json has gained appeal as a place to centralize the theme metadata. Eventually, we'd want to do things like:

Example:

 "name": "theme name",
 "version": 2,
 "customTemplates": [],

Related: WordPress/theme-experiments#81

Tasks:

• Make settings & styles top-level keys Update theme.json shape: make settings & style top-level keys #28110
• Consolidate abstractions to access the metadata stored in theme.json Load page templates via theme.json abstractions #28700 Iterate on the public API of WP_Theme_JSON_Resolver #28855 Move theme.json support check to class #28788
• Allow all block-editor theme support options to be defined via theme.json Allow all Gutenberg theme support options to be defined in theme.json #26901
• Consider allowing themes to enqueue stylesheets in theme.json Consider allowing themes to enqueue stylesheets in theme.json #26902
• Versioning theme.json Handle an evolving theme.json shape (consider add versioning). #27230
• customTemplates Add support for custom templates in FSE themes #27778 Load page templates via theme.json abstractions #28700 Rename pageTemplates config to customTemplates in theme.json #28830 Add mechanism to translate custom page templates #28783
• templateParts Add an 'area' term for Template Parts. #28410

Controlling the visibility of UI controls.

Themes had expressed interest in having more control over what a user can do. At the moment, we have settings to opt-in/opt-out into a feature. There are two use cases to support here:

1. How to offer more granularity and gain the ability to define where a UI control for a property should be shown: in the block sidebar, in the global sidebar, none, or everywhere. See Controlling design tools visibility #27295 (comment)

2. Allow themes to decide which UI controls are shown/hidden per panel for a given block type. See Sidebar Controls & Component System #27331 Some notes:

• The users still have access to the hidden controls and can modify values.
• If those values are modified by the users, the controls should be shown for that particular block (not all blocks of the same kind).

Task:

• Consolidate both use cases in a concrete proposal to implement.

The difference between “root/site block” VS defaults that are inherited.

Status: this is done, the global key was split into defaults and root.

At the moment, we coalesce these two things into one key, global, that behaves differently for settings & styles. The semantics are clearer if we separate the two concepts.

The idea would be to remove the global key from the block list and add two new keys:

• root to represent the root/site block. It maps to the UI in the global styles sidebar at the site editor (the global tab) and can control both settings & styles of that block.
• defaults to represent "all the blocks" and is only allowed in settings. It serves as defaults for the blocks that they can overwrite.

"defaults": { // All blocks inherit these settings unless they overwrite them.
  "color": {
    "palette": [] // Palette to be used by all blocks.
  },
  "typography": {
    "lineHeight": "global" // Line height UI control is only visible in the global styles sidebar.
  }
},
"root": {
  "typography": {
    "lineHeight": false // Disable line height UI for this block entirely.
  }
},
"core/table": {
  "color": {
    "palette": [] // Set a different color palette for this block.
  }
}

Tasks:

• Split global into defaults and root Update theme.json: split global block selector into root and defaults #28533

How to express hierarchy: flat vs nested

Status: a flat structure is preferred.

Task:

• Develop the idea further, see Global Styles: composable styles for different contexts #27233

Comparison of a flat vs nested structure

Eventually, we're going to need to express hierarchy. This can be exemplified by the following use case: paragraphs that are top-level VS paragraphs that live within a sidebar (template part). This is necessary for both settings & styles, as the UI controls need to behave differently in each case and represent faithfully the styles.

During the past months, we discussed two ways to achieve hierarchy and this is still an open discussion:

• Using a flat structure for block selectors, like CSS.

p {
  color: black;
}
 
.sidebar {
  background-color:black;
}
 
.sidebar p { // This selector represents the hierarchy.
  color: white;
}

In the theme.json it'd be:

"core/paragraph": {
  "color": {
    "text": "black"
  }
},
"sidebar": {
  "color": {
    "background": "black"
  }
},
"sidebar core/paragraph": {
  "color": {
    "text": "white"
  }
}

• Using a nested structure for block selectors, like tailwind or the parts of SASS that allow you to nest rules.

p {
  color: black;
}
 
.sidebar {
  background-color: black;
  p { // Hierarchy can be expressed via nesting.
    color: white;
  }
}

"core/paragraph": { // Maps to the “p” CSS selector. 
  "styles": {
    "color": {
      "text": "black"
    }
  }
},
"sidebar": { // Maps to the “.sidebar” CSS selector. 
  "styles": {
    "color": {
      "background": "black"
    }
  },
  "core/paragraph": { // Maps to the “.sidebar p” CSS selector. 
    "styles": {
      "color": {
        "text": "white"
      }
    }
  }
}

Everything together

The full representation of a theme.json file.

• Representing hierarchy via a flat structure for block selectors.

The following example presumes that settings & styles are top-level keys and the block selectors are subtrees of them. An alternative to this would be to maintain today's structure (settings & styles are subtrees of a particular block selector), and/or grouping them under a top-level key called blocks.

{
 "name": "Theme Name",
 "version": 2,
 "pageTemplates": [],
 "settings": {
   "defaults": {
     "color": {
       "palette": []
     },
     "typography": {
       "lineHeight": "global"
     }
   },
   "root": {
     "typography": {
       "lineHeight": false
     }
   },
   "core/table": {
     "color": {
       "palette": []
     }
   }
 },
 "styles": {
   "core/paragraph": {
     "color": {
       "text": "black"
     }
   },
   "sidebar": {
     "color": {
       "background": "black"
     }
   },
   "sidebar core/paragraph": {
     "color": {
       "text": "white"
     }
   }
 }
}

• Representing hierarchy via nesting.

The following example presumes that the nested blocks live at the same level as the settings & styles keys. An alternative to this would be to create an explicit children key to hold nested blocks so each block would have the keys settings, styles, and children.

{
  "name": "Theme Name",
  "version": 2,
  "pageTemplates": [],
  "defaults": {
    "settings": {
      "color": {
        "palette": []
      },
      "typography": {
        "lineHeight": "global"
      }
    },
    "root": {
      "settings": {
        "typography": {
          "lineHeight": false
        }
      }
    },
    "core/table": {
      "settings": {
        "color": {
          "palette": []
        }
      }
    },
    "core/paragraph": {
      "styles": {
        "color": {
          "text": "black"
        }
      }
    },
    "sidebar": {
      "styles": {
        "color": {
          "background": "black"
        }
      },
      "core/paragraph": {
        "styles": {
          "color": {
            "text": "white"
          }
        }
      }
    }
  }
}

[oandregal]

I ran this by some people and the direction that makes more sense at the moment is the flat structure of block selectors.

[ndiego]

Minor point on the examples above, customTemplates is now pageTemplates, right? I believe this was switched after discussion in #27778. Trying to wrap my head around the experimental-theme.json file structure and got a little thrown. That aside, I do like the proposed flat structure!

[oandregal]

This issue has been useful to make decisions in the past and see what was left. There are new things we need to consider so I'm consolidating everything on the overview task #20331