CSS Cascading and Inheritance Level 6

1. Introduction and Missing Sections

This is a diff spec over CSS Cascading and Inheritance Level 5. 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.

2. Cascading

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

2.1. Cascade Sorting Order

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

Origin and Importance

The origin of a declaration is based on where it comes from and its importance is whether or not it is declared with !important (see below). The precedence of the various origins is, in descending order:

1. Transition declarations [css-transitions-1]
2. Important user agent declarations
3. Important user declarations
4. Important author declarations
5. Animation declarations [css-animations-1]
6. Normal author declarations
7. Normal user declarations
8. Normal user agent declarations

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

Context

A document language can provide for blending declarations sourced from different encapsulation contexts, 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.

The Style Attribute

Separately for normal and important declarations, declarations that are attached directly to an element (such as the contents of a style attribute) rather than indirectly mapped by means of a style rule selector take precedence over declarations the same importance that are mapped via style rule.

Layers

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

Strong Scoping Proximity

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

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. The declaration with the highest specificity wins.

Weak Scoping Proximity

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

Order of Appearance

The last declaration in document order wins. For this purpose:

• Style sheets are ordered as in final CSS style sheets.
• Declarations from imported style sheets are ordered as if their style sheets were substituted in place of the @import rule.
• 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. [CSSSTYLEATTR]

Does scope proximity belong above or below specificity in the cascade? [Issue #6790]

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

2.2. Cascading Origins

CSS Cascading 5 § 6.2 Cascading Origins

cascade origin

2.3. Important Declarations: the !important annotation

CSS Cascading 5 § 6.3 Important Declarations: the !important annotation

important normal

2.4. Cascade Layers

CSS Cascading 5 § 6.4 Cascade Layers

2.4.1. Layer Ordering

CSS Cascading 5 § 6.4.3 Layer Ordering

2.5. Scoped Styles

A scope 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 <scope-start> 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 <scope-end> is a <forgiving-selector-list> that is scoped by the <scope-start> selector, with the scoping roots as :scope elements. Each element matched by <scope-end> is a scoping limit. The scoping limit elements define the lower bounds of a scope, so that scoped selectors are not able to match any scoping limit elements, or any elements nested within them.

Each resulting scope includes a scoping root and all its descendants, up to any scoping limit elements. Scoping limit elements and their descendants are not included in the scope.

Note: In contrast to 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.

@scope (.light-scheme) {
  a { color: darkmagenta; }
}

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

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

@scope (.media-object) to (.content > *) {
  img { border-radius: 50%; }
  .content { padding: 1em; }
}

Should scoping limits be added to the definition of scoped selectors?

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

/* .content is only a limit when the :scope is inside .sidebar */
@scope (.media-object) to (.sidebar :scope .content) { ... }

2.5.1. Scoping Styles: the @scope rule

The @scope 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.

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. [Issue #6790]

The syntax of the @scope rule is:

@scope (<scope-start>) [to (<scope-end>)]? {
  <stylesheet>
}

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

• 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 more proximate scoping root, regardless of specificity or source order.

@scope (#hero) {
  img { border-radius: 50%; }
}

#hero img { border-radius: 50%; }

<section data-scope="main-component">
  <p data-scope="main-component">...<p>

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

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

<section data-scope="main-component">
  <p>...<p>
  <section data-scope="sub-component">
    <p>...<p>
  </section>
</section>

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

  /* only the outer section is part of the outer scope */
  section { background: snow; }
}

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

  /* the inner section is only part of the inner scope */
  section { color: ghostwhite; }
}

@scope ([data-scope='main-component']) to ([data-scope] > *) {
  p { color: red; }

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

@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 by the selectors of the outer one.

2.5.2. Scoped Descendant Combinator

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

This combinator differs from the descendant combinator in that it applies weak scoping proximity to the relationship between A and B. It does not change the :scope element.

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

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

.light-scheme >> a:focus { color: teal; }

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

2.5.3. Selector Scoping Notation

The selector scoping notation 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:

<selector-scope> = ( <scope-start> [/ <scope-end>]? )

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.

(.post / .comments) .title { font-size: 2em; }

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.

Should this have the same scope proximity weighting as @scope or different scope proximity weighting (or no scope proximity weighting)?

(.ancestor) .child                { color: darkmagenta; }
.child:is(.ancestor, .ancestor *) { color: darkmagenta; }
.ancestor.child, .ancestor .child { color: darkmagenta; }

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

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

2.6. Precedence of Non-CSS Presentational Hints

CSS Cascading 5 § 6.4 Cascade Layers

3. Changes

This appendix is informative.

3.1. Changes since the 21 December 2021 First Public Working Draft

Significant changes since the 21 December 2021 First Public Working Draft include:

• Scoping limit elements are excluded from the resulting scope. (Issue 6577)

3.2. Additions Since Level 5

The following features have been added since Level 5:

• 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

3.3. Additions Since Level 4

The following features have been added since Level 4:

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

3.4. Additions Since Level 3

The following features have been added since Level 3:

• 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 Cascading 4 § 3.1 Property Aliasing.

3.5. Additions Since Level 2

The following features have been added since Level 2:

• The all shorthand
• The initial keyword
• The unset keyword
• Incorporation of animations and transitions into the cascade.

Acknowledgments

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.

Privacy and Security Considerations

• 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 Content-Type metadata (or any same-origin file if the host document is in quirks mode) are text/css, 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.