diff --git a/HIG/source/accessibility/checklist.rst b/HIG/source/accessibility/checklist.rst index 173ef6b..30cbac6 100644 --- a/HIG/source/accessibility/checklist.rst +++ b/HIG/source/accessibility/checklist.rst @@ -1,272 +1,272 @@ Accessibility Checklist ======================= Introduction ------------ This is a list of common things you should check for to have great :doc:`accessibility ` for your application or widgets. Keyboard Navigation ------------------- - Efficient keyboard access is provided for all application features. - All windows have a logical keyboard navigation order. - The correct tab order is used for controls whose enabled state is dependent on checkboxes, radio buttons or toggle buttons. - Keyboard access to application-specific functions does not override existing system accessibility features. - The application provides more than one method to perform keyboard tasks whenever possible. - There are alternative keyboard shortcuts wherever possible. - Frequently-accessed keyboard shortcuts should be physically easy to access and not require awkwardly bending the wrist or fingers. - The application does not require repetitive, simultaneous keypresses. - The application provides keyboard equivalents for all mouse functions. - The application provides keyboard equivalents for all mouse-based functions, including selecting, moving, and resizing items. - The application does not use any general navigation functions to trigger operations. - All keyboard-invoked menus, windows, and tooltips appear near the object they relate to. Testing ^^^^^^^ The following keyboard operations should be tested. Don't use the mouse in any part of this test. - Using only keyboard commands, move the focus through all menu bars in the application. - Confirm that: - Context-sensitive menus display correctly. - Any functions listed on the toolbar can be triggered using the keyboard. - Every control in the client area of the application can be focused and activated. - Text and objects within the client area can be selected. - Any keyboard enhancements or shortcuts are working as designed. Mouse Interaction ----------------- - No operations depend on input from the right or middle mouse buttons. - All mouse operations can be cancelled before they are complete. - Visual feedback is provided throughout drag and drop operations - The mouse pointer is never moved by the application, or its movement restricted to part of the screen by the application. Graphical Elements ------------------ - There are no hard-coded graphical attributes such as line, border or shadow thickness. - All multi-color graphical elements can be shown in monochrome only, where possible. - All interactive GUI elements are easily distinguishable from static GUI elements. - An option to hide non-essential graphics is provided. See :doc:`units ` for more information on how to use KDE's base units to avoid hardcoded size values. Testing ^^^^^^^ Test the application using a screen reader and confirm that: - Labels and text are being read correctly, including menus and toolbars. - Object information is read correctly. Fonts and Text -------------- - No font styles or sizes are hard-coded. - An option to turn off graphical backdrops behind text is provided. - All labels have names that make sense when taken out of context. - No label names are used more than once in the same window. - Label positioning is consistent throughout the application. - All static text labels that identify other controls end in a colon (:). - Static text labels that identify other controls immediately precede those controls in the tab order. - An alternative to WYSIWYG is provided. For example, the ability to specify different screen and printer fonts in a text editor. See :doc:`typography ` for more information on how to avoid hardcoded font sizes and :doc:`labels ` for more details about labels. Testing ^^^^^^^ - Change the font in the application and confirm that the settings are maintained. - Test the application by changing colors and confirm that all settings are maintained. - If magnification is available, test the font, color, and size using the magnification option. Color and Contrast ------------------ - Application colors are not hard-coded, but either use colors from current desktop theme or an application setting. - Color is only used as an enhancement, and not as the only means to convey information or actions. - The application supports all available :doc:`high contrast themes ` and settings. - The software is not dependent on any particular :doc:`high contrast themes ` or settings. -See :doc:`the HIG's page about color ` and +See :doc:`the HIG's page about color ` and :doc:`colors in Kirigami ` for more information. Testing ^^^^^^^ - Print screenshots to a black and white printer and confirm that all information is visible. - Test applications using only black and white high-contrast settings and confirm that all information is conveyed correctly. - Test that the application provides at least three combinations of color schemes and that high-contrast schemes are available (e.g. white on black or yellow on blue). - Turn on high-contrast settings in the System Settings and confirm that the application respects these settings. - Test various themes to ensure that the software is working for all the available settings. Magnification ------------- - The application provides the ability to scale or magnify the work area. - The application's functionality is not affected by changing the magnification or scale settings. Audio ----- - Sound is not used as the only means of conveying any items of information. - The user can configure the frequency and volume of all sounds and warning beeps. Testing ^^^^^^^ There should be an option in the application to show audio alerts visually. Test that the audio is working correctly by enabling sound in the System Settings and then perform the following actions: - Perform an action that should generate an audio alert and confirm that the application is working as designed. - Verify that the application works correctly when increasing or decreasing the volume. - Confirm that warning messages and alerts can be heard correctly in a noisy work environment. Animation --------- - There are no flashing or blinking elements with a frequency greater than 2Hz or lower than 55Hz. - Any flashing or blinking is confined to small areas of the screen. - If animation is used, an option is available to turn it off before it is first shown. Testing ^^^^^^^ Verify that an option is available to stop animation and that it is working as designed. Turn the animation off. Confirm that all information is still conveyed correctly. Keyboard Focus -------------- - When a window is opened, focus starts at the most commonly-used control. - Current input focus position is clearly displayed at all times. - Input focus is shown in exactly one window or view at all times. - Appropriate audio or visual feedback is provided when the user attempts to navigate past either end of a group of related objects. - The default audio or visual warning signal is played when the user presses an inappropriate key. - There is sufficient audio information for the visual focus that the user can figure out what to do next. - Set the focus to the actual control. Don't just highlight an area. - When using assistive technologies, such as a screen reader or braille device, the current program indicates the position and content of the visual focus indicator. Testing ^^^^^^^ - Verify when moving among objects that the visual focus indicator is easy to identify. - Keyboard navigation through the software and menus should be clearly visible when the focus moves. - Confirm that the screen reader is tracking the visual focus indicator as you navigate using a keyboard. - Run a screen magnification program (if available) and verify that the magnifier can track the visual focus indicator as you navigate using the keyboard and mouse. Timing ------ - There are no hard-coded time-outs or time-based features in the application. - The display or hiding of important information is not triggered solely by movement of the mouse pointer. Testing ^^^^^^^ - Test all messages to confirm that the user is notified before a message times out and is given the option to indicate that more time is needed. - Make sure an option has been included to adjust the response time and confirm that it is working as designed. Documentation ------------- - All documentation is in an accessible format, with textual alternate descriptions provided for all figures and diagrams. - The documentation includes a section that covers all the application's accessibility features. Testing ^^^^^^^ Test ASCII text documentation with a screen reader to confirm that it is clear and precise and can be read by assistive technologies. Test HTML applications using a web browser and screen reader to confirm that the documentation is accessible to assistive technologies. Note: There are web accessibility guidelines available at ``_. Confirm the following information is included in the documentation: - State if the application does not support the standard keyboard access used by the OS. - Identify if there are unique keyboard commands. - Identify any unique accessibility features. - If an action is documented for the mouse, make sure there is an alternative for using the keyboard. .. note:: The content of this page is based on ``_ diff --git a/HIG/source/components/assistance/emblem.rst b/HIG/source/components/assistance/emblem.rst index 90280dd..ba3b3c9 100644 --- a/HIG/source/components/assistance/emblem.rst +++ b/HIG/source/components/assistance/emblem.rst @@ -1,61 +1,61 @@ Emblem ====== Purpose ------- An emblem displays unusual or non-default status information about an icon or image. For example, an emblem could indicate that a folder is shared, that a disk is unmounted, or that an app has unread notifications. Examples -------- .. figure:: /img/emblem-public-on-folder.png :alt: An emblem indicating that a folder is shared on the network .. figure:: /img/emblem-notification-kmail.png :alt: An emblem indicating that a mail program has 15 unread emails Guidelines ---------- - Emblems are used to badge icons, images, or other visually discrete elements in a file manager, system tray, task manager, dock, image view, etc. Emblems should not be applied to textual content. - Use emblems to display that an icon or image has some unusual status associated with it, or that there are unread notifications. Don't use emblems to display an element's normal, common, or typical status. For example, an emblem could indicate that a folder is read-only or is a symlink, or that a disk is unmounted or encrypted. An emblem should not be used to indicate that a folder is read-write or that a disk is mounted. - Emblems that indicate status should be placed in the bottom-right corner. If additional status emblems are needed, they should be placed in other corners in a clockwise order. - Emblems that indicate unread notifications should be located in the top-right corner. - Use the minimum number of emblems and don't overwhelm the icon itself. Three is usually too many. Appearance ---------- An emblem that indicates unread notifications should take the form of a light-colored number inside a blue circle. The circle can become "pill-shaped" if the number is very large. .. figure:: /img/emblem-notification-small.png :alt: Notification emblem .. figure:: /img/emblem-notification-large.png :alt: Notification emblem with a large number -For symbolic icon emblems, see the :doc:`Breeze icon guidelines `. +For symbolic icon emblems, see :doc:`/style/icons/emblem`. diff --git a/HIG/source/components/assistance/inline.rst b/HIG/source/components/assistance/inline.rst index d09ca73..1c1a3f5 100644 --- a/HIG/source/components/assistance/inline.rst +++ b/HIG/source/components/assistance/inline.rst @@ -1,165 +1,165 @@ Inline Message ============== .. container:: intend |desktopicon| |mobileicon| Purpose ------- A inline message is a small panel that informs users of a non-critical problem or special condition. It is embedded in the content and should not overlap content or controls. The panel has four visual style options which can be used for neutral messages, success conditions, warnings, and errors. It can also be given buttons. .. figure:: /img/Message5.png :alt: Different levels of inline messages. :scale: 80% The four different levels of inline messages. Examples -------- .. figure:: /img/Message-example.png :alt: An inline message is used for feeback after an upload has been completed. Guidelines ---------- - Use inline messages in cases of non-critical problems that user can solve. - Use :iconred:`negative feedback` (aka error) as a secondary indicator of failure, e.g. if a transaction was not completed successfully. - Show the information on a warning level in case of relevant information that does not concern the current workflow, e.g. No Internet connection available. - Use :noblefir:`positive feedback` to notify about user-initiated processes, e.g. to indicate completion of background tasks. - Use :plasmablue:`opportunistic interaction` (aka notification) to acknowledge the user about options that he or she might be interested in, e.g. "Remember password?" - Display the information immediately. - When users dismiss the inline message, don't display any other UI or start any other side effect. - Don't add controls to the inline message other than action buttons for opportunistic interaction. -- Consider to show a :doc:`notification` if information does not concern - the current workflow. +- Consider to show a :doc:`notification ` if + information does not concern the current workflow. Is this the right control? / Behavior ------------------------------------- Negative Feedback ~~~~~~~~~~~~~~~~~ The inline message should be used as a secondary indicator of failure: the first indicator is for instance that the action the user expected to happen did not happen. Example: User fills a form, clicks "Submit". - Expected feedback: form closes - First indicator of failure: form stays there - Second indicator of failure: a inline message appears on top of the form, explaining the error condition When used to provide negative feedback, an inline message should be placed close to its context. In the case of a form, it should appear on top of the form entries. An inline message should get inserted in the existing layout. Space should not be reserved for it, otherwise it becomes "dead space", ignored by the user. An inline message should also not appear as an overlay to prevent blocking access to elements the user needs to interact with to fix the failure. When used for negative feedback, don't offer a close button. The message panel only closes when the problem it informs about (e.g. the error) is fixed. Positive Feedback ~~~~~~~~~~~~~~~~~ An inline message can be used for positive feedback but it should not be overused. It is often enough to provide feedback by simply showing the results of an action. Examples of acceptable uses: - Confirm success of "critical" transactions - Indicate completion of background tasks Example of wrong uses: - Indicate successful saving of a file - Indicate a file has been successfully removed Opportunistic Interaction ~~~~~~~~~~~~~~~~~~~~~~~~~ Opportunistic interaction is the situation where the application suggests to the user an action he could be interested in perform, either based on an action the user just triggered or an event which the application noticed. Example use cases: - A browser can propose remembering a recently entered password - A music collection can propose ripping a CD which just got inserted - A chat application may notify the user a "special friend" just connected Appearance ---------- A basic inline messages consists of an icon and text. It can contain an optional close button and :doc:`buttons <../navigation/pushbutton>`. .. figure:: /img/Message1.png :alt: Inline message with a custom icon and a close button. :scale: 80% Inline message with a custom icon and a close button. .. figure:: /img/Message2.png :alt: Inline message with two buttons. :scale: 80% Inline message with two buttons. If there is not enough space to display all the buttons, an overflow menu is shown instead. .. figure:: /img/Message3.png :alt: Inline message with overflow menu. :scale: 80% Inline message with overflow menu. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: InlineMessage ` .. literalinclude:: /../../examples/kirigami/InlineMessage.qml :language: qml Qt Widgets ~~~~~~~~~~ - :kwidgetsaddonsapi:`QtWidgets: KMessageWidget ` diff --git a/HIG/source/components/editing/combobox.rst b/HIG/source/components/editing/combobox.rst index 0030a67..ddc14e8 100644 --- a/HIG/source/components/editing/combobox.rst +++ b/HIG/source/components/editing/combobox.rst @@ -1,93 +1,94 @@ Combo Box ========= .. figure:: /img/Combobox1.png :alt: Combobox :figclass: border A combination of a drop-down list and an edit control. Purpose ------- A combo box is a combination of a drop-down list and an edit control, thus allowing users to enter a value that is not in the list. It behaves like a drop-down list and allows the user to choose from a list of existing items but adds the option to type a value directly into the control. Newly typed items are usually added to the list and can be selected next time. Combo boxes are typically applied to provide auto-complete or auto-type functionality in a convenient way to the user. The list provides auto-complete feature for the whole string, independently of the "editable" property. Given the items of "bike", "boat", and "car": - If one types "b", the list selects "bike". - If one (rapidly) types "bo", it selects "boat". - If one types "c", it selects "car". The input field of the combo box ("editable" is true) marks the completed part of the item as selected, making it easy to change the completion. Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a combo box for single selection of one out of many items of lists that can be extended by the user. Prefer a simple :doc:`drop-down list ` in case of read-only interaction. -- Consider to replace the combo box by a :doc:`list view ` with a connected :doc:`edit control `. +- Consider to replace the combo box by a :doc:`list view ` with a + connected :doc:`line edit control `. Behavior ~~~~~~~~ - Show a maximum of eight items at once. - When possible apply changes immediately but don't initiate an action (like print, send, delete) when the user selects an item from the list. - Don't add controls to the drop-down (e.g. checkboxes for each item). - Place options that represent general options (e.g. all, none) at the beginning of the list. - Sort list items in a logical order. Make sure sorting fits translation. - Make sure the items are easily accessible via keyboard by moving distinctive letters to the beginning of each option. For example, in a list of countries on continents, write "Germany (Europe)" instead of "Europe/Germany". - Don't have blank list items; use meta-options, e.g. (None) instead. Appearance ~~~~~~~~~~ - Combo boxes are distinguished visually from drop-down lists (normally by the raised or lowered bevel). Don't override the common processing, e.g. by using a combo box and making it read only in order to simulate a simple drop-down list. - If activating a choice affects the appearance or the enabled state of other controls, place them next to the combo box. - If certain controls in a configuration dialog are only relevant if a certain item is selected (i.e. they are dependent controls), disable them instead of hiding. - Label the combo box with a descriptive caption to the left (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. - End each label with a colon. - Use :doc:`sentence style capitalization ` for items. Code ---- Kirigami ~~~~~~~~ - `QML: ComboBox `_ Plasma components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma ComboBox ` diff --git a/HIG/source/components/editing/grid.rst b/HIG/source/components/editing/grid.rst index 6ae84eb..e75c0a0 100644 --- a/HIG/source/components/editing/grid.rst +++ b/HIG/source/components/editing/grid.rst @@ -1,91 +1,91 @@ Grid ==== Like a table, a grid is a structure to distribute items into rows and columns. Unlike a table, a grid doesn't have a fixed structure; rather, the rows and columns are determent by the available space. .. figure:: /img/Wallpaper-dark.png :alt: Choose a new Plasma Design :scale: 40% Choose a new wallpaper Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ Like :doc:`lists `, Grids are used to display a sorted or unsorted set of items. All items should be of the same kind. Behavior ~~~~~~~~ Grids adjust the number of columns dynamically to distribute the items according to the available horizontal space without making the grid horizontally scrollable. Grids can be vertically scrollable though. .. raw:: html - Don't have blank grid items; use meta-options, e.g. (None) instead. - Place options that represent general options (e.g. All, None) at the beginning of the grid. - Sort grid items in a logical order. Make sure sorting fits translation. .. attention:: |devicon| For :doc:`accessibility ` make sure to test keyboard navigation with the grid. On-Demand Actions ^^^^^^^^^^^^^^^^^ Grid items can use the :doc:`on-demand pattern ` for inline actions. Picker ^^^^^^ Grids can be used for the :doc:`picker pattern `. Place a button below the grid to add items to the grid. To remove items from the grid, either add a remove action on the item, or give the user the possibility to select items and add a global remove button at the bottom of the grid. Ordering ^^^^^^^^ If the the order of the items can be changed by the user, permit re-ordering via drag-and-drop. Appearance ~~~~~~~~~~ - All items must be the same size. Item can change their size, either through user input or as a response to changes of the available space for the grid. - All rows, except the last one, must have the same number of items. - Use :doc:`sentence style capitalization ` for grid view items. Cards ^^^^^ See :doc:`cards ` for more information on how to use cards in a grid view. KCM ^^^ -Use the :doc:`KCMGrid ` for grids in KCMs. +Use the :doc:`KCMGrid ` for grids in KCMs. Code ---- Kirigami ~~~~~~~~ - `QML: GridView `_ diff --git a/HIG/source/components/navigation/globaldrawer.rst b/HIG/source/components/navigation/globaldrawer.rst index 5ea8583..a3e559a 100644 --- a/HIG/source/components/navigation/globaldrawer.rst +++ b/HIG/source/components/navigation/globaldrawer.rst @@ -1,110 +1,110 @@ Global Drawer ============= Purpose ------- The Global Drawer is a standard element in KDE mobile applications. It contains an application's main menu, and any functions which are not part of the application's main usecases but are not specific to the current context either. .. container:: intend |desktopicon| |mobileicon| .. container:: available plasma qwidgets |nbsp| .. figure:: /img/Globaldrawer1.png :alt: Global drawer on mobile :figclass: border :scale: 40 % Global drawer on mobile Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: /img/Globaldrawer3.png :figclass: border :alt: Global drawer on desktop :scale: 40 % Global drawer on desktop Use a Global Drawer whenever your application has any functions which are not central enough to the application's main purpose to put them in the main user interface, and which are not dependent on the current context. For context-specific actions (e.g. those affecting a selected item), use the :doc:`Context Drawer ` Behavior ~~~~~~~~ .. figure:: /img/Globaldrawer2.png :alt: Global drawer on desktop :scale: 40 % :figclass: border Hamburger button on the toolbar on desktop. The Global Drawer is either opened by clicking on the hamburger button on the toolbar or by swiping from the left edge of the screen. It can be closed by swiping in the other direction, clicking the close button or tapping outside of it. A Global Drawer may contain the following controls: - :doc:`Tabs ` - A main menu - :doc:`Push Buttons ` to execute non-contextual actions - :doc:`Checkboxes <../editing/checkbox>` or :doc:`Radio Buttons <../editing/radiobutton>` to change settings which are commonly changed The main menu - Must not have more than three levels - Should if possible not contain more elements than fit on the screen -- Should contain an entry :doc:`Settings ` in the last position if the - application has settings which are not commonly changed +- Should contain an entry :doc:`Settings ` in the last + position if the application has settings which are not commonly changed - Selecting an entry in the menu either executes an action or goes down one level, replacing the menu with the items in the selected submenu - In lower menu levels, below the entries there is a button to go up one level. Don't use the Menu Drawer for navigation purposes. |desktopicon| Collapsible """"""""""""""""""""""""" On the desktop, if the elements in the Global Drawer need to be accessed more often and enough space is available, the Global Drawer can default to showing a collapsed state, where the labels disappear but all actions continue to be available via icons-only ToolButtons. Pressing the hamburger menu button expands the Global Drawer to its full width and shows the actions' text labels. Pressing the close button or anywhere outside of it collapses it to its collapsed icons-only state. .. raw:: html Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: GlobalDrawer ` .. literalinclude:: /../../examples/kirigami/AddressbookGlobalDrawer.qml :language: qml diff --git a/HIG/source/components/navigation/menubar.rst b/HIG/source/components/navigation/menubar.rst index 4a0efe2..5e9423f 100644 --- a/HIG/source/components/navigation/menubar.rst +++ b/HIG/source/components/navigation/menubar.rst @@ -1,90 +1,90 @@ Menu Bar ======== Purpose ------- A menu bar appears at the top of an application's main window. It provides access to all commands and most of the settings available in an application. Users refer frequently to the menu bar, especially when they are seeking a function for which they know of no other interface. Ensuring that menus are well organized, are worded clearly, and behave correctly is crucial to the user’s ability to explore and access the functionality of the application. Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ - A menu bar is mandatory for applications that have a :doc:`very complex command structure `, such as those used for content creation or editing, file manipulation, or other productivity work. - Menu bars are optional for simple apps that are able to expose all functionality using visible buttons and toolbars. If any functionality is not visible by default, err on the side of providing a menu bar. - Don't display a menu bar in secondary or internal windows, like the settings dialog or file dialog. Very small main windows are likewise usually poor candidates for menu bars. - Don't include a menu bar in a convergent application's mobile user interface. Behavior ~~~~~~~~ - Don't have more than nine menu categories within a menu bar. Too many categories are overwhelming and makes the menu bar difficult to use. - At the minimum, all windows should have File, Edit, Settings, and Help menus. If they apply, the window can also have View, Insert, Format, Tools and, Window menus. - Don't put more than 12 items within a single level of a menu. Add separators between logical groups within a menu. Organize the menu items into groups of seven or fewer strongly related items. - Assign shortcut keys to the most frequently used menu items. Use `KStandardAction `_ and `KStandardShortcut `_ items for common functions, which will result in menu items automatically receiving consistent names, icons, and shortcut keys. Any tool or function that is accessible using a keyboard shortcut must have an item in the menu bar so that users can discover it. - Don't hide the menu bar by default. If this is configurable, users should easily be able to make the menu bar viewable again. - Use submenus cautiously. Submenus add complexity to the interface and are physically more difficult to use, so you should take care not to overuse them. Appearance ~~~~~~~~~~ - Place the most frequently used items at the top of the menu. - Provide icons for all menu items. Don't re-use the same icon for multiple items. - For your menu items' text, follow the :doc:`general label guidelines `. - Don't change menu items' labels dynamically. - Choose single word names for menu categories. Using multiple words makes the separation between categories confusing. - Disable menu items that don't apply to the current context instead of removing them from view. **Exception:** It is acceptable to hide menu items completely if they are permanently unavailable on the user's system due to missing hardware capabilities. -- Assign :doc:`shortcut keys ` to the most frequently used menu items +- Assign shortcut keys to the most frequently used menu items (Ctrl+). For well-known shortcut keys, use standard assignments. Use function keys for commands that have a small-scale effect (F2 = Rename) and ctrl key for large-scale effect (Ctrl+S = Save). - For menu items that toggle some state on or off, always use the positive form. For example, use the text 'Show hidden files' instead of 'Hide hidden files', and don't change the text when hidden files are shown. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: ApplicationWindow ` - `QML: MenuBar `_ .. literalinclude:: /../../examples/kirigami/AddressbookMenubar.qml :language: qml diff --git a/HIG/source/components/navigation/toolbar.rst b/HIG/source/components/navigation/toolbar.rst index 0e2485f..0893f47 100644 --- a/HIG/source/components/navigation/toolbar.rst +++ b/HIG/source/components/navigation/toolbar.rst @@ -1,123 +1,124 @@ Toolbar ======= .. figure:: /img/Toolbar1.png :figclass: border :alt: Primary Action Buttons on Desktop Toolbar with the most important actions :doc:`toolbar ` and an overflow menu Purpose ------- A *toolbar* is a graphical presentation of commands optimized for fast access. A toolbar can be either be defined for a whole application or as part of another component. As an application toolbar it contains buttons that correspond to items in the application's menu, providing direct access to application's most frequently used functions. A good menu bar is a comprehensive catalog of all the available top-level commands, whereas a good toolbar gives quick, convenient access to frequently used commands. As part of another component, like a card or an inline mesage, it is used to allow quick access to the most important commands for a single, focused content item. Guidelines for Applications --------------------------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ - For standard applications, show a toolbar by default. - Provide a toolbar in addition to the menu bar, but don't replace the menu bar. Behavior ~~~~~~~~ - A toolbar should contain only a few frequently used operations. If the number of operations is above 5 they have to be grouped with separators. Not more than 3 of those sections should be implemented. - Don't abuse the toolbar to expose hidden or esoteric features. Only the most frequently-used functions should be accessible from the toolbar. - Execute operations immediately; don't require additional input. - Try to avoid using :doc:`split buttons ` or :doc:`toggle buttons <../editing/togglebutton>` in order to keep the interaction with all buttons in the toolbar consistent. - Don't hide toolbars by default. If a toolbar can be hidden, users should easily be able to make the toolbar viewable again. - Disable buttons that don't apply to the current context. - Consider making toolbar content and position customizable. - Provide both a label and an icon for actions. Guidelines for Components ------------------------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a toolbar only if an item has few actions or few frequently used actions. - Embed a toolbar only in another control that is clearly visually seperated like a card or an inline message. Behavior ~~~~~~~~ - A toolbar should contain only a few, frequently used operations. The number of operations should not exceed 3. - Don't group with separators. - Execute operations immediately; don't require additional input. - Don't hide toolbars or make them configurable. - Toolbars can be responsive. If there is not enough space to display all the buttons, an overflow menu is shown instead. .. raw:: html Appearance ---------- - Don't change the button style from the default, which is :doc:`text beside icons `. - Use and design toolbar icons with special care. Users remember location of an object but rely as well on icon properties. - A distinct association between the underlying function and its visual - depiction is crucial. Follow the advices for :doc:`icon design `. + depiction is crucial. Follow the advices for :doc:`icon design + `. - Don't simulate Microsoft's ribbon controls. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: Action ` - :kirigamiapi:`Kirigami: ScrollablePage ` - :kirigamiapi:`Kirigami: ActionToolBar ` Application Toolbar """"""""""""""""""" .. literalinclude:: /../../examples/kirigami/ApplicationToolbar.qml :language: qml Component Toolbar ^^^^^^^^^^^^^^^^^ .. literalinclude:: /../../examples/kirigami/ComponentToolbar.qml :language: qml Plasma Components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma ToolBar ` diff --git a/HIG/source/conf.py b/HIG/source/conf.py index d167ed2..e2482ad 100644 --- a/HIG/source/conf.py +++ b/HIG/source/conf.py @@ -1,226 +1,226 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # # KDE HIG documentation build configuration file, created by # sphinx-quickstart on Tue Feb 6 13:29:47 2018. # # This file is execfile()d with the current directory set to its # containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. # # All configuration values have a default; values that are commented out # serve to show the default. # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # import os import sys sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../..')) # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. # # needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = ['sphinx.ext.todo', 'sphinxcontrib.doxylink'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The master toctree document. master_doc = 'index' # General information about the project. project = 'Human Interface Guidelines' copyright = '2019, KDE. Licensed under Creative Commons License SA 4.0' author = 'KDE' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. version = '' # The full version, including alpha/beta/rc tags. release = '' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. from globalconf import html_theme_options # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. # # This is required for the alabaster theme # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars html_sidebars = { '**': [ 'relations.html', # needs 'show_related': True theme option to display 'searchbox.html', ] } # -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. htmlhelp_basename = 'KDEHIGdoc' # -- Options for LaTeX output --------------------------------------------- latex_elements = { # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. # # 'preamble': '', # Latex figure (float) alignment # # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'KDEHIG.tex', 'KDE HIG Documentation', 'KDE', 'manual'), ] # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ (master_doc, 'kdehig', 'KDE HIG Documentation', [author], 1) ] # -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ (master_doc, 'KDEHIG', 'KDE HIG Documentation', author, 'KDEHIG', 'One line description of project.', 'Miscellaneous'), ] # Adding common substitions between Kirigami and HIG from epilog import rst_epilog # Adding global substitutions rst_epilog += """ .. |devicon| image:: /img/DevIcon.svg :width: 32px :height: 32px .. |designicon| image:: /img/DesignerIcon.svg :width: 32px :height: 32px .. |touchicon| image:: /img/transform-browse.svg :width: 32px :height: 32px .. |desktopicon| image:: /img/computer.svg :width: 32px :height: 32px .. |mobileicon| image:: /img/smartphone.svg :width: 32px :height: 32px .. |br| raw:: html
.. |nbsp| raw:: html   """ from globalconf import get_doxylink doxylink = get_doxylink() rst_prolog = """ .. role:: iconred .. role:: plasmablue .. role:: noblefir .. role:: intend """ # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { - 'kirigami': ('https://kirigami.kde.org/', None), + 'kirigami': ('https://kirigami.kde.org', None), 'pm': ('https://docs.plasma-mobile.org', None) } # add css file def setup(app): app.add_stylesheet('css/breeze.css') app.add_javascript('js/custom.js') diff --git a/HIG/source/index.rst b/HIG/source/index.rst index 9b76940..ec43bdd 100644 --- a/HIG/source/index.rst +++ b/HIG/source/index.rst @@ -1,86 +1,86 @@ .. KDE HIG documentation master file, created by sphinx-quickstart on Tue Feb 6 13:29:47 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. KDE Human Interface Guidelines ============================== .. toctree:: :titlesonly: :hidden: introduction/index layout/index style/index components/index patterns/command/index patterns/content/index patterns/navigation/index accessibility/index - plattform/index + platform/index resources/about resources/contribute resources/media resources/glossary .. Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` The KDE Human Interface Guidelines (HIG) offer designers and developers a set of recommendations for producing beautiful, usable, and consistent user interfaces for convergent desktop and mobile applications and workspace widgets. Their aim is to improve the experience for users by making application and widget interfaces more consistent and hence more intuitive and learnable. .. figure:: /img/HIGDesignVisionFullBleed.png :scale: 50 % :alt: Different DPIs on desktop and mobile ''Simple by default, powerful when needed.'' Design Vision ------------- KDE's design vision focuses on two attributes of KDE software that connect its future to its history: **Simple by default...** ^^^^^^^^^^^^^^^^^^^^^^^^ *Simple and inviting. KDE software is pleasant to experience and easy to use.* - **Make it easy to focus on what matters** — Remove or minimize elements not crucial to the primary or main task. Use spacing to keep things organized. Use color to draw attention. Reveal additional information or optional functions only when needed. - **I know how to do that!** — Make things easier to learn by reusing design patterns from other applications. Other applications that use good design are a precedent to follow. - **Do the heavy lifting for me** — Make complex tasks simple. Make novices feel like experts. Create ways in which your users can naturally feel empowered by your software. **...Powerful when needed** ^^^^^^^^^^^^^^^^^^^^^^^^^^^ *Power and flexibility. KDE software allows users to be effortlessly creative and efficiently productive.* - **Solve a problem** — Identify and make very clear to the user what need is addressed and how. - **Always in control** — It should always be clear what can be done, what is currently happening, and what has just happened. The user should never feel at the mercy of the tool. Give the user the final say. - **Be flexible** — Provide sensible defaults but consider optional functionality and customization options that don't interfere with the primary task. .. note:: Note: KDE encourages developing and designing for customization, while providing good default settings. Integrating into other desktop environments is also a virtue, but ultimately we aim for perfection within our own Plasma desktop environment with the default themes and settings. This aim should not be compromised. diff --git a/HIG/source/patterns/command/drawer.rst b/HIG/source/patterns/command/drawer.rst index 9fe9699..c3228d1 100644 --- a/HIG/source/patterns/command/drawer.rst +++ b/HIG/source/patterns/command/drawer.rst @@ -1,55 +1,53 @@ Drawers ======= Drawers don't take away any room from the content, but they do require user interaction to become visible, and should therefore not be used for controls that are part of an application's main tasks. Global Drawer ------------- .. figure:: /img/Globaldrawer1.png :alt: Global drawer :scale: 40 % :figclass: border Global drawer on mobile The global drawer is used for global, context-independent controls. - The drawer is opened by an edge-swipe (the side is system-defined) and closed by swiping in the other direction or tapping outside of the panel - For the guidelines regarding its content, see :doc:`global drawer `. Context Drawer -------------- .. figure:: /img/Contextdrawer1.png :alt: Context drawer :scale: 40 % :figclass: border Context drawer on mobile The context drawer (the side is system-defined) is used for context-specific controls that affect only the currently selected object (e.g. copy, delete etc.). - The drawer is opened by an edge-swipe and closed by swiping in the other direction or tapping outside of the panel - For the guidelines regarding its content, see the :doc:`context drawer `. Bottom Drawer and Dialog Sheet ------------------------------ .. image:: /img/Bottom_Drawer.png :alt: Bottom drawer :scale: 40 % -For a full modal dialog, use a -:doc:`dialog sheet `. -For a quick choice, use a -:doc:`bottom drawer `. +For a full modal dialog, use a dialog sheet. For a quick choice, use a bottom +drawer. diff --git a/HIG/source/patterns/content/form.rst b/HIG/source/patterns/content/form.rst index 0fe8ded..dcd5656 100644 --- a/HIG/source/patterns/content/form.rst +++ b/HIG/source/patterns/content/form.rst @@ -1,188 +1,188 @@ Form ==== A form layout is used to help align and structure a layout that contains many controls and input fields. When to Use ----------- - Use a Form layout when there are many related controls and input fields. -- Form layouts are often used for :doc:`settings `. +- Form layouts are often used for :doc:`settings `. How to Use ---------- - Use Qt's QFormLayout or Kirigami.FormLayout wherever possible. - Do not synthesize your own FormLayout-style layout using a grid. .. attention:: |devicon| If for some reason you must create your own FormLayout style layout without using one of the aforementioned controls, there are several very important things to take into account for :doc:`accessibility ` reasons"" - Form labels need to be connected with input fields. - Headlines for groupings need to be connected. - Make sure to test keyboard navigation with the form. - Ctrl + Tab should switch between logical groups of controls. - Make sure to set the focus to focused controls; don't just highlight them. Alignment ^^^^^^^^^ |desktopicon| Desktop """"""""""""""""""""" - On Desktop it is recommended to place the labels to the left of the connected widgets. Labels that are to the left of their connected widgets should be right-aligned and end with a colon (in case of right-to-left languages, mirror the alignment). This makes the whole group of form widgets appear to be center-aligned. In Qt 5, using a QFormLayout handles all of this for you automatically. - Align the form in the top center of the window or view in which it is located, but below the title. - See the pages on :doc:`radio buttons ` and :doc:`checkboxes ` for detailed information regarding how to align these tricky controls in a Form layout. .. container:: flex .. container:: .. figure:: /img/Form_Align_KDE3.png :scale: 80% :figclass: dont :iconred:`Don't.` |br| Don't use KDE3-style form alignment .. container:: .. figure:: /img/Form_Align_KDE5.png :scale: 80% :figclass: do :noblefir:`Do.` |br| Use Plasma 5-style form alignment. .. container:: flex .. container:: .. figure:: /img/Form_Align_OSX.png :scale: 80% :figclass: dont :iconred:`Don't.` |br| Don't use macOS-style form alignment. .. container:: .. figure:: /img/Form_Align_KDE5.png :scale: 80% :figclass: do :noblefir:`Do.` |br| Use Plasma 5-style form alignment. - Position groups of items vertically rather than horizontally, as this makes them easier to scan visually. Use horizontal or rectangular positioning only if it would greatly improve the layout of the window. - Left align controls over multiple groups. This visual anchor facilitates scanning of content, and left-hand alignment fits as well forms that have been oversized individually. .. container:: flex .. container:: .. figure:: /img/Form_Align_NO.png :scale: 80% :figclass: dont :iconred:`Don't.` |br| Don't misalign controls. .. container:: .. figure:: /img/Form_Align_YES.png :scale: 80% :figclass: do :noblefir:`Do.` |br| Align controls to the left. - Keep track of label sizes; avoid large differences in text length that could result in too much whitespace. Keep translation in mind too; existing length differences will be exaggerated for wordy languages such as German and Brazilian Portuguese. .. figure:: /img/Form_Align_Long.png :scale: 80% :figclass: dont :iconred:`Don't.` |br| Don't use very long captions. |mobileicon| Mobile and narrow space """""""""""""""""""""""""""""""""""" - For mobile, or if only a very small amount of horizontal space is available, it is recommended to place the labels above the connected widgets. - When using labels on top, labels and widgets should be left-aligned. .. image:: /img/Form_Align_YES_Mobile.png :scale: 80% Titles """""" .. figure:: /img/Settings-Notification-dark.png :alt: Notifications settings in a form layout :scale: 40% Notifications settings Spacing and Grouping ^^^^^^^^^^^^^^^^^^^^ Use :doc:`spacing ` to group and separate controls in your forms. .. figure:: /img/Form3.png Spacing used to create three groups of controls Alternatively, you can use separators for a stronger separation. .. figure:: /img/Form4.png Using a separator to group controls To create even stronger separation, you can add subtiles for groups of controls. Subtitles are left aligned with the longest label of their group. .. figure:: /img/Form5.png Alignment of subtitles Code ---- Kirigami ^^^^^^^^ - :kirigamiapi:`Kirigami: FormLayout ` .. literalinclude:: /../../examples/kirigami/FormLayout.qml :language: qml diff --git a/HIG/source/patterns/navigation/master.rst b/HIG/source/patterns/navigation/master.rst index 093e740..2b1406f 100644 --- a/HIG/source/patterns/navigation/master.rst +++ b/HIG/source/patterns/navigation/master.rst @@ -1,33 +1,36 @@ Master-Detail ============= .. container:: intend |desktopicon| |mobileicon| Pattern for a flat content structure. .. image:: /img/NP-flat-3a.png :alt: Master-Detail |desktopicon| Desktop --------------------- - These patterns are useful when multiple pieces of content are intended to be shown at once, alongside a larger, more complete presentation of the selected item. -- See the :doc:`wizard ` pattern guidelines for - more details on using that pattern. +- See the `draft for wizard pattern guidelines + `_ for + more details on using + that pattern. - Examples include a contact list that shows the full details of the selected contact, a slideshow with a "film-strip" to select photographs, or setup for newly installed software. + |mobileicon| Mobile ------------------- - The list - detail view pattern is useful when the user usually focuses on a single item in the list. - Tapping an item in the list shows its details in a new view - Use swipe left to go back to the list. - Use a swipe beyond the top/bottom of the content to jump to the previous/next item in the list. diff --git a/HIG/source/plattform/getnew.rst b/HIG/source/platform/getnew.rst similarity index 100% rename from HIG/source/plattform/getnew.rst rename to HIG/source/platform/getnew.rst diff --git a/HIG/source/plattform/index.rst b/HIG/source/platform/index.rst similarity index 96% rename from HIG/source/plattform/index.rst rename to HIG/source/platform/index.rst index e8a2135..9fb3ae9 100644 --- a/HIG/source/plattform/index.rst +++ b/HIG/source/platform/index.rst @@ -1,22 +1,22 @@ Platform -========= +======== .. toctree:: :titlesonly: :hidden: getnew kcmgrid notification settings tray This is an overview of how to integrate your application into the :doc:`Plasma Workspace `. * :doc:`getnew` * :doc:`kcmgrid` * :doc:`notification` * :doc:`settings` * :doc:`tray` diff --git a/HIG/source/plattform/kcmgrid.rst b/HIG/source/platform/kcmgrid.rst similarity index 100% rename from HIG/source/plattform/kcmgrid.rst rename to HIG/source/platform/kcmgrid.rst diff --git a/HIG/source/plattform/notification.rst b/HIG/source/platform/notification.rst similarity index 100% rename from HIG/source/plattform/notification.rst rename to HIG/source/platform/notification.rst diff --git a/HIG/source/plattform/settings.rst b/HIG/source/platform/settings.rst similarity index 100% rename from HIG/source/plattform/settings.rst rename to HIG/source/platform/settings.rst diff --git a/HIG/source/plattform/tray.rst b/HIG/source/platform/tray.rst similarity index 91% rename from HIG/source/plattform/tray.rst rename to HIG/source/platform/tray.rst index 2581acd..a1087e8 100644 --- a/HIG/source/plattform/tray.rst +++ b/HIG/source/platform/tray.rst @@ -1,43 +1,43 @@ System Tray Icon ================ The system tray provides quick access to functionality integrated into the workspace that’s both highly visible to the user and frequently changed, like enabling/disabling WiFi and Bluetooth, or whether or not to show notifications. See :doc:`architecture ` for an overview of plasma workspace components. Examples -------- .. figure:: /img/TrayWithPanel.png :alt: Tray icons with an open volume control panel. Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ An application should only add an icon to the System Tray if the user needs to frequently access the application, or if the user is intrested in status changes within the application. Behavior ~~~~~~~~ - On left click, open the application itself, or a panel that allows quick access to common features. - On right click, open a :doc:`context menu `. - For application like media players, enable the user to change the volume while scrolling over the icon. Appearance ~~~~~~~~~~ -Use a :doc:`monochrome, Shade Black, icon ` and use color only to -communicate state. +Use a :doc:`monochrome, shade black icon ` and use color +only to communicate state. diff --git a/HIG/source/resources/glossary.rst b/HIG/source/resources/glossary.rst index 3294030..1185e3d 100644 --- a/HIG/source/resources/glossary.rst +++ b/HIG/source/resources/glossary.rst @@ -1,43 +1,43 @@ Glossary ======== - **Human Interface Guidelines**, **HIG** A set of recommendations for designing and developing user interfaces for mobile, desktop, convergent applications and workspace widgets. - **User Interface**, **UI** In the field of human–computer interaction, the User Interface is the space where interactions between humans and machines occur. The goal of this interaction is to allow effective operation and control of the machine from the human end, whilst the machine simultaneously feeds back information that aids the operators' decision-making process. *Source*: ``_ - **User Experience**, **UX** UX refers to a person's emotions and attitudes about using a particular product, system or service. It includes the practical, experiential, affective, meaningful and valuable aspects of human–computer interaction and product ownership. Additionally, it includes a person’s perceptions of system aspects such as utility, ease of use and efficiency. User experience may be considered subjective in nature to the degree that it is about individual perception and thought with respect to the system. User experience is dynamic as it is constantly modified over time due to changing usage circumstances and changes to individual systems as well as the wider usage context in which they can be found. In the end, user experience is about how the user interacts with and experiences the product. *Source:*: ``_ - **Get New Stuff**, **GNS** - :doc:`/plattform/getnew` + :doc:`/platform/getnew` - **Aassistive technology**, **AT** Screen readers and other assistive technology is often refered as AT diff --git a/Kirigami/source/style/color.rst b/Kirigami/source/style/color.rst index 2b070e5..027680d 100644 --- a/Kirigami/source/style/color.rst +++ b/Kirigami/source/style/color.rst @@ -1,105 +1,107 @@ +.. _color: + Color ===== .. toctree:: :maxdepth: 2 :caption: Contents: Kirigami has a color palette that follow the system colors, to better integrate on the platform it is running on (i.e. Plasma Desktop, Plasma Mobile, GNOME, Android, etc.). All the default controls available as QML comoponents provided by Kirigami and all the components available in the QtQuickControls2 QML plugin will already follow this palette by default, so usually no custom coloring should be needed at all for those controls. Primitive components such as ``Rectangle`` should always be colored with the color palette provided by Kirigami via the ``Theme`` attached property. Hardcoded colors in QML, such as ``#32b2fa`` or ``red`` should usually be avoided; if it is really necessary to have elements with custom colors, it should be an area where only custom colors are used (usually in the content area of the app, and never in the chrome such as toolbars or dialogs), for instance an hardcoded "black" foreground cannot be used over a ``Kirigami.Theme.backgroundColor`` background, because if the platform uses a dark color scheme the result will bea poor contrasting black over almost black. Theme ----- For more information about the Kirigami Thmeme class, see the :kirigamiapi:`API docs `. ``Kirigami.Theme`` is an attached property, therefore is available to use in any QML item, it contains as properties all the colors available in the palette, and what palette to use, as the ``colorSet`` property. Example: .. literalinclude:: /../../examples/kirigami/UseTheme.qml :language: qml .. TODO:: screenshot of a qml file with an annotated UI showing all the available color Color Set ^^^^^^^^^ Depending where a control is, it should use a different color set: for instance, (with the Breeze light color theme) in itemviews, the normal background is almost white, while in other regions, such as toolbars or dialogs, the normal background color is gray. If you set a color set for an item, all of child items (as well as granchildren and so on) will inherit it automatically (unless the property ``inherit`` has explicitly been set to ``false``, which should always be done when the developer wants to force a specific color set) so it is easy to change colors for an entire hierarchy if items without touching any of the items themselves. ``Kirigami.Theme`` supports 5 different color sets: * View: Color set for item views, usually the lightest of all (in light color themes) * Window: **Default** Color set for windows and "chrome" areas * Button: Color set used by buttons * Selection: Color set used by selectged areas * Tooltip: Color set used by tooltips * Complementary: Color set meant to be complementary to Window: usually is dark even in light themes. may be used for "emphasis" in small areas of the application Example: .. literalinclude:: /../../examples/kirigami/UseColorsets.qml :language: qml Some components such as Labels will automatically inherit by default the color set, some other components have a fixed color set, for instance Buttons are fixed to the ``Button`` color set. If is desired for the button to inherit the parent color set, the inherit property should be explicitly set to true: .. literalinclude:: /../../examples/kirigami/InheritTheme.qml :language: qml .. TODO:: screenshot of a comparison between a button that inherits and one that does not Using Custom Colors ^^^^^^^^^^^^^^^^^^^ Altough is discouraged to use hardcoded colors, Kirigami offers a more maintainable way to assign a custom hardcoded palette to an item and all its children, that will allow to define such custom colors in one place and one only: .. literalinclude:: /../../examples/kirigami/CustomColors.qml :language: qml .. TODO:: Screenshot