GTK, Adwaita, and Vendor Styles

Today at GUADEC we had the “Vendor Themes” BoF:

It was attended by several folks in the GNOME community, including those representing Purism, System76 Pop!_OS, Ubuntu Yaru, elementary, core app developers, and third-party app developers.

Notes from the BoF:

After the BoF, we decided to continue the discussion and find actionable items to move things forward to improve Adwaita itself, the situation for app developers, and the experience for downstream vendors that wish to ship a distinct visual style. We decided that continuing here on Discourse is a good plan to keep the discussion persistent and centralized.

We’ll update here after the impromptu extended session with notes and action items. :slight_smile:

One of the first items we discussed at this extended session was to use the term “Styles” versus themes, mostly to distinguish from the preconceived notions around themes.

Our plan is to use this thread on Discourse to keep the conversation and action items moving along.


As an example of the type of developer-oriented outreach, this is a similar blog post I’ve written for elementary:

We should strive to do the same sort of “high level” documentation/outreach work around app development for the GNOME platform, and honestly that work regarding stylesheet variables can/should be shared with elementary since I think we can aim to not duplicate the exported variables and everything.


Georges is going to document the longer-form action items from today, but from memory they were something like:

  1. Document the existing public colors in Adwaita more thoroughly, i.e. when and how applications are expected to use these variables.

  2. Ensure GNOME apps are using these public variables correctly, and report issues/file merge requests against apps that are hardcoding colors or using these exported variables incorrectly.

  3. Work towards adding the GNOME palette to Adwaita’s exported variables, keeping elementary, Pop!, and Yaru in mind.

We also talked about maybe @tbernard writing a more pie-in-the-sky post about cool new things we could work towards, like per-app accent colors, colored headerbars, etc. to help demonstrate that we’re moving forward towards cool new things together (and that this boring admin-y things are required starting points to move in that direction).


During this GUADEC, we discussed the current state of things, and where and how we want to move towards. Since touching the platform stylesheet is potentially risky, we will play safe and be very conscious and careful when changing anything.


The first goal, for now, is to introduce a color palette.


Color palettes are already part of platforms, but there is no structured way in GNOME to use them. Right now, one needs to hardcode their values in the CSS directly.

elementary OS has an interesting approach to solve this: their palette colors are exposed as CSS variables. We feel this is a good way to go forward.

In addition to that, the work required to introduce a color palette in the platform’s stylesheet will give us a better idea of how to proceed with different goals.


To achieve it, three steps were proposed.

Step 1: Document Adwaita

Adwaita already has a set of publicly defined variables. These are set in the _colors-public.scss file. These variables should be properly documented.


  1. Document the public variables of Adwaita
  2. Make sure these variables are used consistently within Adwaita
  3. Make CSS codes of GNOME Core Apps use these variables as appropriate
  4. Coordinate communication with third-parties

Step 2: Export More Variables

From the list of private Adwaita colors, some of them may need to be exported publicly.


  1. Review GNOME Core Apps and identify which colors may need to be exported
  2. Export and document these colors
  3. Coordinate communication with third-parties

Step 3: Color Palette

With the applications making proper use of CSS variables, it is now possible to introduce a color in the platform stylesheet.


  1. Introduce CSS variables with the platform’s palette colors
  2. Coordinate communication with third-parties

Gnome initiative for this point:


Baby steps –


Browsing through here, there’s some things I’m unclear about:

  • Is this referring to colour palettes as in branding colors (GNOME Color Palette, Material Palette), or is this referring to the overall colorscheme of an application (Qt color palettes)?
  • Are these colordefs/CSS variables intended to be one way (application reads them for their own styles) or two way (application/user changing them will result in the active style changing colors)?

Is this referring to colour palettes as in branding colors (GNOME Color Palette, Material Palette), or is this referring to the overall colorscheme of an application (Qt color palettes)?

I’m unfamiliar with Qt color palettes, but it’s more on the branding color side. For example in elementary OS we expose our platform/brand palette as CSS variables and apps can use that in any custom styling to ensure they match the rest of the platform without having to hardcode colors.

Are these colordefs/CSS variables intended to be one way (application reads them for their own styles) or two way (application/user changing them will result in the active style changing colors)?

Theoretically it can go both ways, but one-way to start. In elementary OS we have experimented with the user being able to set a system-wide accent color, for example, which overrides the default blue accent color. However, apps can set their own accent color which has the highest priority. We also let apps set a couple of brand-color variables to be used on the headerbar, which overrides the system stylesheet. An example:

branded headerbar

But to start I think we should view it as the system has a defined color palette and set of variables, and apps can read and use those variables in their apps.

1 Like

Qt/KDE color palettes define color by type, color, and state instead of by hue and value.

So, instead of Qt Green 500 and Qt Cyan A200 you have Window Background Normal and View Positive Text Disabled for instance.

Should a merge request be opened so it can be reviewed? Or do you have something else in mind before submitting it?

Hi, so I’m an user who recently migrated from a custom theme (Adapta) back to Adwaita after reading about the problems with the current way of theming and how custom themes might break apps in some cases.

I’m quite interested in how the Theme Engine efforts materialize, so I would like to help if my skills are up to it.

There are two points that I liked about Adapta and would like to see being considered in the Theme Engine discussion: Light theme with dark title bar and customizing padding.

I do think the Light Theme with Dark Title Bar option is significantly important: Android, for example, has a Material.Light theme, a Material.Dark theme and a Material.Light.DarkActionBar theme.
One of the most useful situations to use the Material.Light.DarkActionBar theme is so you can have a light app with a colorful action bar whose elements are white (instead of worrying about changing the color of the elements in case you used the pure Light theme). So, this kind of theme could be useful not only by itself but also as a basis for heavily-customized apps.

One other interesting feature of Android is how it had a unit for font size called “sp” which would change the size of the font on an app based on what was selected on the “Font Size” settings of the device. It would be nice to have something like that for padding, in case the usable screen space is important for users. Another option would be having such a thing as a “basic unit of padding” that could be scaled down or select like “I want 3 times the basic unit instead of 4”.

I will be following closely to see how this unfolds. Thanks for trying to make the theme experience better.


A slight misconception: this is not about a “theme engine”. This is about documenting, improving, and reviewing Adwaita’s CSS variables, and making GNOME applications conform to it.

Vendors being able to use that to change colors is simply a collateral effect.

That’s not a concern right now. GTK informal coding guidelines state that CSS should be used for painting, not for layout. Paddings and margins are exceptions, and they require scrutiny.

That kind of thing is generally possible in CSS, although right now there are some bugs. The text-related sizing unit in CSS is em, and changes with font size. In the future it could be possible to scale the UI based on the font size, although this will require changes in GTK to work properly and is thus out of scope for this project. However, I’d be interested to see what could be done with this in the future.

Having played with color in various apps over the past few months I think there’s a strong case from an app developer/designer PoV for better APIs to recolor certain parts of UI.

Some of the use cases I’ve encountered:

  • recoloring the “send” button in a chat app green instead of blue for SMS (Chatty)
  • red header bar for when you’re root in a terminal (KGX)
  • recoloring the entire app UI (background and foreground color) in a contrast checker (Contrast)

Making it easier (and less hacky) to do things like these for developers would be a big win :slight_smile:

1 Like

I have made Contrast and in order to change the various colors depending on the selected bg/fg colors we had to ship Adwaita & libsass in order to recompile the theme each time the user selects a new color. It’s very fast, but not optimal and a bunch of other apps that could use some colors in some cases would need to do the same thing :confused:

One of the issues we have encountered by shipping Adwaita, is even if we change some colors, some are not replaced automatically because they are somehow hardcoded on the SCSS and we had to patch them manually.

For now we have 4 apps that has a heavy coloring: Contrast, Epiphany (GNOME Web), King’s Cross and a WIP app by Zander.

From a developer POV, I would suggest having some colors exported when it makes sense that the user could override or just use on their new fancy widget if that color makes sense.

GNOME Web/Epiphany also defines its style in scss specifically because of this, and includes Adwaita parts from gtk. Though it’s not required at build time, people modifying style are expected to have gtk checked out at a certain dir and to regenerate css as part of their changes, which is far from optimal.

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.