[css-mixins-1] Describe custom function cycles (#11446)

Co-authored-by: Anders Hartvoll Ruud <andruud@google.com>

Author: andruud

css-mixins-1/Overview.bs

@@ -17,6 +17,7 @@ Default Highlight: css
 spec:infra; type:dfn; text:list
 spec:css-properties-values-api; type:dfn; text:supported syntax component name
 spec:css-properties-values-api; type:dfn; text:syntax component
+spec:css-syntax-3; type:dfn; text:declaration
 spec:css-syntax-3; type:dfn; text:descriptor;
 spec:css-values-4; type:dfn; text:keyword;
 spec:css-values-4; type:dfn; text:identifier;
@@ -417,7 +418,81 @@ is the [=guaranteed-invalid value=].
 Cycles {#cycles}
 ----------------
 
-Issue: TODO
+The ''result'' descriptor and [=local variables=]
+within a [=custom function=]
+may reference other [=custom functions=] or [=custom properties=],
+and may therefore create [[css-variables-1#cycles|cycles]].
+
+For each element, add a node for every specified [=custom function=]
+to the graph described in [[css-variables-1#cycles]];
+add a node for each [=local variable=]
+defined within each of those functions;
+then, for each [=custom function=] <var>func</var>, add edges as follows:
+
+* From <var>func</var> to any [=custom function=]
+	referenced by a <<dashed-function>> within <var>func</var>'s body.
+* From <var>func</var> to any [=custom property=] or [=local variable=]
+	referenced by a ''var()'' within <var>func</var>'s body.
+* To <var>func</var> from any [=custom property=] or [=local variable=]
+	that references <var>func</var>
+	using a <<dashed-function>>.
+
+A <<dashed-function>> referencing a [=custom function=]
+which is part of a cycle
+makes the containing [=declaration=] [=invalid at computed-value time=].
+
+Note: Cycles are disallowed even through branches that are not taken
+	during execution.
+
+<div class='example'>
+	In the following,
+	<code>--foo()</code> is in a cycle with itself,
+	even though the media query never evaluates to "true":
+
+	<pre class='lang-css'>
+	@function --foo(--x) {
+	  @media (unknown-feature) {
+	    result: --foo(42);
+	  }
+	  result: 1;
+	}
+	</pre>
+
+	Similarly,
+	<code>--bar()</code> is in a cycle with itself,
+	even though the local variable <code>--x</code> is never referenced:
+
+	<pre class='lang-css'>
+	@function --bar() {
+	  --x: --bar();
+	  result: 1;
+	}
+	</pre>
+</div>
+
+<div class='example'>
+	The function <code>--baz()</code> is not in a cycle in the example below:
+	even though <code>var(--x)</code> and <code>var(--y)</code> appear in the function body,
+	they refer to a [=function parameter=] and [=local variable=], respectively.
+	The [=custom properties=] <code>--x</code> and <code>--y</code>
+	both reference <code>--baz()</code>, but that's fine:
+	those [=custom properties=] are not referenced within <code>--baz()</code>.
+
+	<pre class='lang-css'>
+	@function --baz(--x) {
+	  --y: 10px;
+	  result: calc(var(--x) + var(--y));
+	}
+
+	div {
+	  --x: --baz(1px);
+	  --y: --baz(2px);
+	  width: var(--x);  /* 11px */
+	  height: var(--y); /* 12px */
+	}
+	</pre>
+</div>
+
 
 <!-- Big Text: execution