Overview.bs

<pre class='metadata'>
Title: CSS Values and Units Module Level 3
Group: CSSWG
Shortname: css-values
Level: 3
Status: ED
Deadline: 2022-02-22
Work Status: Testing
Implementation Report: https://drafts.csswg.org/css-values-3/implementation-report.html
ED: https://drafts.csswg.org/css-values-3/
TR: https://www.w3.org/TR/css-values-3/
Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Former Editor: Håkon Wium Lie, Opera Software, howcome@opera.com
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>, pairing, property
Ignored Vars: Cn+1, n
Inline Github Issues: no
Default Highlight: css
WPT Display: open
</pre>
<pre class='link-defaults'>
spec: css-backgrounds-3; type: type; text: <position>
spec: css-backgrounds-3; type: property; text: border-color
spec: css-backgrounds-3; type: property; text: box-shadow
spec: css2; type: property; text: border-collapse
spec: css-color-4; type: value; text: currentcolor
spec: infra; type: dfn; text: string
</pre>
<pre class="ignored-specs">
spec: css-device-adapt-1;
</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>

<style>
/* Put nice boxes around each algorithm. */
[data-algorithm]:not(.heading) {
	padding: .5em;
	border: thin solid #ddd; border-radius: .5em;
	margin: .5em calc(-0.5em - 1px);
}
[data-algorithm]:not(.heading) > :first-child {
	margin-top: 0;
}
[data-algorithm]:not(.heading) > :last-child {
	margin-bottom: 0;
}
[data-algorithm] [data-algorithm] {
	margin: 1em 0;
}
</style>

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

	The value definition field of each CSS property can contain keywords,
	data types (which appear between <css>&lt;</css> and <css>></css>),
	and information on how they can be combined.
	Generic data types (<<length>> being the most widely used)
	that can be used by many properties are described in this specification,
	while more specific data types (e.g., <<spacing-limit>>)
	are described in the corresponding modules.

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

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

<!-- Big Text: syntax

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

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

	The <dfn for=CSS export lt="value definition syntax | CSS value definition syntax">value definition syntax</dfn> described here
	is used to define the set of valid values for CSS properties
	(and the valid syntax of many other parts of CSS).
	A value so described can have one or more components.

<h3 id="component-types">
Component Value Types</h3>

	Component value types are designated in several ways:

	1. <a href="#keywords">Keyword</a> values (such as <css>auto</css>, ''disc'', etc.),
		which appear literally, without quotes (e.g. <code>auto</code>).

	2. Basic data types,
		which appear between <css>&lt;</css> and <css>></css>
		(e.g., <<length>>, <<percentage>>, etc.).
		For <a>numeric data types</a>,
		this type notation can annotate any range restrictions
		using the [[#numeric-ranges|bracketed range notation]] described below.

	3. Property value ranges,
		which represent the same pattern of values as a property bearing the same name.
		These are written as the property name,
		surrounded by single quotes,
		between <css>&lt;</css> and <css>></css>,
		e.g., <<'border-width'>>, <<'background-attachment'>>, etc.

		These types <em>do not</em> include <a href="#common-keywords">CSS-wide keywords</a> such as ''inherit''.
		Additionally,
		if the property's value grammar
		is a <a lt=# grammar>comma-separated repetition</a>,
		the corresponding type
		does not include the top-level <a lt=# grammar>comma-separated list multiplier</a>.
		(E.g. if a property named <css>pairing</css> is defined as <css>[ <<custom-ident>> <<integer>>? ]#</css>,
		then <css>&lt;\'pairing'></css> is equivalent to <css>[ <<custom-ident>> <<integer>>? ]</css>,
		not <css>[ <<custom-ident>> <<integer>>? ]#</css>.)\

		<details class=note>
			<summary>Why remove the multiplier?</summary>

			The top-level multiplier is ripped out of these value types
			because top-level comma-separated repetitions are mostly used for
			[=coordinating list properties=],
			and when a shorthand combines several such properties,
			it needs the unmultiplied grammar
			so it can construct its <em>own</em> comma-separated repetition.

			Without this special treatment,
			every such longhand would have to be defined
			with an ad-hoc production just for the inner value,
			which makes the grammars harder to understand overall.
		</details>

	4. Functional notations and their arguments.
		These are written as the function's name,
		followed by an empty parentheses pair,
		between <css>&lt;</css> and <css>></css>,
		e.g. <<calc()>>,
		and references the correspondingly-named [=functional notation=].

	5. Other non-terminals.
		These are written as the name of the non-terminal
		between <css>&lt;</css> and <css>></css>,
		as in <<spacing-limit>>.
		Notice the distinction between <<border-width>> and <<'border-width'>>:
		the latter represents the grammar of the 'border-width' property,
		the former requires an explicit expansion elsewhere.
		The definition of a non-terminal is typically located near its first appearance in the specification.

	Some property value definitions also include the slash (/),
	the comma (,),
	and/or parentheses as literals.
	These represent their corresponding tokens.
	Other non-keyword literal characters that may appear in a component value,
	such as “+”,
	must be written enclosed in single quotes.

	<strong><dfn lt="," id='comb-comma' export grammar>Commas</dfn> specified in the grammar are implicitly omissible</strong> in some circumstances,
	when used to separate optional terms in the grammar.
	Within a top-level list in a property or other CSS value,
	or a function's argument list,
	a comma specified in the grammar must be omitted if:

	<ul>
		<li>
			all items preceding the comma have been omitted

		<li>
			all items following the comma have been omitted

		<li>
			multiple commas would be adjacent (ignoring <a href="https://www.w3.org/TR/css-syntax/#whitespace">white space</a>/comments),
			due to the items between the commas being omitted.
	</ul>

	<div class='example'>
		For example, if a function can accept three arguments in order,
		but all of them are optional,
		the grammar can be written like:

		<pre class='prod'>
		example( first? , second? , third? )
		</pre>

		Given this grammar,
		writing ''example(first, second, third)'' is valid,
		as is ''example(first, second)'' or ''example(first, third)'' or ''example(second)''.
		However, ''example(first, , third)'' is invalid, as one of those commas are no longer separating two options;
		similarly, ''example(,second)'' and ''example(first,)'' are invalid.
		''example(first second)'' is also invalid,
		as commas are still required to actually separate the options.

		If commas were not implicitly omittable,
		the grammar would have to be much more complicated
		to properly express the ways that the arguments can be omitted,
		greatly obscuring the simplicity of the feature.
	</div>

	All CSS properties also accept the <a href="#common-keywords">CSS-wide keyword values</a>
	as the sole component of their property value.
	For readability these are not listed explicitly in the property value syntax definitions.
	For example, the full value definition of 'border-color'
	under [[CSS-CASCADE-3|CSS Cascading and Inheritance Level 3]]
	is <code>&lt;color>{1,4} | inherit | initial | unset</code>
	(even though it is listed as <code>&lt;color>{1,4}</code>).

	Note: This implies that, in general,
	combining these keywords with other component values in the same declaration
	results in an invalid declaration.
	For example,
	''background: url(corner.png) no-repeat, inherit;'' is invalid.

<h3 id="component-combinators">
Component Value Combinators</h3>

	Component values can be arranged into property values as follows:

	<ul export dfn-type="grammar">
		<li>Juxtaposing components means that
			all of them must occur, in the given order.
		<li>A double ampersand (<dfn id='comb-all'>&&</dfn>) separates two or more components,
			all of which must occur, in any order.
		<li>A double bar (<dfn id='comb-any'>||</dfn>) separates two or more options:
			one or more of them must occur, in any order.
		<li>A bar (<dfn id='comb-one'>|</dfn>) separates two or more alternatives:
			exactly one of them must occur.
		<li>Brackets ([&nbsp;]) are for grouping.
	</ul>

	Juxtaposition is stronger than the double ampersand, the double
	ampersand is stronger than the double bar, and the double bar
	is stronger than the bar. Thus, the following lines are equivalent:

	<pre>
	  a b   |   c ||   d &&   e f
	[ a b ] | [ c || [ d && [ e f ]]]
	</pre>

	For reorderable combinators (||, &&),
	ordering of the grammar does not matter:
	components in the same grouping may be interleaved in any order.
	Thus, the following lines are equivalent:

	<pre>
	a || b || c
	b || a || c
	</pre>

	Note: Combinators are <em>not</em> associative, so grouping is significant.
	For example, ''a || b || c'' and ''a || [ b || c ]'' are distinct grammars:
	the first allows a value like ''b a c'', but the second does not.

<h3 id="component-multipliers">
Component Value Multipliers</h3>

	Every type, keyword, or bracketed group may be followed by one of
	the following modifiers:

	<ul export dfn-type="grammar">
		<li>An asterisk (<dfn id='mult-zero-plus'>*</dfn>)
			indicates that the preceding type, word, or group
			occurs zero or more times.

		<li>A plus (<dfn id='mult-one-plus'>+</dfn>)
			indicates that the preceding type, word, or group
			occurs one or more times.

		<li>A question mark (<dfn id='mult-opt'>?</dfn>)
			indicates that the preceding type, word, or group
			is optional (occurs zero or one times).

		<li>A single number in curly braces (<dfn id='mult-num'>{<var>A</var>}</dfn>)
			indicates that the preceding type, word, or group
			occurs <var>A</var> times.

		<li>A comma-separated pair of numbers in curly braces (<dfn id='mult-num-range'>{<var>A</var>,<var>B</var>}</dfn>)
			indicates that the preceding type, word, or group
			occurs at least <var>A</var> and at most <var>B</var> times.
			The <var>B</var> may be omitted ({<var>A</var>,})
			to indicate that there must be at least <var>A</var> repetitions,
			with no upper bound on the number of repetitions.

		<li>A hash mark (<dfn id='mult-comma'>#</dfn>)
			indicates that the preceding type, word, or group
			occurs one or more times, separated by comma tokens
			(which may optionally be surrounded by <a href="https://www.w3.org/TR/css-syntax/#whitespace">white space</a> and/or comments).
			It may optionally be followed by the curly brace forms, above,
			to indicate precisely how many times the repetition occurs,
			like ''&lt;length>#{1,4}''.

		<li>An exclamation point (<dfn id='mult-req'>!</dfn>) after a group
			indicates that the group is required
			and must produce at least one value;
			even if the grammar of the items within the group
			would otherwise allow the entire contents to be omitted,
			at least one component value must not be omitted.
	</ul>

	The <css>+</css> and <css>#</css> multipliers may be stacked as ''+#'';
	similarly, the <css>#</css> and <css>?</css> multipliers may be stacked as ''#?''.
	These stacks each represent the later multiplier
	applied to the result of the earlier multiplier.
	(These same stacks can be represented using grouping,
	but in complex grammars this can push the number of brackets beyond readability.)

	For repeated component values (indicated by <css>*</css>, <css>+</css>, or <css>#</css>),
	[=UAs=] must support at least 20 repetitions of the component.
	If a property value contains more than the supported number of repetitions,
	the declaration must be ignored as if it were invalid.

<h3 id='combinator-multiplier-patterns'>
Combinator and Multiplier Patterns</h3>

	There are a small set of common ways to combine multiple independent <a>component values</a> in particular numbers and orders.
	In particular, it's common to want to express that,
	from a set of component value,
	the author must select zero or more, one or more, or all of them,
	and in either the order specified in the grammar or in any order.

	All of these can be easily expressed using simple patterns of <a href="#component-combinators">combinators</a> and <a href="#component-multipliers">multipliers</a>:

	<table class='data'>
		<thead>
			<tr>
				<th>
				<th>in order
				<th>any order
		<tbody>
			<tr>
				<th>zero or more
				<td><code>A? B? C?</code>
				<td><code>A? || B? || C?</code>

			<tr>
				<th>one or more
				<td><code>[ A? B? C? ]!</code>
				<td><code>A || B || C</code>

			<tr>
				<th>all
				<td><code>A B C </code>
				<td><code>A && B && C</code>
	</table>

	Note that all of the "any order" possibilities are expressed using combinators,
	while the "in order" possibilities are all variants on juxtaposition.

<h3 id="component-whitespace">
Component Values and White Space</h3>

	Unless otherwise specified,
	<a href="https://www.w3.org/TR/css-syntax/#whitespace">white space</a> and/or comments may appear before, after, and/or between
	components combined using the above
	<a href="#component-combinators">combinators</a> and
	<a href="#component-multipliers">multipliers</a>.

	Note: In many cases, spaces will in fact be <em>required</em> between components
	in order to distinguish them from each other.
	For example, the value ''1em2em'' would be parsed as a single <<dimension-token>>
	with the number ''1'' and the identifier ''em2em'',
	which is an invalid unit.
	In this case, a space would be required before the ''2''
	to get this parsed as the two lengths ''1em'' and ''2em''.

<h3 id="value-examples">
Property Value Examples</h3>

	Below are some examples of properties with their corresponding value
	definition fields

	<div class=example>
		<table class="data" id="propvalues">
			<thead>
				<tr>
					<th>Property
					<th>Value definition field
					<th>Example value
			</thead>
			<tbody>
				<tr>
					<td>'orphans'
					<td>&lt;integer>
					<td>''3''
				<tr>
					<td>'text-align'
					<td>left | right | center | justify
					<td>''text-align/center''
				<tr>
					<td>'padding-top'
					<td>&lt;length> | &lt;percentage>
					<td>''5%''
				<tr>
					<td>'outline-color'
					<td>&lt;color> | invert
					<td>''#fefefe''
				<tr>
					<td>'text-decoration'
					<td>none | underline || overline || line-through || blink
					<td>''overline underline''
				<tr>
					<td><a property>font-family</a>
					<td>[ &lt;family-name> | &lt;generic-family> ]#
					<td>''"Gill Sans", Futura, sans-serif''
				<tr>
					<td>'border-width'
					<td>[ &lt;length> | thick | medium | thin ]{1,4}
					<td>''2px medium 4px''
				<tr>
					<td>'box-shadow'
					<td>[ inset? && &lt;length>{2,4} && &lt;color>? ]# | none
					<td>''3px 3px rgba(50%, 50%, 50%, 50%), lemonchiffon 0 0 4px inset''
			</tbody>
		</table>
	</div>

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

	The <dfn export for=CSS>textual data types</dfn> include
	various keywords and identifiers
	as well as strings (<<string>>) and URLs (<<url>>).

	CSS <dfn export lt="CSS identifier | CSS ident | identifier | ident" for="CSS">identifiers</dfn>,
	generically denoted by <dfn>&lt;ident></dfn>,
	consist of a sequence of characters conforming to the <<ident-token>> grammar. [[!CSS-SYNTAX-3]]
	Identifiers cannot be quoted;
	otherwise they would be interpreted as strings.
	CSS properties accept two classes of [=CSS/identifiers=]:
	[[#keywords|pre-defined keywords]]
	and [[#custom-idents|author-defined identifiers]].

	Note: The <<ident>> production is not meant for property value definitions--
	<<custom-ident>> should be used instead.
	It is provided as a convenience for defining other syntactic constructs.

<!-- Big Text: keywords

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

<h3 id="keywords">
Pre-defined Keywords</h3>

	In the value definition fields,
	<dfn lt="keyword" export for=CSS>keywords</dfn> with a pre-defined meaning appear literally.
	Keywords are [=CSS/identifiers=]
	and are interpreted <a lt="ASCII case-insensitive">ASCII case-insensitively</a>
	(i.e., [a-z] and \[A-Z] are equivalent).

	<div class="example">
		For example, here is the value definition for the 'border-collapse'
		property:

		<pre>Value: collapse | separate</pre>

		And here is an example of its use:

		<pre>table { border-collapse: separate }</pre>
	</div>

<h4 id="common-keywords">
CSS-wide keywords: ''initial'', ''inherit'' and ''unset''</h4>

	As defined <a href="#component-types">above</a>,
	all properties accept the <dfn export>CSS-wide keywords</dfn>,
	which represent value computations common to all CSS properties.
	These keywords are normatively defined in
	the <a href="https://www.w3.org/TR/css-cascade/#defaulting-keywords">CSS Cascading and Inheritance Module</a>.

	<wpt>
	css/css-multicol/multicol-inherit-002.xht
	css/css-multicol/multicol-rule-color-inherit-001.xht
	css/css-multicol/multicol-rule-color-inherit-002.xht
	css/CSS2/values/units-008.xht
	</wpt>

	Other CSS specifications can define additional CSS-wide keywords.

	<!-- Make it easier to add CSS-wide keywords by defining a grammar production. -->

<h3 id='custom-idents'>
Author-defined Identifiers: the <<custom-ident>> type</h3>

	Some properties accept arbitrary author-defined identifiers as a component value.
	This generic data type is denoted by <dfn id="identifier-value">&lt;custom-ident></dfn>,
	and represents any valid [=CSS identifier=]
	that would not be misinterpreted as a pre-defined keyword in that property's value definition.
	Such identifiers are fully case-sensitive,
	even in the ASCII range
	(e.g. ''example'' and ''EXAMPLE'' are two different, unrelated user-defined identifiers).

	The <a>CSS-wide keywords</a> are not valid <<custom-ident>>s.
	The <css>default</css> keyword is reserved
	and is also not a valid <<custom-ident>>.
	Specifications using <<custom-ident>> must specify clearly
	what other keywords are excluded from <<custom-ident>>, if any--
	for example by saying that any pre-defined keywords in that property's value definition are excluded.
	Excluded keywords are excluded in all <a lt="ASCII case-insensitive">ASCII case permutations</a>.

	When parsing positionally-ambiguous keywords in a property value,
	a <<custom-ident>> production can only claim the keyword if no other unfulfilled production can claim it.

	<div class="example">
		For example, the shorthand declaration ''animation: ease-in ease-out''
		is equivalent to the longhand declarations
		''animation-timing-function: ease-in; animation-name: ease-out;''.
		''ease-in'' is claimed by the <<easing-function>> production belonging to 'animation-timing-function',
		leaving ''ease-out'' to be claimed by the <<custom-ident>> production belonging to 'animation-name'.
	</div>

	Note: When designing grammars with <<custom-ident>>,
	the <<custom-ident>> should always be “positionally unambiguous”,
	so that it's impossible to conflict with any keyword values in the property.

<!-- Big Text: string

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

<h3 id="strings">
Quoted Strings: the <<string>> type</h3>

	[=Strings=] are denoted by <dfn id="string-value">&lt;string></dfn>.
	When written literally,
	they consist of a sequence of characters delimited by double quotes or single quotes,
	corresponding to the <<string-token>> production
	in the <a href="https://www.w3.org/TR/css-syntax/">CSS Syntax Module</a> [[!CSS-SYNTAX-3]].

	<div class=example>
		Double quotes cannot occur inside double quotes, unless
		<a href="https://www.w3.org/TR/CSS2/syndata.html#escaped-characters">escaped</a>
		(as <code>"\""</code> or as <code>"\22"</code>).
		Analogously for single quotes (<code>&#39;\&#39;&#39;</code> or <code>&#39;\27&#39;</code>).

		<pre>
		content: "this is a &#39;string&#39;.";
		content: "this is a \"string\".";
		content: &#39;this is a "string".&#39;;
		content: &#39;this is a \&#39;string\&#39;.&#39;
		</pre>
	</div>

	It is possible to break strings over several lines, for aesthetic or
	other reasons, but in such a case the newline itself has to be escaped
	with a backslash (\). The newline is subsequently removed from the
	string. For instance, the following two selectors are exactly the
	same:

	<div class="example">
		<p style="display:none">Example(s):
		<pre>
		a[title="a not s\
		o very long title"] {/*...*/}
		a[title="a not so very long title"] {/*...*/}
		</pre>
	</div>

	Since a string cannot directly represent a newline, to include a
	newline in a string, use the escape "\A". (Hexadecimal A is the line
	feed character in Unicode (U+000A), but represents the generic notion
	of "newline" in CSS.)

<!-- Big Text: url

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

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

	The <dfn>url()</dfn> <a>functional notation</a>,
	denoted by <<url>>,
	represents a <dfn noexport>URL</dfn>,
	which is a pointer to a resource.
	The typical syntax of a <<url>> is:

	<pre class="prod">
		<dfn id="url-value">&lt;url></dfn> = url( <<string>> <<url-modifier>>* )
	</pre>

	<div class="example">
		This example shows a URL being used as a background image:

		<pre highlight=css>
		body { background: url("http://www.example.com/pinkish.gif") }
		</pre>
	</div>

	A ''url()'' can alternatively be written be written without quotation marks around the URL value,
	in which case it is <a lt="consume a url token" spec=css-syntax-3>specially-parsed</a>
	as a <<url-token>>; see [[css-syntax-3#consume-url-token]]. [[!CSS-SYNTAX-3]]

	<div class="example">
		For example, the following declarations are identical:

		<pre>
			background: url("http://www.example.com/pinkish.gif");
			background: url(http://www.example.com/pinkish.gif);
		</pre>
	</div>

	Note: The unquoted ''url()'' syntax cannot accept a <<url-modifier>> argument
	and has extra escaping requirements:
	parentheses, <a href="https://www.w3.org/TR/css-syntax/#whitespace">whitespace</a> characters,
	single quotes (&#39;) and double quotes (") appearing in a URL
	must be escaped with a backslash,
	e.g. ''url(open\(parens)'', ''url(close\)parens)''.
	(In quoted <<string>> ''url()''s,
	only newlines and the character used to quote the string need to be escaped.)
	Depending on the type of URL,
	it might also be possible to write these characters as URL-escapes
	(e.g. ''url(open%28parens)'' or ''url(close%29parens)'')
	as described in [[URL]].

	Some CSS contexts (such as ''@import'') also allow a <<url>>
	to be represented by a bare <<string>>, without the function wrapper.
	In such cases the string behaves identically to a ''url()'' function containing that string.

	<div class="example">
		For example, the following statements act identically:
		<pre>
			@import url("base-theme.css");
			@import "base-theme.css";
		</pre>
	</div>

<h4 id="relative-urls">
Relative URLs</h4>

	In order to create modular style sheets that are not dependent on
	the absolute location of a resource, authors should use relative URLs.
	Relative URLs (as defined in [[!URL]]) are resolved to full URLs
	using a base URL. RFC&nbsp;3986, section&nbsp;3, defines the normative
	algorithm for this process.
	For CSS style sheets, the base URL is that of the style sheet itself,
	not that of the styled source document.
	Style sheets embedded within a document have
	the base URL associated with their container.

	Note: For HTML documents,
	the <a href="https://html.spec.whatwg.org/multipage/urls-and-fetching.html#dynamic-changes-to-base-urls">base URL is mutable</a>.

	When a <<url>> appears in the computed value of a property,
	it is resolved to an absolute URL,
	as described in the preceding paragraph.
	The computed value of a URL that the [=UA=] cannot resolve to an absolute URL is the specified value.

	<div class="example">
		For example, suppose the following rule:

		<pre>body { background: url("tile.png") }</pre>

		is located in a style sheet designated by the URL:

		<pre>http://www.example.org/style/basic.css</pre>

		The background of the source document's <code>&lt;body></code>
		will be tiled with whatever image is described by the resource designated by the URL:

		<pre>http://www.example.org/style/tile.png</pre>

		The same image will be used regardless of the URL of the source document containing the <code>&lt;body></code>.
	</div>

<h5 id='local-urls'>
Fragment URLs</h5>

	To work around some common eccentricities in browser URL handling,
	CSS has special behavior for fragment-only urls.

	If a ''url()''’s value starts with a U+0023 NUMBER SIGN (<code>#</code>) character,
	parse it as per normal for URLs,
	but additionally set the <dfn export for="url()">local url flag</dfn> of the ''url()''.

	When matching a ''url()'' with the <a>local url flag</a> set,
	ignore everything but the URL's fragment,
	and resolve that fragment against the current document that relative URLs are resolved against.
	This reference must always be treated as same-document
	(rather than cross-document).

	When <a href="https://www.w3.org/TR/cssom-1/#serializing-css-values">serializing</a>
	a ''url()'' with the <a>local url flag</a> set,
	it must serialize as just the fragment.

	<details class=note>
		<summary>What “browser eccentricities”?</summary>

		Theoretically, browsers should re-resolve any relative URLs,
		including fragment-only URLs,
		whenever the document's base URL changes
		(such as through mutation of the <{base}> element,
		or calling {{History/pushState()}}).
		In many cases they don't, however,
		and so without special handling,
		fragment-only URLs will suddenly become cross-document references
		(pointing at the previous base URL)
		and break in many of the places they're used.

		Since fragment-only URLs express a clear semantic
		of wanting to refer to the current document
		regardless of what its current URL is,
		this hack preserves the expected behavior at least in these cases.
	</details>

<h4 id="url-empty">
Empty URLs</h4>

	If the value of the <<url>> is the empty string
	(like ''url("")'' or ''url()''),
	the url must resolve to an invalid resource
	(similar to what the url ''about:invalid'' does).

	Its computed value is ''url("")'',
	and it must serialize as such.

	<wpt>
	css/css-values/urls/empty.html
	</wpt>

	Note: This matches the behavior of empty urls for embedded resources elsewhere in the web platform,
	and avoids excess traffic re-requesting the stylesheet or host document
	due to editing mistakes leaving the ''url()'' value empty,
	which are almost certain to be invalid resources for whatever the ''url()'' shows up in.
	Linking on the web platform <em>does</em> allow empty urls,
	so if/when CSS gains some functionality to control hyperlinks,
	this restriction can be relaxed in those contexts.

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

	The ''url()'' function supports specifying additional <dfn>&lt;url-modifier></dfn>s,
	which change the meaning or the interpretation of the URL somehow.
	A <<url-modifier>> is either an <<ident>> or a <a>functional notation</a>.

	This specification does not define any <<url-modifier>>s,
	but other specs may do so.

	Note: A <<url>> that is either unquoted or not wrapped in ''url()'' notation
	cannot accept any <<url-modifier>>s.

<h2 id="numeric-types">
Numeric Data Types</h2>

	Numeric data types are used to represent
	quantities, indexes, positions, and other such values.
	Although many syntactic variations can exist
	in expressing the quantity (numeric aspect) in a given numeric value,
	the <a lt="specified value">specified</a> and <a>computed value</a>
	do not distinguish these variations:
	they represent the value’s abstract quantity,
	not its syntactic representation.

	The <dfn>numeric data types</dfn> include
	<<integer>>,
	<<number>>,
	<<percentage>>,
	and various <a>dimensions</a>
	including <<length>>, <<angle>>, <<time>>, <<frequency>>, and <<resolution>>.

	Note: While general-purpose <a>dimensions</a> are defined here,
	some other modules define additional data types
	(e.g. [[css-grid-1]] introduces ''fr'' units)
	whose usage is more localized.

<h3 id="numeric-ranges">
Range Restrictions and Range Definition Notation</h3>

	Properties can restrict numeric values to some range.
	If the value is outside the allowed range,
	then unless otherwise specified,
	the declaration is invalid and must be <a href="https://www.w3.org/TR/CSS2/conform.html#ignore">ignored</a>.
	Range restrictions can be annotated in the numeric type notation
	using <dfn export local-lt="bracketed range notation">CSS bracketed range notation</dfn>--
	<code>[<var>min</var>,<var>max</var>]</code>--
	within the angle brackets, after the identifying keyword,
	indicating a closed range
	between (and including) <var>min</var> and <var>max</var>.
	For example, <<integer [0,10]>> indicates an integer between ''0'' and ''10'', inclusive,
	while <<angle [0, 180deg]>> indicates an angle between ''0deg'' and ''180deg''
	(expressed in any unit).

	Note: CSS values generally do not allow open ranges;
	thus only square-bracket notation is used.

	CSS theoretically supports infinite precision and infinite ranges for all value types;
	however in reality implementations have finite capacity.
	[=UAs=] should support reasonably useful ranges and precisions.
	Range extremes that are ideally unlimited
	are indicated using &infin; or &minus;&infin; as appropriate.
	For example, <<length [0, &infin;]>> indicates a non-negative length.

	If no range is indicated,
	either by using the <a>bracketed range notation</a>
	or in the property description,
	then <code>[&minus;&infin;,&infin;]</code> is assumed.

	Values of &minus;&infin; or &infin; must be written without units,
	even if the value type uses units.
	Values of ''0'' <em>can</em> be written without units,
	even if the value type doesn't allow “unitless zeroes”
	(such as <<time>>).

	Note: At the time of writing,
	the <a>bracketed range notation</a> is new;
	thus in most CSS specifications
	any range limitations are described only in prose.
	(For example, “Negative values are not allowed” or
	“Negative values are invalid”
	indicate a <code>[0,&infin;]</code> range.)
	This does not make them any less binding.

<!--
	The recommended minimum ranges and precision,
	and the required rounding and clamping rules,
	are given in <a href="#required-ranges">Appendix A</a>.
-->

<!-- Big Text: integer

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

<h3 id="integers">
Integers: the <<integer>> type</h3>

	Integer values are denoted by <dfn id="integer-value">&lt;integer></dfn>.

	When written literally,
	an <dfn export>integer</dfn> is one or more decimal digits ''0'' through ''9''
	and corresponds to a subset of the <<number-token>> production
	in the CSS Syntax Module [[!CSS-SYNTAX-3]].
	The first digit of an integer may be immediately preceded by <css>-</css> or <css>+</css>
	to indicate the integer's sign.

	<wpt>
	css/css-multicol/multicol-count-non-integer-001.xht
	css/css-multicol/multicol-count-non-integer-002.xht
	css/css-multicol/multicol-count-non-integer-003.xht
	css/CSS2/values/numbers-units-001.xht
	css/CSS2/values/numbers-units-004.xht
	</wpt>

<!-- Big Text: number

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

<h3 id="numbers">
Real Numbers: the <<number>> type</h3>

	Number values are denoted by <dfn id="number-value">&lt;number></dfn>,
	and represent real numbers, possibly with a fractional component.

	<wpt>
	css/css-animations/animation-iteration-count-calc.html
	css/CSS2/values/numbers-units-003.xht
	</wpt>

	When written literally,
	a <dfn export>number</dfn> is either an <a>integer</a>,
	or zero or more decimal digits followed by a dot (.) followed by one or more decimal digits;
	optionally, it can be concluded by the letter “e” or “E”
	followed by an integer indicating the base-ten exponent
	in <a href="https://en.wikipedia.org/wiki/Scientific_notation">scientific notation</a>.
	It corresponds to the <<number-token>> production
	in the <a href="https://www.w3.org/TR/css-syntax/">CSS Syntax Module</a> [[!CSS-SYNTAX-3]].
	As with integers, the first character of a number
	may be immediately preceded by <css>-</css> or <css>+</css>
	to indicate the number's sign.

<h3 id='dimensions'>
Numbers with Units: <a>dimension</a> values</h3>

	The general term <dfn export>dimension</dfn> refers to
	a number with a unit attached to it;
	and is denoted by <dfn>&lt;dimension></dfn>.

	When written literally,
	a <a>dimension</a> is a <a>number</a>
	immediately followed by a unit identifier,
	which is an [=CSS/identifier=].
	It corresponds to the <<dimension-token>> production
	in the <a href="https://www.w3.org/TR/css-syntax/">CSS Syntax Module</a> [[!CSS-SYNTAX-3]].
	Like keywords, unit identifiers are <a>ASCII case-insensitive</a>.

	<wpt>
	css/css-values/angle-units-003.html
	</wpt>

	CSS uses <<dimension>>s to specify
	distances (<<length>>),
	durations (<<time>>),
	frequencies (<<frequency>>),
	resolutions (<<resolution>>),
	and other quantities.

<h4 id="compat">
Compatible Units</h4>

	When <a href="https://www.w3.org/TR/cssom-1/#serializing-css-values">serializing</a> <a>computed values</a> [[!CSSOM]],
	<dfn export local-lt=compatible>compatible units</dfn>
	(those related by a static multiplicative factor,
	like the 96:1 factor between ''px'' and ''in'',
	or the computed 'font-size' factor between ''em'' and ''px'')
	are converted into a single <dfn export local-lt=canonical>canonical unit</dfn>.
	Each group of compatible units defines which among them is the <a>canonical unit</a>
	that will be used for serialization.

	When serializing <a href="https://www.w3.org/TR/cssom-1/#resolved-values">resolved values</a>
	that are <a>used values</a>,
	all value types (percentages, numbers, keywords, etc.)
	that represent lengths are considered <a>compatible</a> with lengths.
	Likewise any future API that returns <a>used values</a>
	must consider any values that represent distances/durations/frequencies/etc.
	as <a>compatible</a> with the relevant class of <a>dimensions</a>,
	and canonicalize accordingly.

	<wpt>
	css/css-values/calc-serialization-002.html
	</wpt>

<!-- Big Text: %

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

<h3 id="percentages">
Percentages: the <<percentage>> type</h3>

	Percentage values are denoted by <dfn id="percentage-value">&lt;percentage></dfn>,
	and indicates a value that is some fraction of another reference value.

	When written literally,
	a <dfn export>percentage</dfn> consists of a <a>number</a>
	immediately followed by a percent sign <css>%</css>.
	It corresponds to the <<percentage-token>> production
	in the <a href="https://www.w3.org/TR/css-syntax/">CSS Syntax Module</a> [[!CSS-SYNTAX-3]].

	Percentage values are always relative to another quantity,
	for example a length.
	Each property that allows percentages also defines the quantity to which the percentage refers.
	This quantity can be a value of another property for the same element,
	the value of a property for an ancestor element,
	a measurement of the formatting context
	(e.g., the width of a <a>containing block</a>),
	or something else.

	<wpt>
	css/CSS2/values/numbers-units-016.xht