fix(w3c/style): put the dark stylesheet last on export so the theme toggle works by marcoscaceres · Pull Request #5436 · speced/respec

marcoscaceres · 2026-08-27T07:59:48Z

Refs #5200, and fixes a regression from #5408. On an exported spec that never opted into dark mode the theme toggle did nothing: styleMover was subscribed for the maturity stylesheet unconditionally but for dark.css only when the spec had opted in, so on save the maturity sheet moved past it and won the cascade. The dark sheet now moves for every spec, and its disabled and media state is restored on export, so a document saved while the reader had dark selected no longer ships a permanently dark spec.

Two existing tests asserted the old order and were rewritten.

This makes dark mode reachable where it previously did nothing, which exposes that several of ReSpec's own stylesheets are not dark-ready yet. Those are separate PRs and no release should go out before they land.

Written with AI: this change was generated by Claude. Per AI_POLICY.md.

Proof: the same source exported with the base build and with this branch. Without the fix dark.css lands before W3C-ED and enabling it changes nothing; with the fix it lands last and the toggle works. Marcos then confirmed it manually on exported specs: #5436 (comment)

Copilot

Pull request overview

Fixes exported-document stylesheet ordering in the W3C profile so the TR theme toggle (from W3C fixup.js) actually switches to dark mode by ensuring the dark stylesheet ends up last in <head> on export.

Changes:

Always register the export-time styleMover for dark.css, not only when the spec opts into dark mode.
Update integration/exporter tests to assert the corrected stylesheet order on export.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
`src/w3c/style.js`	Always moves `dark.css` to the end of `<head>` during export so it wins the cascade when enabled.
`tests/spec/w3c/style-spec.js`	Updates W3C style export assertions to expect dark stylesheet last.
`tests/spec/core/exporter-spec.js`	Updates exporter test to expect `dark.css` after the maturity-level W3C stylesheet.

Suppressed comments (1)

src/w3c/style.js:145

The comment mentions that the earlier mover puts base.css at the end of head on export, but the mover above actually targets finalStyleURL (the maturity-level stylesheet, which is often W3C-*, not base.css). Updating the wording would avoid misleading future readers about what is being reordered.

  );
  // Make sure the W3C stylesheet is the last stylesheet, as required by W3C Pub Rules.
  sub("beforesave", styleMover(finalStyleURL));

  // Add color scheme meta tag and style

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot · 2026-08-27T09:16:47Z

One or more custom setup steps configured for this repository failed during this Copilot code review run:

Run {

Setup steps run before each review. If the review above is missing context, or no review was posted at all, the failing step above may be the cause. See the workflow run for failure details, fix your setup steps configuration, and re-request a review.

Note

You can configure setup steps for Copilot code review separately from Copilot cloud agent with a copilot-code-review.yml file. Read the docs for details.

Copilot

Pull request overview

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

Copilot · 2026-08-27T09:23:51Z

One or more custom setup steps configured for this repository failed during this Copilot code review run:

Run {

Setup steps run before each review. If the review above is missing context, or no review was posted at all, the failing step above may be the cause. See the workflow run for failure details, fix your setup steps configuration, and re-request a review.

Note

You can configure setup steps for Copilot code review separately from Copilot cloud agent with a copilot-code-review.yml file. Read the docs for details.

marcoscaceres · 2026-08-27T09:24:16Z

Confirmed manually locally that this works as expected on exported specs.

deniak · 2026-08-27T11:19:17Z

@marcoscaceres I understand that PR addresses the issue where the dark mode isn't working as expected of exported documents such as https://w3c.github.io/wcag/guidelines/.

That said, there seems to be a problem with the respec source documents. I tried that PR with the guidelines source document (see https://nix.w3.org/~denis/respec/guidelines/) and while it's working fine on firefox, chrome 151 renders the spec sometimes in light mode and some other times in dark mode (I have the toggle set to auto). There may be some kind of race condition...

marcoscaceres · 2026-08-27T13:37:06Z

Yep, that’s being addressed an a follow up. Coming in after this PR.

kfranqueiro · 2026-08-27T20:21:01Z

I observe the same issue as Denis, specifically when ReSpec is run client-side (not when viewing an already-processed document). Amusingly, it is somehow always wrong:

When my stored setting is dark or auto (with my system set to dark), it always initially shows light mode
When my stored setting is light mode, it always shows dark mode.

Yep, that’s being addressed an a follow up. Coming in after this PR.

Does that branch exist yet so we can get an idea of its complexity? Otherwise it doesn't seem to make much sense to approve this PR that is visibly broken...

Moreover, how many more upcoming PRs will there be? And why are we addressing a regression caused by a PR that did not fix anything by adding more complexity (and maybe more regressions), rather than by reverting the one PR in question?

This makes dark mode reachable where it previously did nothing, which exposes that several of ReSpec's own stylesheets are not dark-ready yet. Those are separate PRs and no release should go out before they land.

By this logic, 37.3.3+ should not have released with #5408 to begin with. It is also unclear to me, did these issues not already exist in earlier versions when opted into dark mode?

So far, 11 documents have been published to w3.org/TR/ since Monday that exhibit the broken theme toggle (out of 32 total). That number will only increase until it is resolved. This is why I immediately advocated for reverting #5408, which could have limited the number of affected publications to 1 or 2.

There is also still the core issue of #5408 having spontaneously changed default behavior in a patch release, and #5437 plans to move further in that direction. A change this major should only happen after all of the following:

dark mode styles have been fully vetted, including for accessible color contrast
advance notice is given to spec editors to adjust custom styles accordingly
- Although if we give editors this chance, they might as well opt in by themselves via the meta tag to begin with in order to test the styles, which would seemingly obviate any need for these changes?
docs are updated (currently, respec.org still documents dark mode support as opt-in via meta tag)

marcoscaceres · 2026-09-01T08:24:45Z

@deniak @kfranqueiro The race is real, it reproduces on main, and it is not caused by
this PR. The fix is #5439: it sets disabled on the dark stylesheet link before inserting
the link, rather than assigning the property on the statement after. A write that lands
mid-fetch leaves Chrome applying the sheet anyway and then dropping it on the next write,
so the theme you get depends on whether dark.css has arrived. Firefox always has it in
time, which is why it looked Chrome-only. Kenneth, on complexity: the change in
style.js is three lines in and six out, and the rest of that PR is the regression test.

On whether the dark styles were already broken before #5408: you are right, they were.
The dark media queries in var.css.js, algorithms.css.js and cddl.css.js predate it,
so any spec that opted in through the meta tag has had them all along. #5408 did not
create those defects, it made them reachable for everyone. That cuts both ways: it is an
argument for fixing them, and it also means reverting #5408 would not fix them for the
specs that already opted in.

The docs point is correct and unfixed too: respec.org still documents dark mode as
opt-in via the meta tag.

On reverting #5408: I would rather fix these. A revert does stop the race, by taking the
link back out again, but it also restores #5200, where the toggle silently never appears
on a light-only spec. And it does nothing for the documents already published: those are
static, so they need republishing either way. That leaves the revert case resting on
limiting future publications, which #5436 and #5439 do as well, without giving up the
toggle.

Your three preconditions are reasonable and I am not going to pretend they were met. The
styles are not fully vetted, editors got no notice, and the docs are stale. I would rather
work through them than revert: the docs I can fix now, the component styles need their own
PR, and #5437 waits until both are done.

deniak · 2026-09-01T11:35:42Z

@deniak @kfranqueiro The race is real, it reproduces on main, and it is not caused by this PR. The fix is #5439: it sets disabled on the dark stylesheet link before inserting the link, rather than assigning the property on the statement after. A write that lands mid-fetch leaves Chrome applying the sheet anyway and then dropping it on the next write, so the theme you get depends on whether dark.css has arrived. Firefox always has it in time, which is why it looked Chrome-only. Kenneth, on complexity: the change in style.js is three lines in and six out, and the rest of that PR is the regression test.

On whether the dark styles were already broken before #5408: you are right, they were. The dark media queries in var.css.js, algorithms.css.js and cddl.css.js predate it, so any spec that opted in through the meta tag has had them all along. #5408 did not create those defects, it made them reachable for everyone. That cuts both ways: it is an argument for fixing them, and it also means reverting #5408 would not fix them for the specs that already opted in.

The docs point is correct and unfixed too: respec.org still documents dark mode as opt-in via the meta tag.

On reverting #5408: I would rather fix these. A revert does stop the race, by taking the link back out again, but it also restores #5200, where the toggle silently never appears on a light-only spec. And it does nothing for the documents already published: those are static, so they need republishing either way. That leaves the revert case resting on limiting future publications, which #5436 and #5439 do as well, without giving up the toggle.

@kfranqueiro and I have reviewed the PRs and confirm #5439 fixes the issue with chrome. Can you merge #5436 and #5439 so we don't end up with a conflict? It will also be easier to follow the changes if there's only one PR.

Your three preconditions are reasonable and I am not going to pretend they were met. The styles are not fully vetted, editors got no notice, and the docs are stale. I would rather work through them than revert: the docs I can fix now, the component styles need their own PR, and #5437 waits until both are done.

Thank you for addressing my request about allowing the editors to opt-in. I initially thinking it would be easier to keep the old behavior (which is adding the <meta name="color-scheme" content="light dark”> to enable dark mode). This way we wouldn't need to edit the current specs that are not compatible with dark mode.

I'm willing to contact the editors to see how they feel about enabling dark mode support for all specs and point them to #5437 that adds the new config property.
Enabling dark mode by default would be great and I should probably have pushed more fixing the specs that are compatible yet.

kfranqueiro · 2026-09-01T17:57:41Z

On reverting #5408: I would rather fix these. A revert does stop the race, by taking the link back out again, but it also restores #5200, where the toggle silently never appears on a light-only spec.

This statement does not accurately describe #5200. The document that it was reported against was already opted into dark mode using the meta tag, and the report was that the theme controls did render, but didn't work - which I could never reproduce, even when using the versions of ReSpec and matf that were current at the time of the report.

As far as I could tell, there was nothing for #5408 to fix, which is why I suggested reverting it instead of adding more. (I realize there may be other motivations for moving in that direction.)

marcoscaceres · 2026-09-01T19:50:35Z

Specref outage is also blocking us 😢 all the bots are sad.

…oggle works Co-Authored-By: Claude <noreply@anthropic.com>

fixup.js drives the link live and both disabled and media are reflected attributes, so a document saved while the reader had dark selected exported an enabled, unconditional dark sheet. Now that the sheet is last in head it would win, rendering dark for everyone. Co-Authored-By: Claude <noreply@anthropic.com>

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…xport

…comments

…heet comments

marcoscaceres requested a lite review from Copilot August 27, 2026 09:12

Copilot started reviewing on behalf of marcoscaceres August 27, 2026 09:13 View session

marcoscaceres marked this pull request as ready for review August 27, 2026 09:14

marcoscaceres requested a review from deniak August 27, 2026 09:16

Copilot AI reviewed Aug 27, 2026

View reviewed changes

Comment thread tests/spec/core/exporter-spec.js Outdated

marcoscaceres requested a balanced review from Copilot August 27, 2026 09:18

Copilot started reviewing on behalf of marcoscaceres August 27, 2026 09:19 View session

Copilot AI reviewed Aug 27, 2026

View reviewed changes

deniak requested a review from kfranqueiro August 27, 2026 11:19

marcoscaceres mentioned this pull request Aug 27, 2026

feat(w3c/style): let an editor turn dark mode off with darkMode: false #5437

Open

marcoscaceres mentioned this pull request Aug 28, 2026

fix(w3c/style): disable the dark stylesheet before inserting the link #5439

Merged

marcoscaceres added the AI Contains AI-generated logic; see AI_POLICY.md label Sep 2, 2026

marcoscaceres force-pushed the fix/dark-css-last branch from 198b427 to 3cf22c2 Compare September 2, 2026 11:58

marcoscaceres and others added 5 commits September 2, 2026 22:56

fix(w3c/style): put the dark stylesheet last on export so the theme t…

5b77cd4

…oggle works Co-Authored-By: Claude <noreply@anthropic.com>

Potential fix for pull request finding

8f03e44

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

refactor(w3c/style): read the dark mode intent from the meta tag on e…

cc9b515

…xport

docs(w3c/style): drop bare issue references from the dark stylesheet …

6c2dca8

…comments

marcoscaceres force-pushed the fix/dark-css-last branch from 3cf22c2 to 6c2dca8 Compare September 2, 2026 12:59

docs(w3c/style): correct the pub rules claim and trim the dark styles…

98f568e

…heet comments

marcoscaceres merged commit c062116 into main Sep 2, 2026
9 checks passed

marcoscaceres deleted the fix/dark-css-last branch September 2, 2026 13:58

Uh oh!

Uh oh!

Conversation

marcoscaceres commented Aug 27, 2026 • edited 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

Reviewed changes

Uh oh!

Uh oh!

Copilot AI commented Aug 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI commented Aug 27, 2026

Uh oh!

marcoscaceres commented Aug 27, 2026

Uh oh!

deniak commented Aug 27, 2026

Uh oh!

marcoscaceres commented Aug 27, 2026

Uh oh!

kfranqueiro commented Aug 27, 2026

Uh oh!

marcoscaceres commented Sep 1, 2026

Uh oh!

deniak commented Sep 1, 2026

Uh oh!

kfranqueiro commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marcoscaceres commented Sep 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

marcoscaceres commented Aug 27, 2026 •

edited

Loading

kfranqueiro commented Sep 1, 2026 •

edited

Loading