Overview.bs

<pre class='metadata'>
Title: CSS Values and Units Module Level 4
Group: CSSWG
Shortname: css-values
Level: 4
Status: ED
Work Status: Refining
ED: https://drafts.csswg.org/css-values-4/
TR: https://www.w3.org/TR/css-values-4/
Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Abstract: This CSS module describes the common values and units that CSS properties accept and the syntax used for describing them in CSS property definitions.
Ignored Terms: <spacing-limit>, containing block, property
Ignored Vars: Cn+1, n
Inline Github Issues: no
Default Highlight: css
Include Can I Use Panels: yes
</pre>
<pre class='link-defaults'>
spec: css2;
	type: property; text: border-collapse
spec: css-backgrounds-3; type: property;
	text: border-color
	text: box-shadow
	text: border-top-width
	text: border-left-width
	text: border-bottom-width
	text: border-right-width
spec: css-color-4; type: value; text: currentcolor
spec: css-color-5; type: type; text: <color>
spec: css-color-5; type:type; text: <absolute-color-function>
spec: css-shapes-1; type: function; text: rect();
spec: css-sizing-3; type: property;
	text: min-width
	text: box-sizing
spec: cssom-1; type:dfn; text:owner node; for:CSSStyleSheet;
spec: selectors-4; type: type; text: <q-name>
spec: infra; type: dfn; text: string;
spec: css-2023; type: dfn; text: ua
spec:css-typed-om-1; type:dfn; text:internal representation
spec:url; type:dfn; text:url; for:/
</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="component-functions">
	Functional Notation Definitions</h3>

	The syntax of a [=functional notation=] is defined
	as a sequence of:

	1. The function's name written as an identifier
		followed by an open parenthesis
		(such as ''example(''),
		or the <<function-token>> production
		to indicate a function with an arbitrary name.

	2. The function's arguments, if any,
		expressed using the [=value definition syntax=].

	3. A literal closing parenthesis.

	The function’s arguments are considered <em>implicitly grouped</em>,
	as if surrounded by brackets (''[ ... ]'').

	<div class=example>
		For example, a grammar like:

		<xmp class=prod>
			example( <length> , <length> )
		</xmp>

		will match a function whose name is "example"
		and whose arguments match "<<length>> , <<length>>".
	</div>

	<div class=example>
		For example, the Selectors grammar defines pseudo-classes generically,
		allowing any possibly function name after the initial colon:

		<xmp class=prod>
			<pseudo-class-selector> = ':' <ident-token> | ':' <function-token> <any-value> ')'
		</xmp>

		This represents <em>any</em> function name,
		with <<any-value>> as the function arguments.
	</div>

	<div class="example">
		Since the [=functional notation=] <em>implicitly groups</em> its contents,
		the effect of any combinator inside it
		is scoped to the function’s argument.
		For example, the [=functional notation=] syntax definition
		''example( foo | bar )'' is equivalent to ''example( [ foo | bar ] )''.
	</div>

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

<h3 id="production-blocks">
Non-Terminal Definitions and Grammar Production Blocks</h3>

	The precise grammar of non-terminals, like <<position>> or <<calc()>>,
	is often specified in a <dfn export>CSS grammar production block</dfn>.
	These are conventionally represented in a preformatted block of definitions
	like this:

	<div class="example">
		The <css>&lt;foo></css> syntax is defined as follows:

		<xmp class=prod>
			<foo> = keyword | <bar> |
			        some-really-long-pattern-of-stuff
			<bar> = <length>
		</xmp>
	</div>

	Each definition starts on its own line,
	and consists of the non-terminal to be defined,
	followed by an <code>=</code>,
	followed by the fragment of [=value definition syntax=] to which it expands.
	A definition can stretch across multiple lines,
	and terminates before the next line that starts a new grammar production
	or at the end of the grammar production block
	(whichever comes first).

	<div class="example">
		In the above example, the <css>&lt;foo></css> definition covers two lines.
		The third line starts a new definition for <css>&lt;bar></css>.
		(A naked <code>=</code> is never valid in [=value definition syntax=],
		so it's unambiguous when a new line starts a fresh definition.)
	</div>


<h2 id="combining-values">
Combining Values: Interpolation, Addition, and Accumulation</h2>

	Some procedures, for example
	<a href="https://www.w3.org/TR/css-transitions/">transitions</a>
	and <a href="https://www.w3.org/TR/css-animations/">animations</a>,
	<dfn export>combine</dfn> two CSS property values.
	The following combining operations--
	on the two <a>computed values</a> <var>V<sub>A</sub></var> and <var>V<sub>B</sub></var>
	yielding the <a>computed value</a> <var>V<sub>result</sub></var>--
	are defined.
	For operations that are not commutative
	(for example, matrix multiplication,
	or accumulation of mismatched transform lists)
	<var>V<sub>A</sub></var> represents
	the first term of the operation and
	<var>V<sub>B</sub></var> represents
	the second.

	<dl export>
		<dt><dfn id="interpolation" lt="interpolation | interpolate | value interpolation | interpolation procedure">interpolation</dfn>
		<dd>
			Given two property values
			<var>V<sub>A</sub></var> and <var>V<sub>B</sub></var>,
			produces an intermediate value
			<var>V<sub>result</sub></var>
			at a distance of <var>p</var>
			along the interval between
			<var>V<sub>A</sub></var> and <var>V<sub>B</sub></var>
			such that <var>p</var> = 0 produces <var>V<sub>A</sub></var>
			and <var>p</var> = 1 produces <var>V</var><sub>B</sub>.

			The range of <var>p</var> is (&minus;&infin;, &infin;)
			due to the effect of <a>timing functions</a>.
			As a result, this procedure must also define
			extrapolation behavior for <var>p</var> outside [0, 1].

		<dt><dfn id="addition" lt="value addition | addition procedure" local-lt="add | addition">addition</dfn>
		<dd>
			Given two property values
			<var>V<sub>A</sub></var> and <var>V<sub>B</sub></var>,
			returns the sum of the two properties,
			<var>V</var><sub>result</sub>.

			Note: While <a>addition</a>
			can often be expressed
			in terms of the same weighted sum function
			used to define <a>interpolation</a>,
			this is not always the case.
			For example, interpolation of transform matrices involves
			decomposing and interpolating the matrix components
			whilst addition relies on matrix multiplication.

			If a value type does not define a specific procedure for <a>addition</a>
			or is defined as <dfn export>not additive</dfn>,
			its <a>addition</a> operation is simply
			<var>V<sub>result</sub></var> = <var>V<sub>B</sub></var>.

		<dt><dfn id="accumulation" lt="value accumulation | accumulation procedure" local-lt="accumulate | accumulation">accumulation</dfn>
		<dd>
			Given two property values
			<var>V<sub>A</sub></var> and <var>V<sub>B</sub></var>,
			returns the result, <var>V<sub>result</sub></var>,
			of combining the two operands
			such that <var>V<sub>B</sub></var>
			is treated as a <em>delta</em> from <var>V<sub>A</sub></var>.

			<div class="note">
				Note: For many types of animation such as numbers or lengths,
				<a>accumulation</a> is defined to be identical
				to <a>addition</a>.

				A common case where the definitions differ
				is for list-based types
				where <a>addition</a> may be defined as appending to a list
				whilst <a>accumulation</a> may be defined
				as component-based addition.
				For example, the filter list values ''blur(2)'' and ''blur(3)'',
				when <a>added</a> together would produce ''blur(2) blur(3)'',
				but when <a>accumulated</a> would produce ''blur(5)''.
			</div>

			If a value type does not define a specific procedure for <a>accumulation</a>,
			its <a>accumulation</a> operation is identical to <a>addition</a>.
	</dl>

	These operations are only defined on <a>computed values</a>.
	(As a result, it is not necessary to define, for example,
	how to add a <<length>> value of ''15pt'' with ''5em''
	since such values will be resolved to their <a>canonical unit</a>
	before being passed to any of the above procedures.)



<h3 id="combining-range">
Range Checking</h3>

	Interpolation can result in a value outside the valid range for a property,
	even if all of the inputs to interpolation are valid;
	this especially happens when |p| is outside the [0, 1] range,
	but some [=easing functions=] can cause this to occur even within that range.
	If the final result
	<em>after</em> interpolation, addition, and accumulation
	is out-of-range for the target context the value is being used in,
	it does not cause the declaration to be invalid.
	Instead, the value must be clamped to the range allowed in the target context,
	exactly the same as [=math functions=]
	(see [[#calc-range]]).

	Note: Even if interpolation results in an out-of-range value,
	addition/accumulation might "correct" the result and bring it back into range.
	Thus, clamping is only applied to the <em>final</em> result
	of applying all interpolation-related operations.

<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>>).
	Aside from the casing of <a href="#keywords">pre-defined keywords</a>
	or as explicitly defined for a given property,
	no normalization is performed,
	not even Unicode normalization:
	the <a lt="specified value">specified</a> and <a>computed value</a> of a property
	are exactly the provided Unicode values after parsing
	(which includes character set conversion and [[css-syntax-3#escaping|escaping]]).
	[[!UNICODE]] [[!CSS-SYNTAX-3]]

	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.

	All textual data types <a>interpolate</a> as <a>discrete</a>
	and are <a>not additive</a>.

<!-- 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'>
Unprefixed 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
	(meaning they're compared using the "[=identical to=]" operation),
	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.
	Such conflicts can alternatively be avoided by using <<dashed-ident>>.

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

	Some contexts accept <em>both</em> author-defined identifiers
	<em>and</em> CSS-defined identifiers.
	If not handled carefully,
	this can result in difficulties adding new CSS-defined values;
	[=UAs=] have to study existing usage
	and gamble that there are sufficiently few author-defined identifiers in use
	matching the new CSS-defined one,
	so giving the new value a special CSS-defined meaning
	won't break existing pages.

	While there are many legacy cases in CSS
	that mix these two values spaces in exactly this fraught way,
	the <<dashed-ident>> type is meant to be an easy way
	to distinguish author-defined identifiers
	from CSS-defined identifiers.

	The <dfn><<dashed-ident>></dfn> production
	is a <<custom-ident>>,
	with all the case-sensitivity that implies,
	with the additional restriction that it must start with two dashes
	(U+002D HYPHEN-MINUS).

	<<dashed-ident>>s are reserved solely for use as author-defined names.
	CSS will never define a <<dashed-ident>> for its own use.

	<div class=example>
		For example, [=custom properties=] need to be distinguishable from CSS-defined properties,
		as new properties are added to CSS regularly.
		To allow this,
		[=custom property=] names are required to be <<dashed-ident>>s,
		as in this example:

		<pre highlight=css>
		.foo {
			--fg-color: blue;
		}
		</pre>
	</div>

	<div class=example>
		<<dashed-ident>>s are also used in the ''@color-profile'' rule,
		to separate author-defined color profiles
		from pre-defined ones like ''device-cmyk'',
		and allow CSS to define more pre-defined (but overridable) profiles in the future
		without fear of clashing with author-defined profiles:

		<pre highlight=css>
		@color-profile --foo { src: url(https://example.com/foo.icc); }
		.foo {
			color: color(--foo 1 0 .5 / .2);
		}
		</pre>
	</div>

	<div class=example>
		CSS will use <<dashed-ident>> more in the future,
		as more author-controlled syntax is added.
		CSS authoring tools,
		such as preprocessors that turn custom syntax into standard CSS,
		<em>should</em> use <<dashed-ident>> as well,
		to avoid clashing with future CSS design.

		For example,
		if a CSS preprocessor added a new "custom" at-rule,
		it <em>shouldn't</em> spell it <css>@custom</css>,
		as this would clash with a future official <css>@custom</css> rule added by CSS.
		Instead, it should use <css>@--custom</css>,
		which is guaranteed to never clash with anything defined by CSS.

		Even better, it should use <css>@--library1-custom</css>,
		so that if Library2 adds their own "custom" at-rule
		(spelled @--library2-custom),
		there's no possibility of clash.
		Ideally this prefix should be customizable,
		if allowed by the tooling,
		so authors can manually avoid clashes on their own.
	</div>


<!-- 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 <<url>> type,
	written with the <dfn>url()</dfn> and <dfn>src()</dfn> functions,
	represents a <l spec=url>[=/URL=]</l>,
	which is a pointer to a resource.

	The syntax of <<url>> is:

	<pre class="prod">
		<dfn id="url-value">&lt;url></dfn> = <<url()>> | <<src()>>

		&lt;url()> = url( <<string>> <<url-modifier>>* ) | <<url-token>>
		&lt;src()> = src( <<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 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]]

	Note: Because of this special parsing,
	''url()'' can only express its value literally.
	To provide a URL by functions such as ''var()'',
	use the ''src()'' notation,
	which does not have this special parsing rule.

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

		And these have the same meaning as well:

		<pre>
			background: src("http://www.example.com/pinkish.gif");
			--foo: "http://www.example.com/pinkish.gif";
			background: src(var(--foo));
		</pre>

		But this does <em>not</em> work:

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

		...because the unescaped "(" in the value causes a parse error,
		so the entire declaration is thrown out as invalid.
	</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