Themes: Provide more resources to clarify what can be done in theme.json vs Styles interface

[annezazu]

What problem does this address?

Right now, the process for determining which settings need to be done in theme.json vs the Styles interface is very manual. Tied to this, there's a regularly increasing amount of possibilities coming to each. For example, box shadow support was added to theme.json but it would be great to know when this can be controlled in the UI without needing to manually test or crawl through Gutenberg releases.

What is your proposed solution?

I think there are a few to explore including:

• Adding information about when a support was added so folks can see how things evolve over time/get the latest: Update theme schema docs #43716
• Update the schema to be more verbose/informative around what's valid/supported similar to this effort with block.json: Theme.json schema block properties: valid vs supported #36630
• Create a living document that indicates what's available in theme.json vs in the Styles interface (perhaps by having a "theme.json only" section since we inherently have to start with theme.json first).

cc @WordPress/block-themers for thoughts :)

[luminuu]

Yes, please!

[colorful-tones]

Love this idea and am even fine with possibly aggregating it in a spreadsheet or something for now. Although, I'm sure there is possibly room for automation.

[DaisyOlsen]

I started on a somewhat related thing to update the living theme.json reference. I closed my PR since it caused some concerns around validation with the schema.

I think this could be part of a bigger resource around theme.json options. I am working on some thoughts but maybe a stub document would be a good place to start. It's starting to be hard to know if this would be better as part of the block editor handbook or the theme developer handbook, though. Any thoughts on that? If the second then we'll need to move the conversation over the appropriate repo.

[carolinan]

Gutenberg is updated every two weeks, core is updated 3 times per year. Only core features should be in the theme handbook.

[DaisyOlsen]

I've been giving this quite a bit of thought, and I think I'd like to start by creating a table with this information, updated to Gutenberg 15.1 or 15.2, depending on how quickly it comes together, and then use that same table, with the unreleased parts removed onto the theme developer handbook. By keeping them very similar, it will be much easier to keep the Theme handbook side updated as new options are added to core.

I've self-assigned this issue but I've also committed to several other Documentation related issues over on the theme handbook side so I'll be planning out how to get them all done over the next 4 weeks or so. Will update here as I progress.