Declarative CSS Modules #11687

KurtCattiSchmidt · 2025-09-24T00:00:42Z

At least two implementers are interested (and none opposed):
- …
- …
Tests are written and can be reviewed and commented upon at:
- …
Implementation bugs are filed:
- Chromium: …
- Gecko: …
- WebKit: …
- Deno (only for timers, structured clone, base64 utils, channel messaging, module resolution, web workers, and web storage): …
- Node.js (only for timers, structured clone, base64 utils, channel messaging, and module resolution): …
Corresponding HTML AAM & ARIA in HTML issues & PRs:
MDN issue is filed: …
The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

/acknowledgements.html ( diff )
/indices.html ( diff )
/infrastructure.html ( diff )
/scripting.html ( diff )
/semantics.html ( diff )

Copilot

Pull Request Overview

This PR introduces declarative CSS modules support to HTML, allowing CSS to be imported as modules through <style> elements with a specifier attribute and <template> elements with a shadowrootadoptedstylesheets attribute.

Adds a specifier attribute to <style> elements that creates module import maps for CSS content
Introduces a shadowrootadoptedstylesheets attribute for <template> elements to declaratively adopt CSS modules
Implements algorithms for creating declarative CSS module scripts and stylesheet adoption

Comments suppressed due to low confidence (5)

source:1

Missing attribute name in IDL definition. Should be [SameObject, PutForwards=value, Reflect] readonly attribute DOMString <dfn attribute for="HTMLStyleElement" data-x="dom-style-specifier">specifier</dfn>; to match the pattern used for other attributes in this interface.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Grammar error: 'is defines' should be 'defines' - remove the word 'is'.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Grammar error: 'appended with the of the' should be 'appended with the' - remove the duplicate 'the of'.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Logic error: The algorithm references <var>specifier</var> but this variable is not defined in the algorithm. It should reference the value of the shadowrootadoptedstylesheets attribute instead.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Incorrect data-x reference: Should be data-x=\"attr-style-specifier\" not data-x=\"attr-style-blocking\" for the specifier attribute row.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

source

Copilot

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (9)

source:1

The IDL attribute should be named to match the content attribute. The content attribute is specifier but the IDL should use camelCase convention: [SameObject, PutForwards=value, Reflect] readonly attribute DOMString specifier; should have a data-x attribute defining the DOM property name.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

The shadowrootadoptedstylesheets attribute is listed twice in the content attributes section for the template element. This duplication should be removed.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

The shadowrootadoptedstylesheets attribute is listed twice in the content attributes section for the template element. This duplication should be removed.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

The algorithm step is missing proper HTML structure. It should end with </li> and the nested <ol> should be properly closed with </ol>.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

The variable moduleScript is referenced but never defined in this algorithm. This should likely be the current module script or settings object context.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

These variable assignments are missing closing </p> tags. Each should end with </p></li>.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Missing spaces after commas in the parameter list. Should be <var>fetchClient</var>, <var>destination</var>, <var>options</var>, <var>settingsObject</var>, <var>referrer</var> for consistency.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Incorrect data-x reference in the table. Line 148289 should reference data-x=\"element-template\" or similar, not data-x=\"attr-template-shadowrootclonable\".

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Incorrect data-x reference in the table. Line 148363 should reference data-x=\"element-style\" instead of data-x=\"attr-style-blocking\".

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

…able

dandclark

Review in progress, sharing feedback so far.

dandclark · 2025-10-02T22:10:15Z

source

+          https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2740
+          https://github.com/w3c/csswg-drafts/issues/3096 -->
+
+   <li><p>If <var>element</var>'s <code data-x="attr-style-type">type</code> attribute is present


Suggested change

<li><p>If <var>element</var>'s <code data-x="attr-style-type">type</code> attribute is present

<li><p>If <var>element</var>'s <code data-x="attr-style-type">type</code> attribute is not present

dandclark · 2025-10-02T22:10:25Z

source

+          https://github.com/w3c/csswg-drafts/issues/3096 -->
+
+   <li><p>If <var>element</var>'s <code data-x="attr-style-type">type</code> attribute is present
+   and its value is not an <span>ASCII case-insensitive</span> match for


Suggested change

and its value is not an <span>ASCII case-insensitive</span> match for

or its value is not an <span>ASCII case-insensitive</span> match for

dandclark · 2025-10-02T22:17:07Z

source

+   element's <span>child text content</span>, then return. <ref>CSP</ref></p></li>
+
+   <li><p>Let <var>styleDataURI</var> be the string "<code data-x="">data:text/css,</code>"
+   appended with the <span>child text content</span> of the <code>style</code>


We might want to do the urlencoding here rather than further down, to avoid the data:text/css part of the string getting encoded into something like data%3Atext%2Fcss.

dandclark · 2025-10-02T22:30:20Z

source

+      <var>styleDataURI</var>.</li>
+    </ol>
+   </li>
+   <li>Perform <span>parse an import map string</span> with <var>input</var> as the resulting JSON


This creates an import map but doesn't actually apply it. We still need to do some stuff to apply it to the document.
See https://html.spec.whatwg.org/#create-an-import-map-parse-result and https://html.spec.whatwg.org/#script-processing-model:create-an-import-map-parse-result, and https://html.spec.whatwg.org/#register-an-import-map

dandclark · 2025-10-02T23:00:28Z

source

+
+    <ol>
+      <li>A single key of "<code data-x="">imports</code>".</li>
+      <li>A single JSON value containing a <span>module specifier map</span> with a key consisting


It's a little unclear that this value is meant to go with the key "imports". Might be clearer to combine these steps: "A single key of "imports" whose value is a module specifier map with a key consisting of...".

dandclark · 2025-10-02T23:02:33Z

source

+    </ol>
+   </li>
+   <li>Perform <span>parse an import map string</span> with <var>input</var> as the resulting JSON
+    string from the prior step and <var>baseURL</var> as the <span>document base URL</span>.</li>


Instead of saying "the resulting JSON string" we probably need to reference an actual algorithm, i.e. the algo underlying JSON.stringify.

Actually, it could be overall clearer/easier to just construct the JSON string directly in the previous step rather than creating a JSON object, then converting it to a string.

dandclark · 2025-10-02T23:05:27Z

source

+      <dfn data-x="concept-documentorshadowroot-extensions-mixin"
+      data-x-href="https://www.w3.org/TR/cssom-1/#extensions-to-the-document-or-shadow-root-interface">Extensions to the <code>DocumentOrShadowRoot</code> Interface Mixin</dfn>:
+      <ul class="brief">
+       <li><dfn data-x="concept-documentorshadowroot-extensions-mixin-stylesheets" data-x-href="https://www.w3.org/TR/cssom-1/#dom-documentorshadowroot-stylesheets">styleSheets</dfn></li>


styleSheets isn't used here so I don't think you have to list that one.

dandclark · 2025-10-02T23:12:43Z

source

+  <hr>
+
+  <div algorithm>
+  <p>The <dfn>stylesheet adopting steps</dfn> for <code>template</code> elements are:</p>


Looks like the entry point to this algorithm still needs to be added somewhere.

dandclark · 2025-10-02T23:20:44Z

source

+      <var>adoptedStyleSheets</var>. If any error occurs, then <span>continue</span>.</p></li>
+    </ol>
+   </li>
+   <li><p><span data-x="set append">Append</span> <span>adoptedStyleSheets</span> to the


Should this be https://infra.spec.whatwg.org/#list-extend?

Initial commit

7f91f78

KurtCattiSchmidt requested a review from Copilot September 24, 2025 00:00

Copilot AI reviewed Sep 24, 2025

View reviewed changes

mhochk reviewed Sep 24, 2025

View reviewed changes

source Outdated Show resolved Hide resolved

source Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Show resolved Hide resolved

KurtCattiSchmidt added 2 commits September 24, 2025 14:39

Adding missing shadowrootadoptedstylesheets and other small fixes

b8c96ae

Addressing Hoch's feedback

4487b30

KurtCattiSchmidt requested a review from Copilot September 24, 2025 21:54

Copilot AI reviewed Sep 24, 2025

View reviewed changes

Fixing order and removing duplicate shadowrootadoptedstylesheets

fde2e28

KurtCattiSchmidt mentioned this pull request Sep 24, 2025

Upcoming WHATNOT meeting on 2025-09-25 #11696

Closed

KurtCattiSchmidt added 5 commits September 25, 2025 16:21

Fixing shadowrootadoptedstylesheets to definition to not include clon…

141c474

…able

Wrapping algorithm per new requirements

c174820

Fixing formatting

477caa7

Merge branch 'main' into css-modules-firstpr

582566e

Fixing <li> conformance error

ccac8fe

KurtCattiSchmidt requested review from domenic and dandclark September 26, 2025 23:35

KurtCattiSchmidt added 3 commits September 29, 2025 11:46

Simplifying stylesheet adopting steps

746cdad

Making stylesheet adopting steps append instead of set

ca450c7

Fixing typo

d8cae13

KurtCattiSchmidt requested a review from smaug---- September 30, 2025 16:42

KurtCattiSchmidt mentioned this pull request Sep 30, 2025

Declarative CSS Modules and Declarative Shadow DOM adoptedstylesheets attribute #10673

Open

KurtCattiSchmidt removed the request for review from domenic September 30, 2025 16:51

dandclark reviewed Oct 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Declarative CSS Modules #11687

Declarative CSS Modules #11687

KurtCattiSchmidt commented Sep 24, 2025 •

edited by pr-preview bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

dandclark left a comment

Uh oh!

dandclark Oct 2, 2025

Uh oh!

dandclark Oct 2, 2025

Uh oh!

dandclark Oct 2, 2025

Uh oh!

dandclark Oct 2, 2025

Uh oh!

dandclark Oct 2, 2025

Uh oh!

dandclark Oct 2, 2025

Uh oh!

dandclark Oct 2, 2025

Uh oh!

dandclark Oct 2, 2025

Uh oh!

dandclark Oct 2, 2025

Uh oh!

Uh oh!

	<li><p>If <var>element</var>'s <code data-x="attr-style-type">type</code> attribute is present
	<li><p>If <var>element</var>'s <code data-x="attr-style-type">type</code> attribute is not present

	and its value is not an <span>ASCII case-insensitive</span> match for
	or its value is not an <span>ASCII case-insensitive</span> match for

Declarative CSS Modules #11687

Are you sure you want to change the base?

Declarative CSS Modules #11687

Conversation

KurtCattiSchmidt commented Sep 24, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

dandclark left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

KurtCattiSchmidt commented Sep 24, 2025 •

edited by pr-preview bot

Loading