Human Interface Guidelines, libadwaita 1.0 edition

After a lot of hard work, libadwaita 1.0 was released on the last day of 2021. If you haven’t already, check out Alexander’s announcement, which covers a lot of what’s in the new release.

When we rewrote the HIG back in May 2021, the new version expected and recommended libadwaita. However, libadwaita evolved between then and 1.0, so changes were needed to bring the HIG up to date.

Therefore, over the last two or three weeks, I’ve been working on updating the HIG to cover libadwaita 1.0. Hopefully this will mean that developers who are porting to GTK 4 and libadwaita have everything that they need in terms of design documentation but, if anything isn’t clear, do reach out using the usual GNOME design channels.

In the rest of this post, I’ll review what’s changed in the HIG, compared with the previous version.

What’s changed

There’s a bunch of new content in the latest HIG version, which reflects additional capabilities that are present in libadwaita 1.0. This includes material on:

There have also been updates to existing content: all screenshots have been updated to use the latest UI style from libadwaita, and the guidelines on UI styling have been updated, to reflect the flexibility that comes with libadwaita’s new stylesheet.

As you might expect, there have been some general improvements to the HIG, which are unrelated to libadwaita. The page on navigation has been improved, to make it more accessible. A page on selection mode has also been added (we used to have this documented, then dropped the documentation while the pattern was updated). There has also been a large number of small style and structure changes, which should make the HIG an easier read.

If you spot any issues, the HIG issue tracker is open, and you can send merge requests too!

Platform Design Goings On

The GNOME design team has recently been working on GNOME’s application development platform, and I thought that it might be interesting for people to hear about what we’ve been up to.

The following is an overview of our recent platform design activities, particularly libadwaita. It will give an idea of what is currently going into the GNOME platform from a UXD perspective, as well as some of things that people might expect from the platform in the future.

Some context

If you follow GNOME development, you’ll know that GTK 4 was released back in December 2020. You’ll also maybe know about libhandy, which can be used in conjunction with GTK 3 to add additional widgets and capabilities. And you might know that libadwaita is being worked on as the libhandy successor for GTK 4.

Adrien Plazas did a great post announcing libadwaita, and Alexander Mikhaylenko has been posting detailed updates. libadwaita still isn’t stable, but the hope is to have a stable 1.0 release in the not too distant future.

One of the central goals of libadwaita is to make it easy to make great apps, using the components and design practices that make up GNOME’s app design approach. Needless to say, the GNOME design team has been on board with this initiative from the start! It has also required quite a bit of work from us, both to document and systematise the design conventions we’ve been using, as well as to design missing platform pieces.

The first major step in this work was completed last development cycle, with the rewritten HIG. The new version is synchronized with GTK 4 and libadwaita, so its design advice is an accurate portrayal of what can be done with the emerging new version of the GNOME platform.

The updated HIG will be an important part of the application developer experience, and we are now focused on delivering the other key elements.

Ongoing work

The following describes some of the areas of platform design work that the design team are currently involved with, particularly in the run up to libadwaita 1.0. As such, it covers work that is unfinished and is in various states of flux.


One of the first things that people will notice about apps that are using GTK 4 and libadwaita is their look, which is noticeably different from GTK 3 apps.

Header bar buttons are generally plain icons without outline or background. Other buttons have a flat colour. The background colours of container widgets are lighter in light mode, and darker in dark mode. Many of these changes in appearance are driven by technical changes: libadwaita’s support for dark mode and recolouring has knock-on effects for how widgets can be styled.

However, the design team is also keen to use the opportunity of libadwaita 1.0 to update the style of GNOME apps. The last time GTK had a style update was for GNOME 3.32, back in March 2019, and it could be several years before we get another opportunity to make changes.

On top of that, we do feel that the current GTK 3 look could be improved when compared to what’s being done on other platforms.

We are actively testing the style changes that have been made so far, using both in mockups and actual apps, and there could be adjustments before libadwaita 1.0. We also have a few other relatively minor style changes planned.

Dark mode

The new dark style preference is probably the main “feature” to come out of libadwaita — see Alexander’s recent post about it, if you haven’t already.

A properly supported dark style isn’t just a simple switch between two alternate CSS stylesheets, and the design team is currently working through a list of work items to make it into an excellent experience. This includes adjusting application-specific styling to work in both light and dark styles, modifying any full-colour icons we use to have adequate contrast in both modes, and creating light and dark versions of the GNOME wallpapers.

We have also, obviously, been working on designs for how to expose the dark preference itself.

Patterns app

Another ongoing initiative is the design and development of Patterns. This is a demo app which is intended to accompany libadwaita and the HIG.

One explicit goal of Patterns is to demonstrate those design patterns which we recommend app developers as part of the HIG, as opposed to demonstrating every possible UI that the platform is technically capable of producing.

There is plenty of work yet to do on Patterns, so if you’d like to help out with this effort, just head over to its Gitlab project.

New about

There isn’t much scope to add new widgets prior to libadwaita 1.0, but there are a few which the design team is hoping to sneak in. One of these is an updated about window design. The goal is to have a simple, refined design, which works on a variety of form factors.

Looking to the future

In addition to supporting development work that is currently ongoing, the design team is also working on designs which will hopefully happen in future versions of libadwaita, after 1.0, and I’ll give an overview of these so you can see what’s coming down the tracks. That said, all of these designs are speculative, so there is no guarantee that they will happen, or that they will happen in the form that’s described here. Also, note that the images here are mockups which aren’t a fully realistic representation of what any final UI might look like.

Entry rows

Boxed lists are a common design pattern in our apps, and libadwaita includes a number of convenience widgets to make it easy to create common types of lists and rows (currently, AdwActionRow, AdwComboRow, and AdwExpanderRow). One thing that’s missing here is a dedicated widget for rows which contain a text entry, and this is something that we’ve been actively exploring. It’s a tricky design problem but is something that we’re determined to resolve.


In-app notifications are the bars that appear below the header bars of some GNOME apps, to show transient messages. They have been used for some time, and play a key role in a number of core apps. However, despite their centrality, they have never really been supported by the platform, having been provided as cut and paste code from libgd, which has meant that they’ve often been out of reach for many app developers.

Toasts are planned to be a new widget which will be provided by libadwaita, and which will effectively replace in-app notifications. We plan on avoiding some of the issues that can be seen with the existing in-app notifications, by providing a simple API which takes care of the tricky aspects of showing message popups, such as message queing.


Another widget which we hope to provide an alternative to is GtkInfoBars. These have been around for a very long time, and are used in many apps to show a coloured strip below the header containing text and controls.

Info bars require developers to pack the content of the bar themselves, which results in consistency and quality issues, as well as more work for developers. Also, they aren’t adaptive. So we are planning to introduce a new widget – banners – which are simpler to use, adaptive, and which take care of their own internal layout. This will avoid the info bar issues of the past, and be less work to use.

Selection mode

Another area of design development has been selection mode. This is found in some of the GNOME core apps, but is not currently covered by the HIG. Recent design exploration has sought to refine and update the design pattern, in order to allow us to recommend it to developers.

A good next step here will be to try the updated design in a core app, so we get an opportunity to validate it.

Putting it into practice

Over the past few weeks, I’ve been updating a number of GNOME’s core app designs, to put our updating styling and design patterns into practice, and make sure that they work together.

Here, you can see what Contacts, Photos and Clocks might look like once ported to GTK 4 and libadwaita. Obviously, these are just experiments, but they are a helpful way of exploring our new direction.

I have to say that, applying the new style to existing apps has been extremely refreshing from a design perspective, and the new approach has been working even better than I’d expected. The simplified visual style feels lighter, and a number of awkward old designs clicked into place when using the new list and button patterns.

Closing thoughts

Many of the things that are being done for the GNOME platform right now have been a dream for many years, so the fact that they are now happening is incredibly exciting. Having fully supported design patterns, with integrated documentation and demos will be huge win for anyone creating apps for the GNOME platform.

Alexander Mikhaylenko deserves special thanks for his work on libadwaita, which is making all this possible. Tobias Bernard, Adrien Plazas, Chris Davis, Jakub Steiner, and Maximiliano are all also playing key roles.

While phenomenal progress is being made in this area, resources are tight and there’s a lot of work falling on the shoulders of a few contributors. A good number of things we would like to implement for libadwaita 1.0 won’t make it because of these constraints. Which is my way of saying: help would be welcome!

GNOME Foundation Board Elections 2021

The election process for the GNOME Foundation Board of Directors is currently underway. Three positions are up for election this year, and Foundation members are able to nominate themselves until May 31st.

I’ve been sitting on the board since 2015, and have been acting as chair for the past two years. In this post, I’m going to talk a bit about how the board has evolved in the past year, and what sitting on the board involves.

Board Evolution

As I’ve talked about previously, the GNOME Foundation Board has been evolving over recent years. When I first joined the board in 2015 we had a staff of one and a half, and the board was busy keeping the organisation running. We approved conference proposals, helped to organise events, dealt with legal issues when they arose, and attempted to manage our staff.

Nowadays we thankfully don’t have to do these things, because we have an Executive Director and their staff to do them for us. This has allowed the board to increasing move into the role that a board is supposed to have: that is, governance and oversight.

This is of vital importance since, to have a successful Foundation, we need to have a group which is responsible for taking a hard look at its strategy, plans and organisational health. This iisn’t something that a board that is focused on day-to-day operations is able to do.

Recent Changes

Over the past year, the evolution of the Foundation Board has continued, and the board has undergone a number of organisational changes.

First, we switched from having weekly one-hour meetings to monthly two-hour meetings. This has given the board the capacity to have more in-depth discussions. It has also allowed us to structure our year around key board functions. Each meeting now has a particular focus, and there’s a schedule for the year, with quarterly sessions on strategy and finance.

The second major change is that we have created three new board committees, which are primarily made up of directors. These are:

Executive Committee: this monitors operations and meets more frequently than the board. It has executive power and can therefore act on behalf of the board at short notice, should it be required. This committee is traditionally staffed by the Executive Director (or CEO) and board president. It is currently made up of Neil (Executive Director), Rob (President) and myself (Chair).

Governance Committee: this committee exists to monitor and develop the board itself. It does things like checking that the board is living up to its legal and regulatory commitments, running assessment exercises, and developing the board through training and recruitment. The governance committee is currently made up of Kat, Philip, Felipe and myself.

Finance Committee: as you’d expect, the finance committee is responsible for monitoring the Foundation’s finances, proposing budgets and financial policies, and preparing finance reports. The finance committee is currently staffed by Shaun (Treasurer), Rob (President), Neil (Executive Director), and Rosanna (Director of Operations).

These committees are fairly standard for non-profit boards, and allow the board to delegate specific functions to sub-groups, which then report back to the board as a whole. They make sure that important tasks get done, and they also free up full board meetings to have higher-level conversations.

Being a Director

Due to the board’s ongoing development, the role of directors has changed a bit recently.

In many respects, sitting on the board is less involved as it was in the past. It’s no longer the case that you have a weekly meeting, and might have a long list of “operational” tasks to carry out. Instead, it’s a monthly two hour meeting, with the potential for another one-hour committee meeting every month. You might need to pick up tasks, but they are fewer in number than previously.

On the flip side, being on the Foundation Board nowadays involves living up to the standard expectations for any directors. As a director, you have personal legal obligations to ensure that the Foundation is being run effectively and in accordance with the relevant laws and regulations. To do this, you need to do things like review our paperwork and ensuring that we have the correct policies and procedures in place.

Recruits Needed

Sitting on the Board of Directors is an important role, and is a really valuable way ito contribute to both open source and the GNOME project. The time requirements are relatively modest, and it’s a fantastic way to gain new skills and experience. Personally, I’ve found being on the board to be hugely rewarding and educational, and I’ve really enjoyed my time as a director!

A good director is someone who can reliably attend meetings and take on tasks, has an eye for detail, and is able to effectively articulate themselves.

Nowadays we are also looking to our directors to bring additional experience and knowledge. So, if you have management experience, or non-profit experience, then your nomination would be especially welcome.

If this sounds like something that you can help with, we’d love to see your nomination for the coming election! You should also feel free to reach out to any of the current directors: we’d all be very happy to talk more about what being a director involves.


In recent weeks, I’ve been working on a major update to the GNOME Human Interface Guidelines (HIG). The motivations for this work were varied. The HIG is fairly out of date, both in relation to contemporary design practice, as well as GNOME platform capabilities, and so needed updating. But we also wanted to improve the quality of the design guidance that we offer, and do a much better job at integrating our design docs with the rest of the developer platform.

As part of these changes, large parts of HIG have been restructured, and the vast majority of the content has been rewritten to some extent. It has also been expanded to cover a greater range of topics, including app naming, app icons, UI styling, accessibility and tooltips.

We’ve also changed how the HIG is hosted. It now has its own project on Gitlab, uses a lightweight markup language, and has its own website which is automatically updated to reflect the latest changes. This makes it a much more attractive proposition for contributors, and we’re already seeing the number of contributors increase.

A New Era

The new HIG comes at an exciting time for the GNOME platform — there have been some truly amazing developments recently!

First, GNOME design conventions have matured significantly and, I think, are in a really strong place. In the past we maybe didn’t have all the pieces in place, but now it feels like we do, and have a much more comprehensive, integrated and consistent design system.

Second, the platform itself has seen some major improvements, with the release of GTK 4 and the development of libadwaita and libhandy. These include a big set of features that designers and developers can take advantage of, like new widgets for tabs and drop-down lists, a new widget for placeholders, and GTK 4’s high-performance list and grid views.

Third, thanks to Bilal and Zander, we now have a whole collection fantastic design apps, including App Icon Preview, Symbolic Preview, Icon Library, Color Palette and Typography.

Finally, we also have new tooling for API documentation, thanks to Emmanuele and gi-docgen.

If you put all of this together, I think you’ve got a recipe for a really great developer experience. The new HIG aims to bring all these different pieces together: it documents the current state of the design system, references all the latest widgets, tells you when to use the design apps, and links to the correct places in the new developer docs.

Design >< Code

The old HIG documents design conventions which require developers to either use cut and paste widgets, or to write their own custom UI. Often it isn’t clear how this can be done. Not a great developer experience.

The new version does away with this, and has a closer relationship with the developer platform. Every design pattern has a corresponding widget which is included in the developer platform, which the HIG explicitly references. This means that, if you’re using the HIG, you can be confident that everything it describes can be easily implemented.

As part of this effort to bring the HIG closer to the platform, there have been a few terminology changes. For example, “grids” are now “flow boxes”, and “presentation dialogs” have become “secondary windows”. This will hopefully help to ensure that designers and developers are talk the same language.

There’s also been a lot of back and forth with platform developers, to ensure that the design guidelines are in tune with technical reality (which hasn’t always been the case, historically).

Notable Changes

Most of the changes in the new HIG shouldn’t be disruptive: most of them are additions or restructuring of existing advice. However, if you are responsible for an app, there are some changes which it’s worth being aware of.

Widget Updates

As mentioned, the HIG contains advice on using new widgets, and there are a number of places where it recommends using a new widget in place of an old one:

Design Pattern Old Widget New Widget
View switchers Linked toggle buttons AdwSwitcherBar/HdySwitcherBar
Drop-down lists GtkComboBox, or custom-build your own GtkDropDown
Tabs GtkNoteBook AdwTabBar / HdyTabBar

There’s also a number of new widgets that we recommend where none previously existed. This includes:

Utility Panes

Utility panes is a new term for an old concept: a sidebar which includes navigation, information or settings for the current view. It has been introduced to differentiate between sidebars which contain supplementary content for the view, as opposed to sidebars that act as the top-level navigation of a window (the latter being what we actually call a sidebar).

This distinction becomes particularly relevant when it comes to responsive behaviour since, when the window becomes narrow, a sidebar needs to collapse to become the top-level view you go back to, whereas a utility pane needs to behave so that it’s secondary to the main view.


The previous HIG was silent on the subject of tooltips, which led to a fair amount of inconsistency. This has been corrected with the new version. The advice boils down to: show tooltips for all the controls in header bars. Otherwise, use them with restraint, but do so consistently.

Tooltip labels should be similar to button labels (for example, "Fullscreen") as opposed to being written as descriptions (for example, "Press to switch to fullscreen").


The old HIG documents two types of placeholders: initial state placeholders, and empty state placeholders. The former were colourful and engaging, and intended to support onboarding, while the latter were muted and non-distracting, and for cases when a view was, well, empty.

The previous advice was a bit on the complicated side: it said to use both types of placeholder in the same view, depending on circumstances. A user would see the initial state placeholder on first run, but if they populated the app and then removed all the content, they’d get the empty placeholder.

For the new HIG, we’ve simplified the advice. We still have two types of placeholder, but we advise to just use one for each view. So, if you have a main view which uses a more engaging placeholder, then that’s what should be shown whenever that view is empty.


As part of the rewrite, I’ve reviewed GNOME’s old accessibility UI design guide, and incorporated any relevant material directly into the HIG. This means that we’ll be able to retire the UI section of the accessibility guide, and accessibility will be integrated into a standard design guidelines, as it should be. If you happen to still use the old accessibility guide, it’s recommended that you switch to the HIG instead.

Next Steps

The new version of the HIG is yet to officially replace the old one, and is being hosted in a temporary location. Some of us are going to be working on an updated site in the near future; once that’s done we’ll publish the new HIG alongside it.

There are a few critical pieces that the HIG will need in order to shine. First, it will need a stable libadwaita release, since the HIG is primarily targeting GTK 4. Second, it needs a demo app, with examples of the key design patterns. Neither of these are likely to be ready for the initial publication of the new HIG, but they are both in progress and hopefully won’t be too far behind.

GNOME Foundation Board of Directors: a Year in Review

The 2020 elections for the GNOME Foundation Board of Directors are underway, so it’s a good time to look back over the past 12 months and see what the current board has been up to. This is intended as a general update for members of the GNOME project, as well as a potential motivator for those who might be interested in running in the election!

Who’s on the board?

This year, the board has been Britt Yazel, Tristan Van Berkom, Philip Chimento, Rob McQueen, Carlos Soriano, Federico Mena Quintero, and myself.

Rob’s been president, I’ve been the vice-president and chair, Carlos has been treasurer, Philip has been secretary, and Federico has been vice-secretary.

In addition to these formal roles, each of our board members has brought their existing expertise and areas of interest: Britt has brought a concern with marketing and engagement, Federico has been our code of conduct expert, Rob has brought his knowledge of all things Flatpak and Flathub, Carlos knows everything Gitlab, and Philip and Tristan have both been able to articulate the needs and interests of the GNOME developer community.

Meetings and general organisation

The board has been meeting for 1 hour a week, according to a schedule which we’ve been using for a little while: we have a monthly Executive Director’s report, a monthly working session, and standard meetings in the gaps in-between.

This year we made greater use of our Gitlab issue tracker for planning meeting agendas. A good portion of the issues there are private, but anyone can interact with the public ones.

Making the board into a board

Historically, the GNOME Foundation Board has performed a mix of different roles, some operational and some strategic. We’ve done everything from planning and approving events, to running fundraisers, to negotiating contracts.

Much of this work has been important and valuable, but it’s not really the kind of thing that a Board of Directors is supposed to do. In addition to basic legal responsibilities such as compliance, annual filings, etc, a Board of Directors is really supposed to focus on governance, oversight and long-term planning, and we have been making a concerted effort to shift to this type of role over the past couple of years.

This professionalising trend has continued over the past year, and we even had a special training session about it in January 2020, when we all met in Brussels. Concrete steps that we have taken in this direction include developing high-level goals for the organisation, and passing more operational duties over to our fantastic staff.

This work is already having benefits, and we are now performing a more effective scrutiny role. Over the next year, the goal is to bring this work to its logical conclusion, with a schedule for board meetings which better-reflects its high-level governance and oversight role. As part of this, the hope is that, when the new board is confirmed, we’ll switch from weekly to monthly meetings.

This is also the reason behind our change to the bylaws last year, which is taking effect for the first time in this election. As a result of this, directors will have a term of two years. This will provide more consistency from one year to the next, and will better enable the Foundation and staff to make long-term plans. There has been a concern people would be unwilling to sit as a Director for a two year period, but we have significantly reduced the time commitment required of board members, and hope that this will mitigate any concerns prospective candidates might have.

Notable events

The GNOME Foundation has had a lot going on over the last 12 months! Much of this has been “operational”, in the sense that the board has been consulted and has provided oversight, but hasn’t actually been doing the work. These things include hiring new staff, the coding education challenge that was recently launched, and the Rothschild patent case which was settled only last week.

In each case the board has been kept informed, has given its view and has had to give formal approval when necessary. However, the areas where we’ve been most actively working have, in some respects, been more prosaic. This includes things like:

Code of conduct. The board was involved with the review and drafting of the new GNOME code of conduct, which we subsequently unanimously approved in September 2019. We also set up the new Code of Conduct Committee, which is responsible for administering the code of conduct.

Linux App Summit 2019, which happened in Barcelona. This event happened due to the joint support of the GNOME Foundation and KDE e.V, and the board was active in drafting the agreement that allowed this joint support to take place.

Guidelines for committees. As the board takes a more strategic oversight role, we want our committees to be run and report more consistently (and to operate according to the bylaws), so we’ve created new guidelines.

2020 budget. The foundation has had a lot going on (the coding challenge, patent case, etc) and all of this impacted the budget, and made financial scrutiny particularly important.

GNOME software definition and “Circle” proposal. This is a board-led initiative which addresses a long-standing confusion around which projects should be included within GNOME and make use of our infrastructure, branding and whether the teams involved were eligible for Foundation membership. The initiative was announced on Discourse last week for initial community feedback.

Updated conference policy. This primarily involved passing responsibility for conference approvals to our staff, but we have also clarified the rules for conference bidding processes (see the policy page).

In addition to this, the board has been involved with its usual events and workload, including meeting with our advisory board, the AGM, and voting on any issues which require an OK from the board.


2020 Elections

As I mentioned at the beginning of this post, the 2020 board elections are currently happening. Candidates have until Friday to announce their interest. As someone who has served on the board for a while, it’s definitely something that I’d recommend! If you’re interested and want more information, don’t hesitate to reach out. Or, if you’re feeling confident, just throw your hat in the ring.