theme.json docs: add examples and highlight backward compatibility with add_theme_support (#33421)

Author: nosolosw

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

@@ -10,8 +10,10 @@ WordPress 5.8 comes with [a new mechanism](https://make.wordpress.org/core/2021/
 - Specification
     - version
     - settings
+        - Backward compatibility with add_theme_support
         - Presets
         - Custom
+        - Setting examples
     - styles
         - Top-level
         - Block-level
@@ -269,6 +271,10 @@ The settings section has the following structure:
 
 Each block can configure any of these settings separately, providing a more fine-grained control over what exists via `add_theme_support`. The settings declared at the top-level affect to all blocks, unless a particular block overwrites it. It's a way to provide inheritance and configure all blocks at once.
 
+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`.
+
+#### Backward compatibility with add_theme_support
+
 To retain backward compatibility, the existing `add_theme_support` declarations that configure the block editor are retrofit in the proper categories for the top-level section. For example, if a theme uses `add_theme_support('disable-custom-colors')`, it'll be the same as setting `settings.color.custom` to `false`. If the `theme.json` contains any settings, these will take precedence over the values declared via `add_theme_support`. This is the complete list of equivalences:
 
 | add_theme_support           | theme.json setting                                        |
@@ -284,28 +290,6 @@ To retain backward compatibility, the existing `add_theme_support` declarations
 | `editor-gradient-presets`   | Provide the list of gradients via `color.gradients`.      |
 | `experimental-link-color`   | Set `color.link` to `true`.                               |
 
-Let's say a theme author wants to enable custom colors only for the paragraph block. This is how it can be done:
-
-```json
-{
-	"version": 1,
-	"settings": {
-		"color": {
-			"custom": false
-		},
-		"blocks": {
-			"core/paragraph": {
-				"color": {
-					"custom": true
-				}
-			}
-		}
-	}
-}
-```
-
-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
 
 Presets are part of the settings section. They are values that are shown to the user via some UI controls. By defining them via `theme.json` the engine can do more for themes, such as automatically translate the preset name or enqueue the corresponding CSS classes and custom properties.
@@ -511,6 +495,98 @@ body {
 
 Note that the name of the variable is created by adding `--` in between each nesting level and `camelCase` fields are transformed to `kebab-case`.
 
+#### Settings examples
+
+- Enable custom colors only for the paragraph block:
+
+```json
+{
+	"version": 1,
+	"settings": {
+		"color": {
+			"custom": false
+		},
+		"blocks": {
+			"core/paragraph": {
+				"color": {
+					"custom": true
+				}
+			}
+		}
+	}
+}
+```
+
+- Disable border radius for the button block (borders only work in the plugin so far):
+
+```json
+{
+	"version": 1,
+	"settings": {
+		"core/button": {
+			"border": {
+				"customRadius": false
+			}
+		}
+	}
+}
+```
+
+- Provide the group block a different palette than the rest:
+
+```json
+{
+	"version": 1,
+	"settings": {
+		"color": {
+			"palette": [
+				{
+					"slug": "black",
+					"color": "#000000",
+					"name": "Black"
+				},
+				{
+					"slug": "white",
+					"color": "#FFFFFF",
+					"name": "White"
+				},
+				{
+					"slug": "red",
+					"color": "#FF0000",
+					"name": "Red"
+				},
+				{
+					"slug": "green",
+					"color": "#00FF00",
+					"name": "Green"
+				},
+				{
+					"slug": "blue",
+					"color": "#0000FF",
+					"name": "Blue"
+				}
+			]
+		},
+		"core/group": {
+			"color": {
+				"palette": [
+					{
+						"slug": "black",
+						"color": "#000000",
+						"name": "Black"
+					},
+					{
+						"slug": "white",
+						"color": "#FFF",
+						"name": "White"
+					}
+				]
+			}
+		}
+	}
+}
+```
+
 ### Styles
 
 <div class="callout callout-alert">