Overview.bs

<pre class='metadata'>
Title: CSS Values and Units Module Level 5
Group: CSSWG
Shortname: css-values
Level: 5
Status: ED
Work Status: Exploring
ED: https://drafts.csswg.org/css-values-5/
TR: https://www.w3.org/TR/css-values-5/
Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Miriam E. Suzanne, Invited Expert, http://miriamsuzanne.com/contact, w3cid 117151
Abstract: This CSS module describes the common values and units that CSS properties accept and the syntax used for describing them in CSS property definitions.
Ignored Terms: <spacing-limit>, containing block, property
Ignored Vars: Cn+1, n
Inline Github Issues: no
Default Highlight: css
</pre>
<pre class='link-defaults'>
spec: css-values-4; type: dfn; text: determine the type of a calculation
spec: selectors-4; type: dfn; text: selector
</pre>
<style>
code, small { white-space: nowrap }
pre.value { font: inherit; white-space: pre-wrap; margin: 0; padding: 0; }
#propvalues td { text-align: right; }
#propvalues td + td { text-align: left; }
dt + dt::before { content: ", "; }
dl:not(.switch) dt { display: inline; }
td > small { display: block; }
</style>

<h2 id="intro">
Introduction</h2>

	ISSUE: <strong>This is a diff spec against <a href="https://www.w3.org/TR/css-values-4/">CSS Values and Units Level 4</a>.</strong>

<h3 id="placement">
Module Interactions</h3>

	This module extends [[CSS-VALUES-4]]
	which replaces and extends the data type definitions in [[!CSS21]] sections
	<a href="https://www.w3.org/TR/CSS21/about.html#value-defs">1.4.2.1</a>,
	<a href="https://www.w3.org/TR/CSS21/syndata.html#values">4.3</a>,
	and <a href="https://www.w3.org/TR/CSS21/aural.html#aural-intro">A.2</a>.

<h2 id="textual-values">
Textual Data Types</h2>

	See [[css-values-4#textual-values]].


<!-- Big Text: syntax

 ███▌  █   ▐▌ █    █▌ █████▌  ███▌  █     █
█▌  █▌ ▐▌  █  █▌   █▌   █▌   ▐█ ▐█   █   █
█▌      █ ▐▌  ██▌  █▌   █▌   █▌  █▌   █ █
 ███▌   ▐▌█   █▌▐█ █▌   █▌   █▌  █▌    █
    █▌   █▌   █▌  ██▌   █▌   █████▌   █ █
█▌  █▌   █▌   █▌   █▌   █▌   █▌  █▌  █   █
 ███▌    █▌   █▌   ▐▌   █▌   █▌  █▌ █     █
-->

<h2 id=value-defs>
Value Definition Syntax</h2>

	See [[css-values-4#value-defs]].

<h3 id=component-functions>
Functional Notation Definitions</h3>

	See [[css-values-4#component-functions]].

<h4 id=component-function-commas>
Commas and Semicolons in Functions</h4>

	[=Functional notation=] often uses commas
	to separate parts of its internal grammar.
	However, some functions
	(such as ''mix()'')
	allow values that, themselves,
	can contain commas.

	To accommodate these sorts of grammars unambiguously,
	commas in functional grammars are <em>implicitly upgradeable</em> to semicolons in Level 5;
	that is,
	commas in a [=functional notation=]'s grammar
	can instead be represented as <<semicolon-token>>s.
	This is all-or-nothing:
	either every comma in the [=functional notation=] must be written as a semicolon,
	or none of them must be.
	When the [=functional notation=]’s arguments are parsed,
	initially commas in the grammar match only <<comma-token>>s;
	if a <<semicolon-token>> is encountered,
	then the [=functional notation=] is re-interpreted
	with all commas in the grammar replaced by <<semicolon-token>>s.

	Commas contained in productions defined as <dfn>comma-containing productions</dfn>
	(such as <<any-value>> or <<whole-value>>)
	are not implicitly upgradeable.
	Even when a [=functional notation=] is being re-interpreted with semicolons,
	these productions end when a <<semicolon-token>> is encountered.

	<div class="example">
		The following examples are both equivalent declarations:

		<pre>
			list-style: toggle(disc, circle, square);
			list-style: toggle(disc; circle; square);
		</pre>

		however, this is different (and invalid):

		<pre>
			list-style: toggle(disc, circle; square);
		</pre>

		because it represents toggling between two values
		(<css>disc, circle</css> and <css>square</css>)
		and <css>disc, circle</css> is not a valid 'list-style' value.

		This ability is important,
		because sometimes [=functional notation=] arguments need to include commas.
		For example, in 'font-family':

		<pre>
			font-family: random-item(Times, serif; Arial, sans-serif; Courier, monospace);
		</pre>

		This randomly chooses one of three font-family lists:
		either ''Times, serif'', or ''Arial, sans-serif'', or ''Courier, monospace''.
		But if only single fonts were needed for each choice,
		commas <em>could</em> have been used to separate them:

		<pre>
		font-family: random-item(serif, sans-serif, monospace);
		</pre>

	</div>

	[=Functional notations=] are serialized with commas (rather than semicolons) whenever possible.

	The following generic productions are [=comma-containing productions=]:

	* <<any-value>>
	* <<whole-value>>
	* <<declaration-value>>

	Issue: The functions defined in this spec with semicolons in their grammar
	need fixing to just use commas, now.

<!-- Big Text: url

█▌  █▌ ████▌  █▌
█▌  █▌ █▌  █▌ █▌
█▌  █▌ █▌  █▌ █▌
█▌  █▌ ████▌  █▌
█▌  █▌ █▌▐█   █▌
█▌  █▌ █▌ ▐█  █▌
 ███▌  █▌  █▌ █████
-->

<h3 id="urls">
Resource Locators: the <<url>> type</h3>

	See [[css-values-4#urls]].

<h4 id='request-url-modifiers'>
Request URL Modifiers</h4>

	<dfn><<request-url-modifier>></dfn>s are <<url-modifier>>s
	that affect the <<url>>’s resource [=/request=]
	by applying associated [=URL request modifier steps=].
	See [[css-values-4#url-processing]].

	This specification defines the following <<request-url-modifier>>s:

	<pre class=prod>
		<<request-url-modifier>> = <<crossorigin-modifier>> | <<integrity-modifier>> | <<referrerpolicy-modifier>>
		<<crossorigin-modifier>> = crossorigin(anonymous | use-credentials)
		<<integrity-modifier>> = integrity(<<string>>)
		<<referrerpolicy-modifier>> = referrerpolicy(no-referrer | no-referrer-when-downgrade | same-origin | origin | strict-origin | origin-when-cross-origin | strict-origin-when-cross-origin | unsafe-url)
	</pre>

	<dl dfn-for="<request-url-modifier>">
		<dt><dfn><<crossorigin-modifier>></dfn> = <dfn function lt="crossorigin()">crossorigin</dfn>(<dfn value>anonymous</dfn> | <dfn value>use-credentials</dfn>)
		<dd>
			The [=URL request modifier steps=] for this modifier given [=/request=] |req| are:

			1. Set [=/request=]'s [=request/mode=] to "cors".

			2. If the given value is ''use-credentials'',
				set [=/request=]'s [=request/credentials mode=] to "include".

		<dt><dfn><<integrity-modifier>></dfn> = <dfn function lt="integrity()">integrity</dfn>(<<string>>)
		<dd>
			The [=URL request modifier steps=] for this modifier given [=/request=] |req|
			are to set [=/request=]'s [=request/integrity metadata=]
			to the given <<string>>.

		<dt><dfn><<referrerpolicy-modifier>></dfn> = <dfn function lt="referrerpolicy()">referrerpolicy</dfn>(<dfn value>no-referrer</dfn> | <dfn value>no-referrer-when-downgrade</dfn> | <dfn value>same-origin</dfn> | <dfn value>origin</dfn> | <dfn value>strict-origin</dfn> | <dfn value>origin-when-cross-origin</dfn> | <dfn value>strict-origin-when-cross-origin</dfn> | <dfn value>unsafe-url</dfn>)
		<dd>
			The [=URL request modifier steps=] for this modifier given [=/request=] |req|
			are to set [=/request=]'s [=request/referrer policy=]
			to the {{ReferrerPolicy}} that matches the given value.
	</dl>

	<div algorithm>
		To <dfn export>apply request modifiers from URL value</dfn>
		given a [=/request=] |req|
		and a <<url>> |url|,
		call the [=request modifier steps=] for |url|'s <<request-url-modifier>>s in sequence
		given |req|.
	</div>


<!-- Big Text: interp

████ █    █▌ █████▌ █████▌ ████▌  ████▌
 ▐▌  █▌   █▌   █▌   █▌     █▌  █▌ █▌  █▌
 ▐▌  ██▌  █▌   █▌   █▌     █▌  █▌ █▌  █▌
 ▐▌  █▌▐█ █▌   █▌   ████   ████▌  ████▌
 ▐▌  █▌  ██▌   █▌   █▌     █▌▐█   █▌
 ▐▌  █▌   █▌   █▌   █▌     █▌ ▐█  █▌
████ █▌   ▐▌   █▌   █████▌ █▌  █▌ █▌
-->

<h2 id="progress">
Interpolation Progress Functional Notations</h2>

	ISSUE(6245): This section is an exploratory draft, and not yet approved by the CSSWG.

	The ''progress()'', ''media-progress()'', and ''container-progress()'' [=functional notations=]
	represent the proportional distance
	of a given value (the <dfn noxexport>progress value</dfn>)
	from one value (the <dfn noexport>progress start value</dfn>)
	to another value (the <dfn noexport>progress end value</dfn>).
	They allow drawing a progress ratio from
	[=math functions=], [=media features=], and [=container features=],
	respectively,
	following a common syntactic pattern:

	<pre class=prod>
		<var>progress-function</var>() = <var>progress-function</var>( <var>progress value</var> from <var>start value</var> to <var>end value</var> )
	</pre>

	The resulting ratio can then be input into other calculations,
	such as a [=math function=]
	or a [=mix notation=].

<h3 id="progress-func">
Calculated Progress Values: the ''progress()'' notation</h3>

	The <dfn>progress()</dfn> functional notation
	returns a <<number>> value
	representing the position of one [=calculation=]
	(the [=progress value=])
	between two other [=calculations=]
	(the [=progress start value=]
	and [=progress end value=]).
	The argument [=calculations=] can resolve to any <<number>>, <<dimension>>, or <<percentage>>,
	but must have a [=consistent type=]
	or else the function is invalid.
	The result will be a <<number>>,
	[=made consistent=] with the [=consistent type=] of the arguments.

	The syntax of ''progress()'' is defined as follows:

	<pre class=prod>
		<dfn id=typedef-progress-fn><<progress()>></dfn> = progress(<<calc-sum>> from <<calc-sum>> to <<calc-sum>>)
	</pre>

	where the first, second, and third <<calc-sum>> values represent
	the [=progress value=], [=progress start value=], and [=progress end value=],
	respectively.

	The value returned by a valid ''progress()'' notation is
	(<var>progress value</var> - <var>start value</var>) / (<var>end value</var> - <var>start value</var>),
	as a <<number>>.

	ISSUE: Do we need a ''percent-progress()'' notation,
	or do enough places auto-convert that it's not necessary?

	Note: The ''progress()'' function is essentially syntactic sugar
	for a particular pattern of ''calc()'' notations.

<h3 id="media-progress-func">
Media Query Progress Values: the ''media-progress()'' notation</h3>

	Similar to the ''progress()'' notation,
	the <dfn>media-progress()</dfn> functional notation
	returns a <<number>> value
	representing current value of the specified [=media query=]
	[[!MEDIAQUERIES-4]]
	as a [=progress value=]
	between two explicit values of the [=media query=]
	(as the [=progress start value=] and [=progress end value=]).

	The syntax of ''media-progress()'' is defined as follows:

	<pre class=prod>
		<dfn><<media-progress()>></dfn> = media-progress(<<media-feature>> from <<calc-sum>> to <<calc-sum>>)
	</pre>

	The value returned by a valid ''media-progress()'' notation is
	<var>progress value</var> / (<var>end value</var> - <var>start value</var>,
	as a <<number>>.

	The specified [=media query=] must be a valid “range” type query,
	and its specified [=progress start value=] and [=progress end value=]
	must be valid values for the specified [=media query=],
	or else the function is invalid.

	The two input [=calculations=]
	but must have a [=consistent type=]
	or else the function is invalid.
	The result will be a <<number>>,
	[=made consistent=] with the [=consistent type=] of the arguments.

<h3 id="container-progress-func">
Container Query Progress Values: the ''container-progress()'' notation</h3>

	The <dfn>container-progress()</dfn> functional notation
	is identical to the ''media-progress()'' functional notation,
	except that it accepts [=container features=] [[!CSS-CONTAIN-3]]
	in place of [=media features=].

	The syntax of ''container-progress()'' is defined as follows:

	<pre class=prod>
		<dfn><<container-progress()>></dfn> = container-progress(<<size-feature>> [ of <<container-name>> ]? from <<calc-sum>> to <<calc-sum>>)
	</pre>

	where the optional <<container-name>> component specifies
	the named containers to consider when selecting a container
	to resolve against.

	The two input [=calculations=]
	but must have a [=consistent type=]
	or else the function is invalid.
	The result will be a <<number>>,
	[=made consistent=] with the [=consistent type=] of the arguments.

	If no appropriate containers are found,
	''container-progress()'' resolves its <<size-feature>> query
	against the [=small viewport size=].


<!-- Big Text: *-mix()

              █     █ ████ █     █   ██ ██
 █   █        ██   ██  ▐▌   █   █   █▌   ▐█
  █ █         █▌█ █▐█  ▐▌    █ █   █▌     ▐█
███████ ████▌ █▌ █ ▐█  ▐▌     █    █▌     ▐█
  █ █         █▌   ▐█  ▐▌    █ █   █▌     ▐█
 █   █        █▌   ▐█  ▐▌   █   █   █▌   ▐█
              █▌   ▐█ ████ █     █   ██ ██
-->

<h2 id="mixing">
Mixing and Interpolation Notations: the *-mix() family</h2>

	ISSUE(6245): This section is an exploratory draft, and not yet approved by the CSSWG.

	Several <dfn>mix notations</dfn> in CSS
	allow representing the interpolation of two values,
	the <dfn>mix start value</dfn> and the <dfn>mix end value</dfn>,
	at a given point in progress between them (the <dfn>mix progress value</dfn>).
	These [=functional notations=] follow the syntactic pattern:

	<pre class=prod>
		<var>mix-function</var>() = <var>mix-function</var>( <<progress>>, [=mix start value|start-value=], [=mix end value|end-value=] )
	</pre>

	The [=mix notations=] in CSS include:
	* ''calc-mix()'',
		for interpolating <<length>>, <<percentage>>, <<time>>,
		and other dimensions representable in ''calc()'' expressions
	* ''color-mix()'',
		for interpolating two <<color>> values
	* ''cross-fade()'',
		for interpolating <<image>> values
	* ''palette-mix()'',
		for interpolating two 'font-palette' values

	and finally the generic ''mix()'' notation,
	which can represent the interpolation of any property's values
	(but only the property's entire value, not individual components).

	Note: The ''cross-fade()'' notation
	also has an alternative syntax
	that allows for mixing more than two values,
	but does not allow for the more complex expressions of <<progress>>.

	ISSUE: The ''mix()'' notation also has a variant that takes a set of keyframes.
	It does this by referring to an ''@keyframes'' rule,
	and pulling the corresponding property declaration out of that.
	It would be nice to allow the other mix notations to take keyframe also,
	but how would we represent a set of keyframes for a [=component value=]
	(rather than a full property value)?

<h3 id="progress-type">
Representing Interpolation Progress: the <<progress>> type</h2>

	The <dfn><<progress>></dfn> value type represents
	the [=mix progress value=] in a [=mix notation=],
	and ultimately resolves to a percentage.
	It can, however, draw that percentage value
	from sources such as media queries and animation timelines,
	and can also convert it through an [=easing function=]
	before using it for interpolation.

	Its syntax is defined as follows:
	<pre class=prod>
		<<progress>> = [ <<percentage>> | <<number>> | <<'animation-timeline'>> ]? && by <<easing-function>>
	</pre>

	where:

	<dl dfn-type=value dfn-for="<progress>">
		<dt><dfn><<percentage-token>></dfn>
		<dd>
			Computes to the equivalent <<number>>:
			''0%'' becomes ''0'',
			''100%'' becomes ''1'',
			etc.

			Note: This only allows literal percentages,
			like ''15%'';
			calculations like ''calc(100% / 7)'' will not work,
			as they will instead attempt to use the normal rules
			for resolving a percentage against another type
			(such as <<length>>, in 'width').
			Use expressions like ''calc(1 / 7)'' instead.

		<dt><dfn><<number>></dfn>
		<dd>
			Represents the [=mix progress value=].

			Note: This allows the use of the ''progress()'',
			''media-progress()'',
			and ''container-progress()'' notations.

		<dt><dfn><<'animation-timeline'>></dfn>
		<dd>
			Represents the [=mix progress value=]
			as the progress of the specified [[web-animations-1#timelines|animation timeline]].
			The values ''animation-timeline/none'' and ''animation-timeline/auto'', however,
			are invalid.
			[[!CSS-ANIMATIONS-2]] [[!WEB-ANIMATIONS-2]]

		<dt><dfn><<easing-function>></dfn>
		<dd>
			Converts the specified input [=mix progress value=]
			into an output [=mix progress value=]
			using the specified [=easing function=].
			[[!CSS-EASING-1]]
	</dl>

	Note: Progress values below ''0'' and above ''1'' are valid;
	they allow representing interpolation beyond the range
	defined by the start and end values.

	Note: While <<progress>> itself can be a <<percentage>>,
	mapping directly to the equivalent <<number>>,
	a function that <em>resolves</em> to a <<number>>,
	like ''progress()'',
	resolves <<percentage>>s using the normal rules for the context;
	for example, in 'width', they would be resolved against a length.

	The [=computed value=] of a <<progress>> value specified with <<percentage>> or <<number>>
	is the computed <<number>> converted through the <<easing-function>> (if any).
	The [=computed value=] of a <<progress>> value specified with <<'animation-timeline'>>
	is the computed <<'animation-timeline'>> and <<easing-function>> (if any).

<h3 id="calc-mix">
Interpolated Numeric and Dimensional Values: the ''calc-mix()'' notation</h3>

	The <dfn>calc-mix()</dfn> [=mix notation=]
	represents an interpolated numeric or dimensional value.
	Like ''calc()'', it is a [=math function=],
	with the following syntactic form:

	<pre class=prod>
		<dfn><<calc-mix()>></dfn> = calc-mix( <<progress>>, <<calc-sum>>, <<calc-sum>> )
	</pre>

	The <<calc-sum>> arguments can resolve
	to any <<number>>, <<dimension>>, or <<percentage>>,
	but must have a [=consistent type=]
	or else the function is invalid.
	The result's type will be the [=consistent type=],
	[=made consistent=] with the type of the <<progress>> value.

	The [=used value=] of a valid ''calc-mix()'' is
	the result of interpolating these two values
	to the progress given by <<progress>>.
	If the <<progress>> value can be computed to a <<number>>,
	then the [=computed value=] is likewise
	the result of interpolating the two [=computed values=]
	to that <<progress>> value
	(in other words, ''A * (1-progress) + B * progress'')
	it is otherwise the ''calc-mix()'' notation itself
	with its arguments each computed according to their type.

<h3 id="color-mix">
Interpolated Color Values: the ''color-mix()'' notation</h3>

	This specification extends the ''color-mix()'' [=functional notation=]
	as a [=mix notation=] accepting the following syntaxes:

	<pre class=prod>
		<<color-mix()>> =
		  color-mix( <<progress>> && <<color-interpolation-method>>?, <<color>>, <<color>> ) |
		  color-mix( <<color-interpolation-method>>, [<<color>> && <<percentage [0,100]>>?]#{2} )
	</pre>

	The used value of the first [=mix notation=] variant
	is equivalent to assigning the <<progress>> value,
	as a <<percentage>>,
	to the <<percentage>> of the second <<color>> argument in the second variant.
	<span class=note>That is, ''color-mix(progress, color1, color2)'' is equivalent to ''color-mix(color1, color2 progress)''.</span>
	See [[css-color-5#color-mix]] for the normative definition of the second variant.

	ISSUE: <<progress>> allows returning percentages outside 0-100%,
	but ''color-mix()'' doesn't allows such values,
	so need to define how that gets processed.

<h3 id="cross-fade">
Interpolated Image Values: the ''cross-fade()'' notation</h3>

	This specification extends the ''cross-fade()'' [=functional notation=]
	as a [=mix notation=] accepting the following syntaxes:

	<pre class=prod>
		<<cross-fade()>> =
		  cross-fade( <<progress>>, [ <<image>> | <<color>> ], [ <<image>> | <<color>> ] ) |
		  cross-fade( <<cf-image>># )
	</pre>

	The used value of the first [=mix notation=] variant
	is equivalent to assigning the <<progress>> value
	as the <<percentage>> of the second <<color>> argument in the second variant.
	<span class=note>That is, ''cross-fade(progress, image1, image2)'' is equivalent to ''cross-fade(image1, image2 progress)''.</span>
	See [[css-images-4#cross-fade-function]] for the normative definition of the second variant.


<h3 id="transform-mix">
Interpolated Transform Values: the ''transform-mix()'' notation</h3>

	The <dfn>transform-mix()</dfn> [=mix notation=]
	represents an interpolated <<transform-list>>,
	with the following syntactic form:

	<pre class=prod>
		<dfn><<transform-mix()>></dfn> = transform-mix( <<progress>>, <<transform-list>>, <<transform-list>> )
	</pre>

	The [=used value=] of a valid ''transform-mix()'' is
	the result of interpolating these two values
	to the progress given by <<progress>>.
	If the <<progress>> value can be computed to a <<percentage>>,
	and the <<transform-list>>s can be interpolated
	without used-value-time information,
	then the [=computed value=] is likewise
	the result of interpolating the two [=computed values=]
	to that <<progress>> value;
	it is otherwise the ''transform-mix()'' notation itself
	with its arguments each computed according to their type.

	''transform-mix()'' is, itself, a <<transform-function>>.

<h3 id="mix">
Interpolated Property Values: the ''mix()'' notation</h3>

	[=Interpolation=] of any two property values can be represented
	by the <dfn>mix()</dfn> [=mix notation=],
	which supports two alternative syntax patterns:

	<pre class="prod">
		<dfn><<mix()>></dfn> =
		  mix( <<progress>> ';' <<whole-value>> ';' <<whole-value>> ) |
		  mix( <<progress>> && of <<'animation-name'>> )
	</pre>

	The first syntax alternative, like other [=mix notations=],
	interpolates between the first <<whole-value>> (its [=mix start value=])
	and the second <<whole-value>> (its [=mix end value=]).
	The second uses the [=mix progress value=]
	to interpolate the corresponding property declarations from a set of keyframes,
	allowing for more complex interpolation curves.

	Note: This [=functional notation=] uses semicolons to separate arguments
	rather than the more typical comma
	because the values themselves can contain commas.

	For the standard [=mix notation=] variant,
	if the two <<whole-value>>s being interpolated by ''mix()''
	are [=interpolation|interpolable=]
	as values for the property in which it is specified,
	and the interpolated value can be represented without ''mix()'',
	the [=computed value=] of ''mix()'' is
	the result of interpolating these two values
	to the progress given by <<progress>>.
	Otherwise,
	the [=computed value=] of ''mix()'' is
	the ''mix()'' [=functional notation=] itself
	with its <<progress>> value computed
	and its <<whole-value>>s (if provided)
	computed as values for this property.

	<div class="example">
		For example, most uses of ''mix()''
		will resolve at computed-value time:

		<pre>
			color: mix(90%; red; blue);
			/* via simple interpolation,
			   computes to: */
			color: rgb(10% 0 90%);

			color: mix(90%; currentcolor; black);
			/* can't be fully resolved at computed-value time,
			   but still has a defined representation: */
			color: color-mix(currentcolor 90%, black 10%);

			float: mix(90%; left; right);
			/* discretely animatable */
			float: right;
		</pre>

		But a few cases don't have an intermediate representation:

		<pre>
			transform: mix(90%; translate(calc(1em + 50%)); rotate(30deg));
			/* because functions don't match, it will interpolate
			   via matrix(). But translate(%) needs layout
			   information to turn into a matrix(), so the
			   interpolated value can't actually be represented.
			   Computes to: */
			transform: mix(90%; translate(calc(16px + 50%)); rotate(30deg));
			transform: mix(90% of ripple);
		</pre>
	</div>

	The ''mix()'' notation is a <<whole-value>>.
	Additionally,
	if any of its <<whole-value>> arguments are [=not animatable=],
	the notation is invalid.

	<div class="example">
		For example, the following declarations are invalid,
		and will be ignored:

		<pre>
			/* Invalid start value */
			color: mix(90% ; #invalid ; #F00);

			/* Function is mixed with other values */
			background: url(ocean) mix(10% ; blue ; yellow);

			/* 'animation-*' is not animatable */
			animation-delay: mix(0% ; 0s ; 2s);
		</pre>
	</div>


<!-- Big Text: subs

 ███▌  █▌  █▌ ████▌   ███▌
█▌  █▌ █▌  █▌ █▌  █▌ █▌  █▌
█▌     █▌  █▌ █▌  █▌ █▌
 ███▌  █▌  █▌ █████   ███▌
    █▌ █▌  █▌ █▌  █▌     █▌
█▌  █▌ █▌  █▌ █▌  █▌ █▌  █▌
 ███▌   ███▌  ████▌   ███▌
-->

<h2 id="value-insert">
Miscellaneous Value Substituting Functions</h2>

<h3 id="whole-value" type lt="<whole-value>">
Representing An Entire Property Value: the <<whole-value>> type</h3>

	Several functions defined in this specification
	can only be used as the "whole value" of a property.
	For example, ''background-position: toggle(50px 50px, center);'' is valid,
	but ''background-position: toggle(50px, center) 50px;'' is not.
	The <<whole-value>> production represents these values.

	All properties implicitly accept a <<whole-value>>
	as their entire value,
	just as they accept the [=CSS-wide keywords=]
	as their entire value.

	When used as a component value of a function,
	<<whole-value>> also represents any CSS value
	normally valid as the whole value
	of the property in which it is used
	(including additional <<whole-value>> functions).
	However, some functions may restrict
	what a <<whole-value>> argument can include.

<h3 id="first-valid">
Selecting the First Supported Value: the ''first-valid()'' notation</h3>

	CSS supports progressive enhancement with its forward-compatible parsing:
	authors can declare the same property multiple times in a style rule,
	using different values each time,
	and a CSS UA will automatically use the last one that it understands
	and throw out the rest.
	This principle, together with the ''@supports'' rule,
	allows authors to write stylesheets that work well
	in old and new UAs simultaneously.

	However, using ''var()''
	(or similar substitution functions that resolve after parsing)
	thwarts this functionality;
	CSS UAs must assume any such property is valid at parse-time.

	The <dfn>first-valid()</dfn> [=functional notation=]
	inlines the fallback behavior
	intrinsic to parsing declarations.
	Unlike most notations,
	it can accept any valid or invalid syntax in its arguments,
	and represents the first value among its arguments
	that is supported (parsed as valid) by the UA
	as the whole value of the property it's used in.

	<pre class=prod>
		<dfn>&lt;first-valid()></dfn> = first-valid( <<declaration-value>> [ ';' <<declaration-value>> ]* )
	</pre>

	If none of the arguments represent a valid value for the property,
	the property is [=invalid at computed-value time=].

	''first-valid()'' is a <<whole-value>>.

	Issue: Should this have a different name?
	We didn't quite decide on it during the resolution to add this.


<!-- Big Text: toggle()

█████▌  ███▌   ███▌   ███▌  █▌    █████▌   ██ ██
  █▌   █▌  █▌ █▌  █▌ █▌  █▌ █▌    █▌      █▌   ▐█
  █▌   █▌  █▌ █▌     █▌     █▌    █▌     █▌     ▐█
  █▌   █▌  █▌ █▌ ██▌ █▌ ██▌ █▌    ████   █▌     ▐█
  █▌   █▌  █▌ █▌  █▌ █▌  █▌ █▌    █▌     █▌     ▐█
  █▌   █▌  █▌ █▌  █▌ █▌  █▌ █▌    █▌      █▌   ▐█
  █▌    ███▌   ███▌   ███▌  █████ █████▌   ██ ██
-->

<h3 id="toggle-notation">
Toggling Between Values: ''toggle()''</h3>

	The <dfn>toggle()</dfn> expression allows descendant elements
	to cycle over a list of values instead of inheriting the same value.

	<div class='example'>
		The following example makes <code>&lt;em></code> elements italic in general,
		but makes them normal if they're inside something that's italic:

		<pre>em { font-style: toggle(italic; normal); }</pre>
	</div>

	<div class='example'>
		The following example cycles markers for nested lists,
		so that a top level list has ''list-style-type/disc''-shaped markers,
		but nested lists use ''list-style-type/circle'', then ''list-style-type/square'', then ''list-style-type/box'',
		and then repeat through the list of marker shapes,
		starting again (for the 5th list deep) with ''list-style-type/disc''.

		<pre>ul { list-style-type: toggle(disc; circle; square; box); }</pre>
	</div>

	The syntax of the ''toggle()'' expression is:

	<pre class=prod>
		<dfn><<toggle()>></dfn> = toggle( <<whole-value>> [ ';' <<whole-value>> ]+ )
	</pre>

	Note: This [=functional notation=] uses semicolons to separate arguments
	rather than the more typical comma
	because the values themselves can contain commas.

	The ''toggle()'' notation is a <<whole-value>>.
	However, it is not allowed to be nested,
	nor may it contain ''attr()'' or ''calc()'' notations;
	declarations containing such constructs are invalid.

	<div class="example">
		The following ''toggle()'' examples are all invalid:

		<pre>
		background-position: 10px toggle(50px, 100px);
		/* toggle() must be the sole value of the property */

		list-style-type: toggle(disc, 50px);
		/* ''50px'' isn't a valid value of 'list-style-type' */
		</pre>
	</div>

	To determine the computed value of ''toggle()'',
	first evaluate each argument as if it were the sole value of the property in which ''toggle()'' is placed
	to determine the computed value that each represents,
	called <var>C<sub>n</sub></var> for the <var>n</var>-th argument to ''toggle()''.
	Then, compare the property's <a>inherited value</a>
	with each <var>C<sub>n</sub></var>.
	For the earliest <var>C<sub>n</sub></var> that matches the <a>inherited value</a>,
	the computed value of ''toggle()'' is <var>C<sub>n+1</sub></var>.
	If the match was the last argument in the list,
	or there was no match,
	the computed value of ''toggle()'' is the computed value that the first argument represents.


	Note: This means that repeating values in a ''toggle()'' short-circuits the list.
	For example ''toggle(1em; 2em; 1em; 4em)'' will be equivalent to ''toggle(1em; 2em)''.

	<!-- Issue: Should this short-circuiting affect the computed value? -->

	Note: That ''toggle()'' explicitly looks at the computed value of the parent,
	so it works even on non-inherited properties.
	This is similar to the ''inherit'' keyword,
	which works even on non-inherited properties.

	Note: That the <a href="https://www.w3.org/TR/CSS21/cascade.html#computed-value">computed value</a> of a property is an abstract set of values,
	not a particular serialization [[!CSS21]],
	so comparison between computed values should always be unambiguous and have the expected result.
	For example,
	a Level 2 <l spec=css22>'background-position'</l> computed value
	is just two offsets, each represented as an absolute length or a percentage,
	so the declarations ''background-position: top center'' and ''background-position: 50% 0%''
	produce identical computed values.
	If the "Computed Value" line of a property definition seems to define something ambiguous or overly strict,
	please <a href="#sotd">provide feedback</a> so we can fix it.

	If ''toggle()'' is used on a <a>shorthand property</a>,
	it sets each of its longhands to a ''toggle()'' value
	with arguments corresponding to what the longhand would have received
	had each of the original ''toggle()'' arguments been the sole value of the <a>shorthand</a>.

	<div class="example">
		For example, the following shorthand declaration:

		<pre>margin: toggle(1px 2px, 4px, 1px 5px 4px);</pre>

		is equivalent to the following longhand declarations:

		<pre>
		margin-top:    toggle(1px; 4px; 1px);
		margin-right:  toggle(2px; 4px; 5px);
		margin-bottom: toggle(1px; 4px; 4px);
		margin-left:   toggle(2px; 4px; 5px);
		</pre>

		Note that, since ''1px'' appears twice in the top margin and ''4px'' appears twice in bottom margin,
		they will cycle between only two values
		while the left and right margins cycle through three.
		In other words, the declarations above will yield the same computed values
		as the longhand declarations below:

		<pre>
		margin-top:    toggle(1px; 4px);
		margin-right:  toggle(2px; 4px; 5px);
		margin-bottom: toggle(1px; 4px);
		margin-left:   toggle(2px; 4px; 5px);
		</pre>

		which may not be what was intended.
	</div>

<!-- Big Text: attr()

 ███▌  █████▌ █████▌ ████▌    ██ ██
▐█ ▐█    █▌     █▌   █▌  █▌  █▌   ▐█
█▌  █▌   █▌     █▌   █▌  █▌ █▌     ▐█
█▌  █▌   █▌     █▌   ████▌  █▌     ▐█
█████▌   █▌     █▌   █▌▐█   █▌     ▐█
█▌  █▌   █▌     █▌   █▌ ▐█   █▌   ▐█
█▌  █▌   █▌     █▌   █▌  █▌   ██ ██
-->

<h3 id="attr-notation">
Attribute References: the ''attr()'' function</h3>

<!--
Ian's proposal:
  http://lists.w3.org/Archives/Member/w3c-css-wg/2002OctDec/0141.html
-->

	The <dfn>attr()</dfn> function substitutes the value of an  <l spec=dom>[=attribute=]</l> on an <l spec=dom>[=/element=]</l>
	into a property,
	similar to how the ''var()'' function
	substitutes a [=custom property=] value into a function.

	<pre class=prod>
		attr() = attr( <<attr-name>> <<attr-type>>? , <<declaration-value>>?)

		<dfn>&lt;attr-name></dfn> = [ <<ident-token>> '|' ]? <<ident-token>>

		<dfn>&lt;attr-type></dfn> = string | url | ident | color | number | percentage |
		              length | angle | time | frequency | flex | <<dimension-unit>>
	</pre>

	<!-- Switch the <attr-name> to just use <q-name>
		when Namespaces is rewritten
		to use the current grammar structures. -->

	The <dfn>&lt;dimension-unit></dfn> production matches a literal "%" character
	(that is, a <<delim-token>> with a value of "%")
	or an ident whose value is any of the CSS units
	for <<length>>, <<angle>>, <<time>>, <<frequency>>, or <<flex>> values
	(such as ''px'' or ''ms'').

	The arguments of ''attr()'' are:

	: <<attr-name>>
	:: Gives the name of the attribute being referenced,
		similar to <<wq-name>> (from [[SELECTORS-3]])
		but without the possibility of a wildcard prefix.

		If no namespace is specified
		(just an identifier is given, like ''attr(foo)''),
		the null namespace is implied.
		(This is usually what's desired,
		as namespaced attributes are rare.
		In particular, HTML and SVG do not contain namespaced attributes.)
		As with [=attribute selectors=],
		the case-sensitivity of <<attr-name>> depends on the document language.

		If ''attr()'' is used in a property applied to an element,
		it references the attribute of the given name on that element;
		if applied to a pseudo-element,
		the attribute is looked up on the pseudo-element's [=originating element=].

	: <<attr-type>>
	::
		Specifies what kind of CSS value
		the attribute's value will be interpreted into
		(the ''attr()''’s <dfn dfn for=attr()>substitution value</dfn>)
		and what, if any, special parsing will be done to the value.

		The possible values and their behavior are defined in [[#attr-types]].

		Defaults to ''string'' if omitted.

	: <<declaration-value>>
	::
		Specifies a fallback value for the ''attr()'',
		which will be substituted instead of the attribute's value
		if the attribute is missing
		or fails to parse as the specified type.

		If the <<attr-type>> argument is ''string'',
		defaults to the empty string if omitted;
		otherwise, defaults to the [=guaranteed-invalid value=] if omitted.

	If a property contains one or more ''attr()'' functions,
	and those functions are syntactically valid,
	the entire property's grammar must be assumed to be valid at parse time.
	It is only syntax-checked at computed-value time,
	after ''attr()'' functions have been [=substitute an attr()|substituted=].

	<div class='note'>
		Note that the default value need not be of the type given.
		For instance, if the type required of the attribute by the author is ''px'',
		the default could still be <css>auto</css>,
		like in ''width: attr(size px, auto);''.
	</div>

<h4 id="attr-types">
''attr()'' Types</h4>

	The behavior of the ''attr()'' function
	depends partially on the value of the <<attr-type>> argument:

	<dl dfn-type=value dfn-for=attr()>
		: <dfn>string</dfn>
		:: The [=substitution value=] is a CSS string,
			whose value is the literal value of the attribute.
			(No CSS parsing or "cleanup" of the value is performed.)

			No value triggers fallback.

		: <dfn>url</dfn>
		:: The [=substitution value=] is a CSS <<url>> value,
			whose url is the literal value of the attribute.
			(No CSS parsing or "cleanup" of the value is performed.)

			Note: If ''url()'' was syntactically capable of containing functions,
			''attr(foo url)'' would be identical to ''url(attr(foo string))''.

			No value triggers fallback.

		: <dfn>ident</dfn>
		:: The [=substitution value=] is a CSS <<custom-ident>>,
			whose value is the literal value of the attribute,
			with [=strip leading and trailing ASCII whitespace|leading and trailing ASCII whitespace stripped=].
			(No CSS parsing of the value is performed.)

			If the attribute value,
			after trimming,
			is the empty string,
			there is instead no [=substitution value=].

			If the <<custom-ident>>’s value is a [=CSS-wide keyword=]
			or <css>default</css>,
			there is instead no [=substitution value=].

		: <dfn>color</dfn>
		::
			[=Parse a component value=] from the attribute's value.
			If the result is a <<hex-color>>
			or a [=named color=] ident,
			the [=substitution value=] is that result as a <<color>>.

			Otherwise there is no [=substitution value=].

		: <dfn>number</dfn>
		::
			[=Parse a component value=] from the attribute's value.
			If the result is a <<number-token>>,
			the result is the [=substitution value=].

			Otherwise, there is no [=substitution value=].

		: <dfn>percentage</dfn>
		::
			[=Parse a component value=] from the attribute's value.
			If the result is a <<percentage-token>>,
			the result is the [=substitution value=].

			Otherwise, there is no [=substitution value=].

		: <dfn>length</dfn>
		: <dfn>angle</dfn>
		: <dfn>time</dfn>
		: <dfn>frequency</dfn>
		: <dfn>flex</dfn>
		::
			[=Parse a component value=] from the attribute's value.
			If the result is a <<dimension-token>>
			whose unit matches the given type,
			the result is the [=substitution value=].

			Otherwise, there is no [=substitution value=].

		: <dfn><<dimension-unit>></dfn>
		::
			[=Parse a component value=] from the attribute's value.
			If the result is a <<number-token>>,
			the [=substitution value=] is a dimension
			with the result's value,
			and the given unit.

			Otherwise, there is no [=substitution value=].
	</dl>

	Issue: Do we want to allow [=math functions=] as attr values
	for all the numeric types?
	And color functions for "color"?
	I think we do,
	but I'd have to check the contents to make sure they don't contain further reference functions;
	<code highlight=html>foo="rgb(var(--red), 0, 0)"</code>
	needs to be illegal for ''attr(foo color)''.

	<div class="example">
		This example shows the use of attr() to visually illustrate data
		in an XML file:

		<pre>
		&lt;stock>
			&lt;wood length="12"/>
			&lt;wood length="5"/>
			&lt;metal length="19"/>
			&lt;wood length="4"/>
		&lt;/stock>

		stock::before {
			display: block;
			content: "To scale, the lengths of materials in stock are:";
		}
		stock > * {
			display: block;
			width: attr(length em, 0px);
			height: 1em;
			border: solid thin;
			margin: 0.5em;
		}
		wood {
			background: orange url(wood.png);
		}
		metal {
			background: silver url(metal.png);
		}
		</pre>
	</div>

<h4 id=attr-substitution>
''attr()'' Substitution</h4>

	Issue: attr() and var() substitute at the same time,
	so I should probably rewrite [=substitute a var()=]
	to be more generally about "substitute a reference"
	and just use that for both of these functions.

	''attr()'' functions are [=substitute an attr()|substituted=] at computed-value time.
	If a declaration,
	once all ''attr()'' functions are substituted in,
	does not match its declared grammar,
	the declaration is [=invalid at computed-value time=].

	To <dfn export>substitute an ''attr()''</dfn>:

	1. If the ''attr()'' function has a [=substitution value=],
		replace the ''attr()'' function by the [=substitution value=].
	2. Otherwise, if the ''attr()'' function has a fallback value as its last argument,
		replace the ''attr()'' function by the fallback value.
		If there are any ''var()'' or ''attr()'' references in the fallback,
		[=substitute an attr()|substitute=] them as well.
	3. Otherwise, the property containing the ''attr()'' function
		is [=invalid at computed-value time=].

<!-- Big Text: random

████▌   ███▌  █    █▌ ████▌   ███▌  █     █
█▌  █▌ ▐█ ▐█  █▌   █▌ █▌  █▌ █▌  █▌ ██   ██
█▌  █▌ █▌  █▌ ██▌  █▌ █▌  █▌ █▌  █▌ █▌█ █▐█
████▌  █▌  █▌ █▌▐█ █▌ █▌  █▌ █▌  █▌ █▌ █ ▐█
█▌▐█   █████▌ █▌  ██▌ █▌  █▌ █▌  █▌ █▌   ▐█
█▌ ▐█  █▌  █▌ █▌   █▌ █▌  █▌ █▌  █▌ █▌   ▐█
█▌  █▌ █▌  █▌ █▌   ▐▌ ████▌   ███▌  █▌   ▐█
-->

<h2 id=randomness>
Generating Random Values</h2>

	It is often useful to incorporate some degree of "randomness" to a design,
	either to make repeated elements on a page feel less static and identical,
	or just to add a bit of "flair" to a page without being distracting.

	The ''random()'' and ''random-item()'' functions
	(the <dfn export for=CSS>random functions</dfn>)
	allow authors to incorporate randomness into their page,
	while keeping this randomness predictable from a design perspective,
	letting authors decide whether a random value should be reused in several places
	or be unique between instances.

	The exact random-number generation method is UA-defined.
	It <em>should</em> be the case that two distinct random values
	have no easily-detectable correlation,
	but this specification intentionally does not specify what that means
	in terms of cryptographic strength.
	Authors <em>must not</em> rely on [=random functions=]
	for any purposes that depend on quality cryptography.

<h3 id=random>
Generating a Random Numeric Value: the ''random()'' function</h3>

	The <dfn>random()</dfn> function is a [=math function=]
	that represents a random value between a minimum and maximum value,
	drawn from a uniform distribution,
	optionally limiting the possible values to a step between those limits:

	<pre class=prod>
	&lt;random()> = random( <<random-caching-options>>? , <<calc-sum>>, <<calc-sum>>, [by <<calc-sum>>]? )

	<dfn><<random-caching-options>></dfn> = <<dashed-ident>> || per-element
	</pre>

	Its arguments are:

	<dl>
		: <<random-caching-options>>
		:: The optional <<random-caching-options>>
			provides some control over whether a given ''random()'' function
			resolves similarly or differently to other ''random()''s on the page.
			See [[#random-caching]] for details.

			<div class=note>
				By default, ''random()'' resolves to a single value,
				shared by all elements using that style,
				and two ''random()'' functions with identical arguments
				will resolve to the same random value.

				Providing a <<dashed-ident>> does nothing,
				but can make the argument lists distinct
				between two or more otherwise-identical ''random()'' functions,
				so they'll generate distinct values.

				The ''per-element'' keyword causes the ''random()'' function
				to generate a different value <em>on each element</em> the function is applied to,
				rather than resolving to a single value per usage in the stylesheet.
			</div>

		: <<calc-sum>>, <<calc-sum>>
		:: The two required [=calculations=]
			specify the  minimum and maximum value
			the function can resolve to.
			Both limits are inclusive
			(the result can be the min or the max).

			If the maximum value is less than the minimum value,
			it behaves as if it's equal to the minimum value.

			<div class=example>
				For example, ''random(100px, 300px)''
				will resolve to a random <<length>> between ''100px'' and ''300px'':
				it might be ''100px'', ''300px'', or any value between them like ''234.5px''.
			</div>

		: ''by <<calc-sum>>''
		:: The final optional argument
			specifies a step value:
			the values the function can resolve to
			are further restricted to the form <code>min + (N * step)</code>,
			where N is a non-negative integer
			chosen uniformly randomly from the possible values
			that result in an in-range value.

			<div class=example>
				For example, ''random(100px, 300px, by 50px)''
				can only resolve to ''100px'', ''150px'', ''200px'', ''250px'', or ''300px'';
				it will never return a value like ''120px''.

				While the minimum value is always a possible result,
				the maximum value isn't always,
				if it's not also a multiple of the step from the minimum.
				For example, in ''random(100px, 300px, by 30px)'',
				the largest possible value it can resolve to is ''280px'',
				6 steps from the minimum value.

				Note that rounding issues might have an effect here:
				in ''random(100px, 200px, by 100px / 3)''
				you'll definitely get three possible values
				(''100px'', and approximately ''133.33px'' and ''166.67px''),
				but whether ''200px'' is possible depends on rounding precision.
				To be safe, you can put the maximum value
				<em>slightly above</em> where you expect the final step to land,
				like ''random(100px, 201px, by 100px / 3)''.
			</div>

			<div class=example>
				As explained in the definition of ''round()'',
				CSS has no "natural" precision for values,
				but the step value can be used to assign one.

				For example, ''random(100px, 500px, by 1px)''
				restricts it to resolving only to whole px values;
				''random(1, 10, by 1)''
				is restricted to resolving only to integers;
				etc.
			</div>

			Note: The definition of the step <em>does not</em> allow
			for naively generating a random value in the range
			and then rounding it to the nearest step value,
			as that can result in the values not appearing with the same weights.
			For example, ''random(100px, 200px, by 50px)''
			has to generate the three possible values each with a 1/3 chance;
			a naive rounding-based method will instead incorrectly generate ''150px''
			twice as often as the boundary values.
	</dl>

	All of the [=calculation=] arguments can resolve to any <<number>>, <<dimension>>, or <<percentage>>,
	but must have the <em>same</em> [=determine the type of a calculation|type=], or else the function is invalid;
	the result will have the same type as the arguments.

	<div class=example>
		For example, ''random(50px, 100%, by 1em)'' is valid
		(assuming percentages are valid in the context this is used,
		and resolve to a <<length>>),
		as all three arguments resolve to a length.

		However, ''random(50px, 180deg)'' is invalid,
		as lengths and angles are not the same type.
	</div>

	A ''random()'' function can be [=simplify a calculation tree|simplified=]
	as soon as its argument [=calculations=]
	can be simplified to numeric values.

	Note: This means that ''random()'' is <em>usually</em> resolved
	by [=computed value=] time,
	and thus will inherit as a static numeric value.
	However, if the argument [=calculations=] aren't resolved
	until [=used value=] time
	(such as if they include <<percentage>> values
	that require layout information to resolve),
	[=inheritance=] will transfer the ''random()'' function itself.
	(This is no different, however, to the behavior of the <<percentage>>s themselves,
	which would inherit as <<percentage>>s
	and thus might resolve to different values on the child elements.)


	Issue: At least in theory it should be fine to use ''random()''
	in non-property contexts,
	so long as ''per-element'' isn't specified;
	it's well-defined what happens with <code>@media (max-width: random(100px, 500px)) {...}</code>,
	for example.
	I suspect we want to disallow it, tho?

<h4 id=random-infinities>
Argument Ranges</h4>

	In ''random(A, B, by C)'',
	if A or B is infinite,
	the result is NaN.
	If C is infinite,
	the result is A.

	(If C is zero or negative,
	the result is A,
	but that falls out of the standard definition.)

	Note: As usual for [=math functions=],
	if any argument calculation is NaN,
	the result is NaN.

<h3 id=random-item>
Picking a Random Item From a List: the ''random-item()'' function</h3>

	The <dfn>random-item()</dfn> function
	resolves to a random item
	from among its list of items.

	<pre class=prod>
	&lt;random-item()> = random-item( <<random-caching-options>> ';' <<declaration-value>>? [ ';' <<declaration-value>>? ]* )
	</pre>

	The <em>required</em> <<random-caching-options>>
	is interpreted identically to ''random()''.
	(See [[#random-caching]] for details.)

	<div class=note>
		Like ''random()'',
		the <<dashed-ident>> can be used to force similar ''random-item()'' functions
		to generate distinct random values,
		and ''per-element''
		causes it to resolve to a distinct value on each element.

		Aside from these,
		the grouping of ''random-item()'' functions as "identical"
		is much simpler:
		all that matters is the number of arguments.

		That is, ''random-item(--x; red; blue; green)''
		and ''random-item(--x; 1; 2; 3)''
		will always resolve to the same argument index:
		either ''red'' and ''1'', or ''blue'' and ''2'', or ''green'' and ''3''.
		This allows coordination between groups of properties
		that all want to use a random set of values.

		On the other hand, ''random-item(--x; red; blue; green)''
		and ''random-item(--x; 1; 2; 3; 4)''
		will have no connection to each other;
		any of the 12 possible combinations can occur.
	</div>

	Note: The <<random-caching-options>> argument is required in ''random-item()'',
	but optional in ''random()'',
	both for parsing reasons
	(it's impossible to tell whether ''random-item(--foo; --bar; --baz)''
	has three <<declaration-value>> arguments
	or two and a <<random-caching-options>> argument),
	and because accidentally associating the random generation of ''random-item()'' functions together
	is much easier to do accidentally,
	since only the number of arguments is used to distinguish instances.

	The remaining arguments are arbitrary sequences of CSS values,
	separated by semicolons.
	The ''random-item()'' function resolves to one of these sequences,
	chosen uniformly at random.

	Note: Unlike most functions in CSS,
	''random-item()'' separates its arguments with semicolons,
	rather than commas,
	because its arguments can contain commas themselves.

	The ''random-item()'' function is an [=arbitrary substitution function=],
	like ''var()''.

	<div class=note>
		That is, if you use ''random-item()'':

		* So long as ''random-item()'' itself (and any other [=arbitrary substitution functions=])
			is syntactically valid,
			the entire property is assumed to be valid at parse time.
		* ''random-item()'' is substituted with whatever value it resolves to
			at [=computed value=] time
			when you'd [=substitute a var()=],
			so children all inherit the same resolved value.
		* If the substituted value ends up making the property invalid,
			the property's value becomes the [=guaranteed-invalid value=].
	</div>

	Issue: Define [=arbitrary substitution function=],
	probably over in Variables,
	since we have several upcoming functions leaning on this functionality.

	Issue: Since ''random-item()'' is var()-like,
	we probably want to restrict it to only be usable in properties.
	(This is likely something we want to apply to all such functions.)
	Tho ''random()'' is a fundamentally different kind of value,
	we probably want to restrict it as well,
	for thematic consistency.



<h3 id=random-caching>
Generating/Caching Random Values: the <<random-caching-options>> value</h4>

	In a programming language like JavaScript,
	there's a clear temporal ordering to code,
	so you can tell exactly <em>when</em> something like a call to {{Math/random()|Math.random()}} is evaluated.
	You can also store the results in a variable,
	making it clear when you're reusing a single random value in multiple places,
	versus using a distinct random value in each location.

	CSS, on the other hand, is a declarative language
	(code is not "executed" in any particular order,
	nor is there any control over how many times something is "executed");
	it makes it very easy to apply identical styles to multiple elements
	but difficult to specify distinct values for each of them
	(making it unclear whether a property using ''random()''
	is meant to resolve to the same value on each element it's applied to
	or to distinct values on each);
	and it has very limited "variable" functionality
	(making it difficult to intentionally reuse a particular randomly-generated value in several places).

	To resolve these issues,
	the ''random()'' and ''random-item()'' functions are defined to generate random values
	under the following caching semantics:

	* Each instance of ''random()'' or ''random-item()'' in a stylesheet
		specifies a <dfn>random-caching key</dfn>.
		Two instances of either function must resolve to <em>identical</em> values
		if their [=random-caching keys=] are identical;
		they must resolve to <em>distinct</em> values
		if they're different.

		("Distinct" here means generated by a fresh random operation;
		this might coincidentally result in the same value as another random operation.)

	* For ''random()'',
		the [=random-caching key=]
		is a [=tuple=] of:

		1. The [=used value=] of the minimum [=calculation=].
		2. The [=used value=] of the maximum [=calculation=].
		3. The [=used value=] of the step [=calculation=], if present,
			or null otherwise.
		4. The <<dashed-ident>> part of the <<random-caching-options>>, if present,
			or null otherwise.
		5. If ''per-element'' is specified in the <<random-caching-options>>,
			a unique value per element or pseudo-element the function appears in.

	* For ''random-item()'',
		the [=random-caching key=]
		is a [=tuple=] of:

		1. The number of arguments to the function.
		2. The <<dashed-ident>> part of the <<random-caching-options>>, if present,
			or null otherwise.
		3. If ''per-element'' is specified in the <<random-caching-options>>,
			a unique value per element or pseudo-element the function appears in.

	The "unique value per element or pseudo-element" must have the same lifetime
	as a JavaScript reference to the element
	(or to the [=originating element=] + sufficient additional info to uniquely identify the pseudo-element).
	Elements in separate documents
	(including across refreshes of the same page,
	which produces distinct documents with distinct elements)
	<em>should</em> have distinct unique values.
	(This is not strictly required,
	to allow for pseudo-random generation of these values,
	but uniqueness should be likely enough
	that authors cannot depend on elements having the same values across documents.)

	Additionally, the random generation method <em>should</em>
	generate distinct values for the same operation
	when invoked on different documents
	(including refreshes of the same page).

	<div class=example>
		For example, in the following stylesheet:

		<pre highlight=css>
		.random-square {
			width: random(100px, 500px);
			height: random(100px, 500px);
		}
		</pre>

		The [=random-caching keys=] for both functions are identical:
		<code>(100px, 500px, null, null, null)</code>.
		This means that both will resolve to the exact same value,
		guaranteeing a square element
		with a size somewhere between ''100px'' and ''500px''.
		Additionally, <em>every</em> ''.random-square'' element
		will have the same size.

		On other hand, in this stylesheet:

		<pre highlight=css>
		.random-rect {
			width: random(100px, 500px);
			height: random(--x, 100px, 500px);
		}
		</pre>

		The [=random-caching keys=] are distinct between the two functions:
		the function in 'width' has <code>(100px, 500px, null, null, null)</code>,
		while the function in 'height' has <code>(100px, 500px, null, --x, null)</code>.

		This means the two functions will resolve to distinct random values,
		making it very unlikely for the element to be square.
		However, every element matching ''.random-rect''
		will still have the <em>same</em> random size.

		Changing any aspect of the function also alters this key.
		The following two declarations are similarly distinct,
		resulting in the width and height having no connection to each other:

		<pre highlight=css>
		.random-rect-2 {
			width: random(100px, 500px);
			height: random(100px, 500px, by 50px);
		}
		</pre>

		But so long as the [=used values=] end up identical,
		two functions that look distinct might end up identical.
		For example, in the following code:

		<pre highlight=css>
		.random-square-2 {
			font-size: 16px;
			width: random(160px, 320px);
			height: random(10em, 20em);
		}
		</pre>

		The two functions superficially look different,
		but after the lengths are fully resolved
		they end up with identical [=random-caching keys=];
		each is <code>(160px, 320px, null, null, null)</code>,
		so actually the widths and heights will end up always identical.
	</div>

	<div class=example>
		By default, each instance of a ''random()'' function in a stylesheet
		essentially resolves to a static value,
		which is then shared by every element that property applies to.
		This behavior can be changed with the ''per-element'' keyword.

		For example, in:

		<pre highlight=css>
		.foo { width: random(100px, 500px); }
		</pre>

		Multiple elements matching ''.foo'' will end up with the same random width.

		But in:

		<pre highlight=css>
		.foo { width: random(per-element, 100px, 500px); }
		</pre>

		Every element matching ''.foo'' will get its own <em>unique</em> width.

		Note that this causes the value to be unique per element,
		not per <em>value</em> necessarily.
		For example, in:

		<pre highlight=css>
		.random-squares {
			width: random(per-element, 100px, 500px);
			height: random(per-element, 100px, 500px);
		}
		</pre>

		Every element matching ''.random-squares'' will get a distinct random value,
		but that value will be <em>the same</em> for 'width' and 'height' on a given element,
		making the element square.
		This is because in both properties
		the [=random-caching key=] is <code>(100px, 500px, null, null, [unique value for the element])</code>,
		so both functions will resolve to the same length on a single element.

		This makes random values in [=custom properties=] act more predictably.
		The preceding code could also be written as:

		<pre highlight=css>
		.foo {
			--size: random(per-element, 100px, 500px);
			width: var(--size);
			height: var(--size);
		}
		</pre>
	</div>


<!-- Big Text: counting

 ███▌   ███▌  █▌  █▌ █    █▌ █████▌ ████ █    █▌  ███▌
█▌  █▌ █▌  █▌ █▌  █▌ █▌   █▌   █▌    ▐▌  █▌   █▌ █▌  █▌
█▌     █▌  █▌ █▌  █▌ ██▌  █▌   █▌    ▐▌  ██▌  █▌ █▌
█▌     █▌  █▌ █▌  █▌ █▌▐█ █▌   █▌    ▐▌  █▌▐█ █▌ █▌ ██▌
█▌     █▌  █▌ █▌  █▌ █▌  ██▌   █▌    ▐▌  █▌  ██▌ █▌  █▌
█▌  █▌ █▌  █▌ █▌  █▌ █▌   █▌   █▌    ▐▌  █▌   █▌ █▌  █▌
 ███▌   ███▌   ███▌  █▌   ▐▌   █▌   ████ █▌   ▐▌  ███▌
-->

<h2 id="tree-counting">
Tree Counting Functions: the ''sibling-count()'' and ''sibling-index()'' notations</h2>

	The <dfn>sibling-count()</dfn> [=functional notation=] represents,
	as an <<integer>>,
	the total number of child <l spec=css-display-3>[=elements=]</l>
	in the parent of the element on which the notation is used.

	The <dfn>sibling-index()</dfn> [=functional notation=] represents,
	as an <<integer>>,
	the index of the element
	on which the notation is used
	among the children of its parent.
	Like '':nth-child()'',
	''sibling-index()'' is 1-indexed.

	Note: The ''counter()'' function can provide similar abilities as ''sibling-index()'',
	but returns a <<string>> rather than an <<integer>>.

	When used on a [=pseudo-element=],
	these both resolve as if specified
	on its [=ultimate originating element=].

	Note: Like the rest of CSS (other than [=selectors=]),
	''sibling-count()'' and ''sibling-index()''
	operate on the [=flat tree=].

	Note: These functions may, in the future,
	be extended to accept an ''of <<selector>>'' argument,
	similar to '':nth-child()'',
	to filter on a subset of the children.


<!-- Big Text: calc-size()

 ███▌   ███▌  █▌     ███▌         ███▌  ████ █████▌ █████▌   ██ ██
█▌  █▌ ▐█ ▐█  █▌    █▌  █▌       █▌  █▌  ▐▌      ▐▌ █▌      █▌   ▐█
█▌     █▌  █▌ █▌    █▌           █▌      ▐▌     ▐▌  █▌     █▌     ▐█
█▌     █▌  █▌ █▌    █▌     ████▌  ███▌   ▐▌    █▌   ████   █▌     ▐█
█▌     █████▌ █▌    █▌               █▌  ▐▌   █     █▌     █▌     ▐█
█▌  █▌ █▌  █▌ █▌    █▌  █▌       █▌  █▌  ▐▌  █      █▌      █▌   ▐█
 ███▌  █▌  █▌ █████  ███▌         ███▌  ████ █████▌ █████▌   ██ ██
-->

<h2 id=calc-size>
Calculating With Intrinsic Sizes: the ''calc-size()'' function</h2>

When transitioning between two [=definite=] sizes,
or slightly adjusting an existing definite size,
''calc()'' works great:
halfway between ''100%'' and ''20px'' is ''calc(50% + 10px)'',
''20%'' with a margin of ''15px'' on either side is ''calc(20% + 15px * 2)'',
etc.

But these operations are no longer possible if the size you want to adjust
or transition to/from
is an [=intrinsic size=],
for both practical and backward-compatibility reasons.
The ''calc-size()'' function
allows math to be performed on intrinsic sizes
in a safe, well-defined way.

	<pre class=prod>
	<dfn function lt="calc-size()">&lt;calc-size()></dfn> = calc-size( <<calc-size-basis>>, <<calc-sum>>? )

	<dfn>&lt;calc-size-basis></dfn> = [ <<intrinsic-size-keyword>> | <<calc-size()>> | any | <<calc-sum>> ]
	</pre>

The <dfn>&lt;intrinsic-size-keyword></dfn> production
matches any [=intrinsic size=] keywords allowed in the context.
For example, in 'width',
it matches ''width/auto'', ''width/min-content'', ''width/stretch'', etc.

If two arguments are given,
the first is the <dfn>calc-size basis</dfn>,
and the second is the <dfn>calc-size calculation</dfn>.
For either argument,
if a <<calc-sum>> is given,
it must resolve to a <<length>>.

If only one argument is given,
and it's a <<calc-sum>>,
then the provided argument is the [=calc-size calculation=],
and the [=calc-size basis=] defaults to ''calc-size()/any''.
Otherwise, the provided argument is the [=calc-size basis=],
and the [=calc-size calculation=] defaults to ''calc-size()/size''.

Within the [=calc-size calculation=],
if the [=calc-size basis=] is not ''calc-size()/any'',
the keyword <dfn for=calc-size() value>size</dfn> is allowed.
This keyword is a <<length>>,
and resolves at [=used value=] time.

''calc-size()'' represents an [=intrinsic size=].
It is specifically <em>not</em> a <<length>>;
any place that wants to accept a ''calc-size()''
must explicitly include it in its grammar.

<details class=note>
	<summary>Why not just allow intrinsic keywords in ''calc()''?</summary>

	In theory, rather than introducing ''calc-size()'',
	we could have defined ''calc(auto * .5)'' to be valid,
	allowing interpolation to work as normal.

	This has the minor issue that mixing keywords still wouldn't be allowed,
	but it wouldn't be as obvious
	(that is, ''calc((min-content + max-content)/2)'' looks reasonable,
	but would be disallowed).

	The larger issue, tho,
	is that this wouldn't allow us to smoothly transition percentages.
	''calc(50%)'' is only half the size of ''calc(100%)''
	when percentages are [=definite=] in the context;
	if they're not, the two values will usually be the same size
	(depending on the context, either ''0px'' or ''width/auto''-sized).

	Using a new function that explicitly separates
	the size you're calculating with
	from the calculation itself
	lets us get smooth interpolation in <em>all</em> cases.

	An additional consideration is that there are many effects,
	some small and some large,
	that depend on whether an element is intrinsically sized
	or definite.
	Using ''calc()'' would mean that the answer to the question
	"is the element intrinsically-sized"
	can have one answer in the middle of a transition
	("yes", for ''calc(min-content * .2 + 20px * .8))''),
	but a different answer at the end of the transition
	("no", for ''calc(20px)''),
	causing the layout to jump at the end of an otherwise-smooth transition.

	(This is similar to the stacking-layer changes that can occur
	when animating from ''opacity:1'' to ''opacity: 0'';
	any non-''1'' value forces a stacking context.
	With 'opacity' you can get around this by animating to ''.999'',
	which is visually indistinguishable from ''1''
	but forces a stacking context.
	It's not as reasonable to ask people to animate to ''calc(auto * .0001)''
	to ensure it retains its intrinsic-ness.)

	Again, using a new function that identifies itself
	as being <em>inherently</em> an intrinsic size,
	like ''calc-size(auto, 20px)'',
	means we can maintain stable layout behaviors the entire time,
	even when the actual size is a definite length.
</details>


<h3 id=resolving-calc-size>
Resolving ''calc-size()''</h3>

A ''calc-size()'' is treated, in all respects,
as if it were its [=calc-size basis=].
When actually performing layout calculations, however,
the size represented by its [=calc-size basis=]
is modified to the value of its [=calc-size calculation=],
with the ''calc-size()/size'' keyword
evaluating to the [=calc-size basis's=] original size.

(If the [=calc-size basis=] is <dfn for="calc-size()" value>any</dfn>,
the ''calc-size()'' is a [=definite=] length,
equal to its [=calc-size calculation=].)

<div class=example>
	For example,
	an element with ''height: calc-size(auto, size + 20px)''
	will be treated identically to an element with ''height: auto'',
	but will end up being 20px taller.
</div>

When evaluating the [=calc-size calculation=],
if percentages are not definite in the given context,
the resolve to ''0px''.
Otherwise, they resolve as normal.

(In the [=calc-size basis=],
percentages resolve as normal for the context regardless of definite-ness,
including possibly making a property [=behave as auto=], etc.)

<div class=note>
	Percentages in the basis work as normal
	so you can always smoothly transition to <em>any</em> size,
	regardless of its value or behavior.
	For example, without ''calc-size()'',
	transitioning from ''100%'' to ''0px''
	only works smoothly if the percentage is [=definite=];
	if it's not, then during the entire transition
	the property might [=behave as auto=]
	and not actually change size at all.

	Percentages in the calculation, on the other hand,
	are resolved to 0 when indefinite
	to avoid making the ''calc-size()''
	potentially act in two different ways;
	there are some cases where a ''width/min-content'' size
	will cause different layout effects than a ''100%'' size,
	and so a ''calc-size()'' has to masquerade as one or the other.
</div>


<h3 id=interp-calc-size>
Interpolating ''calc-size()''</h3>

Two ''calc-size()'' functions can be interpolated if:

: both [=calc-size basises=] are the same <<intrinsic-size-keyword>>
:: The result's [=calc-size basis=] is that keyword

: both [=calc-size basises=] are <<calc-sum>>s
:: The result's [=calc-size basis=] is the interpolation of the two input basises.

: either [=calc-size basis=] is ''calc-size()/any''
:: The result's [=calc-size basis=] is the non-''calc-size()/any'' basis
	(or ''calc-size()/any'' if both are).

(For these purposes, if the [=calc-size basis=] is a ''calc-size()'',
treat it as its own [=calc-size basis=].)

The result's [=calc-size calculation=] is the interpolation of the two input [=calc-size calculations=].

Note: These interpolation restrictions ensure that a ''calc-size()''
doesn't try to act in two different ways at once;
there are some cases where a ''width/min-content'' and ''width/max-content''
would produce different layout behaviors, for example,
so the ''calc-size()'' has to masquerade as one or the other.
This, unfortunately, means you can't transition between keywords,
like going from ''width/auto'' to ''width/min-content''.

As well, a ''calc-size()'' can be interpolated
with a <<length-percentage>> or an <<intrinsic-size-keyword>>,
behaving as if the second value were ''calc-size(<var ignore>value</var>)''.

<div class=example>
	For example, ''calc-size()'' allows interpolation to/from ''height: auto'':

	<pre class=lang-css>
	details {
		transition: height 1s;
	}
	details::details-content {
		display: block;
	}
	details[open]::details-content {
		height: auto;
	}
	details:not([open])::details-content {
		height: calc-size(0px);
	}
	</pre>

	This will implicitly interpolate
	between ''calc-size(auto, size)'' and ''calc-size(any, 0px)''.
	Half a second after opening the <{details}>,
	the ::details-content wrapper's 'height'
	will be ''calc-size(auto, size * .5)'',
	half its open size;
	thruout the transition it'll smoothly animate its height.
</div>

Note: ''calc-size()'' is designed such that
transitioning to/from ''calc-size([=definite=] length)''
will <em>always</em> work smoothly,
regardless of how the other side of the transition is specified.

Issue: Or is it compatible to just allow direct interpolation
between keywords and fixed lengths,
even without an explicit ''calc-size()'' being used on one size?
This would be nice, but compat analysis is required.



<!-- Big Text: etc

█████▌ █████▌  ███▌
█▌       █▌   █▌  █▌
█▌       █▌   █▌
████     █▌   █▌
█▌       █▌   █▌
█▌       █▌   █▌  █▌
█████▌   █▌    ███▌
-->


<h2 class="no-num" id="acknowledgments">
Acknowledgments</h2>

	Firstly, the editors would like to thank
	all of the contributors to the <a href="https://www.w3.org/TR/css-values-4/#acknowledgments">previous level</a>
	of this module.

	Secondly, we would like to acknowledge
	L. David Baron
	and
	Mike Bremford
	for their comments and suggestions,
	which have improved Level 5.

<h2 class="no-num" id="changes">
Changes</h2>

<h3 class=no-num id="changes-recent">
Recent Changes</h3>

	(This is a subset of [[#additions-L4]].)

<h3 class=no-num id="additions-L4">
Additions Since Level 4</h3>

	Additions since <a href="http://www.w3.org/TR/css-values-4/">CSS Values and Units Level 4</a>:

	<ul>
		<li>Added the ''toggle()'' and ''attr()'' notations
	</ul>

<h2 class="no-num" id="sec-pri">
Security and Privacy Considerations</h2>

	This specification mostly just defines units that are common to CSS specifications,
	and which present no security concerns.

	Note: Does URL handling have a security concern?  Probably.

	This specification defines units that expose the user's screen size
	and default font size,
	but both are trivially observable from JS,
	so they do not constitute a new privacy risk.