Explain :focus-visible intent, add examples and UA guidance

Author: Alice Boxhall

selectors-4/Overview.bs

@@ -2237,62 +2237,84 @@ The Focus-Indicated Pseudo-class: '':focus-visible''</h3>
 
 	The <dfn id='focus-visible-pseudo'>:focus-visible</dfn> pseudo-class applies
 	while an element matches the '':focus'' pseudo-class
-	<em>and</em> the UA determines via heuristics
+	<em>and</em> the user agent determines via heuristics
 	that the focus should be made evident on the element.
-	(Many browsers show a “focus ring” by default in this case.)
 
-	<div class=example>
-		For example, UAs typically display focus indicators on text fields
-		any time they're focused,
-		to draw attention to the fact that keyboard input will affect their contents.
-
-		On the other hand, UAs typically only display focus indicators on buttons
-		when they were focused by a keyboard interaction
-		(such as tabbing through the document)--
-		because it's not always immediately obvious
-		where the focus has gone after such an interaction,
-		but is sufficiently self-evident when the button was focused
-		by more obviously-targetted interactions,
-		like clicking on the button with a mouse pointer.
+  <div class=note>
+	The intent of '':focus-visible'' is 
+	to allow authors to provide <em>clearly identifiable</em> focus styles
+	which are visible when a user is likely to need to understand where focus is,
+  and not visible in other cases.
 	</div>
 
-	<div class=advisement>
-		Page authors should follow these guidelines
-		when deciding whether to use '':focus'' or '':focus-visible''
-		to style the focused state of an element:
-
-		* If the element has “native” focus indicator behavior
-			(such as text fields or buttons),
-			use '':focus-visible''.
-		* Otherwise, if the element is emulating a text input,
-			or something else that is <em>intended</em> to receive keyboard interaction,
-			use '':focus''.
-		* Otherwise,
-			use '':focus-visible''.
+	<div class="example">
+	  In this example, 
+		all focusable elements get a strong yellow outline on '':focus-visible'',
+		and links get both a yellow outline and a yellow background on '':focus-visible''.
+		These styles are consistent throughout the page and are easily visible
+		due to their bold styling,
+		but do not appear unless the user is likely to need to understand
+		where page focus is.
+
+	  <pre>
+		:root {
+			focus-gold: #ffbf47;
+		}
+
+		:focus-visible  {
+      outline: 3px solid --var(focus-gold);
+    }
+
+		a:focus-visible {
+	    background-color: --var(focus-gold);
+	  }
+		</pre>
 	</div>
 
-	When UAs choose to specially indicate focus on an element,
-	or whether they specially indicate focus at all,
-	is UA-dependent.
-	Different UAs,
-	the same UA on different operating systems,
-	or the same UA on the same OS,
-	but with different user settings,
-	can make different choices as to when an element matches '':focus-visible''.
+	User agents may choose their own heuristics for when to match '':focus-visible'';
+	however, the following <em>may</em> be used as a starting point:
+	<ul>
+		<li>Any element which supports user input
+		(such as an ''&lt;input&gt;'' element, 
+		or editing host) 
+		should <strong>always</strong> match '':focus-visible'' when focused.</li>
+		<li>If the user interacts with the page via the keyboard,
+		the currently focused element should match '':focus-visible''
+		(i.e. keyboard usage may change whether this pseudo-class matches
+		even if it doesn't affect '':focus''). 
+		<li>If the user interacts with the page via a pointing device,
+		such that the focus is moved to a new element 
+		which does <em>not</em> support user input,
+		the newly focused element 
+		should <strong>not</strong> not match '':focus-visible''.</li>
+		<li>If the active element matches '':focus-visible'', 
+		and a script causes focus to move elsewhere,
+		the newly focused element should match '':focus-visible''.</li>
+		<li>Conversely, if the active element does not match '':focus-visible'', 
+		and a script causes focus to move elsewhere, 
+		the newly focused element should <strong>not</strong> match '':focus-visible''.</li>
+	</ul>
+
+	<div class=note>
+	User agents should also use '':focus-visible'' to specify the default focus style,
+	so that authors using '':focus-visible'' will not also need to disable 
+	the default '':focus'' style.
+	</div>
 
 	<div class=example>
-		The following guidelines are suggested heuristics
-		for choosing when to apply '':focus-visible''
-		to elements without “native” focus indicator behavior:
-
-		* If the element received focus via a keyboard interaction,
-			including indirectly,
-			such as triggering a dialog
-			by pressing a button using the keyboard,
-			apply '':focus-visible''.
-		* If a keyboard event occurs while an element is focused,
-			even if the element wasn't focused by a keyboard interaction,
-			apply '':focus-visible''.
+	In this example, 
+	authors use a '':not'' pseudo-selector to remove default user agent focus styling
+	if '':focus-visible'' is supported,
+	and provide enhanced focus styling via '':focus-visible''.
+
+	<pre>
+	:focus:not(:focus-visible) {
+		outline: 0;
+	}
+
+	:focus-visible {
+      outline: 3px solid --var(focus-gold);
+	}
 	</div>
 
 <h3 id="the-focus-within-pseudo">