Commit b01003b6 authored by Carson Black's avatar Carson Black Committed by Nate Graham

General HIG polishing - writing style, formatting bugs, image tweaks, etc.

parent 5ab1cad1
......@@ -4,3 +4,4 @@ build
*.jsc
/__pycache__
*.tags
.vscode
\ No newline at end of file
Accessibility checklist
Accessibility Checklist
=======================
Introduction
......@@ -7,7 +7,7 @@ Introduction
This is a list of common things you should check for to have great
:doc:`accessibility <index>` for your application or widgets.
Keyboard navigation
Keyboard Navigation
-------------------
- Efficient keyboard access is provided for all application features.
......@@ -33,7 +33,7 @@ Keyboard navigation
Testing
^^^^^^^
The following keyboard operations should be tested. Do not use the mouse in any
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
......@@ -48,7 +48,7 @@ part of this test.
- Any keyboard enhancements or shortcuts are working as designed.
Mouse interaction
Mouse Interaction
-----------------
- No operations depend on input from the right or middle mouse buttons.
......@@ -57,7 +57,7 @@ Mouse interaction
- The mouse pointer is never moved by the application, or its
movement restricted to part of the screen by the application.
Graphical elements
Graphical Elements
------------------
- There are no hard-coded graphical attributes such as line, border or
......@@ -80,7 +80,7 @@ Test the application using a screen reader and confirm that:
- Object information is read correctly.
Fonts and text
Fonts and Text
--------------
- No font styles or sizes are hard-coded.
......@@ -109,7 +109,7 @@ Testing
magnification option.
Color and contrast
Color and Contrast
------------------
- Application colors are not hard-coded, but either use colors from
......@@ -189,7 +189,7 @@ designed.
Turn the animation off. Confirm that all information is still conveyed
correctly.
Keyboard focus
Keyboard Focus
--------------
- When a window is opened, focus starts at the most commonly-used control.
......@@ -201,7 +201,7 @@ Keyboard focus
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.
- 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.
......
......@@ -28,8 +28,8 @@ usability for all users.
Fonts and Colors
----------------
Many users have some deficiencies when it comes to seeing. This doesn't always
mean that they are blind. For some people it is enough when
Many users have some deficiencies when it comes to seeing. This does not always
mean that they are blind. For some people it's enough when
:doc:`fonts </style/typography>` are clear and the
:doc:`color scheme </style/color/index>` can be adjusted. This is something
every application should do in any case, so here is the list:
......@@ -50,7 +50,7 @@ Keyboard
--------
When you have problems seeing, the mouse is quite hard to use. The keyboard is a
lot more reliable. Therefor it is important that applications can be used with
lot more reliable. Therefore it is important that applications can be used with
the keyboard. For some users, using a mouse is difficult because of motor skill
issues. Making applications keyboard accessible benefits everyone, since it
allows us to use shortcuts to use the applications more efficiently.
......@@ -105,10 +105,10 @@ and an "Accessible Description". The name is short, for example the label on a
button. It should always be short. The description on the other hand is the more
verbose "this button does foo and then bar". Qt will try hard to return
something for the name. In case of a button, usually the text on the button is
returned. But if your button has text that makes only sense when seeing the
arrangement of buttons, or only has an image as label, you need to help the AT
returned. But if your button has text that only makes sense when seeing the
arrangement of buttons, or only has an image as label, then you need to help the AT
read the button. If you don't, it will only say the type of the widget, "Button"
is not a very helpful information.
which is not very helpful information.
Fixing Accessible Name and Description
......@@ -118,8 +118,8 @@ Fire up Qt designer if the app uses .ui files. You'll find the properties and
can type the name/description right in. After saving the file, rebuild and
install the application. You are done, submit a patch to fix the ui file.
If the widget is created in the code, just need to find where. Once you found
the widget, usually where it's created, add some code to it:
If the widget is created in the code, you just need to find where it's initialized.
Once you find it (usually where it's created), add some code to it:
.. code-block:: c++
......
......@@ -4,7 +4,7 @@ Emblem
Purpose
-------
An *emblem* displays unusual or non-default status information about an icon
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.
......@@ -28,7 +28,7 @@ Guidelines
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. Do not use
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
......@@ -38,7 +38,7 @@ Guidelines
in a clockwise order.
- Emblems that indicate unread notifications should be located in the
top-right corner.
- Use the minimum number of emblems and do not overwhelm the icon itself.
- Use the minimum number of emblems and don't overwhelm the icon itself.
Three is usually too many.
Appearance
......
User assistance
User Assistance
===============
.. toctree::
......
Inline message
Inline Message
==============
.. container:: intend
......@@ -9,7 +9,7 @@ Inline message
Purpose
-------
A *inline message* is a small panel that informs users of a non-critical problem
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
......@@ -35,21 +35,23 @@ Guidelines
- Use inline messages in cases of non-critical problems that user can
solve.
- Use *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 do not concern the current workflow, e.g. No
Internet connection available.
- Use *positive feedback* to notify about user-initiated processes,
e.g. to indicate completion of background tasks
- Use *opportunistic interaction* (aka notification) to acknowledge
- 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, do not display any other UI or start
- When users dismiss the inline message, don't display any other UI or start
any other side effect.
- Do not add controls to the inline message other than action buttons
- 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.
......@@ -57,7 +59,7 @@ Guidelines
Is this the right control? / Behavior
-------------------------------------
Negative feedback
Negative Feedback
~~~~~~~~~~~~~~~~~
The inline message should be used as a secondary indicator of failure:
......@@ -81,14 +83,14 @@ 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, do not offer a close button. The
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
Positive Feedback
~~~~~~~~~~~~~~~~~
An inline message can be used for positive feedback but it shouldn't be
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.
......@@ -102,7 +104,7 @@ Example of wrong uses:
- Indicate successful saving of a file
- Indicate a file has been successfully removed
Opportunistic interaction
Opportunistic Interaction
~~~~~~~~~~~~~~~~~~~~~~~~~
Opportunistic interaction is the situation where the application
......
Modal message dialog
Modal Message Dialog
====================
Purpose
......@@ -6,7 +6,7 @@ Purpose
If the processing has reached an unexpected or potentially dangerous condition,
the user must make a decision. The correct presentation for this kind of
disruptive question is a *modal message dialog*: a secondary window that
disruptive question is a modal message dialog: a secondary window that
interrupts user's current activity and blocks interaction until the user decides
how to proceed.
......@@ -14,17 +14,11 @@ Use modal message dialogs sparingly. Users will learn to reflexively dismiss
commonly-encountered modal message dialog without even reading them, defeating
the purpose.
Examples
--------
Guidelines
----------
Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~
Is this the right control?
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Use modal message dialogs only for critical or infrequent tasks that require
completion before continuing. Avoid disrupting the user; workflow maintenance
and, therefore, the prevention of errors should be the primary objective.
......@@ -35,7 +29,7 @@ Is this the right control
Behavior
~~~~~~~~
- Dialogs should be modal, and block user interaction with the rest of the
application until a choice has been made. Do not block the entire user
application until a choice has been made. Don't block the entire user
interface for the whole system, though.
- Create specific, actionable, user-centered error messages. Users should
either perform an action or change their behavior as a result.
......
Progress indicator
Progress Indicator
==================
Purpose
-------
If a foreground task lasts longer than expected or when calculation
takes some time a *feedback on progress* should be given by the system.
takes some time, the system should provide some feedback on the task's progress.
Users are aware of response times of over one second and shorter.
Consequently, operations that take two seconds or longer to complete
should be considered to be lengthy and need of some type of progress
feedback. But even in cases of short delays the user should be assured
that the system is not hung or waiting for user input. Such a feedback
is done by changing the mouse cursor to a *busy pointer* (aka throbber
is done by changing the mouse cursor to a busy pointer (aka throbber
or spinner). When operation lasts longer the user should be able to
anticipate when it’s finished. The appropriate graphical control for
this task is a *progress bar*.
Examples
--------
this task is a progress bar.
Guidelines
----------
Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~
Is this the right control?
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Provide progress feedback when performing a lengthy operation. Users
should never have to guess if progress is being made.
......
Status bars
Status Bars
===========
Purpose
-------
A *status bar* is an area at the bottom of a primary window that
A status bar is an area at the bottom of a primary window that
displays information about the current window's state, background tasks,
or other contextual information.
......@@ -14,31 +14,31 @@ favor of maximized space for content.
Guidelines
----------
Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~
Is this the right control?
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Omit the status bar in the main window to maximize vertical space for
content.
- Do not show meaningless information like 'Ready'.
- Don't show meaningless information like 'Ready'.
- Use a floating panel or :doc:`tooltips <tooltip>` for short-term status
information like full length text of links.
- Move controls to the toolbar.
- If you cannot find good replacements for status bar functions,
please ask the usability team for support.
- Do not display a status bar in secondary or internal windows.
- Don't display a status bar in secondary or internal windows.
- If a status bar is really necessary in your application consider to
use a :doc:`toolbar <../navigation/toolbar>` with all customization features.
Behavior
~~~~~~~~
- Do not use the status bars or any kind of replacement for crucial
- Don't use the status bars or any kind of replacement for crucial
information. Users should never have to know what is in the status
bar.
- Do not use the status bar or any kind of replacement to display
- Don't use the status bar or any kind of replacement to display
advisory messages in place of standard :doc:`tooltips <tooltip>`.
- Keep the status information plain; e.g. do not add icons.
- Keep the status information plain; e.g. don't add icons.
.. for more info see http://user-prompt.com/what-is-a-status-bar-good-for/
......@@ -4,7 +4,7 @@ Tooltip
Purpose
-------
A *tooltip* is a small pop-up window that provides more information on
A tooltip is a small pop-up window that provides more information on
an element under the mouse cursor, such as toolbar controls without
caption or command buttons. Tooltips provide additional descriptive text
including formatting and icons. Tips eliminate the need to always have
......@@ -17,8 +17,8 @@ expectation and foster predictability.
Guidelines
----------
Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~
Is this the right control?
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Use tips to label unlabeled controls and to provide additional
information.
......@@ -49,7 +49,7 @@ Appearance
self-explanatory control labels or in-place supplemental text
- static: tips should not change from one instance to the next
- Do not use icons and formattings for tips of unlabeled controls.
- Don't use icons and formattings for tips of unlabeled controls.
- Use tool-tips with icons and formatting
- if tips describe comprehensive functions,
......
......@@ -7,14 +7,11 @@ Purpose
A card serves as overview and an entry point for more detailed information and can
offer direct access to the most important actions on an item.
Example
-------
Guidelines
----------
Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~
Is this the right control?
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Don't use a card to display long texts.
- Cards can be used to display items with different content types, e.g. images
......@@ -38,7 +35,7 @@ space.
.. raw:: html
<video src="https://cdn.kde.org/hig/video/20180620-1/CardLayout1.webm" loop="true" playsinline="true" width="536" controls="true" onended="this.play()" class="border"></video>
<video autoplay controls src="https://cdn.kde.org/hig/video/20180620-1/CardLayout1.webm" loop="true" playsinline="true" width="536" onended="this.play()" class="border"></video>
It is recommended that you adjust the number of cards displayed next to each other
......@@ -46,7 +43,7 @@ depending on the available space.
.. raw:: html
<video src="https://cdn.kde.org/hig/video/20180620-1/CardLayout2.webm" loop="true" playsinline="true" width="536" controls="true" onended="this.play()" class="border"></video>
<video autoplay controls src="https://cdn.kde.org/hig/video/20180620-1/CardLayout2.webm" loop="true" playsinline="true" width="536" onended="this.play()" class="border"></video>
|mobileicon| Mobile
^^^^^^^^^^^^^^^^^^^
......@@ -61,9 +58,9 @@ It is recomended that you use the standard card layout for consistency, but card
a lot of different layouts.
.. figure:: /img/Card6.qml.png
:alt: Default card layout
:alt: Default card layout with a header image, text content, and optional actions.
Default card layout with a header image, text content and optional actions.
Default card layout with a header image, text content, and optional actions.
The only common requirement is the container around it. While cards can have a lot of
different layouts, each should focus only on one bit of information or content.
......@@ -75,15 +72,19 @@ Here are some general recommendations for card layouts:
- Use a well known aspect ratio for a header image
.. image:: /img/Card5.qml.png
:alt: Cards with 16x9, 4x3, 1x1 header image aspect ratio
.. figure:: /img/Card5.qml.png
:alt: Cards with 16×9, 4×3, 1×1 header image aspect ratio.
Cards with 16×9, 4×3, 1×1 header image aspect ratio.
- Add a padding of at least largeSpacing to the card, except for videos
and images. These can ignore the padding and span the entire width or
height of a card.
.. image:: /img/Card2.qml.png
:alt: Padding for text and buttons
.. figure:: /img/Card2.qml.png
:alt: Padding for text and buttons.
Padding for text and buttons.
Code
----
......
......@@ -4,20 +4,17 @@ Checkbox
Purpose
-------
A *checkbox* is a control that permits the user to make multiple
A checkbox is a control that permits the user to make multiple
selections from a number of options. Checkboxes are used to toggle an
option on or off, or to select or deselect an item. Users make a
decision between two clearly opposite choices, e.g. 'on vs. off', 'apply
vs. don't apply', 'show vs. hide'.
Example
-------
Guidelines
----------
Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~
Is this the right control?
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Use checkboxes for non-exclusive options that have clear
alternatives. Mutually exclusive options should use a set of
......@@ -30,22 +27,22 @@ Is this the right control
.. figure:: /img/Ambiguous_Opposite_Bad.qml.png
:figclass: border
:iconred:`BAD` |br|
Do not use a checkbox if the opposite is ambiguous.
:iconred:`Don't.` |br|
Don't use a checkbox if the opposite is ambiguous.
.. container::
.. figure:: /img/Ambiguous_Opposite_Good.qml.png
:figclass: border
:noblefir:`GOOD` |br|
Using two radio buttons removes the need to guess.
:noblefir:`Do.` |br|
Use two radio buttons to remove the need to guess.
- For more than five options, use either a :doc:`list view <list>` or
the :doc:`dual-list pattern </patterns/content/duallist>` in case of
multiple selections.
- Do not use the selection to perform commands.
- Don't use the selection to perform commands.
.. container:: flex
......@@ -54,15 +51,15 @@ Is this the right control
.. figure:: /img/No_Command_2_Bad.qml.png
:figclass: border
:iconred:`BAD` |br|
Do not use the selection to perform commands.
:iconred:`Don't.` |br|
Don't use the selection to perform commands.
.. container::
.. figure:: /img/No_Command_2_Good.qml.png
:figclass: border
:noblefir:`GOOD` |br|
:noblefir:`Do.` |br|
Consider using a :doc:`push button <../navigation/pushbutton>` instead.
Behavior
......@@ -79,14 +76,16 @@ Behavior
.. figure:: /img/Checkbox_Enable_Bad.qml.png
:figclass: border
:iconred:`BAD`
:iconred:`Don't.` |br|
Don't use checkboxes for negatives.
.. container::
.. figure:: /img/Checkbox_Enable_Good.qml.png
:figclass: border
:noblefir:`GOOD`
:noblefir:`Do.` |br|
Use checkboxes for positives.
- Use the mixed state only to indicate that an option is set for some,
but not all, child objects. Mixed state must not be used to represent
......@@ -98,7 +97,7 @@ Behavior
- Users must not be able to set a mixed state directly.
- Clicking a mixed state checkbox enables all child objects.
- Do not use sliding switches in Desktop applications. They only offer
- Don't use sliding switches in Desktop applications. They only offer
good user interaction on touch screens, so they should only be used
in applications for mobile devices.
......@@ -108,19 +107,21 @@ Behavior
.. figure:: /img/Checkbox_Switch_Desktop.qml.png
:iconred:`BAD`
:iconred:`Don't.` |br|
Don't use sliding switches on desktop.
.. container::
.. figure:: /img/Checkbox_Switch_Mobile.qml.png
:noblefir:`GOOD`
:noblefir:`Do.` |br|
Do use sliding switches on mobile.
Appearance
~~~~~~~~~~
If you are using qt widgets you should use one of Qt's Layout Classes
like , that will take care of lay outing and spacing of your controls.
If you are using Qt Widgets you should use one of Qt's Layout classes,
which will take care of the layout and spacing of your controls.
- The text of a checkbox is on the right of its tick rectangle, which
can make it difficult to avoid blank areas on the left side of the
......@@ -166,14 +167,9 @@ like , that will take care of lay outing and spacing of your controls.
- If certain controls in a configuration dialog are only relevant if a
certain checkbox is checked (i.e. they are dependent controls),
disable them instead of hiding them if that checkbox is unchecked.
- Do not separate checkbox and label. Clicking on both the box and the
- Don't separate checkbox and label. Clicking on both the box and the
label should toggle the option.
.. image:: /img/HIG_Checkbox5.png
:alt: Separate checkbox and label
- Do not add line breaks. If necessary place an additional label below
- Don't add line breaks. If necessary, place an additional label below
the checkbox.
.. container:: flex
......@@ -181,22 +177,24 @@ like , that will take care of lay outing and spacing of your controls.
.. container::
.. figure:: /img/Checkbox_Alignment_Bad.qml.png
:figclass: border
:iconred:`BAD`
:iconred:`Don't.` |br|
Don't use linebreaks in a checkbox's label.
.. container::
.. figure:: /img/Checkbox_Alignment_Good.qml.png
:figclass: border
:noblefir:`GOOD`
:noblefir:`Do.` |br|
Add another label if more explanation is required.
- Label a group of checkbox with a descriptive caption to the top left
of the group (cf. :doc:`alignment </layout/alignment>`).
- Create a buddy relation so access keys are assigned.
- Use :doc:`sentence style capitalization </style/writing/capitalization>`
for checkbox items.
- Do not use ending punctuation (neither dot nor colon) for group
label.
Code
----
......
Combo box
Combo Box
=========
.. figure:: /img/Combobox1.png
......@@ -11,8 +11,8 @@ Combo box
Purpose
-------
A *combo box* is a combination of a drop-down list and an edit control,
thus allowing users to enter a value that isn't in the list. It behaves
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
......@@ -35,8 +35,8 @@ completion.
Guidelines
----------
Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~
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 <dropdown>` in case of read-only interaction.
......@@ -46,10 +46,10 @@ Behavior
~~~~~~~~
- Show a maximum of eight items at once.
- When possible apply changes immediately but do not initiate an action
- When possible apply changes immediately but don't initiate an action
(like print, send, delete) when the user selects an item from the
list.
- Do not add controls to the drop-down (e.g. checkboxes for each
- 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.
......@@ -59,13 +59,13 @@ Behavior
distinctive letters to the beginning of each option. For example, in
a list of countries on continents, write "Germany (Europe)" instead
of "Europe/Germany".
- Do not have blank list items; use meta-options, e.g. (None) instead
- 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). Do not override the common
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
......
Date and time picker
Date and Time Picker
====================
Purpose
-------
The *date/time picker* is a control that provides a convenient way to
The date/time picker is a control that provides a convenient way to
select a certain date or time. The time picker works just like a
:doc:`spin box <spinbox>` with an adopted mask.
The date picker shows all days of a month in weekly columns, has small
......@@ -38,7 +38,7 @@ Guidelines
start date, switch the end date at least to the same date.
- Avoid wrong input by restricting the period to a reasonable range
(for instance when a range is being selected).
- Do not modify localization settings (i.e. first day of week, date
- Don't modify localization settings (i.e. first day of week, date
label etc.)
- Use controls consistently; either all date input should be done by
date picker or none.
......
Drop-down
Drop-Down
=========
.. figure:: /img/Dropdown1.png
......@@ -57,10 +57,10 @@ Behavior