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 other styling classes, _drawing.scss which contains the mixins and a lot of widget SCSS files in the widgets subdirectory.

How to digest upstream changes to the themes but keep Yaru changes

  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 all scss files 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, except when upstream uses a new variable here
  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:

  • we use a _palette.scss file which includes the current yaru palette - variables defined here are then used in _colors.scss
  • we removed the gradients for buttons and the headerbar and text shadows everywhere
  • we use a slightly different shadow for buttons
  • we increased the contrast of buttons by lightening them up by about 4%
  • we use a $focus_border_color for the outline/focus ring everywhere - upstream has this in Gtk4 but is currently not sure to merge this back into the gtk3-24 branch
  • we use another SCSS file _headbar.scss for the current default theme (light window + dark headerbar) - currently it is not possible to make this happen with the upstream theme files alone
  • we use _apps.scss for all app specific changes, because gtk apps sometimes apply styling only if the global theme is Adwaita
  • we use _tweaks.scss for all changes on top of upstream, so if something goes wrong, we know where our changes are, and where the upstream changes are

Important: 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 bugs

Here are three recommendations to achieve this for the Gtk theme:

  1. Do not touch _common.scss after we merged upstream changes into our code except the smaller border-radius.
  2. Try to avoid changes to _drawing.scss after we merged upstream changes into it
  3. If we want to diverge from upstream, either because our palette (orange ;)) does not work in a certain place, or we disagree heavily with a design, we put this into _tweaks.scss
Clone this wiki locally