[css-variables-1] Specify that custom properties must serialize *exactly as specified by the author*. w3c#5685

Author: tabatkins

css-variables-1/Overview.bs

@@ -235,11 +235,11 @@ Defining Custom Properties: the '--*' family of properties</h2>
 
 <!--
  ██████  ██    ██ ██    ██ ████████    ███    ██     ██
-██    ██  ██  ██  ███   ██    ██      ██ ██    ██   ██ 
-██         ████   ████  ██    ██     ██   ██    ██ ██  
- ██████     ██    ██ ██ ██    ██    ██     ██    ███   
-      ██    ██    ██  ████    ██    █████████   ██ ██  
-██    ██    ██    ██   ███    ██    ██     ██  ██   ██ 
+██    ██  ██  ██  ███   ██    ██      ██ ██    ██   ██
+██         ████   ████  ██    ██     ██   ██    ██ ██
+ ██████     ██    ██ ██ ██    ██    ██     ██    ███
+      ██    ██    ██  ████    ██    █████████   ██ ██
+██    ██    ██    ██   ███    ██    ██     ██  ██   ██
  ██████     ██    ██    ██    ██    ██     ██ ██     ██
 -->
 
@@ -312,13 +312,13 @@ Guaranteed-Invalid Values</h3>
 
 
 <!--
- ██████  ██    ██  ██████  ██       ████████  ██████ 
+ ██████  ██    ██  ██████  ██       ████████  ██████
 ██    ██  ██  ██  ██    ██ ██       ██       ██    ██
-██         ████   ██       ██       ██       ██      
-██          ██    ██       ██       ██████    ██████ 
+██         ████   ██       ██       ██       ██
+██          ██    ██       ██       ██████    ██████
 ██          ██    ██       ██       ██             ██
 ██    ██    ██    ██    ██ ██       ██       ██    ██
- ██████     ██     ██████  ████████ ████████  ██████ 
+ ██████     ██     ██████  ████████ ████████  ██████
 -->
 
 <h3 id='cycles'>
@@ -841,6 +841,54 @@ Serializing Custom Properties</h3>
 	property names are restricted to the ASCII range and are <a>ASCII case-insensitive</a>,
 	so implementations typically serialize the name lowercased.
 
+	Specified values of [=custom properties=] must be serialized
+	<em>exactly as specified by the author</em>.
+	Simplifications that might occur in other properties,
+	such as dropping comments,
+	normalizing whitespace,
+	reserializing numeric tokens from their value,
+	etc.,
+	must not occur.
+
+	Computed values of [=custom properties=] must similarly be serialized
+	<em>exactly as specified by the author</em>,
+	save for the replacement of any ''var()'' functions.
+
+	<div class=example>
+		For example, given the following properties:
+
+		<pre>
+			--y: /* baz */;
+			--x: /* foo */ var(--y) /* bar */;
+		</pre>
+
+		the serialization of the specified value of ''--x''
+		must be <code>"/* foo */ var(--y) /* bar */"</code>,
+		while the serialization of the computed value of ''--x''
+		must be <code>"/* foo */ /* baz */ /* bar */"</code>.
+
+		(Note that the leading whitespace on the value is automatically trimmed by the CSS parser;
+		it's not preserved here.)
+	</div>
+
+	<div class=note>
+		This 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,
+		like ''--uuid: 12345678-12e3-8d9b-a456-426614174000'',
+		requires the UUID to be echoed back out as written
+		when it's accessed by script.
+
+		This value is technically parsed by CSS as a series of adjacent numbers and dimensions.
+		In particular, the segment "-12e3" parses as a number, equal to -12000.
+		Reserializing it in that form,
+		as required by CSSOM in other contexts,
+		would fatally break the author's use of the value.
+	</div>
+
+
+
 <h2 id='changes'>
 Changes</h2>