Update documentation for link color in WordPress 5.8 (#33162)

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

@@ -391,20 +391,34 @@ Some blocks can have padding controls. This is off by default, and requires the
 add_theme_support('custom-spacing');
 ```
 
-## Experimental — Link color control
-
-Using the Gutenberg plugin (version 8.3 or later), link color control is available to a number of blocks including Paragraph, Heading, Group, Columns, and Media & Text blocks. This is off by default, and requires the theme to opt in by declaring support:
-
-```php
-add_theme_support('experimental-link-color');
+## Link color control
+
+Link support has been made stable as part of WordPress 5.8. It's `false` by default and themes can enable it via the [theme.json file](./theme-json.md):
+
+```json
+{
+	"version": 1,
+	"settings": {
+		"color": {
+			"link": true
+		}
+	}
+}
 ```
 
- 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:
+> Alternatively, with the Gutenberg plugin active, the old legacy support `add_theme_support('experimental-link-color')` would also work. This fallback would be removed when the Gutenberg plugin requires WordPress 5.8 as the minimum version.
+
+When the user sets the link color of a block, a new style will be added in the form of:
 
 ```css
-:root {
-	--wp--style--color--link: <value>;
+.wp-elements-<uuid> a {
+	color: <link-color> !important;
 }
 ```
 
-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.
+where
+
+- `<uuid>` is a random number
+- `<link-color>` is either `var(--wp--preset--color--slug)` (if the user selected a preset value) or a raw color value (if the user selected a custom value)
+
+The block will get attached the class `.wp-elements-<uuid>`.

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

@@ -1348,6 +1348,10 @@ public static function get_from_editor_settings( $settings ) {
 		}
 
 		// Things that didn't land in core yet, so didn't have a setting assigned.
+		// This should be removed when the plugin minimum WordPress version
+		// is bumped to 5.8.
+		//
+		// Do not port this to WordPress core.
 		if ( current( (array) get_theme_support( 'experimental-link-color' ) ) ) {
 			if ( ! isset( $theme_settings['settings']['color'] ) ) {
 				$theme_settings['settings']['color'] = array();