Skip to content

#3 Yaru theme suite workflow and guidelines

Jump to bottom
Frederik Feichtmeier edited this page Oct 6, 2020 · 9 revisions

Upstream GNOME Desktop themes

The Yaru GTK themes are based on the upstream Adwaita Gtk theme and the Yaru GNOME Shell is theme based on the upstream GNOME shell theme. Those two upstream themes are not static and change over time because they belong to the gnome toolkit and the gnome shell, which's code also developes over time - so it is really important for a distribution that runs the GNOME desktop to keep the themes and the toolkit totally synced.

The upstream Gtk theme

The current upstream Gtk Theme consists of the following SCSS source files, which are then linked together and converted to regular gtk.css light theme and a gtk-dark.css dark theme:

  • _colors.scss contains all global color variables, for example the background colors, the foreground colors, the accent colors
  • _drawing.scss contains all SCSS functions and mixins which are used for widgets that need to be styled very often in different hierarchies but always looking the same
  • _common.scss is the biggest file and it contains global metric variables but most importantly the styling for all widgets in gtk including deep hierarchies and special cases, most of the time it uses the mixins and functions from _drawing.scss

The upstream GNOME Shell theme

The current upstream gnome-shell theme consists of _colors.scs which includes the upstream palette and all global colours for the theme, _common.scss which contains either the styling of widgets or links to a different file in ./widgets, _drawing.scss which contains the mixins and a lot of widget SCSS files in the widgets subdirectory.

Auto-updates of upstream changes - How to process them without removing our colors and differences

  1. Latest changes in the upstream themes are tracked via GitHub Actions which create pull requests when upstream has new changes, to merge them into the dedicated upstream directories for gtk and gnome-shell.

  2. Because we have small differences from upstream we can not just copy paste the changes into the gtk and gnome-shell directories. Thus we need to create separate branches based on the branches GitHub action uses: upstream-gtk-update for an update to our Gtk theme and upstream-gnome-shell-update for an update to our gnome shell theme.

  3. For an update to the gtk theme we then copy the _common.scss file from the gtk upstream directory into our gtk src directory.

  4. Now we need to keep the changes which are marked with a "Yaru change: ..." comment and accept all other changes from upstream.

  5. Do NOT change our _colors.scss file at all

  6. For an update to our gnome shell theme we need to copy all SCSS files from gnome-shell/upstream/gnome-shell-sass into gnome-shell/src/gnome-shell-sass. Accept all changes from upstream, but keep all changes that are marked with a "Yaru change: ..." comment.

Guidelines for further Gtk Theme changes

There are certain details which we change in Yaru because we either found a styling mistake in the upstream code or because we simply disagree on a styling from upstream.

Current differences in the Yaru Gtk theme from upstream(slimmer, more contrast, more origami):

  • we use the "compact" mode usable in the upstream _common.scss file which shrinks buttons, entries and the headerbar a little bit
  • we removed the gradients, text shadow and the top highlights from _drawing.scss for buttons, check/radios and the headerbar
  • we use another SCSS file (_headbar.scss) for a special color variant of the theme which uses light backgrounds and dark text except for the headerbar where a dark background and light text is used - currently it is not possible to make this happen with the upstream theme

All of the changes are made with the least possible "diff" from upstream and responsibility in mind:

  • Do not overwrite Gtk App developers styling classes - i.e. if the app developer wants to use the .flat style class, do not make it look like a regular button and vice versa
  • Do not change the hierarchy of elements as this might cause ugly bugs
  • Basically: do not change anything except the basic colors

Here are three basic rules to achieve this:

  1. Do not touch _common.scss after we merged upstream changes into our code except the rounding and sizing metrics at the top (we are slimmer and less round)
  2. Try to avoid changes to _drawing.scss - if not really necessary just do not change it at all, because it can affect dozens of places in _common.scss, currently we are different from upstream in about 15 lines
  3. Play with the following colors in _color.scss as the rest of the colors descents from those accordingly:
$base_color
$text_color
$bg_color
$fg_color

$selected_fg_color
$selected_bg_color

For widgets like suggested action buttons, switches, sliders and the headerbar we can also control the colors:

//special cased widget colors
$suggested_bg_color
$suggested_border_color
$progress_bg_color
$progress_border_color
$checkradio_bg_color
$checkradio_fg_color
$switch_bg_color
$switch_border_color
$focus_border_color
// Headerbar bg colors for the "mixed" theme
$headerbar_bg_color
$headerbar_fg_color

The upstream theme is so "smart" that it changes the whole theme according to the 4 colors at the top. This is a big benefit of using the upstream theme.

Clone this wiki locally