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

selectors-4/Overview.bs

@@ -2237,62 +2237,91 @@ 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>
+
+	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 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 highlight=css>
+		:root {
+			focus-gold: #ffbf47;
+		}
 
-	<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''.
+		: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 can choose their own heuristics for when to match '':focus-visible'';
+	however, the following (non-normative) suggestions can be used as a starting point:
+
+	* If a user has expressed a preference
+		(such as via a system preference or a browser setting)
+		to always see a visible focus indicator,
+		the user agent should honor this 
+		by having '':focus-visible'' always match on the active element,
+		regardless of any other factors.
+		(Another option may be for the user agent to show its own focus indicator
+		regardless of author styles.)
+	* Any element which supports keyboard input
+		(such as an <{input}> element, 
+		or any other element 
+		which may trigger a virtual keyboard to be shown on focus
+		if a physical keyboard is not present) 
+		should <strong>always</strong> match '':focus-visible'' when focused.
+	* 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''). 
+	* 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> match '':focus-visible''.
+	* If the active element matches '':focus-visible'', 
+		and a script causes focus to move elsewhere,
+		the newly focused element should match '':focus-visible''.
+	* 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''.
+
+	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-class to remove default user agent focus styling
+	if '':focus-visible'' is supported,
+	and provide enhanced focus styling via '':focus-visible''.
+
+	<pre highlight=css>
+	:focus:not(:focus-visible) {
+		outline: 0;
+	}
+
+	:focus-visible {
+ 		outline: 3px solid --var(focus-gold);
+	}
 	</div>
 
 <h3 id="the-focus-within-pseudo">