Changing the dark overlay background on the Activity- and Apps-overview screens, as well as behind dialog boxes (Gnome 3)

On Ubuntu 20.04.1 LTS

Gnome version according the Settings app's "About" tab: 3.36.8

gnome-shell --version
GNOME Shell 3.36.4

Theme: Yaru (the default; not the "light", not the "dark")

When I press the super key, or activate the hot corner, the "overview" screen comes up, where I can search for apps, settings, documents, and more:

Problem / Challenge:

I find this overlay too dark compared to how my desktop normally looks; each time I have to use it, I find it has an intrusive impact on the experience, and it's a tiring exercise for my eyes to adjust.

I would like to make this overlay somewhat lighter / brighter.

I have looked into the settings in org.gnome.shell.extensions.dash-to-dock with dconf-editor, but I have not found anything for it. (I have not enabled the "Ubuntu Dock" additional Gnome shell extension in Tweaks.)

Then I copied the Yaru theme from /usr/share/themes/ to ~/.themes/, and activated it with Gnome-Tweaks.

In ~/.themes/My-Yaru/gtk-3.20/ I have exported the true content of, and overwritten the file gtk.css with

gresource extract gtk.gresource /com/ubuntu/themes/Yaru/3.20/gtk.css > gtk.css

Now, instead of the original single line of import statement, it has 12637 lines of CSS in it.

I did try to identify the CSS selector of the dash overlay, but I have not found anything. Then I was looking for declarations of radial gradients (because this overlay seems to have a radial gradient on it), but what I have found seems unrelated to this overlay.

What can I do now? Am I on the right track at all?

If yes, how could I enable a Gnome debug mode that — comparably to web browsers' developer-tools — would interactively reveal the CSS selector of the this overlay?

If this is not the right direction, then how could I achieve the goal — preferably without having to install an entirely different theme?

Answer compat:

Ubuntu 20.04.1,
gnome-shell version: 3.36.4
display server: X.Org Server

The dark background with a radial gradient comes from gnome shell UI's lightbox.js.

https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/gnome-3-36/js/ui/lightbox.js

There seem to be 3 approaches:

• via parameters (?)
• via js code override, utilizing "gresource overlays"
• via css, through creating a custom gnome-shell theme

Via parameters supplied to gnome-shell UI's lightbox.js

I don't know much about this. I haven't found anything relevant in dconf-editor, plus two out of the three interesting parameters seemed to be hardcoded to me. So I went for the code.

Via overriding gnome-shell UI's lighbox.js code

Changing lighbox.js behavior impacts not only the Activity- and Apps-overview screens, but other dialogs too, such as: Run a Command, Authentication required, Power off, and more.

On Ubuntu 20.04, the file is normally packaged up inside /usr/lib/gnome-shell/libgnome-shell.so.

To override it, one needs to extract a copy of it, and ask Gnome to use this copy.

Create this directory structure, and cd there in a terminal:

~/.gnome-shell-custom-overlays/ui/

# You should be here:
~/.gnome-shell-custom-overlays/ui$

While in this directory, do the following:

# Make a copy of the resource:
cp /usr/lib/gnome-shell/libgnome-shell.so .

# To see all of its contents:
gresource list libgnome-shell.so

# To obtain lightbox.js:
gresource extract libgnome-shell.so /org/gnome/shell/ui/lightbox.js > lightbox.js

# If the extraction was successful, our copy of the resource can
# (probably should?) be removed.
rm libgnome-shell.so

Edit the lightbox.js file; change the three variables near the top, as follows:

// Old:
//var DEFAULT_FADE_FACTOR = 0.4;
//var VIGNETTE_BRIGHTNESS = 0.5;
//var VIGNETTE_SHARPNESS = 0.7;

// New:
var DEFAULT_FADE_FACTOR = 0.1;
var VIGNETTE_BRIGHTNESS = 0.8;
var VIGNETTE_SHARPNESS = 0.2;

Now we need to tell Gnome about our modified file. Put the following line into ~/.profile:

export G_RESOURCE_OVERLAYS="/org/gnome/shell=$HOME/.gnome-shell-custom-overlays"

The term "overlays" here doesn't refer to the lightbox overlay; rather, it suggests how this Gnome/GTK resource overriding feature works.

Important note: before I did all this, I already had the libgtk-3-dev package installed on my system. It's for development / debugging, just like the resource overlays feature seems to be so. Therefore right now I cannot determine whether respecting the G_RESOURCE_OVERLAYS environment variable depends on the presence of this package or not... Just in case be ready to install it...

Anyhow: for the changes to take effect, log out and log back in.

Further tweaking

To see the effect of further tweaks on the lightbox parameters, reloading the Gnome shell after each edit is necessary. It can be done by issuing the r command through the Run command dialog (revealed by Alt+F2).

Interesting: In my experience, when one saves the lightbox.js file with a syntax error within, the Run command dialog doesn't seem to appear any more. But it may be "there", just not "visible". In such case, proceed as if it was there: fix the syntax and save the file, hit Alt+F2, then r, then Enter.

Further important considerations regarding the resources overlay feature's potential impact on system stability are discussed in this answer.

References / literature:

• Credit to Superuser Q/A
• Gnome devs' reference
• Gnome cookbook on Arch wiki

Via CSS (gnome-shell custom theme)

If you managed to override lightbox.js, then this part can offer just a few more adjustments to polish the experience a bit further.

If you did not override lightbox.js however, then this part can offer an additional workaround with limited usefulness for the Activity- and Apps overview screens.

(Also, the following was my original answer to the problem, before I could put my hand on the javascript override above.)

Using custom Gnome shell themes

The Gnome Tweaks app, as well as a Gnome shell extension, "User Themes" (part of the gnome-shell-extensions package, available via apt install), are needed for this.

sudo apt install gnome-tweaks gnome-shell-extensions

Open the Tweaks app, and enable the "User Themes" extension on the "Extensions" tab.

Creating a custom Gnome shell theme

This part is not proven to be the best method; it's just that I found this way.

Create the following directory structure:

~/.themes/my-gnome-shell-theme/gnome-shell/

copy this file (the default Yaru theme's shell theme implementation):

/usr/share/gnome-shell/theme/Yaru/gnome-shell-theme.gresource

into this newly created directory, so you end up with this:

~/.themes/my-gnome-shell-theme/gnome-shell/gnome-shell-theme.gresource

Opening this directory in the terminal, gresource list gnome-shell-theme.gresource reveals the contents of this newly copied file.

A custom-made script can help extracting all the contents.

The script's contents could be something like this, or better (I'm not a bash scripting expert) (I already know that people don't like backticks any more):

#!/bin/bash

currentdir=$(pwd);

# For regular themes:
# gresource_name="gtk.gresource"
# For shell themes:
gresource_name="gnome-shell-theme.gresource"

for resource in `gresource list ${currentdir}/${gresource_name}`;
do
    echo $resource
    filename=`basename ${resource}`
    gresource extract $currentdir/$gresource_name $resource > $currentdir/$filename
done

Note: this custom script does not reproduce the directory structure prescribed within the .gresource file; instead, it places the files in the target (current) directory in a flat fashion. However, it prints the definition of each resource it encounters, complete with its originally intended/defined path. While it does not seem to be always necessary, in some cases (e.g. when broken icons or widget backgrounds are encountered) it might be worth considering to rearrange the files into a directory structure according to what the definitions suggest. Note, that I left the original .gresource file in the directory.

Alternative extractor script: more such scripts can be found by searching for the string "do gresource extract" either on this site or elsewhere on the internet.

Having run the extractor script, and then quickly securing a backup of the original file,

cp gnome-shell.css gnome-shell.css.bak

the extracted gnome-shell.css file is ready for editing.

gnome-shell developer tool

It's called Looking Glass. It can be activated by issuing the lg command through the Run command dialog (revealed by Alt+F2).

CSS tweaks

Below changes worked best for my drab desktop background color; but with some color tweaks it may be useful for any case.

CSS works in such ways that definitions made towards the end of a file can override definitions written earlier in the same file. That's why it's not necessary to scatter edits all over the file; just appending the right thing at the very end does the job. That's what I appended to gnome-shell.css:

/* Activity-Overview-related */

/* Covers up the dark lightbox overlay with a lighter semi-opaque tone.
   This may be needed only if lightbox.js is not overridden. */

/*
#overview {
    background-color: rgba(210,202,194,0.6);
}
*/

.search-section-content {
    /* This has text on it; for eligibility, keep it more opaque. */
    background-color: rgba(29, 29, 29, 0.5);
}
.workspace-thumbnails {
    /* Plain background area, may be pretty transparent. */
    background-color: rgba(29, 29, 29, 0.25);
}

/* A less harsh workspace-switcher popup. */

.workspace-switcher-container {
    background-color: rgba(100, 96, 92, 0.45);
    border-radius: 10px;
}
.ws-switcher-active-up,
.ws-switcher-active-down,
.ws-switcher-active-left,
.ws-switcher-active-right {
    background-color: rgba(215, 86, 41, 0.8);
    border: 1px solid #cc4414;
    border-radius: 5px;
    color: #ffffff; }

/* Misc. */

.switcher-list, .osd-window, .resize-popup {
    /* A bit softer Alt+Tab popup.
     * This has text on it; for eligibility, keep it more opaque. */
    background-color: rgba(100, 96, 92, 0.85);
}

Enabling the custom theme

In the Tweaks app's "Appearance" tab, in the "Themes" section, there's a field labeld "Shell". The new custom theme should be available in the select widget. Remember, for this widget to be active, the "User themes" Gnome shell extension needs to be enabled.

Making CSS modifications to take effect

Method 1: Issuing the r command through the Run command dialog (revealed by Alt+F2) reloads the shell; it should also pick up the new CSS changes.

Method 2: Switching back and forth between the default and custom shell themes seemed to go more smooth and graceful in comparison to Method 1. The theme-switching can be achieved on the Tweaks app's UI, or via gsettings on the cli, as follows:

# For resetting to default, the argument can apparently be either
# an empty string: '' or: default.
gsettings set org.gnome.shell.extensions.user-theme name ''

# The custom theme's name is the name of its directory in ~/.themes/
gsettings set org.gnome.shell.extensions.user-theme name my-gnome-shell-theme

Recovery from a messed up custom theme

If needed, it's possible to switch back to the default theme by executing the above gsettings set command in a virtual console (e.g. Ctrl+Alt+F3) (without the need to start a graphical session).