[css-cascade-5] Tighten up cascade layers prose.

Author: fantasai

css-cascade-5/Overview.bs

@@ -869,17 +869,18 @@ Cascade Sorting Order</h3>
 
 		<dt id='cascade-layering'>Layers
 		<dd>
-			Declarations can be explicitly assigned to a [=cascade layer=].
-			Explicit layers are listed in the document order where they are first introduced.
+			Declarations within each [=origin=] and [=context=]
+			can be explicitly assigned to a [=cascade layer=].
 			For the purpose of this step,
 			any declaration not assigned to an explicit layer is added to an implicit final layer.
 
+			Cascade layers (like declarations) are ordered by order of appearance.
 			When comparing declarations that belong to different layers,
 			then for [=normal=] rules the declaration whose [=cascade layer=] is last wins,
 			and for [=important=] rules the declaration whose [=cascade layer=] is first wins.
 
 			Note: This follows the same logic used for layering [=normal=] and [=important=] [=origins=],
-			so that the ''!important'' flag maintains the same semantic purpose in both settings.
+			so that the ''!important'' flag maintains the same “override” purpose in both settings.
 
 			Issue(w3c/csswg-drafts#5003): Where do Layers fit in the cascade?
 
@@ -1040,12 +1041,12 @@ Cascade Layers</h3>
 
 	In the same way that [=cascade origins=] provide a balance of power
 	between user and author styles,
-	<dfn export>Cascade Layers</dfn> provide an explicit way
-	to balance concerns within a single origin.
+	<dfn export>cascade layers</dfn> provide a structured way
+	to organize and balance concerns within a single origin.
 	Authors can create layers to represent element defaults,
 	third-party libraries, themes, components,
-	overrides, and other styling concerns --
-	and re-order the cascade of layers in a deterministic way,
+	overrides, and other styling concerns--
+	and are able to re-order the cascade of layers in an explicit way,
 	without altering selectors or specificity within each layer,
 	or relying on source-order to resolve conflicts across layers.
 
@@ -1076,10 +1077,10 @@ Cascade Layers</h3>
 	Issue(w3c/csswg-drafts#5793): Do we need a keyword similar to `revert`, but for cascade layers?
 
 <h4 id="at-layer">
-Layering Styles: the ''@layer'' rule</h4>
+Declaring Cascade Layers: the ''@layer'' rule</h4>
 
 	The <dfn at-rule id="at-ruledef-layer">@layer</dfn> rule
-	describes an explicit [=cascade layer=],
+	defines an explicit [=cascade layer=],
 	with the option to assign style rules as either a block or an import.
 
 	The import syntax is:
@@ -1088,6 +1089,10 @@ Layering Styles: the ''@layer'' rule</h4>
 		@layer <<layer-ident>>? <<url>>;
 	</pre>
 
+	Such ''@layer'' import rules have the same restrictions and processing
+	as ''@import'' (see [[#at-import]]),
+	except that the imported rules are assigned to the indicated layer.
+
 	Issue(w3c/csswg-drafts#5681): Is ''@layer'' the proper way to handle layered url imports?
 
 	The block syntax is:
@@ -1098,30 +1103,46 @@ Layering Styles: the ''@layer'' rule</h4>
 		}
 	</pre>
 
-	In both cases the optional <dfn><<layer-ident>></dfn> is a
-	CSS <a href="https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier">identifier</a>
-	that either matches an existing layer name, or defines a new named layer.
-	If no identifier is given, a new unnamed layer is created.
-	The '<<url>>' import or '<<stylesheet>>' block
-	provides arbitrary CSS rules that will be appended to the layer.
+	Such ''@layer'' block rules have the same restrictions and processing
+	as a [=conditional rule=] [[CSS-CONDITIONAL-3]]
+	with a true condition.
+
+	In both cases the optional <dfn for='@layer'><<layer-ident>></dfn>
+	is a [=CSS identifier=] (<<ident>>)
+	that represents its <dfn>layer name</dfn>.
+	If the [=layer name=] matches that of a [=cascade layer=]
+	already defined within this [=origin=] and [=context=]
+	(and same [=layer=] scope, see [[#nested-layers]]),
+	then its style rules are assigned to that same [=cascade layer=].
+	Otherwise, or if no <<layer-ident>> is provided,
+	a new [=cascade layer=] is created.
+
+	Note: Layer name matching does not cross the shadow DOM boundary,
+	so the ordering of layers in the light DOM has no impact
+	on the order of identically-named layers in the shadow DOM.
+
+	Issue(w3c/csswg-drafts#4984): How do Cascade Layers interact with Shadow DOM?
 
 	The ''@layer'' rule can also be used to define new layers
-	without attaching any style rules, by providing only an identifier:
+	without assigning any style rules, by providing only a [=layer name=]:
 
 	<pre class='prod'>
 		@layer <<layer-ident>>;
 	</pre>
 
-	Issue(w3c/csswg-drafts#4969): What are the proper "levels" for managing Cascade Layers?
+	Such empty ''@layer'' are allowed
+	anywhere either import ''@layer'' or block ''@layer'' rules are allowed.
 
-<h5 id="layer-identifiers" class="no-toc">
-Layer Identifiers</h5>
-
-	Layer identifiers are optional,
-	but provide a way to apply multiple style blocks
-	to a single layer.
+	Issue(w3c/csswg-drafts#4969): What are the proper "levels" for managing Cascade Layers?
 
 	<div class="example">
+		Layer identifiers are optional,
+		but provide a way to apply multiple style blocks
+		to a single layer.
+		In the following example,
+		the contents of <code>headings.css</code> and <code>links.css</code>
+		are cascaded within the same layer as the <code>audio[controls]</code> rule:
+
 		<pre class='lang-css'>
 			@layer default url(headings.css);
 			@layer default url(links.css);
@@ -1134,13 +1155,14 @@ Layer Identifiers</h5>
 		</pre>
 	</div>
 
-	The identifier-only syntax
-	also allows authors to establish a layer order in advance,
-	regardless of the order in which style rules are added to each layer.
-
 	<div class="example">
-		In this example, the imported ''theme.css'' style will override
-		any style rules added to the ''default'',
+		The identifier-only syntax
+		allows establishing a layer order in advance,
+		regardless of the order in which style rules are added to each layer.
+
+		In this example,
+		the imported <code>theme.css</code> style rules will override
+		any rules added in the later <css>default</css> block
 		since the order of layers has already been established.
 
 		<pre class='lang-css'>
@@ -1160,22 +1182,16 @@ Layer Identifiers</h5>
 		See also [[#at-layers]].
 	</div>
 
-	Layer identifiers do not cross the shadow DOM boundary,
-	so the ordering of layers in the light DOM has no impact
-	on the order of identically-named layers in the shadow DOM.
-
-	Issue(w3c/csswg-drafts#4984): How do Cascade Layers interact with Shadow DOM?
-
 <h5 id="nested-layers" class="no-toc">
 Nested Layers</h5>
 
-	When multiple layer rules are nested,
-	internal layer identifiers are scoped to their parent layer.
+	When ''@layer'' rules are nested,
+	[=layer names=] are scoped to their parent layer.
 
 	<div class="example">
 		In this example,
-		the nested "framework default" layer is distinct
-		from the top-level "default" layer:
+		the nested ''framework default'' layer is distinct
+		from the top-level ''default'' layer:
 
 		<pre class='lang-css'>
 			@layer default {
@@ -1209,7 +1225,7 @@ Nested Layers</h5>
 	</div>
 
 	It is not possible for nested layers
-	to reference a layer identifier in an outer layer-scope,
+	to reference a [=layer name=] in an outer layer’s scope,
 	but it is possible to reference nested layers
 	from an outer scope,
 	by combining identifiers with a full stop (. U+002E) character.
@@ -1238,12 +1254,10 @@ Nested Layers</h5>
 <h5 id="unnamed-layers" class="no-toc">
 Un-Named Layers</h5>
 
-	Layers without an identifier are also added to the layer order when invoked,
-	but only describe a single rule-block or file import
-	without any external hook for re-arranging or adding styles.
-
-
 	<div class="example">
+		A layer declared without a [=layer name=]
+		does not provide any external hook for re-arranging or adding styles.
+
 		In most use-cases this would only be syntax-sugar for brevity --
 		relying on well-organized source-order rather than any explicit names.
 		However, it could be used by teams as a way to "force" an organizing convention
@@ -1279,10 +1293,12 @@ Layer-Ordering Shorthand: the ''@layers'' rule</h3>
 	Its syntax is:
 
 	<pre class='prod'>
-		@layers <<custom-ident>> [, <<custom-ident>>]* ;
+		@layers <<layer-ident>> [, <<layer-ident>>]* ;
 	</pre>
 
-	This is provided as a shorthand for establishing the order of named layers:
+	This is provided as a shorthand for establishing the order of named layers,
+	and otherwise has the same effect as declaring each [=layer name=]
+	in order in its own empty ''@layer'' rule.
 
 	<div class="example">
 		The following examples have the same result.
@@ -1302,6 +1318,8 @@ Layer-Ordering Shorthand: the ''@layers'' rule</h3>
 		</pre>
 	</div>
 
+	''@layers'' rules are allowed anywhere an empty ''@layer'' rule is allowed.
+
 <h3 id="preshint">
 Precedence of Non-CSS Presentational Hints</h3>