[css-position-4] Expand/rewrite the overlay guidance to make it clearer exactly what its purpose is. w3c#8730

Author: tabatkins

css-position-4/Overview.bs

@@ -574,6 +574,17 @@ Top Layer Manipulation {#top-manip}
 	see [[#overlay]] for details.
 </div>
 
+
+<!--
+ ███████  ██     ██ ████████ ████████  ██          ███    ██    ██
+██     ██ ██     ██ ██       ██     ██ ██         ██ ██    ██  ██
+██     ██ ██     ██ ██       ██     ██ ██        ██   ██    ████
+██     ██ ██     ██ ██████   ████████  ██       ██     ██    ██
+██     ██  ██   ██  ██       ██   ██   ██       █████████    ██
+██     ██   ██ ██   ██       ██    ██  ██       ██     ██    ██
+ ███████     ███    ████████ ██     ██ ████████ ██     ██    ██
+-->
+
 Controlling the Top Layer: the 'overlay' property {#overlay}
 -------------------------------------------------
 
@@ -585,49 +596,66 @@ Inherited: no
 Animation Type: (see prose)
 </pre>
 
-The 'overlay' property determines and reflects
-whether an element is in the [=Document/top layer=] or not.
-Its values are:
+The 'overlay' property is used to help determine
+whether an element should be in the [=Document/top layer=] or not.
 
 <dl dfn-type=value dfn-for=overlay>
 	: <dfn>none</dfn>
-	:: The element is not in the [=Document/top layer=].
+	:: The element shouldn't be in the [=Document/top layer=].
 
 	: <dfn>auto</dfn>
-	:: The element is rendered as part of the [=Document/top layer=].
+	:: The element should be in the [=Document/top layer=].
 		Rather than generating boxes as part of its normal position in the document,
 		it generates boxes as a sibling of the root element.
 </dl>
 
+<div class=note id=overlay-guidance>
+	Note: 'overlay' is a somewhat unusual property:
+	it is <em>only</em> set by the user agent,
+	and can't be set by authors <em>at all</em>.
+	As well, it has almost no effect:
+	an element is [=rendered in the top layer=]
+	as soon as it's [=in the top layer=]
+	and stops as soon as it's not;
+	the 'overlay' property doesn't affect this.
+
+	However, when the user agent wants to remove an element from the [=Document/top layer=],
+	it checks 'overlay' first;
+	if it's still ''overlay/auto'',
+	it delays the removal until it's ''overlay/none''.
+	The user agent is in control of when it goes from ''overlay/auto'' to ''overlay/none'',
+	but authors <em>can</em> set a 'transition' on 'overlay',
+	delaying its change.
+
+	This delay period can then be paired with other animations or transitions
+	to create an "exit animation"--
+	animating the element leaving the top layer,
+	for example by fading its 'opacity'--
+	without it <em>also</em> immediately rendering back in the normal document
+	and possibly becoming obscured.
+</div>
+
 For animation,
 ''overlay/auto'' is [=interpolated=] as a discrete step
 where values of p such that <code>0 < p < 1</code>
 map to ''overlay/auto''
 and other values of p map to the closer endpoint;
 if neither value is ''overlay/auto'' then discrete animation is used.
 
+Note: This is similar to how 'visibility' animates.
+
 User agents must have the following rule in their UA stylesheet:
 
 <pre highlight=css>
 * { overlay: none !important; }
 </pre>
 
-This means that the 'overlay' property <em>cannot be set by authors or users</em>--
+Note: This means that the 'overlay' property <em>cannot be set by authors or users</em>--
 it is entirely controlled by the user agent
 (which sets elements to ''overlay: auto'',
 via another UA-!important rule,
 when they're in the [=Document/top layer=]).
 
-However, authors <em>can</em> set a [=transition=] on 'overlay',
-forcing it to stay ''overlay/auto'' for a period of time
-(keeping the element in the [=Document/top layer=])
-so an "exit animation" can be used on the element
-(such as fading it out,
-moving it offscreen,
-scaling it down,
-etc)
-before it goes back to its normal, non-top-layer rendering.
-
 User agents <em>may</em>, at their discretion,
 remove a running [=transition=] on 'overlay'.
 The conditions for this are intentionally undefined.