[css-nesting-1][editorial] Steal most of the Apple blog post to form …

…an Explainer chapter.
w3c · Oct 9, 2023 · f0eab14 · f0eab14
1 parent 5409a6d
commit f0eab14
Showing 1 changed file with 122 additions and 43 deletions.
diff --git a/css-nesting-1/Overview.bs b/css-nesting-1/Overview.bs
@@ -10,6 +10,7 @@ TR: https://www.w3.org/TR/css-nesting-1/
 Editor: Tab Atkins-Bittner, Google, http://xanthir.com/contact/, w3cid 42199
 Editor: Adam Argyle, Google, https://nerdy.dev, w3cid 112669
 Abstract: This module introduces the ability to nest one style rule inside another, with the selector of the child rule relative to the selector of the parent rule.  This increases the modularity and maintainability of CSS stylesheets.
+Default Highlight: css
 </pre>
 
 <pre class=link-defaults>
@@ -46,54 +47,132 @@ Values</h3>
 
 	This specification does not define any new properties or values.
 
-<h3 id="motivation">
-Motivation</h3>
+<h2 id="explainer">
+Explainer</h2>
 
-	The CSS for even moderately complicated web pages
-	often include lots of duplication
-	for the purpose of styling related content.
-	For example, here is a portion of the CSS markup for one version of the [[CSS-COLOR-3]] module:
+	<em>This section is non-normative.</em>
 
-	<div class='example'>
-		<pre class=lang-css>
-			table.colortable td {
-				text-align:center;
-			}
-			table.colortable td.c {
-				text-transform:uppercase;
-			}
-			table.colortable td:first-child, table.colortable td:first-child+td {
-				border:1px solid black;
-			}
-			table.colortable th {
-				text-align:center;
-				background:black;
-				color:white;
-			}
-		</pre>
-	</div>
+	Imagine you have some CSS that you’d like to write in a more compact way.
 
-	Nesting allows the grouping of related style rules, like this:
+	<pre>
+	.foo {
+		color: green;
+	}
+	.foo .bar {
+		font-size: 1.4rem;
+	}
+	</pre>
 
-	<div class='example'>
-		<pre class=lang-css>
-			table.colortable {
-				& td {
-					text-align:center;
-					&.c { text-transform:uppercase }
-					&:first-child, &:first-child + td { border:1px solid black }
-				}
-				& th {
-					text-align:center;
-					background:black;
-					color:white;
-				}
-			}
-		</pre>
-	</div>
+	With Nesting, you can write such code as:
+
+	<pre>
+	.foo {
+		color: green;
+		.bar {
+			font-size: 1.4rem;
+		}
+	}
+	</pre>
+
+	If you’ve been nesting styles in Sass
+	or other CSS preprocessors,
+	you will find this very familiar.
+
+	You can nest any rules inside of a parent style rule:
+
+	<pre>
+	main {
+		div { ... }
+		.bar { ... }
+		#baz { ...}
+		:has(p) { ... }
+		::backdrop { ... }
+		[lang|="zh"] { ... }
+		* { ... }
+	}
+	</pre>
+
+	By default, the child rule's selector
+	is assumed to connect to the parent rule
+	by a [=descendant combinator=],
+	but you can start the nested selector
+	with any combinator to change that:
+
+	<pre>
+	main {
+		+ article { ... }
+		> p { ... }
+		~ main { ... }
+	}
+	</pre>
+
+	The new ''&'' selector lets you refer to
+	the elements matched by the parent selector explictly,
+	so the previous examples could have been written as:
+
+	<pre>
+	main {
+		& + article { ... }
+		& > p { ... }
+		& ~ main { ... }
+	}
+	</pre>
+
+	But you can place the ''&'' in other locations
+	within the nested selector,
+	to indicate other types of relationships
+	between the parent and child rule.
+	For example,
+	this CSS:
+
+	<pre>
+	ul {
+		padding-left: 1em;
+	}
+	.component ul {
+		padding-left: 0;
+	}
+	</pre>
+
+	Can be rewritten using Nesting as:
+
+	<pre>
+	ul {
+		padding-left: 1em;
+		.component & {
+			padding-left: 0;
+		}
+	}
+	</pre>
+
+	Again, the ''&'' gives you a way to say
+	“this is where I want the nested selector to go”.
+
+	It’s also handy when you don’t want a space between your selectors.
+	For example:
+
+	<pre>
+	a {
+		color: blue;
+		&:hover {
+			color: lightblue;
+		}
+	}
+	</pre>
 
-	Besides removing duplication,
-	the grouping of related rules improves the readability and maintainability of the resulting CSS.
+	Such code yields the same result as <code>a:hover {</code>.
+	Without the ''&'',
+	you’d get <code>a :hover {</code>--
+	notice the space between <code>a</code> and <code>:hover</code>--
+	which would fail to style your hover link.
+
+	You can nest more than one layer deep--
+	nesting CSS inside already-nested CSS--
+	in as many levels as you desire.
+	You can mix Nesting with
+	Container Queries, Supports Queries, Media Queries, and/or Cascade Layers
+	however you want.
+	(Nearly) anything can go inside of anything.
 
 Nesting Style Rules {#nesting}
 ==============================