Bug 2036647 Add use of CSS gradients to extension themes by rebloor · Pull Request #44551 · mdn/content

rebloor · 2026-06-22T18:02:15Z

Description

Addresses the dev-docs-needed requirements of Bug 2036647 "Allow extension themes to use CSS gradients" with:

update to the description of the theme manifest key
a release note

Related issues and pull requests

Related browser compatibility updates in PR mdn/browser-compat-data#29910.

github-actions · 2026-06-22T18:04:07Z

Preview URLs (2 pages)

Flaws (1)

Note! 1 document with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Mozilla/Firefox/Releases/153
Title: Firefox 153 release notes for developers (Beta)
Flaw count: 1

macros:
- Macro domxref produces link /en-US/docs/Web/API/RTCDtlsTransport/getRemoteCertificates which doesn't resolve

External URLs (2)

URL: /en-US/docs/Mozilla/Firefox/Releases/153
Title: Firefox 153 release notes for developers (Beta)

https://bugzil.la/1751346 (1 time) (Note! This may be a new URL 👀)
https://bugzil.la/2036647 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-07-10 18:05:51)

github-actions · 2026-06-23T00:15:46Z

This pull request has merge conflicts that must be resolved before it can be merged.

rpl

@rebloor looks pretty good to me, the following are just small nits and some parts to consider some small rewording for and a followup (for something related to themes and Firefox for Android that I happen to have noticed while reviewing this patch, but I'd leave larger changes for parts that we wouldn't be already changing in this pull request for a separate followup specifically related to cleaning up the theme page from old references to Firefox for Android static theme support).

rpl · 2026-06-30T19:17:20Z

+          <code>"contain"</code>, or explicit width and height values (for
+          example, <code>"100px 200px"</code>).
+        </p>
+        <p>If not specified, defaults to <code>"auto"</code>.</p>


question: should we mention explicitly what happens if the number of entries do not match the number of entries in the additional_backgrounds property? I assume we use the default, auto, in that case. If that feels like already implied we may not need to specify it but I thought to bring it up to double-check it with you.

@rpl According to Claude, we don't default to auto, rather "The implementation joins the size values as a comma-separated CSS background-size property value. That means standard CSS cycling behavior applies — if additional_backgrounds_size has fewer entries than additional_backgrounds, the size values cycle from the beginning of the array for the extra items. For example, with 3 backgrounds and "additional_backgrounds_size": ["auto", "100px"], the third item gets auto (cycling back to index 0)." Are you able to confirm? If so, it doesn't sound like the behavior that we would expect.

@rebloor I've looked a little deeper into this and confirmed which part of the w3c specs explicitly mention this behavior:

https://www.w3.org/TR/css-backgrounds-3/#layering

In this section named "2.1. Layering Multiple Background Images" the specs explicitly mention that:

Each of the background images is sized, positioned, and tiled according to the corresponding value in the other background properties. The lists are matched up from the first value: excess values at the end are not used. If a property doesn’t have enough comma-separated values to match the number of layers, the UA must calculate its used value by repeating the list of values until there are enough.

And so:

the extra background layer (corresponding to extra entries in additional_backgrounds compared to additional_backgrounds_size / additional_backgrounds_alignment / additional_backgrounds_tiling) cycles back to index 0 of the size list (and the ones that may be following it will be matched with the other indexes available and then cycling back to index 0 if necessary)

extra values in additional_backgrounds_size / additional_backgrounds_alignment / additional_backgrounds_tiling are going to be ignored

if additional_background_size is completely omitted then every background image layer would be expected to default to auto (based on https://www.w3.org/TR/css-backgrounds-3/#background-size)

@rpl Also confirmed this while testing the additional background items. I'll update the docs before Monday.

rpl · 2026-06-30T19:20:06Z

+        <p><code>Array</code> of <code>String</code></p>
+      </td>
+      <td>
+        <p>Optional</p>


Nit: the other entry seems to have a period at the end of the Optional string, let's consider to add it here too for consistency (technically also on the properties description in the first table of the section https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme#syntax too).

The more consistent approach across the entire web extensions documentation set is to not have the period. So I've removed them here.

Thanks, sounds great to me, I'm also all for keeping consistency (thanks for double-checking what was the most common convention to match).

…/github.com/rebloor/content into Bug-2036647-CSS-gradients-in-extension-themes

rebloor

Incoming with the next commit

rebloor · 2026-07-02T18:41:31Z

+        <p><code>Array</code> of <code>String</code></p>
+      </td>
+      <td>
+        <p>Optional</p>


The more consistent approach across the entire web extensions documentation set is to not have the period. So I've removed them here.

rebloor · 2026-07-02T18:53:23Z

+          <code>"contain"</code>, or explicit width and height values (for
+          example, <code>"100px 200px"</code>).
+        </p>
+        <p>If not specified, defaults to <code>"auto"</code>.</p>


@rpl According to Claude, we don't default to auto, rather "The implementation joins the size values as a comma-separated CSS background-size property value. That means standard CSS cycling behavior applies — if additional_backgrounds_size has fewer entries than additional_backgrounds, the size values cycle from the beginning of the array for the extra items. For example, with 3 backgrounds and "additional_backgrounds_size": ["auto", "100px"], the third item gets auto (cycling back to index 0)." Are you able to confirm? If so, it doesn't sound like the behavior that we would expect.

rpl

@rebloor the updates looks good to me, in the review comments below there are a couple more details (related to theme_frame not being an array), besides that the only other remaining item is to describe correctly the behavior to expect when the additional_backgrounds and additional_backgrounds_size/additonal_backgrounds_tiling/additonal_backgrounds_alignment arrays length mismatch (which is confirmed based on what the w3d specs are explicitly mentioning, I've added some notes about where those behaviors are mentioned in the specs in this github comment #44551 (comment)), thanks for bringing that up!

rpl · 2026-07-08T10:55:14Z

-          in the array on top, the last image in the array at the bottom.
+          An array of additional background items, each being either the path to an image asset packaged in the extension or <a href="#css_gradient_syntax">CSS gradient</a>, to be added to
+          the header area and displayed behind the
+          <code>"theme_frame":</code> items. These items layer the first item in


Nit: items -> item (give that theme_frame can only provide one, unlike additonal_backgrounds which is expected to be an array0

Suggested change

<code>"theme_frame":</code> items. These items layer the first item in

<code>"theme_frame":</code> item. These items layer the first item in

rpl · 2026-07-08T11:03:28Z

+          <code>"theme_frame":</code> items. These items layer the first item in
+          the array on top and the last item at the bottom. CSS gradients are
+          supported from Firefox 153.


Given that theme_frame isn't an array but a single path to the packaged image asset or a single gradient, I feel like the "These items layer the first item in the array on top and the last item at the bottom" may actually belong to the additional_backgrounds property instead (given that one is expected to be an array).

If I'm not mistaken theme_frame is layered on top of whatever the theme would be listing in additional_backgrounds, @rebloor would you mind to give that a try and then adjust the theme_frame description to mention the actual expected behavior when both additional_backgrounds and theme_frame are specified in a static theme?

@rpl amended this to clarify that "these additional background items" behave as documented (and I tested to confirm). I've also included a note that if you set theme_frame to a CSS gradient, it hides the additional background items.

rpl · 2026-07-08T11:06:43Z

+        <p><code>Array</code> of <code>String</code></p>
+      </td>
+      <td>
+        <p>Optional</p>


Thanks, sounds great to me, I'm also all for keeping consistency (thanks for double-checking what was the most common convention to match).

Bug 2036647 Add use of CSS gradients to extension themes

198600e

rebloor requested review from bacharakis and rpl June 22, 2026 18:02

rebloor self-assigned this Jun 22, 2026

rebloor requested review from a team as code owners June 22, 2026 18:02

rebloor added the Content:WebExt WebExtensions docs label Jun 22, 2026

rebloor requested review from dipikabh and removed request for a team June 22, 2026 18:02

github-actions Bot added Content:Firefox Content in the Mozilla/Firefox subtree size/m [PR only] 51-500 LoC changed labels Jun 22, 2026

Update redirect link

3a42ece

github-actions Bot added the merge conflicts 🚧 [PR only] label Jun 23, 2026

rebloor mentioned this pull request Jun 23, 2026

Bug 2036647 support for CSS gradients in additional_backgrounds and theme_frame mdn/browser-compat-data#29910

Merged

rebloor added 2 commits June 24, 2026 04:37

Added theme_frame support details

b419067

Merge branch 'main' into Bug-2036647-CSS-gradients-in-extension-themes

76716b1

github-actions Bot removed the merge conflicts 🚧 [PR only] label Jun 29, 2026

rpl requested changes Jun 30, 2026

View reviewed changes

Merge branch 'Bug-2036647-CSS-gradients-in-extension-themes' of ssh:/…

e75355c

…/github.com/rebloor/content into Bug-2036647-CSS-gradients-in-extension-themes

rebloor commented Jul 2, 2026

View reviewed changes

Updates for feedback

330f60b

rebloor requested a review from rpl July 2, 2026 19:06

rpl requested changes Jul 8, 2026

View reviewed changes

additional background items clarifications

25ff405

rebloor requested a review from rpl July 10, 2026 18:05

	<code>"theme_frame":</code> items. These items layer the first item in
	<code>"theme_frame":</code> item. These items layer the first item in

Uh oh!

Conversation

rebloor commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issues and pull requests

Uh oh!

github-actions Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

rpl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

rebloor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rpl 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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rebloor commented Jun 22, 2026 •

edited

Loading

github-actions Bot commented Jun 22, 2026 •

edited

Loading