Intent to Ship: CSS light-dark() with image values

[Chromestatus]

Contact emails

cg...@chromium.org, yio...@gmail.com

Specification

https://drafts.csswg.org/css-color-5/#light-dark

Summary

Extends the CSS light-dark() function to accept image values (url(), image-set(), none) in author stylesheets, allowing image properties like background-image, list-style-image, border-image-source, cursor, and content to automatically switch between images based on the user's preferred color scheme. Previously this was only allowed in UA stylesheets. This aligns with the CSS Color 5 spec and matches Firefox's existing implementation.

Blink component

Blink

Web Feature ID

light-dark

Motivation

Without this feature, web developers who want to switch images based on the user's color scheme preference must use @media (prefers-color-scheme) queries or maintain separate stylesheets for light and dark themes. This is verbose and error-prone, especially when the same element uses light-dark() for its color properties but must use a media query for its image properties. The light-dark() function already supports color values, making it the natural place for image values as well. Allowing url(), image-set(), and none inside light-dark() for properties like background-image, list-style-image, border-image-source, cursor, and content lets developers keep light/dark variants co-located and consistent with their color declarations. Firefox has already shipped this behavior. Aligning with the CSS Color 5 spec and Firefox removes an interoperability gap and reduces friction for developers building adaptive UIs.

Initial public proposal

No information provided

TAG review

No information provided

TAG review status

Not applicable

Goals for experimentation

None

Risks

Interoperability and Compatibility

No information provided

Gecko: Shipped/Shipping (https://bugzilla.mozilla.org/show_bug.cgi?id=2023569)

WebKit: No signal (https://github.com/WebKit/standards-positions/issues/658)

Web developers: No signals

Other signals:

WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

No information provided

Debuggability

No information provided

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

Yes

Is this feature fully tested by web-platform-tests?

Yes
https://wpt.fyi/results/css/css-color/light-dark-image-none.html https://wpt.fyi/results/css/css-color/light-dark-image-none-interpolation.html https://wpt.fyi/results/css/css-properties-values-api/register-property-syntax-parsing.html https://wpt.fyi/results/css/css-color/light-dark-image.html

Flag name on about://flags

No information provided

Finch feature name

CSSLightDarkImage

Rollout plan

Will ship enabled for all users

Requires code in //chrome?

False

Tracking bug

https://crbug.com/491829958

Estimated milestones

Shipping on desktop	150
Shipping on Android	150
Shipping on WebView	150
Shipping on iOS	150

Anticipated spec changes

Open questions about a feature may be a source of future web compat or interop issues. Please list open issues (e.g. links to known github issues in the project for the feature specification) whose resolution may introduce web compat/interop risk (e.g., changing to naming or structure of the API in a non-backward-compatible way).

No information provided

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5123253146353664?gate=6509279727190016

Links to previous Intent discussions

Intent to Prototype: https://groups.google.com/a/chromium.org/d/msgid/blink-dev/69bb9df7.050a0220.1a988.00b8.GAE%40google.com

This intent message was generated by Chrome Platform Status.

[Jason Leo]

NOTE: This feature depends on https://chromestatus.com/feature/5121011285622784 as it uses the `image(transparent)` when the result contains none. `light-dark(none, none)` for example.

[Dan Clark]

This will be really useful! LGTM1 pending my question on the other I2S confirming whether Gecko is shipping image()/none.

[Alex Russell]

LGTM2