Add defaultFontSizes theme.json (v2) (#58409)

Co-authored-by: ajlende <[email protected]>
Co-authored-by: draganescu <[email protected]>
Co-authored-by: scruffian <[email protected]>
Co-authored-by: gaambo <[email protected]>
Co-authored-by: youknowriad <[email protected]>
Co-authored-by: oandregal <[email protected]>

Author: 7 people

docs/manifest.json

@@ -564,7 +564,7 @@
 		"parent": "reference-guides"
 	},
 	{
-		"title": "Theme.json Version 2",
+		"title": "Theme.json Version 3",
 		"slug": "theme-json-living",
 		"markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-living.md",
 		"parent": "theme-json-reference"

docs/reference-guides/theme-json-reference/theme-json-living.md

@@ -1,10 +1,11 @@
-# Theme.json Version 2
+# Theme.json Version 3
 
-> This is the living specification for  **version 2** of `theme.json`. This version works with WordPress 5.9 or later, and the latest Gutenberg plugin.
+> This is the living specification for  **version 3** of `theme.json`. This version works with WordPress 5.9 or later, and the latest Gutenberg plugin.
 >
 > There are some related documents that you may be interested in: 
-> - the [theme.json v1](/docs/reference-guides/theme-json-reference/theme-json-v1.md) specification, and 
-> - the [reference to migrate from theme.json v1 to v2](/docs/reference-guides/theme-json-reference/theme-json-migrations.md).
+> - the [theme.json v1](/docs/reference-guides/theme-json-reference/theme-json-v1.md) specification,
+> - the [theme.json v2](/docs/reference-guides/theme-json-reference/theme-json-v2.md) specification, and
+> - the [reference to migrate from older theme.json versions](/docs/reference-guides/theme-json-reference/theme-json-migrations.md).
 
 This reference guide lists the settings and style properties defined in the `theme.json` schema. See the [theme.json how to guide](/docs/how-to-guides/themes/global-settings-and-styles.md) for examples and guidance on how to use the `theme.json` file in your theme.
 
@@ -17,7 +18,7 @@ Code editors can pick up the schema and can provide helpful hints and suggestion
 ```
 {
   "$schema": "https://schemas.wp.org/trunk/theme.json",
-  "version": 2,
+  "version": 3,
   ...
 }
 ```
@@ -179,6 +180,7 @@ Settings related to typography.
 
 | Property  | Type   | Default | Props  |
 | ---    | ---    | ---    |---   |
+| defaultFontSizes | boolean | true |  |
 | customFontSize | boolean | true |  |
 | fontStyle | boolean | true |  |
 | fontWeight | boolean | true |  |

docs/reference-guides/theme-json-reference/theme-json-migrations.md

@@ -63,3 +63,27 @@ Additions to styles:
 ### Changes to property values
 
 The default font sizes provided by core (`settings.typography.fontSizes`) have been updated. The Normal and Huge sizes (with `normal` and `huge` slugs) have been removed from the list, and Extra Large (`x-large` slug) has been added. When the UI controls show the default values provided by core, Normal and Huge will no longer be present. However, their CSS classes and CSS Custom Properties are still enqueued to make sure existing content that uses them still works as expected.
+
+## Migrating from v2 to v3
+
+Upgrading to v3 adjusts preset defaults to be more consistent with one another.
+
+### How to migrate from v1 to v2:
+
+1. Update `version` to `3`.
+2. Configure the changed defaults.
+
+### Changed defaults
+
+#### `settings.typography.defaultFontSizes`
+
+In theme.json v2, the default font sizes were only shown when theme sizes were not defined. A theme providing font sizes with the same slugs as the defaults would always override them.
+
+The new `defaultFontSizes` option gives control over showing default font sizes and preventing those defaults from being overridden.
+
+- When set to `true` it will show the default font sizes and prevent them from being overridden by the theme.
+- When set to `false` it will hide the default font sizes and allow the theme to use the default slugs.
+
+It is `true` by default when switching to v3. This is to be consistent with how other `default*` options work such as `settings.color.defaultPalette`.
+
+To keep behavior similar to v2, set this value to `false`.