Add color_scheme_dark member and themeable members (colors only)

[christianliebel]

Closes #975

This change (choose at least one, delete ones that don't apply):

• Adds new normative requirements

Implementation commitment (delete if not making normative changes):

• WebKit (https://bugs.webkit.org)
• Chromium (https://bugs.chromium.org/)
• Gecko (http://bugzilla.mozilla.org)

If change is normative, and it adds or changes a member:

• updated JSON schema

Commit message:

Add color_scheme_dark member and themeable members

Person merging, please make sure that commits are squashed with one of the following as a commit message prefix:

• chore:
• editorial:
• BREAKING CHANGE:
• And use none if it's a normative change

---

Preview | Diff

[Copilot]

Pull request overview

Adds a manifest-level mechanism to specify dark-mode overrides for color-related members, addressing the need to provide different theme/background colors for light vs. dark color schemes (Issue #975).

Changes:

• Marks theme_color and background_color as “themeable members”.
• Introduces a new color_scheme_dark manifest member (ordered map) to hold dark-theme overrides.
• Adds a processing algorithm for color_scheme_dark and hooks it into the manifest processing steps.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

"theme overrides" is introduced here but not defined elsewhere in the document. Consider either defining what a "theme override" is (including its value type) or rephrasing to state that the values are the same types as the corresponding members (e.g., color strings) and are processed with the existing color-member processing algorithm.

Suggested change

	values are their corresponding theme overrides.
	values are their corresponding <dfn>theme overrides</dfn>. A theme
	override is a value of the same type as its corresponding
	[=themeable member=] (for example, a color string for a color
	member) and is processed using that member's existing processing
	algorithm.

[dmurph]

If we do this, we could avoid having the algorithm below. But - I'm generally a fan of algorithms in spec.....

One idea without the algorithm, we can:

• When we define a 'themeable member', we can say the member may be changed based the color theme of the operating system.
• We define "color_scheme_dark" as a "theme"
• When parsing a 'theme', kind of like *_Localized, we apply these values on top of the manifest json if that theme is being used. This makes it so we don't have to define parsing of the fields.

What do you think?

[dmurph]

I think the current version should 'work' - but interested in your thoughts on alternative design here.
Sorry for review delay - was trying to think about the alternative way here.

If you prefer this way, then we can keep it. Happy to hear others thoughts though

[dmurph]

If we do this, we could avoid having the algorithm below. But - I'm generally a fan of algorithms in spec.....

One idea without the algorithm, we can:

• When we define a 'themeable member', we can say the member may be changed based the color theme of the operating system.
• We define "color_scheme_dark" as a "theme"
• When parsing a 'theme', kind of like *_Localized, we apply these values on top of the manifest json if that theme is being used. This makes it so we don't have to define parsing of the fields.

What do you think?

[marcoscaceres]

Hi @christianliebel and @dmurph — I've pushed a few commits on top of yours addressing the review comments. Here's a summary of what changed:

Spec design changes:

• themeable member is now defined by enumeration (theme_color and background_color in a <ul>) rather than the circular "is a manifest member that can be themed". The <ul> makes it easy to add new themeable members in the future.
• The processing algorithm now loops over the fixed set of themeable members (« "theme_color", "background_color" ») rather than hardcoding two separate steps. This addresses both @dmurph's suggestion and the prose/algorithm inconsistency @Copilot flagged.
• The "is a themeable member" classification is now inlined into the theme_color and background_color member definitions rather than sitting in standalone paragraphs.
• Added normative applying text: when the OS uses a dark color theme, the user agent SHOULD use the color_scheme_dark values in place of the base themeable member values, unless user preferences (e.g. accessibility settings) take precedence. This also covers the dark-only case implicitly — if a base member is absent, the dark override is still used in dark mode.
• Replaced "dark mode" throughout with "dark color theme" / "operating system's color theme preference", consistent with how CSS MQ Level 5 describes prefers-color-scheme.
• Removed the historical justification note — the design stands on its own.

xref/markup fixes:

• themeable member dfn scoped to manifest/ with data-dfn-for="manifest"; all link sites updated to [=manifest/themeable member=]
• Removed undefined "theme overrides" term from prose

On @dmurph's *_localized suggestion: the loop-over-fixed-set approach achieves the same goal (no hardcoding, generic application) without restructuring the algorithm more radically. Happy to discuss if you had something different in mind.

Let me know if anything looks off.

[christianliebel]

Thanks @marcoscaceres, LGTM!