From cdd41ca9065d9ebe57dc09dc28b16f9c94d067de Mon Sep 17 00:00:00 2001
From: Tab Atkins-Bittner <jackalmage@gmail.com>
Date: Fri, 21 Feb 2025 17:14:58 -0800
Subject: [PATCH] [css-variables-1] Specify that empty custom props serialize
 as the empty string. #9847

---
 css-variables-1/Overview.bs | 37 ++++++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)

diff --git a/css-variables-1/Overview.bs b/css-variables-1/Overview.bs
index ee4eb9a075ef..825525ccd30b 100644
--- a/css-variables-1/Overview.bs
+++ b/css-variables-1/Overview.bs
@@ -886,7 +886,8 @@ Serializing Custom Properties</h3>
 	so implementations typically serialize the name lowercased.
 
 	Specified values of [=custom properties=] must be serialized
-	<em>exactly as specified by the author</em>.
+	<em>exactly as specified by the author</em>
+	(with one exception, below).
 	Simplifications that might occur in other properties,
 	such as dropping comments,
 	normalizing whitespace,
@@ -895,9 +896,15 @@ Serializing Custom Properties</h3>
 	must not occur.
 
 	Computed values of [=custom properties=] must similarly be serialized
-	<em>exactly as specified by the author</em>,
+	<em>exactly as specified by the author</em>
+	(with the same one exception, below),
 	save for the replacement of any ''var()'' functions.
 
+	The one exception to serialization being precisely as specified in the source file
+	is that an <em>empty</em> custom property
+	(such as ''--foo:;'')
+	must serialize with a single space as its value.
+
 	<wpt>
 	variable-reference-shorthands-cssom.html
 	variable-reference-variable.html
@@ -921,7 +928,8 @@ Serializing Custom Properties</h3>
 	</div>
 
 	<div class=note>
-		This requirement exists because authors sometimes store non-CSS information in custom properties,
+		This "exactly as specified" requirement exists
+		because authors sometimes store non-CSS information in custom properties,
 		and "normalizing" this information can change it in ways that break author code.
 
 		For example, storing a UUID in a custom property,
@@ -936,6 +944,29 @@ Serializing Custom Properties</h3>
 		would fatally break the author's use of the value.
 	</div>
 
+	<div class=note>
+		The requirement to serialize an empty custom property
+		as a string with a single space in it instead
+		is due to compatibility with the existing CSSOM API.
+		{{setProperty()}} specifies that
+		if the passed value is an empty string
+		it instead acts as {{removeProperty()}}.
+
+		This is a frankly weird behavior,
+		and not something we would do in new APIs.
+		But we can't change the past,
+		and letting empty properties accurately serialize as the empty string
+		would mean that round-tripping a custom property value,
+		or reading a property on one element
+		and setting a property on another element to the same value,
+		wouldn't work as intended.
+		Using a single space preserves the author-intended behavior as much as possible,
+		while having the smallest chance of accidentally breaking things,
+		since authors working with custom property values in JS
+		are probably calling {{String/trim()}} on the values anyway.
+	</div>
+
+
 
 <!-- Big Text: etc