The Adwaita Library ($1449) · Snippets

What Happens to the Themes?

I'd avoid the T word, "stylesheet" is the technical term ;)

Similarly, "icon theme" -> "icon set".

The plan is for the Adwaita library to adopt the Adwaita stylesheet, and for GTK to develop a simpler one.

Seeing as @jimmac wasn't there for the meeting, this needs more discussion. My understanding is that Adwaita used to live outside GTK and was moved into that repo precisely because nobody was maintaining the simple default one, causing integration issues.

A new, simpler stylesheet isn't going to magically materialize or maintain itself into the future (especially since most likely nobody will actually ship that stylesheet), so I'm skeptical this is doable given that we already had this situation a few years back and moved away from it...

The library will be released under LGPL-2.1 to ease code exchange with GTK.

LGPL-2.1 or later.

As for Adwaita-the-stylesheet: we probably want to do something like GNOME Shell, and have a shared Git module that contains the various assets. Then both GTK and libadwaita can share the stylesheet.

GTK also ships two other themes:

HighContrast
HighContrast-inverse

which descend from Adwaita, and are there for accessibility purposes.

I'm interested in practical workflows maintaining a componentized stylesheet. First we have to assume we have somebody willing to do the required refactoring (there is neat prior art, some great work on the shell stylesheet by Sam Hewitt). In the past shell's submodule approach has proven to bring more pain and suffering than avoid redundancy, so I wonder about the ways of syncing the 'gtk core' to libadwaita (or possibly the opposite way).

I imagine cloning the library in Builder, hitting build and getting an equivalent of the gtk-demo app, presenting the up to date, supported patterns alongside the ability to use the gtk inspector referencing the stylesheet. Having a change affect two modules at once is not viable for our current gitlab/merge request based process.

HC and HCi at this point are special contexts of the same stylesheet. All four have to be developed concurrently (light, dark, contrasty, contrasty inverse).

While the icon theme lives in its own repository, the GTK stylesheet lives in the GTK repsitory and serves as its default stylesheet. The plan is for the Adwaita library to adopt the Adwaita stylesheet, and for GTK to develop a simpler one.

I think it would be good to

explain what problem this solves
make an argument for why it does not cause more problems than it solves

The reasoning behind that is that most GTK-based platforms or independent GTK applications already implement their own stylesheet, so they won't be affected by such a change, and it will help independent applications not shipping a custom stylsheet to not look like half-baked GNOME apps on other platforms.

I'd say this is just plain not true

What isn't mentioned (and what we didn't really discuss at length in the meeting yesterday) is the expected API stability of libadwaita. How often are API breaks supposed to happen, what's going to happen with the old version and are apps expected to port and how quickly.

I think it's good to have a plan there, even if the plan will likely not survive unscathed once it meets reality.

It seems I completely misunderstood what we agreed on regarding the stylesheet, thanks! 🙂️ I rewrote that section, let me know if anything is wrong. I also didn't mention HighContrast because it's still a bit unclear to me what we will do with it. I personally see it as a variant of Adwaita hence I expect both to move to that new repository.

@jimmac: Don't hesitate to ping me if you want to sidcuss the theme development workflow.

@otte: Do you have specific points that aren't explained by the last two sections? I'm too involved to have the necessary distance to understand what isn't clear.

Some questions like:

How long until libdwaita 2.0 is released? Gnome 42, Gnome 45 or Gnome 60?
When libadwaita 2.0 is out (or 3.0 or 4.0), how long will 1.x be supported?
When I write a program against libadwaita 1.0 today, will it keep working with libadwaita 1.x or will it require maintenance like GTK3 themes did?

This is mainly about questions from app developers outside of the ecosystem that develop way slower or and way different schedules.
Should Inkscape target it? Should Pidgin? Should XFCE?

Thanks for this @aplazas! I really like what you have so far. Some questions and comments:

If the contents of libadwaita are to be "the official platform" which we recommend to developers, then how and where do we develop those components up to the point when they are ready to be included?
What will the main communication channel be for libadwaita? I think it would be good to facilitate conversations and visability between GTK and libadwaita. At the moment it feels like the two teams are living in different silos.
It would be good to state what the intention is regarding support and deprecations.
Personally I found the libadwaita name to be confusing. Adwaita is the stylesheet - "libadwaita" makes it sounds that this is just to do with styling.
As someone who hasn't had much direct involvement in libhandy, I feel fairly uncomfortable about designating libadwaita as the canonical reference for GNOME app design patterns. What I want to avoid is a) components landing in libadwaita without the design team at large being aware of it (as has happened in libhandy so far) and b) divergence between libadwaita and the GNOME HIG. Maybe having a shared roadmap or something of that nature could be the answer? (Related - I think it would be really good to aspire to have libadwaita and the HIG in sync. Could we have this as a stated goal?)
Will libadwaita include a subset of libhandy, or everything? If the former, could you provide a list of what will be carried over?

I filed https://gitlab.gnome.org/GNOME/gtk/-/issues/3582 to capture the result of some followup irc discussion on themes

I think we should have some followup discussion around governance and maintenance.

Before we hand over 'the GNOME visual language and identity' to the people working on this library, some questions need to be answered:

Who decides what does and does not make it into libadwaita ?
How does the stuff currently in libhandy relate to the HIG, if at all ?
How is the library kept in sync with the HIG ?
How does migration between GTK and libadwaita work ? We've seen quite a few things go into libhandy that would be better off in GTK (out of necessity, since GTK3 was frozen). We should not continue that, but make a serious attempt to merge things back into GTK where possible, or at least GTK provide the right plumbing

Who decides what does and does not make it into libadwaita ?

In my thinking, it would be consensus between the designers that a design should become a common pattern in GNOME, and consensus between designers and maintainers that it should be included in libadwaita rather than handled by apps or a library with a different scope.

How does the stuff currently in libhandy relate to the HIG, if at all ?

The HIG is quite out of date, but design patterns have been evolving over time. This is what libhandy/libadwaita currently implement.

Going down the list of what we have in libadwaita currently:

AdwActionRow, AdwExpanderRow, and AdwComboRow provide a simple way to have listbox rows with a prefix, suffix, an icon, title, and subtitle, etc. - see the list design patterns mockup.
AdwWindow and AdwApplicationWindow are windows without the titlebar/content separation. This makes it easy to have unified window content, or windows with no titlebars. Also makes setting up a split headerbar pattern with AdwLeaflet simpler.
AdwAvatar is for consistent user avatars.
AdwCarousel is used for things like image galleries or tours, providing a nice way to have swipe-able, sequential pages. Boxes and Tour use it for tutorials, and it would be used for images in Software or making something like EOG swipe-able.
AdwClamp is for setting a maximum size without hard-coding a size, since many things don't scale well to larger sizes, but need to shrink to smaller sizes.
AdwFlap is for sidebars that aren't split headerbars. It provides an adaptive widget that can be swiped on touchscreens. This will be used to make Nautilus adaptive, could potentially be used for Evince, Fonts, and at one point the Text Editor mockups had a sidebar that could use AdwFlap.
AdwHeaderBar provides a headerbar with loose or strict centering. loose centering means the center widget doesn't need to be at the strict center, and can touch the edges / neighbors at smaller sizes. strict centering means it must be in the center of the headerbar, and that can restrict the headerbar's sizing. This is needed for adaptivity.
AdwLeaflet has two modes: with can-unfold as true, it acts a bit like a box, except it can fold/unfold. This is used for apps like Fractal and Settings to fold and unfold at small screensizes, and it provides transitions & swiping between pages at small sizes. This is very useful for split headerbar apps. With can-unfold set to false, it is like GtkStack, but with swiping and re-ordering children. This gives it the ability to act like a deck of cards, where you can put widgets on top/bottom and swipe off the top of the deck to navigate.
The AdwPreferences* widgets provide everything you need to create a simple preferences window with search and swiping between sub-pages. It could also be used for e.g. Control Center, Tweaks, or Flatseal for preferences pages that have groups of listboxes for changing settings. An example of that in action is here.
AdwSqueezer is a helper widget for a container that has different modes depending on what fits at what size.
AdwViewSwitcher* implements the new view switcher patterns. All new mockups use this pattern instead of GtkStackSwitcher, and GNOME apps are recommended to switch to it for the headerbar.
AdwWindowTitle is a helper for setting a view title in a headerbar that isn't the window title, with a subtitle. This helps developers with the removal of the title/subtitle APIs from GtkHeaderBar and AdwHeaderBar. Apps can use this and set the title/subtitle there.

The only widget that doesn't have relevance to the HIG or newer design patterns is AdwKeypad, which we are considering removing.

The HIG is quite out of date, but design patterns have been evolving over time. This is what libhandy/libadwaita currently implement.

It does raise the question: how does this make anything better?

The complaint I've been hearing about the HIG vs GTK is: it is not obvious how to implement HIG patterns with the widgets we have.

Now you are telling me libadwaita doesn't do that either, and instead implements bits and pieces of other things that somebody drew and put into /os-mockups. Whats the story for 3rd party developers who are not in the secret matrix channels to find out what in /os-mockups is current, and what is outdated, like 'the hig' ?

That's solved by updating the HIG and keeping it up-to-date, and keeping libadwaita in sync with it - which I do think should be a goal.

The complaint I've been hearing about the HIG vs GTK is: it is not obvious how to implement HIG patterns with the widgets we have.

For many of the patterns listed here that are in use already (e.g. lists, title+subtitle, split headerbar, columns with a maximum size, avatars), it isn't obvious. Many apps implement each of these things in different ways now - just like how before e.g. GtkStackSwitcher some apps used linked radio buttons to manually implement it. libadwaita/libhandy provides easy widgets to replace individual app implementations, which makes things more consistent.

That's solved by updating the HIG and keeping it up-to-date, and keeping libadwaita in sync with it - which I do think should be a goal.

I think we should make it a goal to do that together with rolling out libadwaita. And we should look at cross-linking the hig and the libadwaita api docs as much as we can.

How long until libdwaita 2.0 is released? Gnome 42, Gnome 45 or Gnome 60?

When libadwaita 2.0 is out (or 3.0 or 4.0), how long will 1.x be supported?

It would be good to state what the intention is regarding support and deprecations.

When I write a program against libadwaita 1.0 today, will it keep working with libadwaita 1.x or will it require maintenance like GTK3 themes did?

It would be good to state what the intention is regarding support and deprecations.

Between minor versions we will never break the API, and we will never break wanted behaviors. We can change behaviors if the current one isn't what was intended: in that case it's a behavior fix.

New major versions will appear when changes can't be introduced by deprecation or when we accumulated too many deprecated API. It's very informal, but we will try to avoid releasing new major version too often (maximum once per two GNOME verisons under normal circumstances).

Deprecating elements will never produce build errors, only buils warnings. Because major versions are parallel-installable, an application will never see its target API/ABI or its behavior change unexpectedly.

New major versions could be as frequent as one per GNOME version and as sparce as not having any. Sorry for not being more precise as my crystal ball is broken, but my experience on libhandy suggests we can expect new major versions every 2 to 4 GNOME versions.

Major versions could be supported for a year after the release of their last minor version. Maybe two. Do you have suggestions about this?

This is mainly about questions from app developers outside of the ecosystem that develop way slower or and way different schedules. Should Inkscape target it? Should Pidgin? Should XFCE?

libadwaita will exist to help implementing the GNOME HIG and will very specifically be designed to catter to GNOME's needs, just like Granite currently is for elementary.

XFCE is free to use libadwaita, though that would be extremently odd as the library will very specificaly catter to the needs of a different platform.

I'd recommend Inkscape and Pidgin to use libadwaita if they want to offer a modern GNOME UI, whether it is their only UI on one in many like Transmission does. If they choose to use libadwaita, I'd recommend them to completely follow the GNOME HIG, as the library is just a tool to help doing so.

If the contents of libadwaita are to be "the official platform" which we recommend to developers, then how and where do we develop those components up to the point when they are ready to be included?

What will the main communication channel be for libadwaita? I think it would be good to facilitate conversations and visability between GTK and libadwaita. At the moment it feels like the two teams are living in different silos.

New patterns would be designed as usual by the design team. Once the pattern's design is in a good shape, a widget would be designed in an issue or a merge request in liadwaita's GitLab, it would be reviewed by at least one libadwaita dev that isn't the MR's author, and ideally by a member of the design team. Before merging, the branch should be tested by using it in at least two applications that need it — ideally with mathcing MRs — to ensure it fits their needs correctly.

For informal conversations, we plan to have a #libadwaita (or #adwaita?) Matrix room bridged to GimpNet, which should maximize inclusiveness.

Personally I found the libadwaita name to be confusing. Adwaita is the stylesheet - "libadwaita" makes it sounds that this is just to do with styling.

That's the best and most relevant name we found, and believe me me considered about everything. It will become even more relevant once we add a theming and recoloring API, as the library will be heavily tied to the Adwaita stylsheet.

Beyond that, Adwaita is already more than a stylesheet as it's also an icon set.

As someone who hasn't had much direct involvement in libhandy, I feel fairly uncomfortable about designating libadwaita as the canonical reference for GNOME app design patterns. What I want to avoid is a) components landing in libadwaita without the design team at large being aware of it (as has happened in libhandy so far)

Will libadwaita include a subset of libhandy, or everything? If the former, could you provide a list of what will be carried over?

See Chris' overview of what is currently included on master. :) We already dropped elements that didn't fit the criteria (being needed by at least two apps and following GNOME's HIG) like the keypad, or that were not relevant anymore for GTK 4 like header groups.

While the design team was already pretty involded into libhandy, we want to make that involvement more formal for libadwaita: do you have suggetion on which shape this involvement could take?

and b) divergence between libadwaita and the GNOME HIG. Maybe having a shared roadmap or something of that nature could be the answer? (Related - I think it would be really good to aspire to have libadwaita and the HIG in sync. Could we have this as a stated goal?)

How is the library kept in sync with the HIG ?

I think we should make it a goal to do that together with rolling out libadwaita. And we should look at cross-linking the hig and the libadwaita api docs as much as we can.

The vast majority of patterns that were developed by the design team over the previous years are not documented in the HIG. They were implemented in libhandy in collaboration with the design team, so I think the issue isn't that libadwaita would diverge from the HIG but that the HIG isn't updated fast enough to document these new patterns. It is problematic as we should have the HIG and libadwaita cross-referencing each other.

What I think could be done: once we pick up a pattern for inclusion into libadwaita, we should file an issue against the HIG so the design team can start documenting the pattern while we develop and document a widget to help implementing that pattern. That would also help cross-referencing the HIG and the libadwaita documentation.

Similarly, that would help the design team ask us things they need to update the HIG, like a demo application to take screenshots. Would that work for you?

Who decides what does and does not make it into libadwaita ?

In my thinking, it would be consensus between the designers that a design should become a common pattern in GNOME, and consensus between designers and maintainers that it should be included in libadwaita rather than handled by apps or a library with a different scope.

In previous discussions about this, we'd spoken about having some steps in the process to make sure that widgets have had some real world testing, and have general relevance. Potential inclusion criteria could include having been successfully used in an app or two, and having a list of 3 or 4 apps where the widget would be useful.

The HIG is quite out of date, but design patterns have been evolving over time. This is what libhandy/libadwaita currently implement.

It does raise the question: how does this make anything better?

The complaint I've been hearing about the HIG vs GTK is: it is not obvious how to implement HIG patterns with the widgets we have.

I definitely agree that the HIG is an important part of this, and we should aim to have the library accompanied by design and developer documentation

In terms of the complaint and how to improve the general situation, the plan for the HIG is to:

ensure that every pattern in the HIG contains a) links to the relevant api docs b) if possible, links to examples and templates
remove any patterns which aren't supported by our toolkit libraries

I'm hopefully that we can that with a new version of the HIG during the GNOME 41 development cycle.

For informal conversations, we plan to have a #libadwaita (or #adwaita?) Matrix room bridged to GimpNet, which should maximize inclusiveness.

Sounds good!

Will libadwaita include a subset of libhandy, or everything? If the former, could you provide a list of what will be carried over?

See Chris' overview of what is currently included on master. :)

Thanks, very helpful!

The vast majority of patterns that were developed by the design team over the previous years are not documented in the HIG. They were implemented in libhandy in collaboration with the design team,

There's a reasonable amount of elision between "the design team" and "Tobias" in this thread. 😀 That's not meant to be a criticism of anyone, but does make me wonder what's meant by "collaboration with the design team".

It'd be good to have some way to ensure that the broader team is involved - perhaps a widget roadmap that we jointly review, or having 2 designers sign off on each widget, or having tracking happen as part of the HIG so we know what's coming up.

One important question will be another libraries like vte and webkit. How they deal with this.

@marcthe12: I'm not sure that's a relevant question: they can just dynamically link to it if they think it's relevant to them, just as they do with GTK.

Also I doubt they need to use it, as they both implement a very specific widget. Similar irrelevant libs are gnome-bluetooth and RetroGTK.

I think they may need it depending on what they are doing and how much stuff we move to libadwaita eventually tbh. For example, WebKit uses a GtkMessageDialog atm for alert()s. Also an emoji picker.