[css-cascade-6][editorial] Reorganize and update examples

Author: mirisuzanne

css-cascade-6/Overview.bs

@@ -261,20 +261,26 @@ Scoping Styles: the ''@scope'' rule</h3>
 		For example,
 		an author might have wide-reaching color-scheme scopes,
 		which overlap more narrowly-scoped design patterns
-		such as a media object:
+		such as a media object.
+		The selectors in the ''@scope'' rule
+		establish [=scoping root=] and optional [=scoping limit=] elements,
+		while the nested selectors only match elements
+		that are [=in scope|in a resulting scope=]:
 
 		<pre class=lang-css>
 		@scope (.light-scheme) {
+		  /* Only match links inside a light-scheme */
 		  a { color: darkmagenta; }
 		}
 
 		@scope (.dark-scheme) {
+		  /* Only match links inside a dark-scheme */
 		  a { color: plum; }
 		}
 
 		@scope (.media-object) {
-		  .media-image { border-radius: 50%; }
-		  .media-content { padding: 1em; }
+		  /* Only match author images inside a media-object */
+		  .author-image { border-radius: 50%; }
 		}
 		</pre>
 	</div>
@@ -299,29 +305,10 @@ Scoping Styles: the ''@scope'' rule</h3>
 
 	Issue: Should scoping limits be added to the definition of [=scoped selectors=]?
 
-	<div class=example>
-		[=Scoping limits=] can use the '':scope'' pseudo-class
-		to require a specific relationship to the [=scoping root=]:
-
-		<pre class=lang-css>
-		/* .content is only a limit when it is a direct child of the :scope */
-		@scope (.media-object) to (:scope > .content) { ... }
-		</pre>
-
-		[=Scoping limits=] can also reference elements outside their [=scoping root=]
-		by using '':scope''.
-		For example:
-
-		<pre class=lang-css>
-		/* .content is only a limit when the :scope is inside .sidebar */
-		@scope (.media-object) to (.sidebar :scope .content) { ... }
-		</pre>
-	</div>
 
 <h4 id="scope-effects">
 Effects of ''@scope''</h4>
 
-
 	The ''@scope'' [=at-rule=] has three primary effects
 	on the [=style rules=] it contains:
 
@@ -356,72 +343,6 @@ Effects of ''@scope''</h4>
 	selectors within an ''@scope'' rule
 	do not acquire the specificity of any parent selector(s) in the ''@scope'' prelude.
 
-<h4 id="scope-syntax">
-Syntax of ''@scope''</h4>
-
-	The syntax of the ''@scope'' rule is:
-
-	<pre class="prod def">
-	@scope [(<<scope-start>>)]? [to (<<scope-end>>)]? {
-	  <<stylesheet>>
-	}
-	</pre>
-
-	where:
-
-	* <dfn><<scope-start>></dfn> is a <<forgiving-selector-list>> [=selector=]
-		used to identify the [=scoping root=](s).
-	* <dfn><<scope-end>></dfn> is a <<forgiving-selector-list>> [=selector=]
-		used to identify any [=scoping limits=].
-	* the <<stylesheet>> represents the [=scoped style rules=].
-
-	[=Pseudo-elements=] cannot be [=scoping roots=] or [=scoping limits=];
-	they are invalid both within <<scope-start>> and <<scope-end>>.
-
-<h4 id="scoped-rules">
-Scoped Style Rules</h4>
-
-	<dfn>Scoped style rules</dfn> differ from non-scoped rules
-	in the following ways:
-
-	* Their selectors can only match elements that are [=in scope=].
-		(This only applies to the [=subject=];
-		the rest of the selector can match unrestricted.)
-
-	* They accept a <<relative-selector-list>> as their prelude
-		(rather than just a <<selector-list>>).
-		Such [=relative selectors=]
-		are relative to '':scope''.
-
-	* Any selector in the <<relative-selector-list>>
-		that does not start with a [=combinator=]
-		but does [=contain the nesting selector=] or the '':scope'' selector,
-		is interpreted as a non-[=relative selector=]
-		(but the [=subject=] must still be [=in scope=] to match).
-
-<h4 id="scope-limits">
-Identifying Scoping Roots and Limits</h4>
-
-	A ''@scope'' rule produces one or more [=scopes=] as follows:
-
-	: Finding the [=scoping root=](s)
-	:: For each element matched by <<scope-start>>,
-		create a [=scope=] using that element as the [=scoping root=].
-		If no <<scope-start>> is specified,
-		the [=scoping root=] is the [=parent element=] of the [=owner node=]
-		of the stylesheet where the ''@scope'' rule is defined.
-		(If no such element exists,
-		then the [=scoping root=] is the [=root=] of the containing [=node tree=].)
-		Any '':scope'' or ''&'' selectors in <<scope-start>>
-		are interpreted as defined for its outer context.
-
-	: Finding any [=scoping limits=]
-	:: For each [=scope=] created by a [=scoping root=],
-		its [=scoping limits=] are set to all elements
-		that are [=in scope=] and that match <<scope-end>>,
-		interpreting '':scope'' and ''&''
-		exactly as in [=scoped style rules=].
-
 	<div class=example>
 		The following selectors have the same specificity (0,0,1):
 
@@ -433,8 +354,11 @@ Identifying Scoping Roots and Limits</h4>
 		:where(#hero) img { border-radius: 50%; }
 		</pre>
 
-		But because one <{img}> selector is scoped,
-		that selector is weighted more strongly in the cascade.
+		The additional specificity of the ''#hero'' selector
+		is not applied to the specificity of the scoped selector.
+		However, since one <{img}> selector is scoped,
+		that selector is weighted more strongly in the cascade
+		with the application of [=weak scoping proximity=].
 	</div>
 
 	<div class=example>
@@ -523,6 +447,91 @@ Identifying Scoping Roots and Limits</h4>
 		</pre>
 	</div>
 
+<h4 id="scope-syntax">
+Syntax of ''@scope''</h4>
+
+	The syntax of the ''@scope'' rule is:
+
+	<pre class="prod def">
+	@scope [(<<scope-start>>)]? [to (<<scope-end>>)]? {
+	  <<stylesheet>>
+	}
+	</pre>
+
+	where:
+
+	* <dfn><<scope-start>></dfn> is a <<forgiving-selector-list>> [=selector=]
+		used to identify the [=scoping root=](s).
+	* <dfn><<scope-end>></dfn> is a <<forgiving-selector-list>> [=selector=]
+		used to identify any [=scoping limits=].
+	* the <<stylesheet>> represents the [=scoped style rules=].
+
+	[=Pseudo-elements=] cannot be [=scoping roots=] or [=scoping limits=];
+	they are invalid both within <<scope-start>> and <<scope-end>>.
+
+<h4 id="scoped-rules">
+Scoped Style Rules</h4>
+
+	<dfn>Scoped style rules</dfn> differ from non-scoped rules
+	in the following ways:
+
+	* Their selectors can only match elements that are [=in scope=].
+		(This only applies to the [=subject=];
+		the rest of the selector can match unrestricted.)
+
+	* They accept a <<relative-selector-list>> as their prelude
+		(rather than just a <<selector-list>>).
+		Such [=relative selectors=]
+		are relative to '':scope''.
+
+	* Any selector in the <<relative-selector-list>>
+		that does not start with a [=combinator=]
+		but does [=contain the nesting selector=] or the '':scope'' selector,
+		is interpreted as a non-[=relative selector=]
+		(but the [=subject=] must still be [=in scope=] to match).
+
+<h4 id="scope-limits">
+Identifying Scoping Roots and Limits</h4>
+
+	A ''@scope'' rule produces one or more [=scopes=] as follows:
+
+	: Finding the [=scoping root=](s)
+	:: For each element matched by <<scope-start>>,
+		create a [=scope=] using that element as the [=scoping root=].
+		If no <<scope-start>> is specified,
+		the [=scoping root=] is the [=parent element=] of the [=owner node=]
+		of the stylesheet where the ''@scope'' rule is defined.
+		(If no such element exists,
+		then the [=scoping root=] is the [=root=] of the containing [=node tree=].)
+		Any '':scope'' or ''&'' selectors in <<scope-start>>
+		are interpreted as defined for its outer context.
+
+	: Finding any [=scoping limits=]
+	:: For each [=scope=] created by a [=scoping root=],
+		its [=scoping limits=] are set to all elements
+		that are [=in scope=] and that match <<scope-end>>,
+		interpreting '':scope'' and ''&''
+		exactly as in [=scoped style rules=].
+
+	<div class=example>
+		[=Scoping limits=] can use the '':scope'' pseudo-class
+		to require a specific relationship to the [=scoping root=]:
+
+		<pre class=lang-css>
+		/* .content is only a limit when it is a direct child of the :scope */
+		@scope (.media-object) to (:scope > .content) { ... }
+		</pre>
+
+		[=Scoping limits=] can also reference elements outside their [=scoping root=]
+		by using '':scope''.
+		For example:
+
+		<pre class=lang-css>
+		/* .content is only a limit when the :scope is inside .sidebar */
+		@scope (.media-object) to (.sidebar :scope .content) { ... }
+		</pre>
+	</div>
+
 <h4 id="scope-scope">
 Scope Nesting</h4>