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

source

mhochk

LGTM (No permissions to actually Approve)

dandclark

This is coming together nicely. I think the biggest thing still to figure out is to prevent a given <style type=module> from being processed twice. I'm about to head out on leave so I'm going to Approve this since I'm supportive of the direction and I trust that the remaining open issues will be handled appropriately.

dandclark · 2025-10-07T23:21:46Z

source

+  <ol>
+   <li><p>Let <var>element</var> be the <code>style</code> element.</p></li>
+
+   <li><p>If <var>element</var> is not <span>connected</span>, then return.</p></li>


I guess this is also the point where we'd also check a new equivalent of the already started flag to ensure a given <style type=module> only ever gets processed once?

Yeah I'll have to think about this a little more. I will likely bring this up soon with the WHATWG.

source

dandclark · 2025-10-07T23:27:51Z

source

+   of the value of the <span data-x="attr-style-specifier">specifier attribute</span> and a value of
+   <var>styleDataURI</var>.</p></li>
+
+   <li><p><span>Create an import map parse result</span> with <var>input</var> as <var>jsonString</var>


Create an import map parse result can throw -- do we need to handle any of those cases? The one I particularly had in mind to watch for is does it throw when a given specifier is invalid? If not, do we need to handle an invalid specifier some other way?

Good question. For now I added a step to look at the importMapParseResult's error to rethrow and to continue if that happens. In practice, we probably want to log something in the console, but this might be enough for the spec.

source

zcorpan · 2025-10-09T16:57:52Z

You can include "Fixes #10673" in the OP so that there's a link from the issue in GitHub's UI. (Also should be in the commit message when squashing.)

KurtCattiSchmidt · 2025-10-09T23:43:01Z

@annevk - I believe the last two commits addressed all of the issues you brought up this morning, so please take a look when you get a chance. And also let me know if I missed anything else you mentioned today.

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

KurtCattiSchmidt added 2 commits October 6, 2025 13:40

Addressing Dan's feedback

11fcb56

Minor style fixes

9e2f7ee

KurtCattiSchmidt requested review from dandclark and mhochk October 6, 2025 21:16

mhochk reviewed Oct 6, 2025

View reviewed changes

dandclark approved these changes Oct 8, 2025

View reviewed changes

Addressing Dan's second round of feedback

b2c6025

zcorpan reviewed Oct 9, 2025

View reviewed changes

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

KurtCattiSchmidt added 3 commits October 9, 2025 16:00

Updating external URL references to draft URL's

adf1484

Adding component percent-encode set per Anne's feedback

05edbed

Separating JSON string step into a JSON object + stringify

6cee43f

KurtCattiSchmidt requested a review from annevk October 9, 2025 23:41

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mhochk left a comment

Choose a reason for hiding this comment

Uh oh!

dandclark left a comment

Choose a reason for hiding this comment

Uh oh!

dandclark Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

KurtCattiSchmidt Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dandclark Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

KurtCattiSchmidt Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zcorpan commented Oct 9, 2025

Uh oh!

KurtCattiSchmidt commented Oct 9, 2025

Uh oh!

Uh oh!

KurtCattiSchmidt commented Sep 24, 2025 •

edited by pr-preview bot

Loading