[css-values-5] Pseudo element and tree-scope for sibling functions #9573

css-values-5/Overview.bs

@@ -2455,9 +2455,46 @@ Tree Counting Functions: the ''sibling-count()'' and ''sibling-index()'' notatio
 	Note: The ''counter()'' function can provide similar abilities as ''sibling-index()'',
 	but returns a <<string>> rather than an <<integer>>.
 
-	When used on a [=pseudo-element=],
-	these both resolve as if specified
-	on its [=ultimate originating element=].
+	When used on an [=element-backed pseudo-element=] which is also a real element,
+	the tree counting functions resolve for that real element. For other pseudo
+	elements, they resolve as if they were resolved against the
+	originating element. It follows that for nested pseudo elements the resolution
+	will recursively walk the originating elements until a real element is found.
+
+	A tree counting function is a [=tree-scoped reference=] where it references
+	an implicit [=tree-scoped name=] for the element it resolves against. This is
+	done to not leak tree information to an outer [=tree=]. A tree counting
+	function that is scoped to an outer [=tree=] relative to the element it
+	resolves against, will alway resolve to 0.
+
+	<div class=example>
+		Examples of how ''sibling-index()'' resolves for pseudo elements, and when the
+		rule and the element come from different [=trees=]:
+
+		<pre class=lang-css>
+		#target::before {
+			/* Based on the sibling-index() of #target */
+			width: calc(sibling-index() * 10px);
+		}
+		#target::before::marker {
+			/* Based on the sibling-index() of #target */
+			width: calc(sibling-index() * 10px);
+		}
+		::slotted(*)::before {
+			/* Based on the sibling-index() of the slotted element - outer tree */
+			width: calc(sibling-index() * 10px);
+		}
+		::part(my-part) {
+			/* 0px - inner tree */
+			width: calc(sibling-index() * 10px);
+		}
+		:host {
+			/* Based on the hosts sibling-index() - outer tree */
+			width: calc(sibling-index() * 10px);
+		}
+		</pre>
+
+	</div>
 
 	Note: Like the rest of CSS (other than [=selectors=]),
 	''sibling-count()'' and ''sibling-index()''