UI Styling#

The visual style used for UI in GNOME is called Adwaita. It includes light and dark style options, which apply to all UI components, as well as a range of style options for individual widgets.

Light and Dark UI Styles#

The GNOME platform provides the ability for apps to have either a light or a dark UI style. Applications can choose which of the two styles to use by default. They can also include a control to allow users to switch between the light and dark style, and they can select the light and dark style based on the system-wide UI style setting.

Guidelines:

  • Most apps should use the standard light UI style by default. However, apps can alternatively choose to use the dark style by default instead. This is primarily recommended for apps which display rich visual content like images or video.

  • Apps that use the light UI by default style are encouraged to follow the system style setting, which allows users to set a preference to use dark instead of light.

  • Per-app style preferences are primarily useful for text editing apps, or apps which users use for long periods of time. In these cases, the style preference can be useful as a way of controlling visual contrast and brightness.

  • When providing a per-app style preference, three options should typically be included: light, dark, and follow system preference.

See AdwStyleManager for the relevant APIs.

High Contrast Mode#

High contrast mode is an accessibility feature which changes the UI style to have very high contrast. As part of testing your app, it is important to test it with high contrast mode enabled, to ensure that it is correctly rendered with this style. This can be done by using the system high-contrast mode setting, or with GTK Inspector.

Built-In Style Options#

Libadwaita includes a range of visual style options for individual UI elements. For example, the suggested and destructive styles changes the color of buttons, to indicate their function. The HIG pages for each design pattern include further guidance on the style options that are available for each UI element.

Libadwaita’s style class documentation also provides a complete list of the different style classes that are available.

Custom Styling#

GTK and Libadwaita can be used as the basis for custom UI elements, which are not included in the GNOME platform. The appearance of preexisting widgets can also be customized.

As a general rule, it is better to keep the amount of this custom styling to a minimum, as this will reduce maintenance overhead, will reduce bugs, and will help to ensure compatibility with accessibility and internationalization features.

When designing custom styling, it is recommended to use existing style classes and color variables as much as possible, since these automatically adjust for the light, dark and high-contrast styles. Be careful not to use classes and variables outside of their intended uses, as this could cause issues.

The Libadwaita named color and style class documentation can be a useful reference here.

Accessibility Considerations#

When creating custom UI elements, there are a number of accessibility issues to avoid regarding visual styling:

  • Using color as the only means to distinguish items of information. Instead, all information should be provided by at least one other method, such as shape, position or text description.

  • The use of flashing or blinking elements, as this may cause problems for people who are susceptible to visually-induced seizures.

Thorough testing of custom UI is essential. In particular, take care to run through the range of accessibility tests.