YaST/Web/Docu/Style Guide
From openSUSE
Contents |
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
Dialog elements in a form are aligned via css.
Dialog elements belonging to each other are surrounded by <fieldset>. You need to give fieldset a unique id. Class can be given optional.
If you want to use headlines in a form, use <fieldset>.
Form elements are separated by putting each form element into a single paragraph.
The description of a form element, which is shown on the left side later, is surrounded by <label>
In order to allow the user to activate an input field by clicking on the form element description the "label for" and the text field tag/form id have to be identical.
Code example: Form alignment for setting DNS
<fieldset id="dns" class="">
<legend><%=_("DNS")%></legend>
<p>
<label for="<%= :name %>"><%=_("Hostname")%></label>
<%=text_field_tag :name, @name, :disabled => write_disabled %>
</p>
</fieldset>
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
|
| Combo Box | Combo boxes are used for selecting one options from several ones. Possibly editable to define your own value. Guidelines
|
| Input Field | One or more line textual entry. Guidelines
|
| Push Button | A push button is used to start an action (e.g. save something, open a pop up). Guidelines
|
| Radio Button | Radio buttons are used for selecting one from two or more mutually exclusive options. Guidelines
|
| 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).
|
| 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
|
| Table/List | Lists show several entries with several pieces of information at once and to provide an overview. Guidelines
|
| 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.
|
| 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
|
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.
|
|
|
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)
This site uses the YAML CSS framework.
About openSUSE | Disclaimers | Feedback
This page was last modified 09:17, 28 October 2009. This page has been accessed 955 times.
