Clarify issue with how layouts work when using theme.json

[justintadlock]

Issue Description

Wide/full alignments and layouts work differently when using a theme with a theme.json vs. one without. A full description of this issue is outlined in an ongoing Gutenberg ticket. A good breakdown of it is in this comment.

The Theme Handbook should note this issue because it is a blocker for gradual adoption of FSE features, breaking the user experience when theme authors update to adopt theme.json.

URL of the Page with the Issue

https://developer.wordpress.org/themes/advanced-topics/theme-json/

Section of Page with the issue

I think the best location for addressing this is in the Layout section of theme.json page: https://developer.wordpress.org/themes/advanced-topics/theme-json/#layout

Why is this a problem?

It is a back-compatibility issue for end-users. There is currently a pull request for fixing this. However, even if this fix lands in WordPress 6.1, theme authors need to be aware that it's an issue for at least WordPress 5.9 and 6.0. It is a definite blocker for gradual FSE adoption.

Suggested Fix

We need two or three paragraphs that succinctly describes the issue and what theme authors should expect if updating their classic theme to use theme.json.

There is already a vague note in the Layout section of the page that seems to refer to this issue (this bit needs to be extended for clarity):

Note that the alignment mechanism leveraged here is different than what was previously enabled via align-wide theme support.

It may also be worth noting that user expectations may not be met when switching from a classic theme to a block theme where wide/full layouts work differently. I'm not sure if this part would best fit into the theme dev handbook since this would be more of a user-experience thing.

I am ready to work on this document update.

[andrewserong]

Thanks for opening this tracking issue @justintadlock, it'd be great to document many parts of the current state of the Layout support in addition to the content and wide sizes. I've started a draft PR over in WordPress/gutenberg#42619 that is less about the specifics of theme.json and tries to give a bit more top-level overview about the current state of the Layout support and why it does what it does. I think it might make sense to document things in both places (the Layout section of the link you suggested, with more technical detail, and also reference it in the architecture section in WordPress/gutenberg#42619).

I am ready to work on this document update.

Let me know if I can help / happy to help review any documentation updates!

[github-actions]

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

[justintadlock]

Thanks for opening this tracking issue @justintadlock, it'd be great to document many parts of the current state of the Layout support in addition to the content and wide sizes. I've started a draft PR over in WordPress/gutenberg#42619 that is less about the specifics of theme.json and tries to give a bit more top-level overview about the current state of the Layout support and why it does what it does. I think it might make sense to document things in both places (the Layout section of the link you suggested, with more technical detail, and also reference it in the architecture section in WordPress/gutenberg#42619).

@andrewserong - I agree that it needs to be documented in both places. I think this page of the Theme Handbook mostly needs to note the issue, but we need a deeper explanation of the features elsewhere. I'm also working on a tutorial around layouts and alignments with the hope that it offers more clarity around how all of this works.

[justintadlock]

The following is a first pass at an update for Layout section of the theme.json page in the Theme Handbook: https://developer.wordpress.org/themes/advanced-topics/theme-json/#layout

I'm trying to keep it relatively short (and we can go shorter) with links to relevant information for theme authors who want to dig into it more. Let me know what you think or please make any adjustments.

---

Layout

The layout setting enables wide and full-width blocks.

{
	"version": 2,
	"settings": {
		"layout": {
			"contentSize": "840px",
			"wideSize": "1100px"
		}
	}
}

Note that the alignment mechanism leveraged here is different than what was previously enabled via align-wide theme support. If gradually adopting FSE features within a classic theme, some user's layouts may change when upgrading the theme. Because classic themes managed their own content width, the editor always displayed wide/full controls for blocks that supported them.

However, the logic for wide/full handling changes when a theme has a theme.json file. WordPress then handles the styles for content width. For wide/full alignments to appear, the theme must define the layout setting in theme.json. The major difference in the handling is that content widths need to be set for each container, and the wide/full controls only appear on children of blocks with a content width set.

There is an open ticket with a full description of the issue and a pull request for a new default layout type to address this for users.

[justintadlock]

Updated text after cross-check with @kafleg. https://developer.wordpress.org/themes/advanced-topics/theme-json/#layout

[kafleg]

Thank you Justin :)