From 45f7907086f16b8fd8345631d633b5089e318cbb Mon Sep 17 00:00:00 2001
From: Stephen Chenney <schenney@chromium.org>
Date: Wed, 30 Aug 2023 20:53:12 -0400
Subject: [PATCH] [css-pseudo-4] Add spec for resolving custom properties

In https://github.com/w3c/csswg-drafts/issues/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.
---
 css-pseudo-4/Overview.bs | 43 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/css-pseudo-4/Overview.bs b/css-pseudo-4/Overview.bs
index 26622b91425..33f2d57d193 100644
--- 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>