First full draft of cascade layers

Author: mirisuzanne

css-cascade-5/Overview.bs

@@ -871,11 +871,11 @@ Cascade Sorting Order</h3>
 			any declaration not assigned to an explicit layer is added to an implicit final layer.
 
 			When comparing declarations that belong to different layers,
-			then for [=normal=] rules the last declaration whose [=cascade layer=] is last wins,
+			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 ''!important'' maintains the same semantic purpose.
+			so that the ''!important'' flag maintains the same semantic purpose in both settings.
 
 			Issue(w3c/csswg-drafts#5003): Where do Layers fit in the cascade?
 
@@ -1039,7 +1039,8 @@ Cascade Layers</h3>
 	<dfn export>Cascade Layers</dfn> provide an explicit way
 	to balance concerns within a single origin.
 	Authors can create layers to represent element defaults,
-	third-party libraries, themes, components, overrides, and other styling concerns --
+	third-party libraries, themes, components,
+	overrides, and other styling concerns --
 	and re-order the cascade of layers in a deterministic way,
 	without altering selectors or specificity within each layer,
 	or relying on source-order to resolve conflicts across layers.
@@ -1074,22 +1075,38 @@ Layering Styles: the ''@layer'' rule</h4>
 	The <dfn at-rule id="at-ruledef-layer">@layer</dfn> rule
 	describes an explicit [=cascade layer=],
 	with the option to assign style rules as either a block or an import.
-	The syntax is:
+
+	The import syntax is:
 
 	<pre class='prod'>
-		@layer [ <<layer-ident>>? [ <<url>>; | {
+		@layer <<layer-ident>>? <<url>>;
+	</pre>
+
+	Issue(w3c/csswg-drafts#5681): Is ''@layer'' the proper way to handle layered url imports?
+
+	The block syntax is:
+
+	<pre class='prod'>
+		@layer <<layer-ident>>? {
 			<<stylesheet>>
-		} ]? ]!
+		}
 	</pre>
 
-	where the optional <dfn><<layer-ident>></dfn> is a
+	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,
-	the optional [<<url>>;|{<<stylesheet>>}]
-	either gives the URL of the style sheet to be imported into that layer,
-	or contains style rules to be added to the layer.
+	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 a arbitrary CSS rules that will be appended to the layer.
 
-	Issue(w3c/csswg-drafts#5681): Is ''@layer'' the proper way to handle layered url imports?
+	The ''@layer'' rule can also be used to define new layers
+	without attaching any style rules, by providing only an identifier:
+
+	<pre class='prod'>
+		@layer <<layer-ident>>;
+	</pre>
+
+	Issue(w3c/csswg-drafts#4969): What are the proper "levels" for managing Cascade Layers?
 
 <h5 id="layer-identifiers" class="no-toc">
 Layer Identifiers</h5>
@@ -1111,10 +1128,15 @@ Layer Identifiers</h5>
 	</pre>
 	</div>
 
-	This also allows authors to establish a layer order in advance,
-	regardless of the order styles are added to each layer.
+	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'',
+	since the order of layers has already been established.
+
 	<pre class='lang-css'>
 	@layer default;
 	@layer theme;
@@ -1132,6 +1154,12 @@ 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 layer 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>
 
@@ -1180,8 +1208,6 @@ Nested Layers</h5>
 	from an outer scope,
 	by combining identifiers with a full stop (. U+002E) character.
 
-	Issue: What is the appropriate syntax for nested layer identifiers?
-
 	<div class="example">
 	<pre class='lang-css'>
 	@layer framework {
@@ -1201,28 +1227,42 @@ Nested Layers</h5>
 	</pre>
 	</div>
 
+	Issue(w3c/csswg-drafts#5791): What is the appropriate syntax for appending to nested layers?
+
 <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 --
+	but only describe a single rule-block or file import
 	without any external hook for re-arranging or adding styles.
-	This can be used to create "private" layers
-	that should not be manipulated or re-ordered
-	by other layer rules.
+
 
 	<div class="example">
-	In the following example,
-	additional styles can be added to the ''default'' layer,
-	but not the layer containing ''framework.css'':
+	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
+	(all layer code must be defined in one place),
+	or by libraries wanting to merge & hide a set of internal "private" layers
+	that they don't want exposed to author manipulation:
 
 	<pre class='lang-css'>
-	@layer default url(headings.css);
-	@layer url(framework.css);
+	/* bootstrap-base.css */
+	/* unnamed wrapper layers around each sub-file */
+	@layer url(base-forms.css);
+	@layer url(base-links.css);
+	@layer url(base-headings.css);
+
+	/* bootstrap.css */
+	/* the intrnal names are hidden from access, subsumed in "base" */
+	@layer base url(bootstrap-base.css);
+
+	/* author.css */
+	/* author has access to bootstrap.base layer, but not into unnamed layers */
+	@layer bootstrap url(bootstrap.css);
 	</pre>
 	</div>
 
-	Issue: Should un-named layers be allowed?
+	Issue(w3c/csswg-drafts#5792): Should unnamed cascade layers be allowed?
 
 <h4 id="at-layers">
 Layer-Ordering Shorthand: the ''@layers'' rule</h3>
@@ -1236,6 +1276,26 @@ Layer-Ordering Shorthand: the ''@layers'' rule</h3>
 		@layers <<custom-ident>> [, <<custom-ident>>]* ;
 	</pre>
 
+	This is provided as a shorthand for establishing the order of named layers:
+
+	<div class="example">
+	The following examples have the same result.
+
+	Using multiple ''@layer'' rules with identifier only:
+
+	<pre class='lang-css'>
+	@layer default;
+	@layer theme;
+	@layer components;
+	</pre>
+
+	Using the ''@layers'' shorthand syntax:
+
+	<pre class='lang-css'>
+	@layers default, theme, components;
+	</pre>
+	</div>
+
 <h3 id="preshint">
 Precedence of Non-CSS Presentational Hints</h3>