Rename experimental-theme.json to theme.json and add a fallback for backwards-compatibility

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

@@ -1,15 +1,15 @@
 # Full Site Editing
 
-At the highest level, the vision of Full Site Editing is to provide a collection of features that bring the familiar experience and extendability of blocks to all parts of your site rather than just post and pages. You can think of Full Site Editing as the umbrella project name for various sub-projects within Gutenberg that make this vision possible. Projects under Full Site Editing (FSE) include everything from the Site Editor, Global Styles, numerous Site/Post/Page specific blocks, Query block, Navigation block, Templates, and block themes. What follows are brief descriptions of the major pieces with more details found [here](https://github.com/WordPress/gutenberg/issues/24551): 
+At the highest level, the vision of Full Site Editing is to provide a collection of features that bring the familiar experience and extendability of blocks to all parts of your site rather than just post and pages. You can think of Full Site Editing as the umbrella project name for various sub-projects within Gutenberg that make this vision possible. Projects under Full Site Editing (FSE) include everything from the Site Editor, Global Styles, numerous Site/Post/Page specific blocks, Query block, Navigation block, Templates, and block themes. What follows are brief descriptions of the major pieces with more details found [here](https://github.com/WordPress/gutenberg/issues/24551):
 
-- Site Editor: the cohesive experience that allows you to directly edit and navigate between various templates, template parts, styling options, and more. 
-- Template Editing: a scaled down direct editing experience allowing you to edit/change/create the template a post/page uses. 
-- Block Theme: work to allow for a theme that's built using templates composed using blocks that works with full site editing. More below. 
+- Site Editor: the cohesive experience that allows you to directly edit and navigate between various templates, template parts, styling options, and more.
+- Template Editing: a scaled down direct editing experience allowing you to edit/change/create the template a post/page uses.
+- Block Theme: work to allow for a theme that's built using templates composed using blocks that works with full site editing. More below.
 - Styling: the feature that enables styling modifications across three levels (local blocks, theme defaults, and global modifications).
-- Theme Blocks: new blocks that accomplish everything possible in traditional templates using template tags (ex: Post Author Block). 
-- Browsing: the feature that unlocks the ability to navigate between various entities in the site editing experience including templates, pages, etc. 
+- Theme Blocks: new blocks that accomplish everything possible in traditional templates using template tags (ex: Post Author Block).
+- Browsing: the feature that unlocks the ability to navigate between various entities in the site editing experience including templates, pages, etc.
 - Navigation Block: a new block that allows you to edit a site's navigation menu, both in terms of structure and design.
-- Query Block: a new block that replicates the classic WP_Query and allows for further customization with additional functionality. 
+- Query Block: a new block that replicates the classic WP_Query and allows for further customization with additional functionality.
 
 There are other projects, like the Navigation Editor and Widget Editor, that are meant to specifically help classic themes begin adapting more to the block framework and to act as a stepping stone of sorts to Full Site Editing. These are separate projects from Full Site Editing though but are worth being aware of as they ultimately help the cause of getting more people adjusted to using blocks in more places.
 
@@ -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

@@ -10,10 +10,13 @@ This tutorial is up to date as of Gutenberg version 9.1.
 
 ## Table of Contents
 
-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)
+- [Create a block theme](#create-a-block-theme)
+	- [Table of Contents](#table-of-contents)
+	- [What is needed to create a block theme?](#what-is-needed-to-create-a-block-theme)
+		- [Required files and file structure](#required-files-and-file-structure)
+	- [Creating the theme](#creating-the-theme)
+		- [Creating the templates and template parts](#creating-the-templates-and-template-parts)
+		- [theme.json - Global styles](#themejson---global-styles)
 
 ## What is needed to create a block theme?
 
@@ -27,7 +30,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 +39,7 @@ theme
 |__ style.css
 |__ functions.php
 |__ index.php
-|__ experimental-theme.json
+|__ theme.json
 |__ block-templates
 	|__ index.html
 	|__ single.html
@@ -179,9 +182,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 +194,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 should [define default link colors](https://developer.wordpress.org/block-editor/developers/themes/theme-json/#color-properties) in `theme.json` (or in its theme styles if no `theme.json` is present). For example:
 
 ```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;