Overview.bs

<pre class='metadata'>
Title: CSS Cascading and Inheritance Level 6
Shortname: css-cascade
Level: 6
Status: ED
Prepare for TR: no
Work Status: Exploring
Group: csswg
ED: https://drafts.csswg.org/css-cascade-6/
TR: https://www.w3.org/TR/css-cascade-6/
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Miriam E. Suzanne, Invited Expert, http://miriamsuzanne.com/contact, w3cid 117151
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/, w3cid 42199
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.
Abstract:
Abstract: New in this level is [[#scoped-styles]].
Ignored Terms: auto, flex items, <supports-condition>
Informative Classes: ex
</pre>

<pre class=link-defaults>
spec:css-syntax-3; type:dfn; text:css identifier
spec:dom; type:dfn; text:shadow tree
spec:css-color-4; type:property; text:color
spec:css-values-3; type: value; text:ex
spec:css-conditional-3; type:at-rule; text:@media
spec:mediaqueries-4; type:type; for:@media; text:all
spec:mediaqueries-4; type:type; text:<media-query>
</pre>

<pre class=ignored-specs>
spec:mediaqueries-5
spec:css-values-4
spec:css-fonts-4
</pre>

<h2 id="intro" oldids='filtering,fragments,stages-examples,actual,used,computed,cascaded,declared,specified,value-stages,all-shorthand,aliasing,shorthand,content-type,import-processing,conditional-import,at-import,defaulting,initial-values,inheriting,defaulting-keywords,initial,inherit,inherit-initial,default'>
Introduction and Missing Sections</h2>

	Issue: This is a diff spec over <a href="https://www.w3.org/TR/css-cascade-5/">CSS Cascading and Inheritance Level 5</a>.
	It is currently an Exploratory Working Draft:
	if you are implementing anything, please use Level 5 as a reference.
	We will merge the Level 5 text into this draft once it reaches CR.

<!--
 ██████     ███     ██████   ██████     ███    ████████  ████████
██    ██   ██ ██   ██    ██ ██    ██   ██ ██   ██     ██ ██
██        ██   ██  ██       ██        ██   ██  ██     ██ ██
██       ██     ██  ██████  ██       ██     ██ ██     ██ ██████
██       █████████       ██ ██       █████████ ██     ██ ██
██    ██ ██     ██ ██    ██ ██    ██ ██     ██ ██     ██ ██
 ██████  ██     ██  ██████   ██████  ██     ██ ████████  ████████
-->

<h2 id='cascading'>
Cascading</h2>

	The <dfn export>cascade</dfn>
	takes an unordered list of <a>declared values</a>
	for a given property on a given element,
	sorts them by their [=declaration’s=] precedence as determined below,
	and outputs a single <a>cascaded value</a>.

<h3 id="cascade-sort">
Cascade Sorting Order</h3>

	The cascade sorts [=declarations=] according to the following criteria,
	in descending order of precedence:

	<dl>
		<dt id='cascade-origin'>Origin and Importance
		<dd>
			The <a>origin</a> of a [=declaration=] is based on where it comes from
			and its <a lt="important">importance</a> is
			whether or not it is declared with ''!important''
			(see [[#importance|below]]).
			The precedence of the various <a>origins</a> is, in descending order:

			<ol>
				<li>Transition declarations [[!css-transitions-1]]
				<li>[=Important=] [=user-agent origin|user agent=] declarations
				<li>[=Important=] [=user origin|user=] declarations
				<li>[=Important=] [=author origin|author=] declarations
				<li>Animation declarations [[!css-animations-1]]
				<li>[=Normal=] [=author origin|author=] declarations
				<li>[=Normal=] [=user origin|user=] declarations
				<li>[=Normal=] [=user-agent origin|user agent=] declarations
			</ol>

			Declarations from <a>origins</a> earlier in this list win over declarations from later <a>origins</a>.

		<dt id='cascade-context'>Context
		<dd>
			A document language can provide for blending [=declarations=] sourced
			from different <dfn local-lt="context">encapsulation contexts</dfn>,
			such as the nested [=tree contexts=] of [=shadow trees=] in the [[!DOM]].

			When comparing two declarations
			that are sourced from different [=encapsulation contexts=],
			then for [=normal=] rules
			the declaration from the outer context wins,
			and for [=important=] rules
			the declaration from the inner context wins.
			For this purpose,
			[[DOM]] [=tree contexts=] are considered to be nested
			in [=shadow-including tree order=].

			Note: This effectively means that
			[=normal=] declarations belonging to an [=encapsulation context=]
			can set defaults that are easily overridden by the outer context,
			while [=important=] declarations belonging to an [=encapsulation context=]
			can enforce requirements that cannot be overridden by the outer context.

		<dt id='style-attr'>The Style Attribute
		<dd>
			Separately for [=normal=] and [=important=] [=declarations=],
			declarations that are attached directly to an element
			(such as the <a href="https://www.w3.org/TR/css-style-attr/#interpret">contents of a style attribute</a>)
			rather than indirectly mapped by means of a style rule selector
			take precedence over declarations the same [=importance=]
			that are mapped via style rule.

		<dt id='cascade-layering'>Layers
		<dd>
			[=Declarations=] within each [=origin=] and [=context=]
			can be explicitly assigned to a [=cascade layer=].
			For the purpose of this step,
			any declaration not assigned to an explicit layer is added to an implicit final layer.

			Cascade layers (like declarations) are sorted by order of appearance,
			see [[#layer-ordering]].
			When comparing declarations that belong to different layers,
			then for [=normal=] rules the declaration whose [=cascade layer=] is latest in the layer order wins,
			and for [=important=] rules the declaration whose [=cascade layer=] is earliest wins.

			Note: This follows the same logic used for precedence of [=normal=] and [=important=] [=origins=],
			thus the ''!important'' flag maintains the same “override” purpose in both settings.

		<dt id='cascade-proximity-strong'><dfn>Strong Scoping Proximity</dfn>
		<dd>
			If two declarations both have elements
			selected by scoped descendant relationships
			applying [=strong scoping proximity=],
			then the declaration with the fewest generational hops
			between the ancestor/descendant element pair wins.

			If multiple such pairs are represented,
			their [=strong scoping proximity=] weights are compared
			from innermost scoping relationship to outermost scoping relationship
			(with any missing pairs weighted as infinity).

		<dt id='cascade-specificity'>Specificity
		<dd>
			The <a href="https://www.w3.org/TR/selectors/#specificity">Selectors module</a> [[!SELECT]] describes how to compute the specificity of a selector.
			Each declaration has the same specificity as the style rule it appears in.
			The declaration with the highest specificity wins.

		<dt id='cascade-proximity-weak'><dfn>Weak Scoping Proximity</dfn>
		<dd>
			If two declarations both have elements
			selected by scoped descendant relationships
			applying [=weak scoping proximity=],
			then the declaration with the fewest generational hops
			between the ancestor/descendant element pair wins.

			If multiple such pairs are represented,
			their [=weak scoping proximity=] weights are compared
			from innermost scoping relationship to outermost scoping relationship
			(with any missing pairs weighted as infinity).

		<dt id='cascade-order'>Order of Appearance
		<dd>
			The last declaration in document order wins.
			For this purpose:

			<ul>
				<li>Style sheets are ordered as in <a href="https://drafts.csswg.org/cssom/#documentorshadowroot-final-css-style-sheets">final CSS style sheets</a>.
				<li>Declarations from <a at-rule lt="@import">imported style sheets</a>
					are ordered as if their style sheets were substituted in place of the ''@import'' rule.
				<li>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.
				<li>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.
					[[!CSSSTYLEATTR]]
			</ul>
	</dl>

	Issue(6790): Does <dfn>scope proximity</dfn> belong above or below specificity in the cascade?

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


<h3 id='cascading-origins'>
Cascading Origins</h3>

	Issue: [[css-cascade-5#cascading-origins]]

	<dfn id=origin export local-lt="origin">cascade origin</dfn>

<h3 id='importance'>
Important Declarations: the ''!important'' annotation</h3>

	Issue: [[css-cascade-5#importance]]

	<dfn export local-lt="importance">important</dfn>
	<dfn>normal</dfn>

<h3 id='layering'>
Cascade Layers</h3>

	Issue: [[css-cascade-5#layering]]


<!--
 ██████   ██████   ███████  ████████  ████ ██    ██  ██████
██    ██ ██    ██ ██     ██ ██     ██  ██  ███   ██ ██    ██
██       ██       ██     ██ ██     ██  ██  ████  ██ ██
 ██████  ██       ██     ██ ████████   ██  ██ ██ ██ ██   ████
      ██ ██       ██     ██ ██         ██  ██  ████ ██    ██
██    ██ ██    ██ ██     ██ ██         ██  ██   ███ ██    ██
 ██████   ██████   ███████  ██        ████ ██    ██  ██████
-->

<h3 id='scoped-styles'>
Scoped Styles</h2>

	A <dfn>scope</dfn> is a subtree or fragment of a document,
	which can be used by selectors for more targeted matching.
	[=Scopes=] are described in CSS through a combination of two selector lists:

	* The <dfn><<scope-start>></dfn> is a <<forgiving-selector-list>>.
		Each element matched by <<scope-start>> is a [=scoping element=],
		creating a scope with itself as the [=scoping root=].
	* The <dfn><<scope-end>></dfn> is a <<forgiving-selector-list>>
		that is [=scoped selector|scoped=] by the <<scope-start>> selector,
		with the [=scoping roots=] as [=:scope elements=].
		Each element matched by <<scope-end>> is a [=scoping limit=].
		The <dfn>scoping limit</dfn> elements define the lower bounds of a scope,
		so that [=scoped selectors=] are not able to match
		any elements nested within them.

	Each resulting [=scope=] includes a [=scoping root=] and all its descendants,
	up to and including any [=scoping limit=] elements,
	but not the descendants of those limits.

	Issue(6577): Inclusive vs exclusive scope boundaries

	Note: In contrast to [[CSS-SCOPING-1#shadow-dom|Shadow Encapsulation]],
	which describes a persistent one-to-one relationship in the DOM
	between a [=shadow host=] and its nested [=shadow tree=],
	multiple overlapping [=scopes=] can be defined in relation to the same elements.

	<div class=example>
		For example,
		an author might have wide-reaching color-scheme scopes,
		which overlap more narrowly-scoped design patterns
		such as a media object:

		<pre class=lang-css>
		@scope (.light-scheme) {
		  a { color: darkmagenta; }
		}

		@scope (.dark-scheme) {
		  a { color: plum; }
		}

		@scope (.media-object) {
		  .media-image { border-radius: 50%; }
		  .media-content { padding: 1em; }
		}
		</pre>
	</div>

	<div class=example>
		By providing [=scoping limits=],
		an author can limit matching more deeply nested descendants.
		For example:

		<pre class=lang-css>
		@scope (.media-object) to (.content) {
		  img { border-radius: 50%; }

		  /* it is also possible to style the lower limit element itself */
		  .content { padding: 1em; }
		}
		</pre>

		The ''img'' selector will only match image tags that are in a DOM fragment
		starting with any ''.media-object'',
		and including all descendants until any intervening ''.content'' class.
	</div>

	Issue: Should scoping limits be added to the definition of [=scoped selectors=]?

	<div class=example>
		[=Scoping limits=] can use the '':scope'' pseudo-class
		to require a specific relationship to the [=scoping root=]:

		<pre class=lang-css>
		/* .content is only a limit when it is a direct child of the :scope */
		@scope (.media-object) to (:scope > .content) { ... }
		</pre>

		[=Scoping limits=] can also reference elements outside their [=scoping root=]
		by using '':scope''.
		For example:

		<pre class=lang-css>
		/* .content is only a limit when the :scope is inside .sidebar */
		@scope (.media-object) to (.sidebar :scope .content) { ... }
		</pre>
	</div>

<!--
 ███████   ██████   ██████   ███████  ████████  ████████
██     ██ ██    ██ ██    ██ ██     ██ ██     ██ ██
██ ███ ██ ██       ██       ██     ██ ██     ██ ██
██ ███ ██  ██████  ██       ██     ██ ████████  ██████
██ █████        ██ ██       ██     ██ ██        ██
██        ██    ██ ██    ██ ██     ██ ██        ██
 ███████   ██████   ██████   ███████  ██        ████████
-->

<h4 id='scope-atrule'>
Scoping Styles: the ''@scope'' rule</h4>

	The <dfn>@scope</dfn> [=block at-rule=]
	allows authors to scope style rules in CSS,
	with the application of [=weak scoping proximity=]
	between the [=scoping root=] and the [=subject=] of each style rule.
	<!-- This causes declarations [insert appropriate sentence from issue below]. -->

	Issue(6790): Should ''@scope'' use strong or weak scoping proximity?
	[=Strong scoping proximity=] causes declarations to be weighted more strongly
	by scope proximity than by their selector’s specificity.
	[=Weak scoping proximity=] causes declarations of the same specificity
	to be weighted by proximity to their scoping root
	before falling back to source ordering,
	but declarations of higher specificity win over more tightly-scoped declarations.
	The Working Group currently leans towards weak proximity,
	and recommends that as a starting point for prototypes.

	The syntax of the ''@scope'' rule is:

	<pre class='prod'>
	@scope (<<scope-start>>) [to (<<scope-end>>)]? {
	  <<stylesheet>>
	}
	</pre>

	The ''@scope'' [=at-rule=] has three primary effects
	on the [=style rules=] in its <<stylesheet>>:

	* [=scoped selectors|Selectors are scoped=] to the given [=scope=],
		with the [=:scope element=] being the [=scoping root=].
	* Selectors are given the added specificity of
		the most specific [=complex selector=] in the <<scope-start>> argument.

		Note: This is designed to match the behavior of the '':is()'' selector.

	* The [=cascade=] prioritizes declarations
		with a [=scope proximity|more proximate=] [=scoping root=],
		regardless of specificity or source order.

	<div class=example>
		The following selectors have the same specificity (1,0,1):

		<pre class=lang-css>
		@scope (#hero) {
		  img { border-radius: 50%; }
		}

		#hero img { border-radius: 50%; }
		</pre>

		But because <{img}> is scoped,
		it is weighted more strongly in the cascade.
	</div>

	<div class=example>
		Many existing tools implement "scoped styles"
		by applying a unique class or attribute
		to every element in a given scope
		or "single file component."
		In this example there are two scopes
		(<code>main-component</code> and <code>sub-component</code>)
		and every element is marked as part of one or both scopes
		using the <code>data-scope</code> attribute:

		<pre class=lang-html>
		&lt;section data-scope="main-component">
		  &lt;p data-scope="main-component">...&lt;p>

		  &lt;!-- sub-component root is in both scopes -->
		  &lt;section data-scope="main-component sub-component">
		    &lt;!-- children are only in the inner scope -->
		    &lt;p data-scope="sub-component">...&lt;p>
		  &lt;/section>
		&lt;/section>
		</pre>

		Those custom scope attributes are then
		appended to every single selector in CSS:

		<pre class=lang-css>
		p[data-scope~='main-component'] { color: red; }
		p[data-scope~='sub-component'] { color: blue; }

		/* both sections are part of the outer scope */
		section[data-scope~='main-component'] { background: snow; }

		/* the inner section is also part of the inner scope */
		section[data-scope~='sub-component'] { color: ghostwhite; }
		</pre>

		Using the ''@scope'' rule,
		authors and tools can replicate similar behavior
		with the unique attribute or class
		applied only to the [=scoping roots=]:

		<pre class=lang-html>
		&lt;section data-scope="main-component">
		  &lt;p>...&lt;p>
		  &lt;section data-scope="sub-component">
		    &lt;!-- children are only in the inner scope -->
		    &lt;p>...&lt;p>
		  &lt;/section>
		&lt;/section>
		</pre>

		Then the class or attribute can be used
		for establishing both upper and lower boundaries,
		such that scopes only overlap at those boundaries:

		<pre class=lang-css>
		@scope ([data-scope='main-component']) to ([data-scope]) {
		  p { color: red; }

		  /* both sections are part of the outer scope */
		  section { background: snow; }
		}

		@scope ([data-scope='sub-component']) to ([data-scope]) {
		  p { color: blue; }

		  /* the inner section is also part of the inner scope */
		  section { color: ghostwhite; }
		}
		</pre>
	</div>

	''@scope'' rules can be nested.
	In this case, just as with the nested style rules,
	the selectors of the inner ''@scope''
	(including those defining its [=scope=])
	are [=scoped selectors|scoped by=]
	the selectors of the outer one.

<h4 id="scope-combinator">
Scoped Descendant Combinator</h4>

	The <dfn export>scoped descendant combinator</dfn>
	describes a descendant relationship between two elements.
	A selector of the form ''A >> B'' represents
	an element <code>B</code> that is an arbitrary descendant
	of some ancestor element <code>A</code>.

	This combinator differs from the [=descendant combinator=]
	in that it applies [=weak scoping proximity=]
	to the relationship between <css>A</css> and <css>B</css>.
	It does not change the [=:scope element=].

	ISSUE: Should the [=scoped descendant combinator=]
	use strong or weak scoping proximity?
	Should it even exist?
	It's defined here to work the way many people expected
	the regular [=descendant combinator=] to work...

	<div class="example">
		This means that style rules using the [=scoped descendant combinator=]
		are sorted by specificity just like the regular [=descendant combinator=],
		except that when their specificities are equal
		the more tightly-scoped declaration wins.

		In this example
		the <code>&lt;a></code> element's color will be determined
		by the nearest ancestor with either
		a ''light-scheme'' or ''dark-scheme'' class.
		(If the descendant selector had been used,
		its color would always be ''plum'',
		because it is later in the source order.)

		<pre>
			.light-scheme >> a { color: darkmagenta; }
			.dark-scheme >> a { color: plum; }
		</pre>

		However if the <code>&lt;a></code> element has a ''light-scheme''
		ancestor and is focused,
		its color will be ''teal''
		even if it has a nearer ''dark-scheme'' ancestor,
		because there is no equivalent ''dark-scheme'' rule.

		<pre>
			.light-scheme >> a:focus { color: teal; }
		</pre>
	</div>

	Note: Most simple scoping relationships can be represented with this syntax,
	rather than the more complex [=selector scoping notation=] defined below.

<h4 id='selector-scoping'>
Selector Scoping Notation</h4>

	The <dfn>selector scoping notation</dfn>
	allows [=selectors=] to be scoped
	to a subtree of the document,
	and allows the possibility of excluding nested subtrees.
	It is prepended to the selector or selector list,
	and its syntax is as follows:

	<pre class='prod'>
	<dfn><<selector-scope>></dfn> = ( <<scope-start>> [/ <<scope-end>>]? )
	</pre>

	If, after parsing, <<scope-start>> is an empty list,
	the selector is valid but matches nothing.
	Otherwise, the selector matches any element
	that is within the [=scope=] described
	by the given <<scope-start>> and <<scope-end>> selectors.

	<div class="note">
		The purpose of the [=selector scoping notation=]
		is to allow adding [=scoping limits=] to a selector:

		<pre class=lang-css>
		(.post / .comments) .title { font-size: 2em; }
		</pre>

		Without any such lower limits,
		the [=selector scoping notation=] is similar to existing descendant selectors,
		except that the [=scoping root=] can be matched
		by the selector as well.
	</div>

	The specificity of
	the most specific [=complex selector=] in <<scope-start>>
	is added to the specificity of each such scoped selector.
	The specificity of the <<scope-end>> is ignored.
	The [=selector scoping notation=] also applies [=weak scoping proximity=]
	between the [=scoping root=] and the [=subject=] of the scoped selector.

	ISSUE: Should this have the same [=scope proximity=] weighting as ''@scope''
	or different [=scope proximity=] weighting
	(or no [=scope proximity=] weighting)?

	<div class="example">
		For example,
		these three selectors will all select the same elements,
		with the same specificity:

		<pre class=lang-css>
		(.ancestor) .child                { color: darkmagenta; }
		.child:is(.ancestor, .ancestor *) { color: darkmagenta; }
		.ancestor.child, .ancestor .child { color: darkmagenta; }
		</pre>

		However the first rule will win,
		because it also applies [=weak scoping proximity=].
	</div>

	ISSUE: How does this interact with [[CSS-NESTING-1]]?

	ISSUE: This notation was added in order to allow scoping limits
	to be applied within <code>querySelector()</code>.
	Is this something we want to have?

<h3 id="preshint">
Precedence of Non-CSS Presentational Hints</h3>

	Issue: [[css-cascade-5#layering]]


<!--
████████ ████████  ██████
██          ██    ██    ██
██          ██    ██
██████      ██    ██
██          ██    ██
██          ██    ██    ██
████████    ██     ██████
-->

<h2 id="changes">
Changes</h2>

<h3 id="additions-l5">
Additions Since Level 5</h3>

	The following features have been added since
	<a href="https://www.w3.org/TR/css-cascade-5/">Level 5</a>:

	* The definition of a [=scope=],
		as described by a combination of <<scope-start>> and <<scope-end>> selectors.
	* The in-scope ('':in()'') pseudo-class for selecting with lower-boundaries
	* The ''@scope'' rule for creating scoped stylesheets
	* The definition of [=scope proximity=] in the cascade


<h3 id="additions-l4">
Additions Since Level 4</h3>

	The following features have been added since
	<a href="https://www.w3.org/TR/css-cascade-4/">Level 4</a>:

	* Added [=cascade layers=] to the [=cascade=] sort criteria
		(and defined style attributes as a distinct step of the [=cascade=] sort criteria
		so that they interact appropriately).
	* Introduced the ''@layer'' rule for defining cascade layers.
	* Added ''layer''/''layer()'' option to ''@import'' definition.
	* Introduced the ''revert-layer'' keyword for rolling back values to previous layers.

<h3 id="additions-l3">
Additions Since Level 3</h3>

	The following features have been added since
	<a href="https://www.w3.org/TR/css-cascade-3/">Level 3</a>:

	* Introduced ''revert'' keyword, for rolling back the cascade.
	* Introduced ''supports()'' syntax for supports-conditional ''@import'' rules.
	* Added [=encapsulation context=] to the [=cascade=] sort criteria
		to accommodate Shadow DOM. [[DOM]]
	* Defined the property two aliasing mechanisms CSS uses to support legacy syntaxes. See [[css-cascade-4#aliasing]].
<!--
	* Added definition of how scoped styles would cascade
		(deferred from Level 3)
-->

<h3 id="changes-2">
Additions Since Level 2</h3>

	The following features have been added since
	<a href="http://www.w3.org/TR/CSS2/cascade.html">Level 2</a>:

	<ul>
		<li>The 'all' shorthand
		<li>The ''initial'' keyword
		<li>The ''unset'' keyword
		<li>Incorporation of animations and transitions into the <a>cascade</a>.
	</ul>

<h2 class="no-num" id="acknowledgments">Acknowledgments</h2>

	David Baron,
	Tantek Çelik,
	Keith Grant,
	Giuseppe Gurgone,
	Theresa O'Connor,
	Florian Rivoal,
	Noam Rosenthal,
	Simon Sapin,
	Jen Simmons,
	Nicole Sullivan,
	Lea Verou,
	and Boris Zbarsky
	contributed to this specification.

<h2 class=no-num id=priv-sec>
Privacy and Security Considerations</h2>

	* The cascade process does not distinguish between same-origin and cross-origin stylesheets,
		enabling the content of cross-origin stylesheets to be inferred
		from the computed styles they apply to a document.

	* User preferences and UA defaults expressed via application of style rules
		are exposed by the cascade process,
		and can be inferred from the computed styles they apply to a document.

	* The ''@import'' rule does not apply the [=CORS protocol=] to loading cross-origin stylesheets,
		instead allowing them to be freely imported and applied.

	* The ''@import'' rule assumes that resources without <a href="https://html.spec.whatwg.org/multipage/urls-and-fetching.html#content-type"><code>Content-Type</code> metadata</a>
		(or any same-origin file if the host document is in quirks mode)
		are <code>text/css</code>,
		potentially allowing arbitrary files to be imported into the page
		and interpreted as CSS,
		potentially allowing sensitive data to be inferred from the computed styles they apply to a document.