Abstract

This CSS module describes how to collate style rules and assign values to all properties on all elements. By way of cascading and inheritance, values are propagated for all properties on all elements.

CSS is a language for describing the rendering of structured documents
(such as HTML and XML)
on screen, on paper, in speech, etc.

Status of this document

This is a public copy of the editors’ draft.
It is provided for discussion only and may change at any moment.
Its publication here does not imply endorsement of its contents by W3C.
Don’t cite this document other than as work in progress.

The (archived) public mailing list
www-style@w3.org
(see instructions)
is preferred for discussion of this specification.
When sending e-mail,
please put the text “css-cascade” in the subject,
preferably like this:
“[css-cascade] …summary of comment…”

1.
Introduction

One of the fundamental design principles of CSS is cascading,
which allows several style sheets to influence the presentation of a document.
When different declarations try to set a value for the same element/property combination,
the conflicts must somehow be resolved.

The opposite problem arises when no declarations try to set a the value for an element/property combination.
In this case, a value is be found by way of inheritance
or by looking at the property’s initial value.

The rules for finding the specified value for all properties on all elements in the document are described in this specification.
The rules for finding the specified values in the page context and its margin boxes are described in [CSS3PAGE].

The @import rule allows users to import style rules from other style sheets.
If an @import rule refers to a valid stylesheet,
user agents must treat the contents of the stylesheet as if they were written in place of the @import rule.

For example, declarations in style rules from imported stylesheets interact with the cascade
as if they were written literally into the stylesheet at the point of the @import.
Similarly, style rules in a stylesheet imported into a scoped stylesheet
are scoped in the same way.

Any @import rules must precede all other at-rules and style rules in a style sheet
(besides @charset, which must be the first thing in the style sheet if it exists),
or else the @import rule is invalid.
The syntax of @import is:

The evaluation and full syntax of the expressions after the URL
is defined by the Media Queries specification [MEDIAQ].
If the media query does not match,
the rules in the imported stylesheet do not apply,
exactly as if the imported stylesheet were wrapped in an @media block with the given media query.
User agents may therefore avoid fetching a media-dependent import
as long as the media query does not match.

The following rules illustrate how @import rules can be made media-dependent:

When the same style sheet is imported or linked to a document in multiple places,
user agents must process (or act as though they do) each link
as though the link were to an independent style sheet.

Note: This does not place any requirements on resource fetching,
only how the style sheet is reflected in the CSSOM and used in specs such as this one.
Assuming appropriate caching,
it is perfectly appropriate for a UA to fetch a style sheet only once,
even though it’s linked or imported multiple times.

The origin of an imported style sheet is the same as the origin of the style sheet that imported it.

2.1.
Content-Type of CSS Style Sheets

The processing of imported style sheets depends on the actual type of the linked resource.
If the resource does not have Content-Type metadata,
or the host document is in quirks mode
and has the same origin as the imported style sheet,
the type of the linked resource is text/css.
Otherwise, the type is determined from its Content-Type metadata.

If the linked resource’s type is text/css,
it must be interpreted as a CSS style sheet.
Otherwise, it must be interpreted as a network error.

3.
Shorthand Properties

Some properties are shorthand properties,
meaning that they allow authors to specify the values of several properties with a single property.
A shorthand property sets all of its longhand sub-properties,
exactly as if expanded in place.

This means that a shorthand property declaration always sets all of its sub-properties,
even those that are not explicitly set.
Carelessly used, this might result in inadvertently resetting some sub-properties.
Carefully used, a shorthand can guarantee a “blank slate”
by resetting sub-properties inadvertently cascaded from other sources.

As more fontsub-properties are introduced into CSS,
the shorthand declaration resets those to their initial values as well.

In some cases, a shorthand might have different syntax
or special keywords
that don’t directly correspond to values of its sub-properties.
(In such cases, the shorthand will explicitly define the expansion of its values.)

In other cases, a property might be a reset-only sub-property of the shorthand:
Like other sub-properties, it is reset to its initial value by the shorthand when unspecified,
but the shorthand might not include syntax to set the sub-property
to any of its other values.
For example, the border shorthand resets border-image
to its initial value of none,
but has no syntax to set it to anything else. [CSS3BG]

For example, if an author specifies all: initial on an element
it will block all inheritance and reset all properties,
as if no rules appeared in the author, user, or user-agent levels of the cascade.

This can be useful for the root element of a "widget" included in a page,
which does not wish to inherit the styles of the outer page.
Note, however, that any "default" style applied to that element
(such as, e.g. display: block from the UA style sheet on block elements such as <div>)
will also be blown away.

4.
Value Processing

Once a user agent has parsed a document and constructed a document tree,
it must assign,
to every element in the tree,
and correspondingly to every box in the formatting structure,
a value to every property that applies to the target media type.

The final value of a CSS property for a given element or box
is the result of a multi-step calculation:

First, all the declared values applied to an element are collected,
for each property on each element.
There may be zero or many declared values applied to the element.

Formatting the document yields the used value.
An element only has a used value for a given property
if that property applies to the element.

Finally, the used value is transformed to the actual value
based on constraints of the display environment.
As with the used value, there may or may not be an actual value
for a given property on an element.

4.3.
Specified Values

The specified value the value of a given property that the style sheet authors intended for that element.
It is the result of putting the cascaded value through the defaulting processes,
guaranteeing that a specified value exists for every property on every element.

4.4.
Computed Values

The computed value is the result of resolving the specified value
as defined in the “Computed Value” line of the property definition table,
generally absolutizing it in preparation for inheritance.

Note: The computed value is the value that is transferred from parent to child during inheritance.
For historical reasons,
it is not necessarily the value returned by the getComputedStyle() function.

A specified value can be either absolute (i.e., not relative to another value, as in red or 2mm)
or relative (i.e., relative to another value, as in auto, 2em).
Computing a relative value generally absolutizes it:

values with relative units
(em, ex, vh, vw)
must be made absolute by multiplying with the appropriate reference size

certain keywords
(e.g., smaller, bolder)
must be replaced according to their definitions

percentages on some properties must be multiplied by a reference value
(defined by the property)

Note: In general, the computed value resolves the specified value
as far as possible without laying out the document
or performing other expensive or hard-to-parallelize operations,
such as resolving network requests
or retrieving values other than from the element and its parent.

The computed value exists even when the property does not apply
(as defined by the “Applies To” line).
However, some properties may change how they determine the computed value
based on whether the property applies to the element.

4.5.
Used Values

The used value is the result of taking the computed value
and completing any remaining calculations to make it the absolute theoretical value
used in the layout of the document.
If the property does not apply to this element,
then the element has no used value for that property.

4.6.
Actual Values

A used value is in principle ready to be used,
but a user agent may not be able to make use of the value in a given environment.
For example, a user agent may only be able to render borders with integer pixel widths
and may therefore have to approximate the used width.
Also, the font size of an element may need adjustment based on the availability of fonts
or the value of the font-size-adjust property.
The actual value is the used value after any such adjustments have been made.

Note: By probing the actual values of elements,
much can be learned about how the document is laid out.
However, not all information is recorded in the actual values.
For example, the actual value of the page-break-after property
does not reflect whether there is a page break or not after the element.
Similarly, the actual value of orphans
does not reflect how many orphan lines there is in a certain element.
See examples (j) and (k) in the table below.

Declarations from origins earlier in this list win over declarations from later origins.

Scope

A declaration can be scoped to a subtree of the document
so that it only affects its scoping element and that element’s descendants.
For example, [HTML5] defines scoped <style> elements,
whose style sheets are scoped to the element’s parent.

If the scoping elements of two declarations
have an ancestor/descendant relationship,
then for normal rules the declaration whose scoping element is the descendant wins,
and for important rules the declaration whose scoping element is the ancestor wins.

Note: In other words, for normal declarations the inner scope’s declarations override,
but for !important rules outer scope’s override.

For the purpose of this step,
all unscoped declarations are considered to be scoped to the root element.
Normal declarations from style attributes
are considered to be scoped to the element with the attribute,
whereas important declarations from style attributes
are considered to be scoped to the root element.
[CSSSTYLEATTR]

Note: This odd handling of !important style attribute declarations
is to match the behavior defined in CSS Levels 1 and 2,
where style attributes simply have higher specificity than any other author rules. [CSS21]

Specificity

The Selectors module[SELECT] describes how to compute the specificity of a selector.
Each declaration has the same specificity as the style rule it appears in.
For the purpose of this step,
declarations that do not belong to a style rule
(such as the contents of a style attribute)
are considered to have a specificity higher than any selector.
The declaration with the highest specificity wins.

Declarations from style sheets independently linked by the originating document
are treated as if they were concatenated in linking order,
as determined by the host document language.

Declarations from style attributes
are ordered according to the document order of the element the style attribute appears on,
and are all placed after any style sheets.

The output of the cascade
is a (potentially empty) sorted list of declared values for each property on each element.

6.1.
Cascading Origins

Each style rule has an origin,
which determines where it enters the cascade.
CSS defines three core origins:

Author

The author specifies style sheets for a source document according to the conventions of the document language. For instance, in HTML, style sheets may be included in the document or linked externally.

User

The user may be able to specify style information for a particular document.
For example, the user may specify a file that contains a style sheet
or the user agent may provide an interface that generates a user style sheet
(or behaves as if it did).

User agent

Conforming user agents must apply a default style sheet
(or behave as if they did).
A user agent’s default style sheet should present the elements of the document language in ways that satisfy general presentation expectations for the document language
(e.g., for visual browsers, the EM element in HTML is presented using an italic font).
See e.g. the HTML user agent style sheet. [HTML5]

6.2.
Important Declarations: the !important annotation

CSS attempts to create a balance of power between author and user style sheets.
By default, rules in an author’s style sheet override those in a user’s style sheet,
which override those in the user-agent’s default style sheet.
To balance this, a declaration can be made important,
which increases its weight in the cascade and inverts the order of precedence.

A declaration is important if it has a !important annotation,
as defined by [CSS3SYN].
i.e. if the last two (non-whitespace, non-comment) tokens
in its value are the delimiter token ! followed by the identifier token important.

Important declarations from all origins take precedence over animations.
This allows authors to override animated values in important cases.
(Animated values normally override all other rules.)
[CSS3-ANIMATIONS]

User agent style sheets may also contain !important declarations.
These override all author and user declarations.

The first rule in the user’s style sheet in the following example contains an !important declaration,
which overrides the corresponding declaration in the author’s style sheet.
The declaration in the second rule will also win due to being marked !important.
However, the third declaration in the user’s style sheet is not !important
and will therefore lose to the second rule in the author’s style sheet
(which happens to set style on a shorthand property).
Also, the third author rule will lose to the second author rule since the second declaration is !important.
This shows that !important declarations have a function also within author style sheets.

6.3.
Precedence of Non-CSS Presentational Hints

The UA may choose to honor presentational hints in a source document’s markup,
for example the bgcolor attribute or <s> element in [HTML5].
All document language-based styling must be translated to corresponding CSS rules
and either enter the cascade at the user agent level or
be treated as author level rules with a specificity of zero placed at the start of the author style sheet.
A document language may define whether a presentational hint enters at the UA or author level of the cascade;
if so, the UA must behave accordingly.
For example, [SVG11] maps its presentation attributes into the author level.

Note: Presentational hints entering the cascade at the UA level can be overridden by author or user styles.
Presentational hints entering the cascade at the author level can be overridden by author styles,
but not by non-!important user styles.
Host languages should choose the appropriate level for presentational hints with these considerations in mind.

7.2.
Inheritance

Inheritance propagates property values from parent elements to their children.
The inherited value of a property on an element
is the computed value of the property on the element’s parent element.
For the root element,
which has no parent element,
the inherited value is the initial value of the property.

(Pseudo-elements inherit according to a fictional tag sequence described for each pseudo-element [SELECT].)

Some properties are inherited properties,
as defined in their property definition table.
This means that,
unless the cascade results in a value,
the value will be determined by inheritance.

Note: Inheritance follows the document tree and is not intercepted by anonymous boxes,
or otherwise affected by manipulations of the box tree.

7.3.
Explicit Defaulting

Several CSS-wide property values are defined below;
declaring a property to have these values explicitly specifies a particular defaulting behavior.
As specified in CSS Values and Units Level 3[CSS3VAL],
all CSS properties can accept these values.

If the cascaded value of a property is the unset keyword,
then if it is an inherited property, this is treated as inherit,
and if it is not, this is treated as initial.
This keyword effectively erases all declared values occurring earlier in the cascade,
correctly inheriting or not as appropriate for the property
(or all longhands of a shorthand).

Explained reset-only sub-properties
and clarified that they also get affected by a CSS-wide keyword value in the shorthand declaration.

In other cases, a property might be a reset-only sub-property of the shorthand:
Like other sub-properties, it is reset to its initial value by the shorthand when unspecified,
but the shorthand might not include syntax to set the sub-property
to any of its other values.
For example, the border shorthand resets border-image
to its initial value of none,
but has no syntax to set it to anything else. [CSS3BG]

Acknowledgments

David Baron, Simon Sapin, and Boris Zbarsky contributed to this specification.

Conformance

Document conventions

Conformance requirements are expressed with a combination of
descriptive assertions and RFC 2119 terminology. The key words "MUST",
"MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this
document are to be interpreted as described in RFC 2119.
However, for readability, these words do not appear in all uppercase
letters in this specification.

All of the text of this specification is normative except sections
explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words "for example"
or are set apart from the normative text with class="example",
like this:

This is an example of an informative example.

Informative notes begin with the word "Note" and are set apart from the
normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are
set apart from other normative text with <strong class="advisement">, like
this:
UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification
is defined for three conformance classes:

A style sheet is conformant to this specification
if all of its statements that use syntax defined in this module are valid
according to the generic CSS grammar and the individual grammars of each
feature defined in this module.

A renderer is conformant to this specification
if, in addition to interpreting the style sheet as defined by the
appropriate specifications, it supports all the features defined
by this specification by parsing them correctly
and rendering the document accordingly. However, the inability of a
UA to correctly render a document due to limitations of the device
does not make the UA non-conformant. (For example, a UA is not
required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification
if it writes style sheets that are syntactically correct according to the
generic CSS grammar and the individual grammars of each feature in
this module, and meet all other conformance requirements of style sheets
as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to
assign fallback values, CSS renderers must
treat as invalid (and ignore
as appropriate) any at-rules, properties, property values, keywords,
and other syntactic constructs for which they have no usable level of
support. In particular, user agents must not selectively
ignore unsupported component values and honor supported values in a single
multi-value property declaration: if any value is considered invalid
(as unsupported values must be), CSS requires that the entire declaration
be ignored.

Experimental implementations

To avoid clashes with future CSS features, the CSS2.1 specification
reserves a prefixed
syntax for proprietary and experimental extensions to CSS.

Prior to a specification reaching the Candidate Recommendation stage
in the W3C process, all implementations of a CSS feature are considered
experimental. The CSS Working Group recommends that implementations
use a vendor-prefixed syntax for such features, including those in
W3C Working Drafts. This avoids incompatibilities with future changes
in the draft.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage,
non-experimental implementations are possible, and implementors should
release an unprefixed implementation of any CR-level feature they
can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across
implementations, the CSS Working Group requests that non-experimental
CSS renderers submit an implementation report (and, if necessary, the
testcases used for that implementation report) to the W3C before
releasing an unprefixed implementation of any CSS features. Testcases
submitted to W3C are subject to review and correction by the CSS
Working Group.