Add defaultFontSizes theme.json (theme.json v3)

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,23 @@ 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 if you'd like.
+
+### Changed defaults
+
+#### `settings.typography.defaultFontSizes`
+
+In theme.json v2, the default font sizes were always merged with the theme ones.
+
+The new `defaultFontSizes` option differs from that behavior.
+
+- 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.

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

@@ -0,0 +1,333 @@
+# Theme.json Version 2
+
+> 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.
+>
+> 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).
+
+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.
+
+## Schema
+
+Remembering the `theme.json` settings and properties while you develop can be difficult, so a [JSON schema](https://schemas.wp.org/trunk/theme.json) was created to help.
+
+Code editors can pick up the schema and can provide helpful hints and suggestions such as tooltips, autocomplete, or schema validation in the editor. To use the schema in Visual Studio Code, add `$schema`: "https://schemas.wp.org/trunk/theme.json" to the beginning of your theme.json file together with a `version` corresponding to the version you wish to use, e.g.:
+
+```
+{
+  "$schema": "https://schemas.wp.org/trunk/theme.json",
+  "version": 2,
+  ...
+}
+```
+
+## Settings
+
+### appearanceTools
+
+Setting that enables the following UI tools:
+
+- background: backgroundImage
+- border: color, radius, style, width
+- color: link
+- dimensions: aspectRatio, minHeight
+- position: sticky
+- spacing: blockGap, margin, padding
+- typography: lineHeight
+
+---
+
+### useRootPaddingAwareAlignments
+
+_**Note:** Since WordPress 6.1._
+
+Enables root padding (the values from `styles.spacing.padding`) to be applied to the contents of full-width blocks instead of the root block.
+
+Please note that when using this setting, `styles.spacing.padding` should always be set as an object with `top`, `right`, `bottom`, `left` values declared separately.
+
+---
+
+### border
+
+Settings related to borders.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| color | boolean | false |  |
+| radius | boolean | false |  |
+| style | boolean | false |  |
+| width | boolean | false |  |
+
+---
+
+### shadow
+
+Settings related to shadows.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| defaultPresets | boolean | true |  |
+| presets | array |  | name, shadow, slug |
+
+---
+
+### color
+
+Settings related to colors.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| background | boolean | true |  |
+| custom | boolean | true |  |
+| customDuotone | boolean | true |  |
+| customGradient | boolean | true |  |
+| defaultDuotone | boolean | true |  |
+| defaultGradients | boolean | true |  |
+| defaultPalette | boolean | true |  |
+| duotone | array |  | colors, name, slug |
+| gradients | array |  | gradient, name, slug |
+| link | boolean | false |  |
+| palette | array |  | color, name, slug |
+| text | boolean | true |  |
+| heading | boolean | true |  |
+| button | boolean | true |  |
+
+---
+
+### background
+
+Settings related to background.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| backgroundImage | boolean | false |  |
+
+---
+
+### dimensions
+
+Settings related to dimensions.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| aspectRatio | boolean | false |  |
+| minHeight | boolean | false |  |
+
+---
+
+### layout
+
+Settings related to layout.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| contentSize | string |  |  |
+| wideSize | string |  |  |
+| allowEditing | boolean | true |  |
+| allowCustomContentAndWideSize | boolean | true |  |
+
+---
+
+### lightbox
+
+Settings related to the lightbox.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| enabled | boolean |  |  |
+| allowEditing | boolean |  |  |
+
+---
+
+### position
+
+Settings related to position.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| sticky | boolean | false |  |
+
+---
+
+### spacing
+
+Settings related to spacing.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| blockGap | undefined | null |  |
+| margin | boolean | false |  |
+| padding | boolean | false |  |
+| units | array | px,em,rem,vh,vw,% |  |
+| customSpacingSize | boolean | true |  |
+| spacingSizes | array |  | name, size, slug |
+| spacingScale | object |  |  |
+
+---
+
+### typography
+
+Settings related to typography.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| customFontSize | boolean | true |  |
+| fontStyle | boolean | true |  |
+| fontWeight | boolean | true |  |
+| fluid | undefined | false |  |
+| letterSpacing | boolean | true |  |
+| lineHeight | boolean | false |  |
+| textAlign | boolean | true |  |
+| textColumns | boolean | false |  |
+| textDecoration | boolean | true |  |
+| writingMode | boolean | false |  |
+| textTransform | boolean | true |  |
+| dropCap | boolean | true |  |
+| fontSizes | array |  | fluid, name, size, slug |
+| fontFamilies | array |  | fontFace, fontFamily, name, slug |
+
+---
+
+### custom
+
+Generate custom CSS custom properties of the form `--wp--custom--{key}--{nested-key}: {value};`. `camelCased` keys are transformed to `kebab-case` as to follow the CSS property naming schema. Keys at different depth levels are separated by `--`, so keys should not include `--` in the name.
+
+---
+
+## Styles
+
+### border
+
+Border styles.
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| color | string, object |  |
+| radius | string, object |  |
+| style | string, object |  |
+| width | string, object |  |
+| top | object | color, style, width |
+| right | object | color, style, width |
+| bottom | object | color, style, width |
+| left | object | color, style, width |
+
+---
+
+### color
+
+Color styles.
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| background | string, object |  |
+| gradient | string, object |  |
+| text | string, object |  |
+
+---
+
+### dimensions
+
+Dimensions styles
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| aspectRatio | string, object |  |
+| minHeight | string, object |  |
+
+---
+
+### spacing
+
+Spacing styles.
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| blockGap | string, object |  |
+| margin | object | bottom, left, right, top |
+| padding | object | bottom, left, right, top |
+
+---
+
+### typography
+
+Typography styles.
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| fontFamily | string, object |  |
+| fontSize | string, object |  |
+| fontStyle | string, object |  |
+| fontWeight | string, object |  |
+| letterSpacing | string, object |  |
+| lineHeight | string, object |  |
+| textColumns | string |  |
+| textDecoration | string, object |  |
+| writingMode | string, object |  |
+| textTransform | string, object |  |
+
+---
+
+### filter
+
+CSS and SVG filter styles.
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| duotone | string, object |  |
+
+---
+
+### shadow
+
+Box shadow styles.
+
+---
+
+### outline
+
+Outline styles.
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| color | string, object |  |
+| offset | string, object |  |
+| style | string, object |  |
+| width | string, object |  |
+
+---
+
+### css
+
+Sets custom CSS to apply styling not covered by other theme.json properties.
+
+---
+
+## customTemplates
+
+Additional metadata for custom templates defined in the templates folder.
+
+Type: `object`.
+
+| Property | Description | Type |
+| ---      | ---         | ---  |
+| name | Filename, without extension, of the template in the templates folder. | string |
+| title | Title of the template, translatable. | string |
+| postTypes | List of post types that can use this custom template. | array |
+
+## templateParts
+
+Additional metadata for template parts defined in the parts folder.
+
+Type: `object`.
+
+| Property | Description | Type |
+| ---      | ---         | ---  |
+| name | Filename, without extension, of the template in the parts folder. | string |
+| title | Title of the template, translatable. | string |
+| area | The area the template part is used for. Block variations for `header` and `footer` values exist and will be used when the area is set to one of those. | string |
+
+## Patterns
+
+An array of pattern slugs to be registered from the Pattern Directory.
+Type: `array`.