gem-graph-client/doc/GTK-docs/gnome-dev-documentation/developer.gnome.org/hig/guidelines/ui-styling.html

309 lines
20 KiB
HTML
Raw Normal View History

<!doctype html>
<html class="no-js">
<head><meta charset="utf-8"/>
<meta name="viewport" content="width=device-width,initial-scale=1"/>
<meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" /><link rel="next" title="Writing Style" href="writing-style.html" /><link rel="prev" title="UI Icons" href="ui-icons.html" />
<meta name="generator" content="sphinx-4.3.0, furo 2021.07.05.beta38"/>
<title>UI Styling - GNOME Human Interface Guidelines documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/styles/furo.css" />
<link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css" />
<link rel="stylesheet" type="text/css" href="../_static/gnome.css" />
<style>
:root {
--color-code-background: #f8f8f8;
--color-code-foreground: black;
--color-brand-primary: #4a86cf;
--color-brand-content: #4a86cf;
}
@media (prefers-color-scheme: dark) {
:root {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
}
/* For allowing end-user-specific overrides */
.override-light {
--color-code-background: #f8f8f8;
--color-code-foreground: black;
--color-brand-primary: #4a86cf;
--color-brand-content: #4a86cf;
}
.override-dark {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
</style><link media="(prefers-color-scheme: dark)" rel="stylesheet" href="../_static/pygments_dark.css"></head>
<body dir="">
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-toc" viewBox="0 0 24 24">
<title>Contents</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none"
stroke-width="1.5" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round">
<path stroke="none" d="M0 0h24v24H0z"/>
<line x1="4" y1="6" x2="20" y2="6" />
<line x1="10" y1="12" x2="20" y2="12" />
<line x1="6" y1="18" x2="20" y2="18" />
</svg>
</symbol>
<symbol id="svg-menu" viewBox="0 0 24 24">
<title>Menu</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none"
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
class="feather feather-menu">
<line x1="3" y1="12" x2="21" y2="12"></line>
<line x1="3" y1="6" x2="21" y2="6"></line>
<line x1="3" y1="18" x2="21" y2="18"></line>
</svg>
</symbol>
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
<title>Expand</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none"
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
class="feather feather-chevron-right">
<polyline points="9 18 15 12 9 6"></polyline>
</svg>
</symbol>
</svg>
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
<label class="overlay sidebar-overlay" for="__navigation"></label>
<label class="overlay toc-overlay" for="__toc"></label>
<div class="page">
<header class="mobile-header">
<div class="header-left">
<label class="nav-overlay-icon" for="__navigation">
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
</label>
</div>
<div class="header-center">
<a href="../index.html"><div class="brand">GNOME Human Interface Guidelines</div></a>
</div>
<div class="header-right">
<label class="toc-overlay-icon toc-header-icon" for="__toc">
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
</header>
<aside class="sidebar-drawer">
<div class="sidebar-container">
<div class="sidebar-sticky"><a class="sidebar-brand centered" href="../index.html">
<div class="sidebar-logo-container">
<img class="sidebar-logo" src="../_static/logo.svg" alt="Logo"/>
</div>
<span class="sidebar-brand-text">GNOME Human Interface Guidelines</span>
</a><form class="sidebar-search-container" method="get" action="../search.html">
<input class="sidebar-search" placeholder=Search name="q">
<input type="hidden" name="check_keywords" value="yes">
<input type="hidden" name="area" value="default">
</form><div class="sidebar-scroll"><div class="sidebar-tree">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../principles.html">Design Principles</a></li>
<li class="toctree-l1"><a class="reference internal" href="../resources.html">Tools &amp; Resources</a></li>
<li class="toctree-l1 current has-children"><a class="reference internal" href="../guidelines.html">Guidelines</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label for="toctree-checkbox-1"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="app-naming.html">App Naming</a></li>
<li class="toctree-l2"><a class="reference internal" href="app-icons.html">App Icons</a></li>
<li class="toctree-l2"><a class="reference internal" href="pointer-touch.html">Pointer &amp; Touch</a></li>
<li class="toctree-l2"><a class="reference internal" href="keyboard.html">Keyboard</a></li>
<li class="toctree-l2"><a class="reference internal" href="ui-icons.html">UI Icons</a></li>
<li class="toctree-l2 current current-page"><a class="current reference internal" href="#">UI Styling</a></li>
<li class="toctree-l2"><a class="reference internal" href="writing-style.html">Writing Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="typography.html">Typography</a></li>
<li class="toctree-l2"><a class="reference internal" href="navigation.html">Navigation</a></li>
<li class="toctree-l2"><a class="reference internal" href="adaptive.html">Scaling &amp; Adaptiveness</a></li>
<li class="toctree-l2"><a class="reference internal" href="accessibility.html">Accessibility</a></li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../patterns.html">Patterns</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/><label for="toctree-checkbox-2"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2 has-children"><a class="reference internal" href="../patterns/containers.html">Containers</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/><label for="toctree-checkbox-3"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/windows.html">Windows</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/header-bars.html">Header Bars</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/popovers.html">Popovers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/utility-panes.html">Utility Panes</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/boxed-lists.html">Boxed Lists</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/grid-views.html">Grid Views</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/list-column-views.html">List &amp; Column Views</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/selection-mode.html">Selection &amp; Edit Modes</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../patterns/nav.html">Navigation</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" type="checkbox"/><label for="toctree-checkbox-4"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../patterns/nav/browsing.html">Browsing</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/nav/view-switchers.html">View Switchers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/nav/tabs.html">Tabs</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/nav/sidebars.html">Sidebars</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/nav/search.html">Search</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../patterns/controls.html">Controls</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" type="checkbox"/><label for="toctree-checkbox-5"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/buttons.html">Buttons</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/menus.html">Menus</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/switches.html">Switches</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/text-fields.html">Text Fields</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/checkboxes.html">Checkboxes</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/radio-buttons.html">Radio Buttons</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/drop-downs.html">Drop-Down Lists</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/sliders.html">Sliders</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/spin-buttons.html">Spin Buttons</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/overlaid.html">Overlaid Controls</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../patterns/feedback.html">Feedback</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" type="checkbox"/><label for="toctree-checkbox-6"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/notifications.html">Notifications</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/toasts.html">Toasts</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/info-bars.html">Info Bars</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/progress-bars.html">Progress Bars</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/spinners.html">Spinners</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/dialogs.html">Dialogs</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/placeholders.html">Placeholder Pages</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/tooltips.html">Tooltips</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../reference.html">Reference</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" type="checkbox"/><label for="toctree-checkbox-7"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="../reference/keyboard.html">Standard Keyboard Shortcuts</a></li>
<li class="toctree-l2"><a class="reference internal" href="../reference/palette.html">Palette</a></li>
<li class="toctree-l2"><a class="reference internal" href="../reference/backgrounds.html">Backgrounds</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
</aside>
<main class="main">
<div class="content">
<article role="main">
<label class="toc-overlay-icon toc-content-icon" for="__toc">
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
<section id="ui-styling">
<h1>UI Styling<a class="headerlink" href="#ui-styling" title="Permalink to this headline"></a></h1>
<p>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.</p>
<section id="light-and-dark-ui-styles">
<h2>Light and Dark UI Styles<a class="headerlink" href="#light-and-dark-ui-styles" title="Permalink to this headline"></a></h2>
<p>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.</p>
<p>Guidelines:</p>
<ul class="simple">
<li><p>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.</p></li>
<li><p>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.</p></li>
<li><p>Per-application 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.</p></li>
<li><p>When providing a per-application style preference, three options should typically be included: light, dark, and follow system preference.</p></li>
</ul>
<p>See <a class="reference external" href="https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.StyleManager.html">AdwStyleManager</a> and <a class="reference external" href="https://gnome.pages.gitlab.gnome.org/libhandy/doc/master/HdyStyleManager.html">HdyStyleManager</a> for the relevant APIs.</p>
</section>
<section id="high-contrast-mode">
<h2>High Contrast Mode<a class="headerlink" href="#high-contrast-mode" title="Permalink to this headline"></a></h2>
<p>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 <a class="reference external" href="https://wiki.gnome.org/Projects/GTK/Inspector">GTK Inspector</a>.</p>
</section>
<section id="built-in-style-options">
<h2>Built-In Style Options<a class="headerlink" href="#built-in-style-options" title="Permalink to this headline"></a></h2>
<p>Adwaita includes a range of visual style options for individual UI elements. For example, the <a class="reference internal" href="../patterns/controls/buttons.html#button-styles"><span class="std std-ref">suggested and destructive styles</span></a> 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.</p>
<p><a class="reference external" href="https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/style-classes.html">libadwaitas style class documentation</a> also provides a complete list of the different style classes that are available.</p>
</section>
<section id="custom-styling">
<h2>Custom Styling<a class="headerlink" href="#custom-styling" title="Permalink to this headline"></a></h2>
<p>GTK and Adwaita 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.</p>
<p>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.</p>
<p>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.</p>
<p>The libadwaita <a class="reference external" href="https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/named-colors.html">named color</a> and <a class="reference external" href="https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/style-classes.html">style class</a> documentation can be a useful reference here.</p>
<section id="accessibility-considerations">
<h3>Accessibility Considerations<a class="headerlink" href="#accessibility-considerations" title="Permalink to this headline"></a></h3>
<p>When creating custom UI elements, there are a number of accessibility issues to avoid regarding visual styling:</p>
<ul class="simple">
<li><p>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.</p></li>
<li><p>The use of flashing or blinking elements, as this may cause problems for people who are susceptible to visually-induced seizures.</p></li>
</ul>
<p>Thorough testing of custom UI is essential. In particular, take care to run through the range of <a class="reference internal" href="accessibility.html#accessibility-tests"><span class="std std-ref">accessibility tests</span></a>.</p>
</section>
</section>
</section>
</article>
<footer>
<div class="related-pages">
<a class="next-page" href="writing-style.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Writing Style</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="ui-icons.html">
<svg><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">UI Icons</div>
</div>
</a>
</div>
</footer>
</div>
<aside class="toc-drawer">
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
Contents
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">UI Styling</a><ul>
<li><a class="reference internal" href="#light-and-dark-ui-styles">Light and Dark UI Styles</a></li>
<li><a class="reference internal" href="#high-contrast-mode">High Contrast Mode</a></li>
<li><a class="reference internal" href="#built-in-style-options">Built-In Style Options</a></li>
<li><a class="reference internal" href="#custom-styling">Custom Styling</a><ul>
<li><a class="reference internal" href="#accessibility-considerations">Accessibility Considerations</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
</main>
</div><script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/scripts/main.js"></script>
</body>
</html>