Stabilise gradient theme API's (#20107)

docs/designers-developers/developers/themes/theme-support.md

@@ -148,7 +148,7 @@ Different blocks have the possibility of selecting from a list of predefined gra
 
 ```php
 add_theme_support(
-	'__experimental-editor-gradient-presets',
+	'editor-gradient-presets',
 	array(
 		array(
 			'name'     => __( 'Vivid cyan blue to vivid purple', 'themeLangDomain' ),
@@ -181,6 +181,14 @@ add_theme_support(
 
 `name` is a human-readable label (demonstrated above) that appears in the tooltip and provides a meaningful description of the gradient to users. It is especially important for those who rely on screen readers or would otherwise have difficulty perceiving the color. `gradient` is a CSS value of a gradient applied to a background-image of the block. Details of valid gradient types can be found in the [mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Images/Using_CSS_gradients). `slug` is a unique identifier for the gradient and is used to generate the CSS classes used by the block editor.
 
+Themes are responsible for creating the classes that apply the gradients. So to correctly apply "Vivid cyan blue to vivid purple" a theme should implement the following class:
+
+```css
+.has-vivid-cyan-blue-to-vivid-purple-gradient-background {
+	background: linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%);
+}
+```
+
 
 ### Block Font Sizes:
 
@@ -248,6 +256,16 @@ add_theme_support( 'disable-custom-colors' );
 
 This flag will make sure users are only able to choose colors from the `editor-color-palette` the theme provided or from the editor default colors if the theme did not provide one.
 
+### Disabling custom gradients
+
+Themes can disable the ability to set a custom gradient with the following code:
+
+```php
+add_theme_support( 'disable-custom-gradients' );
+```
+
+When set, users will be restricted to the default gradients provided in the block editor or the gradients provided via the `editor-gradient-presets` theme support setting.
+
 ## Editor styles
 
 The block editor supports the theme's [editor styles](https://codex.wordpress.org/Editor_Style), however it works a little differently than in the classic editor.

lib/experiments-page.php

@@ -149,12 +149,12 @@ function gutenberg_experiments_editor_settings( $settings ) {
 		'__experimentalEnablePageTemplates'       => gutenberg_is_experiment_enabled( 'gutenberg-page-templates' ),
 	);
 
-	$gradient_presets = current( (array) get_theme_support( '__experimental-editor-gradient-presets' ) );
+	$gradient_presets = current( (array) get_theme_support( 'editor-gradient-presets' ) );
 	if ( false !== $gradient_presets ) {
 		$experiments_settings['gradients'] = $gradient_presets;
 	}
 
-	$experiments_settings['disableCustomGradients'] = get_theme_support( '__experimental-disable-custom-gradients' );
+	$experiments_settings['disableCustomGradients'] = get_theme_support( 'disable-custom-gradients' );
 
 	return array_merge( $settings, $experiments_settings );
 }