Add a description key to theme.json style variations

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

@@ -313,10 +313,12 @@ class WP_Theme_JSON_Gutenberg {
 	 * @since 5.8.0 As `ALLOWED_TOP_LEVEL_KEYS`.
 	 * @since 5.9.0 Renamed from `ALLOWED_TOP_LEVEL_KEYS` to `VALID_TOP_LEVEL_KEYS`,
 	 *              added the `customTemplates` and `templateParts` values.
+	 * @since 6.3.0 Added the `description` value.
 	 * @var string[]
 	 */
 	const VALID_TOP_LEVEL_KEYS = array(
 		'customTemplates',
+		'description',
 		'patterns',
 		'settings',
 		'styles',

lib/theme-i18n.json

@@ -1,5 +1,6 @@
 {
 	"title": "Style variation name",
+	"description": "Style variation description",
 	"settings": {
 		"typography": {
 			"fontSizes": [

packages/edit-site/src/components/global-styles/style-variations-container.js

@@ -11,7 +11,7 @@ import { useSelect } from '@wordpress/data';
 import { useMemo, useContext, useState } from '@wordpress/element';
 import { ENTER } from '@wordpress/keycodes';
 import { __experimentalGrid as Grid } from '@wordpress/components';
-import { __ } from '@wordpress/i18n';
+import { __, sprintf } from '@wordpress/i18n';
 import { privateApis as blockEditorPrivateApis } from '@wordpress/block-editor';
 
 /**
@@ -60,6 +60,16 @@ function Variation( { variation } ) {
 		return areGlobalStyleConfigsEqual( user, variation );
 	}, [ user, variation ] );
 
+	let label = variation?.title;
+	if ( variation?.description ) {
+		label = sprintf(
+			/* translators: %1$s: variation title. %2$s variation description. */
+			__( '%1$s (%2$s)' ),
+			variation?.title,
+			variation?.description
+		);
+	}
+
 	return (
 		<GlobalStylesContext.Provider value={ context }>
 			<div
@@ -73,7 +83,7 @@ function Variation( { variation } ) {
 				onClick={ selectVariation }
 				onKeyDown={ selectOnEnter }
 				tabIndex="0"
-				aria-label={ variation?.title }
+				aria-label={ label }
 				aria-current={ isActive }
 				onFocus={ () => setIsFocused( true ) }
 				onBlur={ () => setIsFocused( false ) }

schemas/json/theme.json

@@ -2049,6 +2049,10 @@
 			"type": "string",
 			"description": "Title of the global styles variation. If not defined, the file name will be used."
 		},
+		"description": {
+			"type": "string",
+			"description": "Description of the global styles variation."
+		},
 		"settings": {
 			"description": "Settings for the block editor and individual blocks. These include things like:\n- Which customization options should be available to the user. \n- The default colors, font sizes... available to the user. \n- CSS custom properties and class names used in styles.\n- And the default layout of the editor (widths and available alignments).",
 			"type": "object",