From 28cf15d0e12b2687b51087d9a23338bb14498c79 Mon Sep 17 00:00:00 2001
From: Tab Atkins-Bittner <jackalmage@gmail.com>
Date: Thu, 25 Jul 2019 13:13:18 -0700
Subject: [PATCH] [css-variables] Better define invalid-at-cvt and
 cyclic-at-cvt, and the 'guaranteed-invalid value' concept. Fixes #4075.

---
 css-variables-1/Overview.bs | 33 +++++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/css-variables-1/Overview.bs b/css-variables-1/Overview.bs
index 347ba0e9ff3..1eecc55beb7 100644
--- a/css-variables-1/Overview.bs
+++ b/css-variables-1/Overview.bs
@@ -59,10 +59,10 @@ Defining Custom Properties: the '--*' family of properties</h2>
 	<pre class='propdef'>
 	Name: --*
 	Value: <<declaration-value>>?
-	Initial: (nothing, see prose)
+	Initial: the [=guaranteed-invalid value=]
 	Applies to: all elements
 	Inherited: yes
-	Computed value: specified value with variables substituted (but see prose for "invalid variables")
+	Computed value: specified value with variables substituted, or the [=guaranteed-invalid value=]
 	Animatable: no
 	</pre>
 
@@ -262,6 +262,22 @@ Custom Property Value Syntax</h3>
 		to make maintaining the translations simpler.
 	</div>
 
+<h3 id='guaranteed-invalid'>
+Guaranteed-Invalid Values</h3>
+
+	The initial value of a [=custom property=] is a <dfn export>guaranteed-invalid value</dfn>.
+	As defined in [[#using-variables]],
+	using ''var()'' to substitute a [=custom property=] with this as its value
+	makes the property referencing it [=invalid at computed-value time=].
+
+	This value serializes as the empty string,
+	but actually writing an empty value into a custom property,
+	like ''--foo: ;'',
+	is a valid (empty) value,
+	not the [=guaranteed-invalid value=].
+	If, for whatever reason,
+	one wants to manually reset a variable to the [=guaranteed-invalid value=],
+	using the keyword ''initial'' will do this.
 
 
 <h3 id='cycles'>
@@ -281,10 +297,19 @@ Resolving Dependency Cycles</h3>
 	(including in the fallback argument of ''var()''),
 	add an edge between <var>prop</var> and the <var>var</var>.
 	<span class='note'>Edges are possible from a custom property to itself.</span>
+
 	If there is a cycle in the dependency graph,
 	all the <a>custom properties</a> in the cycle
-	must compute to their initial value
-	(which is a guaranteed-invalid value).
+	are <dfn export>cyclic at computed-value time</dfn>,
+	and must compute to the [=guaranteed-invalid value=].
+
+	Note: Defined properties that participate in a dependency cycle
+	either end up with invalid variables in their value
+	(becoming [=invalid at computed-value time=]),
+	or define their own cyclic handling
+	(like 'font-size' using ''em'' values).
+	They do not computed to the [=guaranteed-invalid value=]
+	like custom properties do.
 
 	<div class='example'>
 		This example shows a custom property safely using a variable: