openSUSE

Discover it

Toolbox

Create an account or log in

YaST/Web/Docu/Style Guide

From openSUSE

(Difference between revisions)

Revision as of 11:19, 14 October 2009

webYaST Style Guide

About

The YaST Style Guide has been created to specify the look-and-feel for YaST. This will help the developers to create their applications interfaces and to increase the consistency of webYaST.

Generic Layout

Description

Header

The header contains appliance logo, appliance title and login credentials. The login credentials are handled by the id login-wrapper and provide information about logged in user and host.
header-links are embedded into login-wrapper and contain a link to the control center and the possibility to log out.

Content

The id "content" includes the icon of the module (handled by the id "plugin-icon") and the actual content of the module (handled by the id "plugin-content").

Footer

Beneath the content the copyright information is shown via id "copy".

Dialog Types

Dialog Types - Overview

Here is the brief overview of all kinds of YaST Dialog Types

Dialog Type	Used For
Generic Module	Basic layout of a module
Overview	Dialog to show an overview of items and the possibility to add/edit/delete them
Configuration Wizard	All kinds of dialog sequences with more than one step, e.g. adding new sound card, configuring DNS Server in three wizard steps, ...
Pop ups	Small window for editing few settings

Dialog Types - Detailed Description

Generic Module Dialog

Headline

The headline is a breadcrumb trail starting with "Home", "All Modules" and "Module Title".
If a module is called from another module the previous module is also shown in the breadcrumb trail.
To support skimming and user orientation the last breadcrumb item has a different larger font size.
Breadcrumbs also provide basic navigation and allows the user e.g. to return to "All Modules" where he can select another module to work with.

Content

Below the headline the module content is shown. If another module started from the module the user currently works, the new module opens in the same screen in full screen mode.

The content of the module is organized in tabs. Arrange controls in your dialog from left to right and top to bottom Main controls are shown closer to the top left corner then controls which are needed lesser. Provide and show default values if possible in order to make it easier for the user to use a dialog.

Validation Field entries are not validated until the user has moved the focus to a different control or changes within the module are saved. Do not report invalid entries by displaying a message box and give the user a proper hint which entries are invalid.

Overview Dialog

Used for listing devices, services, and other table entries providing possibility to Add new, and Edit, and Delete the current one.

Headline

The headline is a breadcrumb trail starting with "Home", "All Modules" and "Module Name".
The module name is consistent with the module name in „Show all“ or "Home" page.
If a module is called from another module the previous module is also shown in the breadcrumb trail.
To support skimming and user orientation the last breadcrumb item has a different larger font size.
Breadcrumbs also provide basic navigation and allows the user e.g. to return to "All Modules" where he can select another module to work with.

Content

The content shows a list of detected or configured items and an "Add" button.
Add starts a configuration wizard
Edit and Delete are accessed when the user clicks on an item in the list.

Edit
The editable configuration options are displayed here.
If there are many options they are organized in tabs.
To ease configuration the tab headings should be consistent with headings in the configuration wizard used for adding items.

At the bottom of the "Edit" pane there are two buttons:
Save: saves changes and closes the edit pane
Cancel: discard changes and closes the edit pane

Delete
In order to delete an item from the list, the user clicks on "Delete". To make his action effective the user needs to confirm a pop up.

Configuration Wizard

A configuration wizard is used when

multiple steps need to be accomplished in order to add some item or service or configuration
no item is found and the user would be presented with a blank overview at module start up

If the add sequence consists of no more than one step use a pop up dialog instead.

Do not use tabs within the configuration wizard. A wizard per definition is a series of steps.

During the configuration wizard try to avoid using additional pop-ups.

If it is possible inform the user about the total amount of steps and the show him the step he is currently accomplishing.

If possible use the same wording for wizard steps and tabs shown in the edit section later. This makes it easier for the user to make later changes.

A configuration wizard is displayed on a layer above the current screen.

A wizard contains:

introductory page
content page(s)
finish page

Introductory Page

The introductory page provides the user with an idea about the wizard`s goal and a short description the item to be added.

Description of buttons

Next - Leads to the following screen
x - Discards changes, closes the wizard and returns to module beneath the wizard

Content Page

Content pages use a headline and content area.

The headline contains the title of the configuration step. Use a summary of current settings as title. If possible use the same wording for wizard steps and tabs shown in the edit section later. This makes it easier for the user to make later changes.
If it is possible inform the user about the total amount of steps and the show him the step he is currently accomplishing.

The content area contains the actual settings made in this step.

Description of buttons

Back - Leads to the previous screen
Next - Leads to the following screen
x - Discards changes, closes the wizard and returns to module beneath the wizard

Finish Page

Finish page uses a headline and content area.

The headline contains the title of the configuration step. Use a summary of current settings as title.
If it is possible inform the user about the total amount of steps and the show him the step he is currently accomplishing.

The content area contains a summary of settings made during the use of the assistant. Description of buttons

Back - Leads to the previous screen
Finish - Saves settings, closes the wizard and returns to module beneath the wizard
x - Discards changes, closes the wizard and returns to module beneath the wizard

Pop up

A pop up is a small window which pops up over a parent window and where the user can edit some information.

If contains a meaningful heading, a content area and a navigation area.

The navigation area contains two buttons:
Save: saves changes and closes the pop up
Cancel: discard changes and closes the pop up

Dialog Elements

Presentation of Dialog Elements in a Form

The dialog element label is shown on the left side of the dialog element.
The dialog element label uses regular typeface.
It is separated from the dialog element by at least one space character.

Short Description of Dialog Elements

Dialog Element	Description / Used For
Check Box	A check box is a clickable true/false action toggle button used when both states have obvious meaning (e.g. set and unset, enable/disable) Guidelines Check boxes may initiate actions like enable/disable or hide/show settings or services. Use check boxes also if you want the user to select multiple options. To show the user that these check boxes belong together draw a frame around the options. If there are more than 4 options use combo box instead. If a check box enables other controls, place it above or to the left of the controls that it affects to support the user to indicate which controls are affected. Check box labels use sentence style capitalization If it proves to difficult to find a meaningful label which explains the effects of a check box consider to use radio buttons. By using radio buttons you can provide both states with different labels. A group of check boxes is labeled with a descriptive heading above or left to the group of check boxes. Try to avoid frames around check boxes and use blank space for grouping instead. Align multiple check boxes vertically to ease visual scanning.
Combo Box	Combo boxes are used for selecting one options from several ones. Possibly editable to define your own value. Guidelines Use combo boxes if a setting contains more than 4 radio buttons or check boxes A selected entry from a combo box may initiate actions like enable/disable or hide/show settings or services. Combo box labels and entries use sentence style capitalization. Place the combo box label above or left to the combo box
Input Field	One or more line textual entry. Guidelines Labeled with sentenced capitalization When the user activates an input field the text cursor is placed at the end of the existing text and its content is high lightened. This makes it easier to over type or append new text. Adjust size of input field according to the estimated size of input. Input is validated when the user exists the input field. In order to give the user an idea which input format is appropriate use static text prompt. Another way is to separate the input field.
Push Button	A push button is used to start an action (e.g. save something, open a pop up). Guidelines Buttons are labeled by using sentenced capitalization. Do not use more than one or two different widths of button in the same window, and make all of them the same height.
Radio Button	Radio buttons are used for selecting one from two or more mutually exclusive options. Guidelines If there are only two obvious states use a check box instead. If there are more than 4 options use a combo box instead. Radio buttons are used in groups. Single settings are either displayed by a check box or by two radio buttons (one for each state). Only one radio button can be set within a group of radio buttons. A radio button may initiate actions like enable/disable or hide/show settings or services. If a radio button enables other controls, place it above or to the left of the controls that it affects to support the user to indicate which controls are affected. Radio button labels use sentence style capitalization A group of radio buttons is labeled with a descriptive heading above or left to the group of radio buttons. Try to avoid frames around radio buttons and use blank space for grouping instead. Align multiple radio buttons vertically to ease visual scanning.
Slider	In order to select a value from a fixed, ordered range use a slider. Use slider when it is more important for the user to adjust a value relatively than absolutely (e.g. Making something louder or quieter). Guidelines Label slider with sentence capitalization Mark significant values with text or tick marks
Spin Box	A spin box is a text box which allows the user to choose between a range of numeric values by increasing and decreasing them with two arrows. Guidelines Capitalize labels in sentence style As spin boxes are used for numerical input only use combo boxes instead when you the user needs to select fixed entries. Use slider control for volume controls.
Table/List	Lists show several entries with several pieces of information at once and to provide an overview. Guidelines Lists labels and list entries use sentence style and are positioned above or left to the list. Use reasonable size of table Use labeled column headers if you want to make a list sortable or if the table contains more than one column. Column header are displayed in title style. If you use sorting make this options and the sorting method obvious to the user
Tabs	Tabs are used to organize module content if the settings need more than one page. A tab is a navigational widget for horizontal switching between various settings. Use a tab to symbolize independent or hierarchically equal sections. Guidelines Tabs are labeled with title capitalization When switching between the various branches changed values are preserved. If you think, that this behavior leads to potential destructive consequences you may include a pop up, which has to be confirmed by the user. Do not use more than five tabs or more than one row of tabs because this makes it hard for the user to find the section he is looking for and it makes your dialog look complicated and ugly. If you need more than five tabs use a tree instead.
Tree	Use a tree to display a hierarchical structure or if a dialog with tabs would look too crowded and complicated. When switching between the various branches changed values are preserved. If you think, that this behavior leads to potential destructive consequences you may include a pop up, which has to be confirmed by the user. Guidelines Trees use sentence style and are positioned above or left to the list. Use reasonable size of tree. Use labeled column headers if you want to make a tree sortable or if the table contains more than one column. Column headers are displayed in title style

Messages

In webYaST there are two kinds of messages:

Questions
Error messages

Questions

A "question" message box provides feedback about a situation or a condition that requires the user's decision and input before proceeding. The message is in form of a question. Write button labels as imperative verbs, for example Save, Print. This allows users to select an action with less hesitation. Try to avoid "Yes" and "No" as the only answer possibilities. If you use "Yes" and "No" the user needs to read the whole question to get a glimpse of what you want from him. By labeling the buttons meaningfully the consequences can be perceived more quickly.

Try to avoid questions as they interrupt the users workflow which annoys him.

Questions are displayed in the middle of the screen as modal dialogs. They do not use an icon.

Typical use cases for questions:

Confirmation of deleting an item
Confirmation of shutting down firewall
Confirmation of shutting down/restarting system

Error Messages

Error messages are displayed between header and content area. There is no distinction between severities of errors. Error messages contain a heading, which is a one sentence summary of the information or suggested action. The user gets the essential details of the problem or suggestion. The font is bold and slightly larger than the additional information, which is a more detailed description of the problem.
The user has a possibility to view details of the error (e.g. log data) and is provided with a link where he can report the error (e.g. bugzilla).

The user has the possibility to close the error message.
Multiple messages are shown below each other.

They are handled by jquery XX.

Typical use cases for messages

could not connect to a server
no permission

Text Style Guide

General

Keep the text short and meaningful.

Capitalization

Use title style for titles (e.g. headings, module titles) and sentence style for all other UI elements:

Sentence stlye: first letter of the sentence is capitalized, all others lower case (with the exceptions of proper nouns and acronyms)
Title style: the first letter of each word is capitalized, the rest are lower case. In some cases short articles, prepositions, and conjunctions are not capitalized unless they are the first word in the title. E.g.
- Articles (a, an, the)
- Coordinate conjunctions (and, but, for, nor, or)
- Prepositions of four or fewer letters

When capitalizing, do not change the capitalization of filenames, configuration variables, and similar casesensitive items. These should be presented in the case required by the system to avoid confusion.

Punctuation

Do not use spaces before commas (,), periods (.), colons (:), or semicolons (;). Avoid using exclamation marks at all. The wording and the type of message provide the needed emphasis. Avoid using punctuation dashes, called em dashes. If it cannot be avoided, use . Only use / if it is part of a standard term, such as TCP/IP. Usually or or and should be used where a / is used.

Spelling

Use American English as the original language for all texts. Many words have multiple "acceptable" spellings, but it has been necessary for SuSE and Novell to standardize on certain variants for consistency. Use the first variant in Webster's dictionary as the standard spelling for anything not on these lists.

3D
backend
back up (verb)
backup (noun)
boot disk
boot loader
cannot
casesensitive, caseinsensitive
certificate authority
client/server
command line
email
filename
file system
frontend

GNOME
hard disk
hostname
hotplug, hotplugging, hotpluggable
Internet
intranet
journaling
KDE
local host (normal), localhost (default name of the local host)
log file
log in (verb), login (noun)
log out (verb), logout(noun)
mount point
pathname
RAM disk

reconfigure
recreate
runlevel
runtime
set up (verb), setup (noun)
standalone
startup
SSH
uninstall
username
Web
Web page
Web server
X Window System (do not shorten to X Windows)

Module Title

Use title style for the module title.
Keep the title short and meaningful.
The module title is consistent with the module title in „Show all“ or "Home" page.
Do not use "Configure" or any other verb in the title.
If the module is used to configure a client, use the word "Client" in the title.
If the module is used to configure a server, use the word "Server" in the title.

Terms

Home = Page with status information, quick links to modules and all modules
All Modules = Page which gives access to all available modules (equals control center in YaST)

Retrieved from "http://en.opensuse.org/YaST/Web/Docu/Style_Guide"

The content on this and other wiki pages is posted by community members who are not acting for or on behalf of Novell, Inc., whether or not they otherwise have affiliation with Novell.
This site uses the YAML CSS framework.
About openSUSE | Disclaimers | Feedback

 The dialog element label is shown on the left side of the dialog element.<br>
-The dialog element label uses regular typeface and has a colon at its end.<br>
+The dialog element label uses regular typeface.<br>
 It is separated from the dialog element by at least one space character.<br>