[css-highlight-api-1] Add note recommending authors to only use one name to style a highlight and add an example showcasing why using multiple names is problematic.

sanketj · sanketj · commit 296318c31509 · 2021-04-14T23:26:08.000-07:00
diff --git a/css-highlight-api-1/Overview.bs b/css-highlight-api-1/Overview.bs
@@ -233,6 +233,40 @@ Registering Custom Highlights</h3>
 	[=custom highlight name=] that is a valid CSS [=identifier=]. Using a name that is not a valid
 	identifier can make the highlight hard, and in some cases impossible, to style via CSS.
 
+	Note: It is possible to [=register=] a [=custom highlight=] with more than one [=custom highlight name=].
+	However, using more than one name to style a highlight will assign the highlight multiple different sets
+	of styles, without a way to control the stacking order of conflicting styles within these sets
+	during [[#painting|painting]]. This may be limiting for authors and may cause confusing painting behavior
+	(see the [[#styling-problems-with-multiple-names-per-highlight|example]] below for more context). Therefore,
+	<b>it is recommended that authors only use one name per highlight during styling</b>.
+	<div class=example id=styling-problems-with-multiple-names-per-highlight>
+		<xmp highlight=html>
+			<style>
+			div::highlight(bar) {
+				color: red;
+			}
+			div::highlight(foo) {
+				color: green;
+			}
+			</style>
+			<body><div>abc</div>
+			<script>
+			let r = new Range();
+			r.setStart(div, 0);
+			r.setEnd(div, 1);
+			let h = new Highlight(r);
+			CSS.highlights.set('foo', h);
+			CSS.highlights.set('bar', h);
+			</script>
+		</xmp>
+		In the example above, the same [=custom highlight=] object is [=registered=] under the names 'foo' and 'bar'.
+		Since each of the [=style rules=] target the same highlight and have the same [=specificity=], authors may
+		expect the last rule to win in cascading order and the highlighted content to be green. However, each highlight
+		name gets an independent set of highlight styles, and the highlight will be painted once per name. In
+		this case, because 'foo' was registered before 'bar', the highlight will be first painted with 'foo''s
+		color (green) and then with 'bar''s color (red). As a result, the highlighted content will appear red.
+	</div>
+
 <h2 id=styling-highlights>
 Styling Custom Highlights</h2>
 
