CSS Scoping Module Level 1

Editor’s Draft,

This version:
https://drafts.csswg.org/css-scoping/
Latest published version:
https://www.w3.org/TR/css-scoping-1/
Previous Versions:
https://www.w3.org/TR/2014/WD-css-scoping-1-20140403/
Feedback:
www-style@w3.org with subject line “[css-scoping] … message topic …” (archives)
Issue Tracking:
Bugzilla
Inline In Spec
Editors:
Tab Atkins Jr. (Google)
Elika J Etemad / fantasai (Invited Expert)

Abstract

This specification defines various scoping/encapsulation mechanisms for CSS, including scoped styles and the @scope rule, Shadow DOM selectors, and page/region-based styling.

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-scoping” in the subject, preferably like this: “[css-scoping] …summary of comment…

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

1. Introduction

...

2. Scoped Styles

Scoped style rules apply only within a subtree of a document, rather than matching against the entire document. Scoping has two primary effects:

2.1. Scoping Mechanisms

Style rules can be scoped using constructs defined in the document language or using the @scope rule in CSS.

“Scoping” consists of three somewhat independent concepts, which are in practice generally used together:

2.1.1. Document Markup for Scoping

Document languages may define a mechanism for a stylesheet to be scoped to some element in the document. For example, in HTML, a style element with a scoped attribute defines a stylesheet that is scoped to the style element’s parent element. [HTML]

The element that the stylesheet is scoped to is the scoping root for all the style rules in the stylesheet, and selectors of style rules in the stylesheet are scope-contained to the scoping root.

2.1.2. CSS Syntax for Scoping: the @scope rule

The @scope#at-ruledef-scopeReferenced in:2.1. Scoping Mechanisms2.1.2. CSS Syntax for Scoping: the @scope rule (2) (3) (4) (5) (6) (7) (8) at-rule allows authors to create scoped style rules using CSS syntax. The syntax of the @scope rule is:

@scope <selector-list> {
  <stylesheet>
}

where the elements matched by the <selector-list> are scoping roots for the style rules in <stylesheet>, and selectors of style rules scoped by @scope are scope-contained to their scoping root.

This rule makes it very easy for authors to create scoped style sheets, which could affect the optimization strategies for implementing scoped styles.

If multiple elements match the <selector-list>, the <stylesheet> is effectively duplicated and scoped independently to each one. Authors should avoid using overly-generic selectors as it can have confusing interactions with the cascade.

A scoped stylesheet is attached not only to the outermost scoping element, but to all matching elements. For example, given the style sheet below
@scope div {
  span {
    color: blue;
  }
}
@scope section {
  span {
    color: orange;
  }
}

and the following document fragment

<div>
  <section>
    <div>
      <span>text</span>
    </div>
  </section>
</div>

the text will be blue.

@scope rules can be nested. In this case, just as with the nested style rules, the selector of an outer @scope scope-contains the selector of the inner one.

The specificity of selectors inside the @scope rule is calculated locally: the selector specifying the scoping element is ignored. However, because scoped styles override non-scoped styles, style rules inside the @scope will override rules outside of it.

In the following example, the text would be green:
@scope aside {
  p { color: green; }
}
aside#sidebar p { color: red; }

If multiple @scope rules apply to an element, should they be cascaded by specificity?

2.2. Querying the Scoping Context

2.2.1. Selecting the Scoping Root: :scope pseudo-class

In a scoped stylesheet, the :scope pseudo-class, defined in [SELECTORS4], matches the scoping root.

2.2.2. Selecting Outside the Scope: :scope-context() pseudo-class

This would be defined similarly to :host-context(), but matching the ancestors of the scoping root instead.

However, since for scoped stylesheets you may want the ability to match complex selectors against the outside tree, rather than a single compound selector, we may want to instead use a more general mechanism that doesn’t syntactically invert the order of tree elements.

Possible ideas:

:scope-context(<selector-list>) div {...}
scope(<selector-list>) div {...}
\scope <selector-list>\ div {...}
<selector-list> \scope\ div {...}

This functionality would replace @global, which is a poor excuse for a selector.

3. Default Styles for Custom Elements

When defining custom elements, one often wants to set up "default" styles for them, akin to the user-agent styles that apply to built-in elements. This is, unfortunately, hard to do in vanilla CSS, due to issues of scoping and specificity—the element in question might be used in shadow trees, and thus is unreachable by any selector targeting it in the outermost document; and selectors, even low-specificity ones like simple type selectors, can accidentally override author-level styles meant to target the element.

To aid in this, this section defines a way to create a stylesheet of "default element styles" for a given element. This stylesheet applies across the entire document, in all shadow trees, and the rules in it apply at the user agent origin, so author-level rules automatically win.

Windows gain a private slot [[defaultElementStylesMap]]#dom-window-defaultelementstylesmap-slotReferenced in:3. Default Styles for Custom Elements which is a map of local names to stylesheets.

These stylesheets must apply to every document in the window. They must be interpreted as user agent stylesheets.

Note: This implies, in particular, that they apply to all shadow trees in every document, and that the declarations in them are from the user agent origin.

For the purpose of the cascade, these stylesheets are ordered after the user agent’s own stylesheets; their relative ordering doesn’t matter as it is not observable.

Within these stylesheets, complex selectors must be treated as invalid. Every compound selector must be treated as containing an additional type selector that selects elements with the local name that the stylesheet is keyed with.

Do we need to restrict the at-rules that can be used in these sheets? For example, do we allow an @font-face? I’m going to leave it as allowed unless/until I hear complaints.

This specification does not define how to add to, remove from, or generally manipulate the [[defaultElementStylesMap]]. It is expected that other specifications, such as [DOM], will define ways to do so.

4. Shadow Encapsulation

4.1. Informative Explanation of Shadow DOM

The following is a non-normative explanation of several concepts normatively defined in the DOM Standard [DOM], to aid in understanding what this spec defines without having to fully grok the DOM Standard.

In addition to the qualities of an element tree defined in Selectors Level 4 §data-model, the DOM Standard adds several new concepts related to shadow trees, several of which are relevant to CSS.

An element can host a shadow tree, which is a special kind of document fragment with a shadow root (a non-element node) at its root. Children of the shadow root are ordinary elements and other nodes. The element hosting the shadow tree is its host, or shadow host#shadow-hostReferenced in:4.1. Informative Explanation of Shadow DOM (2)4.2.1. Matching Selectors Against Shadow Trees4.2.2. Selecting Shadow Hosts from within a Shadow Tree (2) (3) (4) (5) (6) (7) (8) (9)4.2.3. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes (2) (3) (4) (5)4.2.4. Selecting Slot-Assigned Content: the ::slotted() pseudo-element4.4. Flattening the DOM into an Element Tree (2) (3).

The elements in a shadow tree are not descendants of the shadow host in general (including for the purposes of Selectors like the descendant combinator). However, the shadow tree, when it exists, is used in the construction of the flattened element tree, which CSS uses for all purposes after Selectors (including inheritance and box construction).

Loosely, the shadow tree is treated as the shadow host’s contents instead of its normal light tree contents. However, some of its light tree children can be "pulled into" the shadow tree by assigning them to slots. This causes them to be treated as children of the slot for CSS purposes. The slots can then be assigned to slots in deeper shadow trees; luckily, slots themselves don’t generate boxes by default, so you don’t get an unpredictable cascade of slot wrapper elements disrupting your CSS.

If nothing is explicitly assigned to a slot, the slot’s own children are instead assigned to it, as a sort of "default" contents.

4.2. Shadow DOM and Selectors

4.2.1. Matching Selectors Against Shadow Trees

When a selector is matched against a shadow tree, the selector match list is initially the shadow host, followed by all children of the shadow tree’s shadow root and their descendants, ordered by a pre-order traversal.

Note: Remember that the descendants of an element are based on the light tree children of the element, which does not include the shadow trees of the element.

When a selector is matched against a tree, its tree context#tree-contextReferenced in:4.2.1. Matching Selectors Against Shadow Trees (2)4.3. Shadow Trees and the Cascade is the root of the root elements passed to the algorithm. If the tree context is a shadow root, that selector is being matched in the context of a shadow tree#in-the-context-of-a-shadow-treeReferenced in:4.2.1. Matching Selectors Against Shadow Trees4.2.2. Selecting Shadow Hosts from within a Shadow Tree4.2.3. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes (2) (3).

For example, any selector in a stylesheet embedded in or linked from an an element in a shadow tree is in the context of a shadow tree. So is the argument to querySelector() when called from a shadow root.

Declarations inherit the tree context of the selector that was matched to apply them.

4.2.2. Selecting Shadow Hosts from within a Shadow Tree

A shadow host is outside of the shadow tree it hosts, and so would ordinarily be untargettable by any selectors evaluated in the context of the shadow tree (as selectors are limited to a single tree), but it is sometimes useful to be able to style it from inside the shadow tree context.

For the purpose of Selectors, a shadow host also appears in its shadow tree, with the contents of the shadow tree treated as its children. (In other words, the shadow host is treated as replacing the shadow root node.)

When considered within its own shadow trees, the shadow host is featureless. Only the :host, :host(), and :host-context() pseudo-classes are allowed to match it.

Why is the shadow host so weird?

The shadow host lives outside the shadow tree, and its markup is in control of the page author, not the component author.

It would not be very good if a component used a particular class name internally in a shadow tree stylesheet, and the page author using the component accidentally also used the the same class name and put it on the shadow host. Such a situation would result in accidental styling that is impossible for the component author to predict, and confusing for the page author to debug.

However, there are still some reasonable use-cases for letting a stylesheet in a shadow tree style its shadow host. (For example, the component might want to be laid out as a flexbox, requiring the shadow host to be set to display: flex.) So, to allow this situation but prevent accidental styling, the shadow host appears but is completely featureless and unselectable except through :host and its related functional forms, which make it very explicit when you’re trying to match against markup provided by the page author.

4.2.3. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes

The :host#selectordef-hostReferenced in:4.2.2. Selecting Shadow Hosts from within a Shadow Tree (2)4.2.3. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes (2) pseudo-class, when evaluated in the context of a shadow tree, matches the shadow tree’s shadow host. In any other context, it matches nothing.

The :host()#selectordef-host-functionReferenced in:4.2.2. Selecting Shadow Hosts from within a Shadow Tree4.2.3. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes function pseudo-class has the syntax:

:host( <compound-selector> )

When evaluated in the context of a shadow tree, it matches the shadow tree’s shadow host if the shadow host, in its normal context, matches the selector argument. In any other context, it matches nothing.

For example, say you had a component with a shadow tree like the following:
<x-foo class="foo">
  <"shadow tree">
    <div class="foo">...</div>
  </>
</x-foo>

For a stylesheet within the shadow tree:

Ordinary, selectors within a shadow tree can’t see elements outside the shadow tree at all. Sometimes, however, it’s useful to select an ancestor that lies somewhere outside the shadow tree, above it in the document.

For example, a group of components can define a handful of color themes they they know how to respond to. Page authors could opt into a particular theme by adding a specific class to the components, or higher up in the document.

The :host-context()#selectordef-host-contextReferenced in:2.2.2. Selecting Outside the Scope: :scope-context() pseudo-class4.2.2. Selecting Shadow Hosts from within a Shadow Tree4.2.3. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes (2) functional pseudo-class tests whether there is an ancestor, outside the shadow tree, which matches a particular selector. Its syntax is:

:host-context( <compound-selector> )

When evaluated in the context of a shadow tree, the :host-context() pseudo-class matches the shadow host, if the shadow host or one of its shadow-including ancestors matches the provided <compound-selector>. In any other context, it matches nothing.

Note: This means that the selector pierces through shadow boundaries on the way up, looking for elements that match its argument, until it reaches the document root.

4.2.4. Selecting Slot-Assigned Content: the ::slotted() pseudo-element

The ::slotted()#selectordef-slottedReferenced in:4.2.4. Selecting Slot-Assigned Content: the ::slotted() pseudo-element (2) (3) (4) (5) (6) (7)4.4. Flattening the DOM into an Element Tree pseudo-element represents the elements assigned, after flattening, to a slot. This pseudo-element only exists on slots.

The ::slotted() pseudo-element is an alias for other elements in the tree, and does not generate any boxes itself.

The grammar of the ::slotted() pseudo-element is:

::slotted( <compound-selector> )

The ::slotted() pseudo-element represents the elements that are:

For example, say you had a component with both children and a shadow tree, like the following:
<x-foo>
  <div id="one" slot="foo" class="foo">...</div>
  <div id="two" slot="foo">...</div>
  <div id="three" class="foo">
    <div id="four" slot="foo">...</div>
  </div>
  <"shadow tree">
    <div id="five">...</div>
    <div id="six">...</div>
    <slot name="foo"></content>
  </"shadow tree">
</x-foo>

For a stylesheet within the shadow tree, a selector like ::slotted(*) selects #one and #two only, as they’re the elements assigned to the sole slot element. It will not select #three (no slot attribute) nor #four (only direct children of a shadow host can be assigned to a slot).

A selector like ::slotted(.foo), on the other hand, will only select #one, as it matches .foo, but #two doesn’t.

Note: Note that a selector like ::slotted(*) is equivalent to *::slotted(*), where the * selects many more elements than just the slot element. However, since only the slot elements are slots, they’re the only elements with a ::slotted() pseudo-element as well.

Note: ::slotted() can only represent the elements assigned to the slot. Slots can also be assigned text nodes, which can’t be selected by ::slotted(). The only way to style assigned text nodes is by styling the slot and relying on inheritance.

4.2.5. Selecting Through Shadows: the >>> combinator

When a >>>#selectordef-shadow-piercing-descendant-combinatorReferenced in:4.2.5. Selecting Through Shadows: the >>> combinator combinator (or shadow-piercing descendant combinator#shadow-piercing-descendant-combinatorReferenced in:4.2.5. Selecting Through Shadows: the >>> combinator) is encountered in a selector, replace every element in the selector match list with every element reachable from the original element by traversing any number of child lists or shadow trees.

For example, say you had a component with a shadow tree like the following:
<x-foo>
  <"shadow tree">
    <div>
      <span id="not-top">...</span>
    </div>
    <span id="top">...</span>
    <x-bar>
      <"shadow tree">
        <span id="nested">...</span>
      </>
    </x-bar>
  </>
</x-foo>

For a stylesheet in the outer document, the selector x-foo >>> span selects all three of <span> elements: #top, #not-top, and #nested.

The shadow-piercing descendant combinator is part of the static profile of Selectors, not the dynamic profile. This means that it is usable in, for example, the querySelector() method, but is invalid when used in stylesheets.

4.3. Shadow Trees and the Cascade

To address the desired cascading behavior of rules targetting elements in shadow roots, this specification extends the cascade order defined in the Cascade specification. [CSS3CASCADE]

An additional cascade criteria must be added, between Origin and Scope, called Shadow Tree.

4.4. Flattening the DOM into an Element Tree

While Selectors operates on the DOM tree as the host language presents it, with separate trees that are unreachable via the standard parent/child relationship, the rest of CSS needs a single unified tree structure to work with. This is called the flattened element tree#flat-treeReferenced in:4.1. Informative Explanation of Shadow DOM4.4. Flattening the DOM into an Element Tree (2) (3) (4) (or flat tree), and is constructed as follows:

  1. Let pending nodes be a list of DOM nodes with associated parents, initially containing just the document’s root element with no associated parent.

  2. Repeatedly execute the following substeps until pending nodes is empty:

    1. Pop the first element from pending nodes, and assign it to pending node.

    2. Insert pending node into the flat tree as a child of its associated parent. (If it has no associated parent, it’s the document root—just insert it into the flat tree as its root.)

    3. Perform one of the following, whichever is the first that matches:

      pending node is a shadow host
      Append the child nodes of the shadow root of the shadow tree it hosts to pending nodes, with pending node as their associated parent.
      pending node is a slot
      Find slotables for pending node, and append them to pending nodes, with pending node as their associated parent.

      If no slotables were found for pending node, instead append its children to pending nodes, with pending node as their associated parent.

      Otherwise,
      Append the child nodes of pending node’s light tree to pending nodes, with pending node as their associated parent.

Note: In other words, the flat tree is the top-level DOM tree, but shadow hosts are filled with their shadow tree children instead of their light tree children (and this proceeds recursively if the shadow tree contains any shadow hosts), and slots get filled with the nodes that are assigned to them (and this proceeds recursively if the slots are themselves assigned to a slot in a deeper shadow tree).

A non-obvious result of this is that elements assigned to a slot inherit from that slot, not their light-tree parent or any deeper slots their slot gets assigned to. This means that text nodes are styled by the shadow tree of their parent, with nobody else capable of intervening in any way. Do we want an additional pseudo-element for targeting those text nodes so they can be styled at all slot-assignment levels, like normal elements can be? This implies it needs to work for text nodes in the light tree before they’re assigned downwards, so this can’t just be a ::slotted() variant. Luckily, this is a long-standing request!

4.4.1. Slots and Slotted Elements in a Shadow Tree

Slots must act as if they were assigned display: contents via a rule in the UA origin. This must be possible to override via display, so they do generate boxes if desired.

Note: A non-obvious result of assigning elements to slots is that they inherit from the slot they’re assigned to. Their original light tree parent, and any deeper slots that their slot gets assigned to, don’t affect inheritance.

5. Fragmented Styling

Fragmented content can be styled differently based on which line, column, page, region, etc. it appears in. This is done by using an appropriate fragment pseudo-element, which allows targetting individual fragments of an element rather than the entire element.

In our example, the designer wants to make text flowing into #region1 dark blue and bold. This design can be expressed as shown below.
#region1::region p {
  color: #0C3D5F;
  font-weight: bold;
}

The ::region pseudo-element is followed by a p relative selector in this example. The color and font-weight declarations will apply to any fragments of paragraphs that are displayed in #region1. The following figure shows how the rendering changes if we apply this styling specific to #region1. Note how less text fits into this box now that the font-weight is bold instead of normal.

Illustrate how changing region styling affects the flow of content.
Different rendering with a different region styling

Note: This feature is an extension of ::first-line styling.

5.1. Region-based Styling: the ::region pseudo-element

Extend this to specify:

A ::region pseudo-element represents a relationship between a selector that matches a CSS Region, and a relative selector that matches some named flow content. This allows style declarations to be applied to fragments of named flow content flowing into particular regions.

<region selector>::region <content selector>  {
  ... CSS styling declarations ...
}

When the ::region pseudo-element is appended to a selector that matches one or more CSS Regions, this creates a 'flow fragment' selector. The flow fragment selector specifies which range of elements in the flow can be matched by the relative selector. The relative selector can match elements in the range(s) (see [DOM]) of the named flow that are displayed fully or partially in the selected region(s).

Elements that are fully or partially in the flow fragment range may match the relative selector. However, the style declarations only apply to the fragment of the element that is displayed in the corresponding region(s).

Only a limited list of properties apply to a ::region pseudo-element:

Either this list should be all functionally inheritable properties, or all properties. Why is it a seemingly-arbitrary subset of all properties, including box properties?

  1. font properties

  2. color property

  3. opacity property

  4. background property

  5. word-spacing

  6. letter-spacing

  7. text-decoration

  8. text-transform

  9. line-height

  10. alignment and justification properties

  11. border properties

  12. rounded corner properties

  13. border images properties

  14. margin properties

  15. padding properties

  16. text-shadow

  17. box-shadow

  18. box-decoration-break

  19. width

In the following example, the named flow “article-flow” flows into “region-1” and “region-2”.
<style>
  #div-1 {
  flow-into: article-flow;
  }

  #region-1, #region-2 {
  flow-from: article-flow;
  }

  /* region styling */
  #region-1::region p  {
  margin-right: 5em;
  }
</style>

<body>
  <div id="div-1">
    <p id="p-1">...</p>
    <p id="p-2">...</p>
  </div>
  <div id="region-1"></div>
  <div id="region-2"></div>
</body>
Example showing how a named flow content fits into regions to illustrate region styling.
  •  div div-1
  •  paragraph p-1
  •  paragraph p-2
  •  range of flow that fits into region-1
  •  range of flow that fits into region-2

The region styling applies to flow content that fits in region-1. The relative selector matches p-1 and p-2 because these paragraphs flow into region-1. Only the fragment of p-2 that flows into region-1 is styled with the pseudo-element.

All of the selectors in a ::region pseudo-element contribute to its specificity. So the specificity of the ::region pseudo-element in the example above would combine the id selector’s specificity with the specificity of the type selector, resulting in a specificity of 101.

Selectors that match a given element or element fragment (as described above), participate in the CSS Cascading order as defined in [CSS21].

Note: Region styling does not apply to nested regions. For example, if a region A receives content from a flow that contains region B, the content that flows into B does not receive the region styling specified for region A.

We’ll need some way to query the styles of a fragment in a particular region. getComputedStyle() isn’t enough, because an element can exist in multiple regions, for example, with each fragment receiving different styles.

6. Changes

The following significant changes were made since the 3 April 2014 Working Draft.

7. Privacy and Security Considerations

This specification introduces Shadow DOM and some shadow-piercing capabilities, but this does not introduce any privacy or security issues—shadow DOM, as currently specified, is intentionally not a privacy/security boundary (and the parts of the UA that use shadow DOM and do have a privacy/security boundary implicitly rely on protections not yet specified, which protect them from the things defined in 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:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

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.

Requirements for Responsible Implementation of CSS

The following sections define several conformance requirements for implementing CSS responsibly, in a way that promotes interoperability in the present and future.

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

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Implementations of CR-level Features

Once a specification reaches the Candidate Recommendation stage, implementers should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec, and should avoid exposing a prefixed variant of that feature.

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.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-BACKGROUNDS-3]
CSS Backgrounds and Borders Module Level 3 URL: https://drafts.csswg.org/css-backgrounds-3/
[CSS-BREAK-3]
Rossen Atanassov; Elika Etemad. CSS Fragmentation Module Level 3. 14 January 2016. CR. URL: http://dev.w3.org/csswg/css-break/
[CSS-CASCADE-4]
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 4. 14 January 2016. CR. URL: http://dev.w3.org/csswg/css-cascade/
[CSS-FONTS-3]
John Daggett. CSS Fonts Module Level 3. 3 October 2013. CR. URL: http://dev.w3.org/csswg/css-fonts/
[CSS-PSEUDO-4]
Daniel Glazman; Elika Etemad; Alan Stearns. CSS Pseudo-Elements Module Level 4. 15 January 2015. WD. URL: http://dev.w3.org/csswg/css-pseudo-4/
[CSS-SYNTAX-3]
Tab Atkins Jr.; Simon Sapin. CSS Syntax Module Level 3. 20 February 2014. CR. URL: http://dev.w3.org/csswg/css-syntax/
[CSS-TEXT-3]
Elika Etemad; Koji Ishii. CSS Text Module Level 3. 10 October 2013. LCWD. URL: http://dev.w3.org/csswg/css-text-3/
[CSS-TEXT-DECOR-3]
Elika Etemad; Koji Ishii. CSS Text Decoration Module Level 3. 1 August 2013. CR. URL: http://dev.w3.org/csswg/css-text-decor-3/
[CSS21]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. REC. URL: http://www.w3.org/TR/CSS2
[CSS3CASCADE]
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 3. 16 April 2015. CR. URL: http://www.w3.org/TR/css-cascade-3/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[HTML]
Ian Hickson. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SELECTORS-4]
Selectors Level 4 URL: https://drafts.csswg.org/selectors-4/
[SELECTORS4]
Elika Etemad; Tab Atkins Jr.. Selectors Level 4. 2 May 2013. WD. URL: http://www.w3.org/TR/selectors4/

Issues Index

This rule makes it very easy for authors to create scoped style sheets, which could affect the optimization strategies for implementing scoped styles.
If multiple @scope rules apply to an element, should they be cascaded by specificity?
This would be defined similarly to :host-context(), but matching the ancestors of the scoping root instead.

However, since for scoped stylesheets you may want the ability to match complex selectors against the outside tree, rather than a single compound selector, we may want to instead use a more general mechanism that doesn’t syntactically invert the order of tree elements.

Possible ideas:

:scope-context(<selector-list>) div {...}
scope(<selector-list>) div {...}
\scope <selector-list>\ div {...}
<selector-list> \scope\ div {...}

This functionality would replace @global, which is a poor excuse for a selector.

Do we need to restrict the at-rules that can be used in these sheets? For example, do we allow an @font-face? I’m going to leave it as allowed unless/until I hear complaints.
A non-obvious result of this is that elements assigned to a slot inherit from that slot, not their light-tree parent or any deeper slots their slot gets assigned to. This means that text nodes are styled by the shadow tree of their parent, with nobody else capable of intervening in any way. Do we want an additional pseudo-element for targeting those text nodes so they can be styled at all slot-assignment levels, like normal elements can be? This implies it needs to work for text nodes in the light tree before they’re assigned downwards, so this can’t just be a ::slotted() variant. Luckily, this is a long-standing request!
Extend this to specify:
Either this list should be all functionally inheritable properties, or all properties. Why is it a seemingly-arbitrary subset of all properties, including box properties?
We’ll need some way to query the styles of a fragment in a particular region. getComputedStyle() isn’t enough, because an element can exist in multiple regions, for example, with each fragment receiving different styles.