Rename experimental-theme.json to theme.json and add a fallback for b…

…ackwards-compatibility (#29981)

* Rename experimental-theme to theme & add fallbacks

* update all newer docs

* update md files

* conflicts fixes

docs/getting-started/full-site-editing.md

@@ -56,6 +56,6 @@ See the [architecture document on templates](/docs/explanations/architecture/ful
 
 ### theme.json
 
-Instead of the proliferation of theme support flags or alternative methods, a new `theme.json` file is being used to define theme settings. **NOTE:** This feature is still experimental and changing, so the interim file name is `experimental-theme.json`
+Instead of the proliferation of theme support flags or alternative methods, a new `theme.json` file is being used to define theme settings.
 
 See [documentation for theme.json](/docs/how-to-guides/themes/theme-json.md).

docs/how-to-guides/themes/block-theme-overview.md

@@ -17,7 +17,7 @@ A very simple block theme is structured like so:
 ```
 theme
 |__ style.css
-|__ experimental-theme.json
+|__ theme.json
 |__ functions.php
 |__ block-templates
     |__ index.html
@@ -31,7 +31,7 @@ theme
     |__ ...
 ```
 
-The difference with existing WordPress themes is that the different templates in the template hierarchy, and template parts, are block templates instead of php files. In addition, this example includes an [`experimental-theme.json`](/docs/how-to-guides/themes/theme-json.md) file for some styles.
+The difference with existing WordPress themes is that the different templates in the template hierarchy, and template parts, are block templates instead of php files. In addition, this example includes a [`theme.json`](/docs/how-to-guides/themes/theme-json.md) file for some styles.
 
 ## What is a block template?
 

docs/how-to-guides/themes/create-block-theme.md

@@ -13,7 +13,7 @@ This tutorial is up to date as of Gutenberg version 9.1.
 1.  [What is needed to create a block-theme?](#what-is-needed-to-create-a-block-theme)
 2.  [Creating the theme](#creating-the-theme)
 3.  [Creating the templates and template parts](#creating-the-templates-and-template-parts)
-4.  [experimental-theme.json - Global styles](#experimental-theme-json-global-styles)
+4.  [theme.json - Global styles](#theme-json-global-styles)
 
 ## What is needed to create a block theme?
 
@@ -27,7 +27,7 @@ Each template or template part contains the [block grammar](/docs/explanations/a
 
 A block theme requires an `index.php` file, an index template file, a `style.css` file, and a `functions.php` file.
 
-The theme may optionally include an [experimental-theme.json file](/docs/how-to-guides/themes/theme-json.md) to manage global styles. You decide what additional templates and template parts to include in your theme.
+The theme may optionally include an [theme.json file](/docs/how-to-guides/themes/theme-json.md) to manage global styles. You decide what additional templates and template parts to include in your theme.
 
 Templates are placed inside the `block-templates` folder, and template parts are placed inside the `block-template-parts` folder:
 
@@ -36,7 +36,7 @@ theme
 |__ style.css
 |__ functions.php
 |__ index.php
-|__ experimental-theme.json
+|__ theme.json
 |__ block-templates
 	|__ index.html
 	|__ single.html
@@ -179,9 +179,9 @@ If you used a different theme name, adjust the value for the theme text domain.
 
 Eventually, you will be able to create and combine templates and template parts directly in the site editor.
 
-### Experimental-theme.json - Global styles
+### theme.json - Global styles
 
-The purpose of the `experimental-theme.json` file is to make it easier to style blocks by setting defaults.
+The purpose of the `theme.json` file is to make it easier to style blocks by setting defaults.
 
 It is used to:
 
@@ -191,13 +191,13 @@ It is used to:
 
 [The documentation for global styles contains a list of available block and style combinations.](/docs/how-to-guides/themes/theme-json.md)
 
-Create a file called `experimental-theme.json` and save it inside the main folder.
+Create a file called `theme.json` and save it inside the main folder.
 
 CSS variables are generated using **Global presets**. The variables are added to the `:root` on the front, and to the `.editor-styles-wrapper` class in the editor.
 
 Styles that are added to the themes `style.css` file or an editor style sheet are loaded after global styles.
 
-Add the following global presets to the `experimental-theme.json` file:
+Add the following global presets to the `theme.json` file:
 
 ```
 {

docs/how-to-guides/themes/theme-json.md

@@ -25,19 +25,19 @@ This is documentation for the current direction and work in progress about how t
 
 The Block Editor API has evolved at different velocities and there are some growing pains, specially in areas that affect themes. Examples of this are: the ability to [control the editor programmatically](https://make.wordpress.org/core/2020/01/23/controlling-the-block-editor/), or [a block style system](https://github.com/WordPress/gutenberg/issues/9534) that facilitates user, theme, and core style preferences.
 
-This describes the current efforts to consolidate the various APIs related to styles into a single point – a `experimental-theme.json` file that should be located inside the root of the theme directory.
+This describes the current efforts to consolidate the various APIs related to styles into a single point – a `theme.json` file that should be located inside the root of the theme directory.
 
 ### Global settings for the block editor
 
-Instead of the proliferation of theme support flags or alternative methods, the `experimental-theme.json` files provides a canonical way to define the settings of the block editor. These settings includes things like:
+Instead of the proliferation of theme support flags or alternative methods, the `theme.json` files provides a canonical way to define the settings of the block editor. These settings includes things like:
 
 -   What customization options should be made available or hidden from the user.
 -   What are the default colors, font sizes... available to the user.
 -   Defines the default layout of the editor. (widths and available alignments).
 
 ### Settings can be controlled per block
 
-For more granularity, these settings also work at the block level in `experimental-theme.json`.
+For more granularity, these settings also work at the block level in `theme.json`.
 
 Examples of what can be achieved are:
 
@@ -47,7 +47,7 @@ Examples of what can be achieved are:
 
 ### Some block styles are managed
 
-By using the `experimental-theme.json` file to set style properties in a structured way, the Block Editor can "manage" the CSS that comes from different origins (user, theme, and core CSS). For example, if a theme and a user set the font size for paragraphs, we only enqueue the style coming from the user and not the theme's.
+By using the `theme.json` file to set style properties in a structured way, the Block Editor can "manage" the CSS that comes from different origins (user, theme, and core CSS). For example, if a theme and a user set the font size for paragraphs, we only enqueue the style coming from the user and not the theme's.
 
 Some of the advantages are:
 
@@ -132,9 +132,9 @@ body {
 
 ## Specification
 
-This specification is the same for the three different origins that use this format: core, themes, and users. Themes can override core's defaults by creating a file called `experimental-theme.json`. Users, via the site editor, will also be also to override theme's or core's preferences via an user interface that is being worked on.
+This specification is the same for the three different origins that use this format: core, themes, and users. Themes can override core's defaults by creating a file called `theme.json`. Users, via the site editor, will also be also to override theme's or core's preferences via an user interface that is being worked on.
 
-The `experimental-theme.json` file declares how a theme wants the editor configured (`settings`) as well as the style properties it sets (`styles`).
+The `theme.json` file declares how a theme wants the editor configured (`settings`) as well as the style properties it sets (`styles`).
 
 ```
 {
@@ -214,7 +214,7 @@ The settings section has the following structure and default values:
 
 Each block can configure any of these settings separately, providing a more fine-grained control over what exists via `add_theme_support`.
 
-The block settings declared under the `defaults` block selector affect to all blocks, unless a particular block overwrites it. It's a way to provide inheritance and quickly configure all blocks at once. To retain backward compatibility, the existing `add_theme_support` declarations that configure the block editor are retrofit in the proper categories for the `defaults` section. If a theme uses `add_theme_support('disable-custom-colors')`, it'll be the same as set `settings.defaults.color.custom` to `false`. If the `experimental-theme.json` contains any settings, these will take precedence over the values declared via `add_theme_support`.
+The block settings declared under the `defaults` block selector affect to all blocks, unless a particular block overwrites it. It's a way to provide inheritance and quickly configure all blocks at once. To retain backward compatibility, the existing `add_theme_support` declarations that configure the block editor are retrofit in the proper categories for the `defaults` section. If a theme uses `add_theme_support('disable-custom-colors')`, it'll be the same as set `settings.defaults.color.custom` to `false`. If the `theme.json` contains any settings, these will take precedence over the values declared via `add_theme_support`.
 
 Let's say a theme author wants to enable custom colors only for the paragraph block. This is how it can be done:
 
@@ -235,7 +235,7 @@ Let's say a theme author wants to enable custom colors only for the paragraph bl
 }
 ```
 
-Note, however, that not all settings are relevant for all blocks. The settings section provides an opt-in/opt-out mechanism for themes, but it's the block's responsibility to add support for the features that are relevant to it. For example, if a block doesn't implement the `dropCap` feature, a theme can't enable it for such a block through `experimental-theme.json`.
+Note, however, that not all settings are relevant for all blocks. The settings section provides an opt-in/opt-out mechanism for themes, but it's the block's responsibility to add support for the features that are relevant to it. For example, if a block doesn't implement the `dropCap` feature, a theme can't enable it for such a block through `theme.json`.
 
 #### Presets
 
@@ -313,11 +313,11 @@ body {
 
 {% end %}
 
-To maintain backward compatibility, the presets declared via `add_theme_support` will also generate the CSS Custom Properties. If the `experimental-theme.json` contains any presets, these will take precedence over the ones declared via `add_theme_support`.
+To maintain backward compatibility, the presets declared via `add_theme_support` will also generate the CSS Custom Properties. If the `theme.json` contains any presets, these will take precedence over the ones declared via `add_theme_support`.
 
 #### Free-form CSS Custom Properties
 
-In addition to create CSS Custom Properties for the presets, the `experimental-theme.json` also allows for themes to create their own, so they don't have to be enqueued separately. Any values declared within the `settings.<some/block>.custom` section will be transformed to CSS Custom Properties following this naming schema: `--wp--custom--<variable-name>`.
+In addition to create CSS Custom Properties for the presets, the `theme.json` also allows for themes to create their own, so they don't have to be enqueued separately. Any values declared within the `settings.<some/block>.custom` section will be transformed to CSS Custom Properties following this naming schema: `--wp--custom--<variable-name>`.
 
 For example:
 
@@ -358,7 +358,7 @@ Note that, the name of the variable is created by adding `--` in between each ne
 
 ### Styles
 
-Each block declares which style properties it exposes via the [block supports mechanism](../block-api/block-supports.md). The support declarations are used to automatically generate the UI controls for the block in the editor. Themes can use any style property via the `experimental-theme.json` for any block ― it's the theme's responsibility to verify that it works properly according to the block markup, etc.
+Each block declares which style properties it exposes via the [block supports mechanism](../block-api/block-supports.md). The support declarations are used to automatically generate the UI controls for the block in the editor. Themes can use any style property via the `theme.json` for any block ― it's the theme's responsibility to verify that it works properly according to the block markup, etc.
 
 ```json
 {

docs/how-to-guides/themes/theme-support.md

@@ -399,12 +399,12 @@ Using the Gutenberg plugin (version 8.3 or later), link color control is availab
 add_theme_support('experimental-link-color');
 ```
 
-If a theme opts in, it can [define link colors](/docs/how-to-guides/themes/theme-json.md#color-properties) by using the `experimental-theme.json`. If the theme doesn't use the `experimental-theme.json` it can configure the color of links by settings the value of the `--wp--style--color--link` CSS Custom Property such as:
+ If a theme opts in, it can [define link colors](/docs/how-to-guides/themes/theme-json.md#color-properties) by using the `theme.json`. If the theme doesn't use the `theme.json` it can configure the color of links by settings the value of the `--wp--style--color--link` CSS Custom Property such as:
 
 ```css
 :root {
 	--wp--style--color--link: <value>;
 }
 ```
 
-The framework will take care of enqueing the necessary rules for this to work. Whether or not the theme supports `experimental-theme.json` the presets will also be enqueued as CSS Custom Properties, so themes can also use `--wp--style--color-link: var(--wp--preset--color--<color-slug>)`. See [the docs](/docs/how-to-guides/themes/theme-json.md#color-properties) for details.
+The framework will take care of enqueing the necessary rules for this to work. Whether or not the theme supports `theme.json` the presets will also be enqueued as CSS Custom Properties, so themes can also use `--wp--style--color-link: var(--wp--preset--color--<color-slug>)`. See [the docs](/docs/how-to-guides/themes/theme-json.md#color-properties) for details.

lib/class-wp-theme-json-resolver.php

@@ -272,7 +272,11 @@ public static function get_core_data() {
 	 */
 	public static function get_theme_data( $theme_support_data = array() ) {
 		if ( null === self::$theme ) {
-			$theme_json_data = self::read_json_file( self::get_file_path_from_theme( 'experimental-theme.json' ) );
+			$theme_json_data = self::read_json_file( self::get_file_path_from_theme( 'theme.json' ) );
+			// Fallback to experimental-theme.json.
+			if ( empty( $theme_json_data ) ) {
+				$theme_json_data = self::read_json_file( self::get_file_path_from_theme( 'experimental-theme.json' ) );
+			}
 			$theme_json_data = self::translate( $theme_json_data, wp_get_theme()->get( 'TextDomain' ) );
 			self::$theme     = new WP_Theme_JSON( $theme_json_data );
 		}
@@ -467,7 +471,11 @@ public static function get_user_custom_post_type_id() {
 	 */
 	public static function theme_has_support() {
 		if ( ! isset( self::$theme_has_support ) ) {
-			self::$theme_has_support = (bool) self::get_file_path_from_theme( 'experimental-theme.json' );
+			self::$theme_has_support = (bool) self::get_file_path_from_theme( 'theme.json' );
+			if ( ! self::$theme_has_support ) {
+				// Fallback to experimental-theme.json.
+				self::$theme_has_support = (bool) self::get_file_path_from_theme( 'experimental-theme.json' );
+			}
 		}
 
 		return self::$theme_has_support;