diff --git a/ShadowDOM/explainer.md b/ShadowDOM/explainer.md new file mode 100644 index 00000000..8f1d9f8c --- /dev/null +++ b/ShadowDOM/explainer.md @@ -0,0 +1,397 @@ +# Declarative shadow DOM style sharing + +## Authors + +- Kurt Catti-Schmidt +- Daniel Clark +- Alex Russell +- Tien Mai + +## Participate +- [Discussion forum](https://github.com/WICG/webcomponents/issues/939) + +## Status of this Document + +This document is intended as a starting point for engaging the community and +standards bodies in developing collaborative solutions fit for standardization. +As the solutions to problems described in this document progress along the +standards-track, we will retain this document as an archive and use this section +to keep the community up-to-date with the most current standards venue and +content location of future work and discussions. + +* This document status: **Active** +* Expected venue: [Web Components CG](https://w3c.github.io/webcomponents-cg/) +* Current version: this document +## Table of Contents + - [Authors](#authors) + - [Participate](#participate) + - [Status of this Document](#status-of-this-document) + - [Background](#background) + - [Problem](#problem) + - [Goals](#goals) + - [Non-goals](#non-goals) + - [Use case](#use-case) + - [Media site control widgets](#media-site-control-widgets) + - [Anywhere web components are used](#anywhere-web-components-are-used) + - [Alternatives to using style in DSD](#alternatives-to-using-style-in-dsd) + - [Proposal: Inline, declarative SS module scripts](#proposal-inline-declarative-css-module-scripts) + - [Alternate proposals](#alternate-proposals) + - [Summary](#summary) + - [Open issues](#open-issues) + - [References and acknowledgements](#references-and-acknowledgements) + + +## Background +With the use of web components in web development, web authors often encounter challenges in managing styles, such as distributing global styles into shadow roots and sharing styles across different shadow roots. Markup-based shadow DOM, or [Declarative shadow DOM (DSD)](https://developer.chrome.com/docs/css-ui/declarative-shadow-dom), is a new concept that makes it easier and more efficient to create a shadow DOM definition directly in HTML, without needing JavaScript for setup. [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) provides isolation for CSS, JavaScript, and HTML. Each shadow root has its own separate scope, which means styles defined inside one shadow root do not affect another or the main document. + +## Problem +Sites that make use of Declarative Shadow DOM (DSD) have reported that the lack of a way to reference repeated stylesheets creates large payloads that add large amounts of latency. Authors have repeatedly asked for a way to reference stylesheets from other DSD instances in the same way that frameworks leverage internal data structures to share constructable style sheets via `adoptedStyleSheets`. This Explainer explores several potential solutions. + +Relying on JavaScript for styling is not ideal for DSD for several reasons: +* One of the main goals of DSD is to not rely on JavaScript [for performance and accessibility purposes](https://web.dev/articles/declarative-shadow-dom). +* Adding stylesheets via script may cause an FOUC (Flash of Unstyled Content). +* The current `adoptedStylesheets` property only supports Constructable Stylesheets, not inline stylesheets or stylesheets from tags [(note that the working groups have recently decided to lift this restriction)](https://github.com/w3c/csswg-drafts/issues/10013#issuecomment-2165396092). + +While referencing an external file via the tag for shared styles in DSD works today [(and is currently recommended by DSD implementors)](https://web.dev/articles/declarative-shadow-dom#server-rendering_with_style), it is not ideal for several reasons: +* If the linked stylesheet has not been downloaded and parsed, there may be an FOUC. +* External stylesheets are considered “render blocking”, and Google’s Lighthouse guidelines for high-performance web content recommends [using inline styles instead](https://developer.chrome.com/docs/lighthouse/performance/render-blocking-resources#how_to_eliminate_render-blocking_stylesheets). +* Google’s Lighthouse guidelines recommend minimizing network requests for best performance. Stylesheets included via tags are always external resources that may initiate a network request (note that the network cache mitigates this for repeated requests to the same file). + +This example shows how a developer might use DSD to initialize a shadow root without JavaScript. + +```html + + + +``` +While this approach is acceptable for a single component, a rich web application may define many `