diff --git a/source/conf.py b/source/conf.py --- a/source/conf.py +++ b/source/conf.py @@ -165,5 +165,14 @@ 'Miscellaneous'), ] - +# Adding global substitutions +rst_epilog = """ +.. |devicon| image:: /img/DevIcon.svg + :width: 32px + :height: 32px + +.. |designicon| image:: /img/DesignerIcon.svg + :width: 32px + :height: 32px +""" diff --git a/source/index.rst b/source/index.rst --- a/source/index.rst +++ b/source/index.rst @@ -7,30 +7,24 @@ ================================================= .. toctree:: - :maxdepth: 1 :caption: Contents: :titlesonly: - :hidden: - - introduction/vision - layout/units - style/typography + introduction/vision + layout/index + style/index + components/index .. Indices and tables ================== - + * :ref:`genindex` * :ref:`modindex` * :ref:`search` - -.. |devicon| image:: /img/DevIcon.svg - :width: 32px - :height: 32px -The Classic KDE Human Interface Guidelines (HIG) offer application designers and developers a set of recommendations for designing and developing user interfaces for QWidget-based, desktop-only applictions. Their aim is to improve the experience for users by making application interfaces more consistent and hence more intuitive and learnable. +The Classic KDE Human Interface Guidelines (HIG) offer application designers and developers a set of recommendations for designing and developing user interfaces for QWidget-based, desktop-only applictions. Their aim is to improve the experience for users by making application interfaces more consistent and hence more intuitive and learnable. For applications which are supposed to run on both desktop and mobile systems, consult the [[../KirigamiHIG | Kirigami Human Interface Guidelines (HIG)]] diff --git a/source/layout/metrics.rst b/source/layout/metrics.rst --- a/source/layout/metrics.rst +++ b/source/layout/metrics.rst @@ -75,9 +75,9 @@ .. hint:: |designicon| For mockup and design you can use these values: - - units.smallSpacing = 4px - - units.largeSpacing = 18px - - units.gridUnit = 18px + - units.smallSpacing = 4px + - units.largeSpacing = 18px + - units.gridUnit = 18px Use Multiples of units.smallSpacing or units.largeSpacing, where more spacing is required. diff --git a/source/layout/units.rst b/source/layout/units.rst --- a/source/layout/units.rst +++ b/source/layout/units.rst @@ -1,13 +1,6 @@ Units & measurements ==================== -.. |devicon| image:: /img/DevIcon.svg - :width: 32px - :height: 32px - -.. |designicon| image:: /img/DesignerIcon.svg - :width: 32px - :height: 32px Purpose ------- diff --git a/source/style/index.rst b/source/style/index.rst --- a/source/style/index.rst +++ b/source/style/index.rst @@ -2,16 +2,16 @@ ===== .. toctree:: - :maxdepth: 1 :caption: Contents: :titlesonly: :hidden: - - typography + imagery - + typography + writing/index + The Style layer is concerned with emotion, tone, and visual vocabulary. Because it is the most visible and concrete aspect of an interface, it typically accounts for people’s first impression of a product. Style is influenced by the use of color,the design of icons throughout the interface and the use of typography. Elements of style support Organization, Viewing and Navigation, Editing and Manipulation and User Assistance. * :doc:`imagery` * :doc:`typography` - +* :doc:`writing/index` diff --git a/source/style/writing/capitalization.rst b/source/style/writing/capitalization.rst new file mode 100644 --- /dev/null +++ b/source/style/writing/capitalization.rst @@ -0,0 +1,82 @@ +Capitalization +============== + +Purpose +------- + +*Capitalization* is a feature of case-sensitive languages to foster +relevance. In terms of software it draws attention to words with capital +letters. For a consistent look and feel of the software it is important +to implement capitalization consistently. On the other hand, +capitalization slows down translation and increases the risk of +inconsistent terminology. + +Guidelines +---------- + +There are two types of capitalization, title capitalization and sentence +style capitalization: + +Title Capitalization +~~~~~~~~~~~~~~~~~~~~ + +Title capitalization is when every word in a sentence, statement, +phrase, or label are capitalized except for certain words. Words with +less than five letters are generally lowercase in titles, unless they +are the first or last words in a title. + +Do not capitalize: + +- Articles: a, an, the +- Coordinating Conjunctions: and, but, or, for, nor, etc. +- Prepositions (fewer than five letters): on, at, to, from, by, etc. + +Always capitalize + +- Nouns (man, bus, book) +- Adjectives (angry, lovely, small) +- Verbs (run, eat, sleep) +- Adverbs (slowly, quickly, quietly) +- Pronouns (he, she, it) +- Subordinating conjunctions (as, because, that) + +Use title capitalization in the following cases: + +- Window and dialog box titles +- Group box / group line labels +- Button labels +- Tab labels +- Listview column headers +- Menu titles / menu items +- Derivatives of KCommand +- Combobox items +- Listbox items +- Tree list items +- Other heading/title text + +Sentence Style Capitalization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sentence style capitalization is when the first letter of the sentence, +statement, phrase, or label is capitalized and all other words are lower +case. The only exception to this is proper nouns which are always +capitalized. + +Use sentence style capitalization in the following cases: + +- Edit box labels +- List box labels +- Combo box labels +- Spin box labels +- Check box labels +- Option button labels +- Slider labels +- Pop-up hint text +- Dialog header/description +- Other non heading/title text + +Acronyms/Initialisms, Internet +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Words such as URL, JPEG, or LDAP should be written in capital letters +- Internet (if referring to *the* Internet) takes a capital I. diff --git a/source/style/writing/index.rst b/source/style/writing/index.rst new file mode 100644 --- /dev/null +++ b/source/style/writing/index.rst @@ -0,0 +1,21 @@ +Writing +======= + +.. toctree:: + :caption: Contents: + :titlesonly: + :hidden: + + wording + capitalization + labels + static + localization + +Text includes all the written, language-based elements of the interface. This includes the labels used to represent the organizational model, the names of the input and navigational controls contained for Viewing and Navigation, and the alert messages and help text used for User Assistance. + +* :doc:`wording` +* :doc:`capitalization` +* :doc:`labels` +* :doc:`static` +* :doc:`localization` diff --git a/source/style/writing/labels.rst b/source/style/writing/labels.rst new file mode 100644 --- /dev/null +++ b/source/style/writing/labels.rst @@ -0,0 +1,136 @@ +Lables +====== + +Purpose +------- + +Common controls should behave ‘common’ and look like everyday controls. +Therefore, it is much recommended to use standard font. Bold or italic +font should not be applied to control labels. + +Guidelines +---------- + +- Keep labels short; be aware that :doc:`translated ` English text can + expand up to 30% in some languages. +- Do not shorten your labels to the point of losing meaning. However, a + three-word label that provides clear information is better than a + one-word label that is ambiguous or vague. Try to find the fewest + possible words to satisfactorily convey the meaning of your label. +- When the label is associated with another control, like a line edit, + be sure to set the the line edit as the + `buddy `_ of + the label. + +Dialogs +~~~~~~~ + +- If a dialog is user-initiated, identify it using the command or + feature name. +- If it is application- or system-initiated (and therefore out of + context), label it using the program or feature name to provide + context. +- Do not use the title to explain what to do in the dialog – that's the + purpose of the main instruction. + +Menus +~~~~~ + +- Prefer verb-based names; Avoid generic, unhelpful verbs, such as + *Change* or *Manage*. +- Use singular nouns for commands that apply to a single object, + otherwise use plural nouns. +- For pairs of complementary commands, choose clearly complementary + names. Examples: *Add/Remove*, *Show/Hide*, or *Insert/Delete*. +- Choose menu item names based on user goals and tasks, not on + technology. +- Assign access keys to all menu items (Alt+Letter). + +Buttons +~~~~~~~ + +- Label command buttons with an imperative verb. +- Do not use ending punctuation for labels. +- Describe the action that the button performs in a tooltip. +- End the label with an ellipsis if the command requires additional + information to execute. +- Assign access keys to all buttons (Alt+Letter). + +Links +~~~~~ + +- Choose a concise, self-explanatory label that clearly communicates + and differentiates what the command link does. +- Do not use ellipses. + +Tabs +~~~~ + +- Label tabs based on their pattern. Use nouns rather than verbs, + without ending punctuation. +- Do not assign an access key. Tabs are accessible through their + shortcut keys (Ctrl+Tab, Ctrl+Shift+Tab). + +Check boxes and Radio buttons +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Label every check box or radio button. Do not leave check boxes or + radio buttons unlabeled. +- Assign a unique access key to each label. +- Labels must start with an active verb clearly defining the state to + be enabled or disabled. +- For a group, use parallel phrasing and try to keep the length about + the same for all labels. +- For a group, focus the label text on the differences among the + options. +- Use affirmative phrases. Do not use negative phrases such as "Don't + enable wifi". Use rather "Enable wifi". +- Describe just the option with the label. Keep labels brief so it's + easy to refer to them in messages and documentation. + +Group box +~~~~~~~~~ + +- Use group labels to explain the purpose of the group, not how to make + the selection. +- End each label with a colon to show a relationship. +- Do not assign an access key to the label. +- For a selection of one or more dependent choices, explain the + requirement on the label. + +Using Ellipses in Labels +~~~~~~~~~~~~~~~~~~~~~~~~ + +- Use an ellipsis (...) after menu items and button labels which + require user’s input before completing their action. +- Do not use an ellipsis if no further user input is required to + complete the action +- Do not use an ellipsis for selections which result in actions (such + as Save or Print Preview) or do not require user input (such as + configuration dialogs). +- Do not use an ellipsis for an action which may require confirmation + before it is completed (such as a Deletion confirmation), but no + other input. +- Use an ellipsis for the following menu items and buttons: + + - Find... + - Find and Replace... + - Open... + - Print... + - Replace... + - Save As... + - Send To... + +- Do not use an ellipsis for the following menu items and buttons: + + - About + - Advanced Options + - Check Spelling + - Close or Quit + - Configure [something] + - Delete or Remove + - Help + - Preferences + - Print Preview + - Properties + - Toolboxes diff --git a/source/style/writing/localization.rst b/source/style/writing/localization.rst new file mode 100644 --- /dev/null +++ b/source/style/writing/localization.rst @@ -0,0 +1,29 @@ +Localization +============ + +Purpose +------- + +KDE address a world wide audience and is therefore fully localized. +Localization means to adopt language, text layout, numerals as well as +cultural aspects and regulatory compliance. + +Guidelines +---------- + +- Provide bidirectional mode dependent to language (left-to-right vs. + right-to-left). +- Make sure your GUI displays correctly in languages written from + right-to-left +- Allow translation with + [http://www.gnu.org/software/gettext/manual/html_mono/gettext.html#Plural-forms\ \| + multiple plural forms]. +- Design GUI with enough room for long captions. +- Respect system-wide locale settings (unit systems, date and time + format, currencies etc.). +- Take cultural comprehension of icons (Red Cross vs. Red Crescent) + into account. +- Do not localize standard `short-cuts`_. +- Be aware of intercultural (mis-)comprehension of acronyms. + +.. _short-cuts: KDE_Visual_Design_Group/HIG/Keyboard_Shortcuts diff --git a/source/style/writing/static.rst b/source/style/writing/static.rst new file mode 100644 --- /dev/null +++ b/source/style/writing/static.rst @@ -0,0 +1,24 @@ +Static text +=========== + +Users tend to read only interactive control labels, especially those +that appear relevant to completing the task at hand. By contrast, users +read *static text* when they think they need to. + +Guidelines +---------- + +- Use the inverted pyramid for text. Start with the the conclusion and + the fundamental "takeaway" that readers must have. Then fill in + progressively more detail that readers may be interested in - perhaps + just to scan. +- Remove redundant text. Leave full text in main instructions and + interactive controls, and remove any redundancy from the other + places. +- Avoid large blocks of UI text by chunking text into shorter sentences + and paragraphs or providing help links to useful, but not essential, + information. +- Use bold font sparingly to draw attention to text users must read. A + different font, e.g. bold or italic, can be used to attract attention + when changes to UI design are not applicable or not efficient enough. + diff --git a/source/style/writing/wording.rst b/source/style/writing/wording.rst new file mode 100644 --- /dev/null +++ b/source/style/writing/wording.rst @@ -0,0 +1,30 @@ +Wording +======= + +Purpose +------- + +Every word displayed in an application is part of a conversation with +users. This conversation is an opportunity to provide clarity and to +help people feel comfortable in the system. + +Guidelines +---------- + +- Use terminology that is familiar and easy to understand for the + target audience (i.e. Persona) of your application. +- Start your sentence with the most important objective first. +- Use short words, active verbs and common nouns. +- Avoid :doc:`contraction` such as "Don't", "Won't", etc. +- Avoid abbreviations (including ampersand instead of 'and'), acronyms, + and tech-babble. +- Use an informal and friendly tone, but not too informal or humorous. +- Avoid popular, but transient, words and phrases. +- Keep information short and consistent; avoid redundancy or wordiness. + e.g. Do not repeat the dialog title in the dialog text. +- Don't abuse :doc:`capitalization` because it draws people’s attention. +- For date and time information, consider that your app may potentially + be used for several years; do not use immutable date references like + *this year* unless it is algorithmically determined. +- Follow system-wide wording conventions for basic functions to keep + wording consistent.