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

spec: css-device-adapt-1;

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

/* 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;

}

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.

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

███▌ █ ▐▌ █ █▌ █████▌ ███▌ █ █

█▌ █▌ ▐▌ █ █▌ █▌ █▌ ▐█ ▐█ █ █

█▌ █ ▐▌ ██▌ █▌ █▌ █▌ █▌ █ █

███▌ ▐▌█ █▌▐█ █▌ █▌ █▌ █▌ █

█▌ █▌ █▌ ██▌ █▌ █████▌ █ █

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █ █

███▌ █▌ █▌ ▐▌ █▌ █▌ █▌ █ █

-->

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.

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

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.

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.

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.

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.

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

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>

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

█▌ █▌ █████▌ █ ▐▌ █▌ █▌ ███▌ ████▌ ████▌ ███▌

█▌ █▌ █▌ ▐▌ █ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

█▌█▌ █▌ █ ▐▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

██ ████ ▐▌█ █▌ █▌ █▌ █▌ ████▌ █▌ █▌ ███▌

█▌█▌ █▌ █▌ █▌ ▐ █▌ █▌ █▌ █▌▐█ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ ▐█ █▌ █▌ █▌ █▌

█▌ █▌ █████▌ █▌ ██ ▐█▌ ███▌ █▌ █▌ ████▌ ███▌

-->

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>

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

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

███▌ █████▌ ████▌ ████ █ █▌ ███▌

█▌ █▌ █▌ █▌ █▌ ▐▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ ▐▌ ██▌ █▌ █▌

███▌ █▌ ████▌ ▐▌ █▌▐█ █▌ █▌ ██▌

█▌ █▌ █▌▐█ ▐▌ █▌ ██▌ █▌ █▌

█▌ █▌ █▌ █▌ ▐█ ▐▌ █▌ █▌ █▌ █▌

███▌ █▌ █▌ █▌ ████ █▌ ▐▌ ███▌

-->

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

█▌ █▌ ████▌ █▌

█▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌

█▌ █▌ ████▌ █▌

█▌ █▌ █▌▐█ █▌

█▌ █▌ █▌ ▐█ █▌

███▌ █▌ █▌ █████

-->

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

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

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>

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>

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.

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.

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.

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

████ █ █▌ █████▌ █████▌ ███▌ █████▌ ████▌

▐▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

▐▌ ██▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

▐▌ █▌▐█ █▌ █▌ ████ █▌ ██▌ ████ ████▌

▐▌ █▌ ██▌ █▌ █▌ █▌ █▌ █▌ █▌▐█

▐▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ ▐█

████ █▌ ▐▌ █▌ █████▌ ███▌ █████▌ █▌ █▌

-->

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

█ █▌ █▌ █▌ █ █ ████▌ █████▌ ████▌

█▌ █▌ █▌ █▌ ██ ██ █▌ █▌ █▌ █▌ █▌

██▌ █▌ █▌ █▌ █▌█ █▐█ █▌ █▌ █▌ █▌ █▌

█▌▐█ █▌ █▌ █▌ █▌ █ ▐█ █████ ████ ████▌

█▌ ██▌ █▌ █▌ █▌ ▐█ █▌ █▌ █▌ █▌▐█

█▌ █▌ █▌ █▌ █▌ ▐█ █▌ █▌ █▌ █▌ ▐█

█▌ ▐▌ ███▌ █▌ ▐█ ████▌ █████▌ █▌ █▌

-->

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.

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.

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

▐█▌ █

█ █ ▐▌

▐█▌ █

▐▌

█ ▐█▌

▐▌ █ █

█ ▐█▌

-->

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