[css-pseudo-4] Add spec for resolving custom properties

In #6641 it was resolved that "highlight pseudos inherit across the highlight tree, and the root highlight inherits custom props from the root element". Here we add spec language to explain the behavior.
w3c · Nov 20, 2023 · 1991760 · 1991760
1 parent 1e4328c
commit 1991760
Showing 1 changed file with 43 additions and 0 deletions.
diff --git a/css-pseudo-4/Overview.bs b/css-pseudo-4/Overview.bs
@@ -936,6 +936,49 @@ Cascading and Per-Element Highlight Styles</h3>
   css/css-pseudo/cascade-highlight-002.html
   </wpt>
 
+<h4 id="highlight-custom-properties">
+Custom Properties in Highlight Styles</h3>
+
+  A [=custom property=] used in highlight styles uses the
+  first custom property value found in the highlight cascade.
+  However, if a custom property value cannot be resolved
+  through the highlight cascade, the property value is taken from
+  the root element.
+
+  <div class="example">
+    For example, if an author specified
+    <pre class="lang-css">
+     :root {
+        --background-color: green;
+        --decoration-thickness: 10px;
+        --decoration-color: purple;
+      }
+      ::selection {
+        --decoration-thickness: 1px;
+        --decoration-color: green;
+      }
+      div::selection {
+        --decoration-color: blue;
+        background-color: var(--background-color, red);
+        text-decoration-line: underline;
+        text-decoration-style: line;
+        text-decoration-thickness: var(--decoration-thickness, 5px);
+        text-decoration-color: var(--decoration-color, red);
+      }
+    </pre>
+    A div's selection highlight would be a green background to the
+    selected content, with a 1px thick blue underline. The
+    ''--background-color'' custom property is not found on the
+    ''div::selection'' nor ''::selection'' so it is taken from the
+    ''::root'' custom property match. The ''--decoration-thickness''
+    property is inherited from ''::selection'' via the highlight
+    cascade and ''--decoration-color'' is found in
+    ''div::selection'' itself.
+  </div>
+
+  This behavior is intended to accomodate the standard practice of
+  defining document-wide custom properties on '':root''.
+
 <h3 id="highlight-painting">
 Painting the Highlight</h3>