Document that transparent StyleBoxes/textures should be used for UI focus

12 files changed, 12 insertions, 12 deletions

diff --git a/doc/classes/Button.xml b/doc/classes/Button.xml
index d1a19861e4..65b66b2fd5 100644
--- a/doc/classes/Button.xml
+++ b/doc/classes/Button.xml
@@ -149,7 +149,7 @@
 			[StyleBox] used when the [Button] is disabled.
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			[StyleBox] used when the [Button] is focused. It is displayed over the current [StyleBox], so using [StyleBoxEmpty] will just disable the focus visual effect.
+			[StyleBox] used when the [Button] is focused. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 		<theme_item name="hover" data_type="style" type="StyleBox">
 			[StyleBox] used when the [Button] is being hovered.
diff --git a/doc/classes/CheckBox.xml b/doc/classes/CheckBox.xml
index 32ef70a5cf..6180f56858 100644
--- a/doc/classes/CheckBox.xml
+++ b/doc/classes/CheckBox.xml
@@ -76,7 +76,7 @@
 			The [StyleBox] to display as a background when the [CheckBox] is disabled.
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			The [StyleBox] to display as a background when the [CheckBox] is focused.
+			The [StyleBox] to display as a background when the [CheckBox] is focused. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 		<theme_item name="hover" data_type="style" type="StyleBox">
 			The [StyleBox] to display as a background when the [CheckBox] is hovered.
diff --git a/doc/classes/CheckButton.xml b/doc/classes/CheckButton.xml
index cf3aa869c3..659fb5126f 100644
--- a/doc/classes/CheckButton.xml
+++ b/doc/classes/CheckButton.xml
@@ -78,7 +78,7 @@
 			The [StyleBox] to display as a background when the [CheckButton] is disabled.
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			The [StyleBox] to display as a background when the [CheckButton] is focused.
+			The [StyleBox] to display as a background when the [CheckButton] is focused. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 		<theme_item name="hover" data_type="style" type="StyleBox">
 			The [StyleBox] to display as a background when the [CheckButton] is hovered.
diff --git a/doc/classes/CodeEdit.xml b/doc/classes/CodeEdit.xml
index 04c3d73357..59da64314b 100644
--- a/doc/classes/CodeEdit.xml
+++ b/doc/classes/CodeEdit.xml
@@ -680,7 +680,7 @@
 			[StyleBox] for the code completion popup.
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			Sets the [StyleBox] when in focus.
+			Sets the [StyleBox] when in focus. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 		<theme_item name="normal" data_type="style" type="StyleBox">
 			Sets the [StyleBox].
diff --git a/doc/classes/ColorPickerButton.xml b/doc/classes/ColorPickerButton.xml
index 2f78b10660..7fd6ffcc0d 100644
--- a/doc/classes/ColorPickerButton.xml
+++ b/doc/classes/ColorPickerButton.xml
@@ -93,7 +93,7 @@
 			[StyleBox] used when the [ColorPickerButton] is disabled.
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			[StyleBox] used when the [ColorPickerButton] is focused. It is displayed over the current [StyleBox], so using [StyleBoxEmpty] will just disable the focus visual effect.
+			[StyleBox] used when the [ColorPickerButton] is focused. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 		<theme_item name="hover" data_type="style" type="StyleBox">
 			[StyleBox] used when the [ColorPickerButton] is being hovered.
diff --git a/doc/classes/LineEdit.xml b/doc/classes/LineEdit.xml
index 06094300de..c3e3088d69 100644
--- a/doc/classes/LineEdit.xml
+++ b/doc/classes/LineEdit.xml
@@ -422,7 +422,7 @@
 			Texture for the clear button. See [member clear_button_enabled].
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			Background used when [LineEdit] has GUI focus.
+			Background used when [LineEdit] has GUI focus. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 		<theme_item name="normal" data_type="style" type="StyleBox">
 			Default background for the [LineEdit].
diff --git a/doc/classes/LinkButton.xml b/doc/classes/LinkButton.xml
index 17a9e13842..a20db4d7e9 100644
--- a/doc/classes/LinkButton.xml
+++ b/doc/classes/LinkButton.xml
@@ -94,7 +94,7 @@
 			Font size of the [LinkButton]'s text.
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			[StyleBox] used when the [LinkButton] is focused. It is displayed over the current [StyleBox], so using [StyleBoxEmpty] will just disable the focus visual effect.
+			[StyleBox] used when the [LinkButton] is focused. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 	</theme_items>
 </class>
diff --git a/doc/classes/MenuButton.xml b/doc/classes/MenuButton.xml
index b0774d4cab..632b22c1de 100644
--- a/doc/classes/MenuButton.xml
+++ b/doc/classes/MenuButton.xml
@@ -80,7 +80,7 @@
 			[StyleBox] used when the [MenuButton] is disabled.
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			[StyleBox] used when the [MenuButton] is focused. It is displayed over the current [StyleBox], so using [StyleBoxEmpty] will just disable the focus visual effect.
+			[StyleBox] used when the [MenuButton] is focused. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 		<theme_item name="hover" data_type="style" type="StyleBox">
 			[StyleBox] used when the [MenuButton] is being hovered.
diff --git a/doc/classes/OptionButton.xml b/doc/classes/OptionButton.xml
index d2f9b08fbf..b91d8f22a7 100644
--- a/doc/classes/OptionButton.xml
+++ b/doc/classes/OptionButton.xml
@@ -228,7 +228,7 @@
 			[StyleBox] used when the [OptionButton] is disabled (for right-to-left layouts).
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			[StyleBox] used when the [OptionButton] is focused. It is displayed over the current [StyleBox], so using [StyleBoxEmpty] will just disable the focus visual effect.
+			[StyleBox] used when the [OptionButton] is focused. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 		<theme_item name="hover" data_type="style" type="StyleBox">
 			[StyleBox] used when the [OptionButton] is being hovered (for left-to-right layouts).
diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml
index 84956805c9..1a6fa65f75 100644
--- a/doc/classes/RichTextLabel.xml
+++ b/doc/classes/RichTextLabel.xml
@@ -593,7 +593,7 @@
 			The default text font size.
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			The background The background used when the [RichTextLabel] is focused.
+			The background used when the [RichTextLabel] is focused. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 		<theme_item name="normal" data_type="style" type="StyleBox">
 			The normal background for the [RichTextLabel].
diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml
index ffc91decca..d6738bfb89 100644
--- a/doc/classes/TextEdit.xml
+++ b/doc/classes/TextEdit.xml
@@ -1271,7 +1271,7 @@
 			Sets a custom [Texture2D] for tab text characters.
 		</theme_item>
 		<theme_item name="focus" data_type="style" type="StyleBox">
-			Sets the [StyleBox] when in focus.
+			Sets the [StyleBox] when in focus. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</theme_item>
 		<theme_item name="normal" data_type="style" type="StyleBox">
 			Sets the [StyleBox] of this [TextEdit].
diff --git a/doc/classes/TextureButton.xml b/doc/classes/TextureButton.xml
index 2be27617ab..476ab2d1bf 100644
--- a/doc/classes/TextureButton.xml
+++ b/doc/classes/TextureButton.xml
@@ -31,7 +31,7 @@
 			Texture to display when the node is disabled. See [member BaseButton.disabled].
 		</member>
 		<member name="texture_focused" type="Texture2D" setter="set_focused_texture" getter="get_focused_texture">
-			Texture to display when the node has mouse or keyboard focus.
+			Texture to display when the node has mouse or keyboard focus. [member texture_focused] is displayed [i]over[/i] the base texture, so a partially transparent texture should be used to ensure the base texture remains visible. A texture that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a fully transparent texture of any size. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
 		</member>
 		<member name="texture_hover" type="Texture2D" setter="set_hover_texture" getter="get_hover_texture">
 			Texture to display when the mouse hovers the node.