Design Guideline

Author: Kevin K.M. Chiu
Copyright 2000, Cobalt Networks.  All rights reserved.
$Id: designGuideline.txt,v 1.12 2001/03/03 07:23:26 kevin Exp $

Overview
========

This document describes design guidelines for Cobalt's user interfaces. As
much as possible, these guidelines should be followed when designing user
interface for Cobalt products.

Choosing Widgets
================

There are many widget classes in UIFC. It is, however, not that hard to choose
which widgets to use if we understand the decision path to the right widget.

We shall start with a classification of widgets. There are essentially 4
groups of widgets. They are buttons, containers, form fields and labels.
Buttons can be grouped into typed-buttons and untyped-buttons, Within form
fields, we can group widgets into selectors and typed-fields.

Buttons include Button, MultiButton, AddButton, CancelButton, ModifyButton and
the like.
Typed-buttons include AddButton, CancelButton, ModifyButton and the like.
Untyped-buttons include Button, MultiButton and the like.

Containers include PagedBlock, ScrollList, SimpleBlock, CompositeFormField and
the like.

Form fields include Boolean, DomainName, IpAddress, MultiChoice, SetSelector,
TextBlock and the like.
Selectors include Boolean, MultiChoice, SetSelector and the like.
Typed-fieldss include DomainName, IpAddress and the like.

Labels include Label, ImageLabel and the like.

Picking between buttons, containers, form fields or labels is straight forward.
Buttons are for actions. Containers are for containing other widgets. Form
fields are for inputs and displays. Labels are for labeling things. What takes
more thinking is to select the right widget within these classes because some
of them (e.g. form field) has a lot of widgets.

To pick a container, ask yourself what kind of information you want to contain.
SimpleBlock is good at presenting a small number of information for display
purposes. PagedBlock is good at presenting multiple form fields for a single
entity. ScrollList is good at presenting multiple entities of the same type.
For example, PagedBlock is good at presenting different properties of a user
while ScrollList is good at presenting a list of users. Do not choose a
container simply because of how it looks. UIFC classes represents design
concepts instead of implementation method. This means looks of containers can
change.

A large number of UIFC widgets are form fields. Selectors and typed-fields are
two groups of form fields. If you are looking for a widget for users to pick
value(s) from a limited set of options, use selectors. If you need a widget for
displaying or entering value(s) of a certain type, use typed-fields.

To picking the right selector, ask yourself how many options do users need to
pick from. Boolean is good for binary options such as true/false, on/off,
enable/disable, etc. If there are more options and only one of them can be
chosen, use MultiChoice. It is also good if there are form fields associated
with those options. SetSelector is primary for selecting a small set out of a
very large set of similar options.

Picking a typed-field is very straight forward. If you need to display or have
users to enter an IP address, use IpAddress field. If you need something for
domain names, use DomainName field. Sometimes, the type you are looking for may
not be available. In this case, you can use TextField and TextList widgets.
They are for generic text.

Widget Usage
============

- As much as possible, widgets should have default values.
- As much as possible, widgets should not force users to switch back and forth
  between input devices.
- Must-be-filled widgets should be placed before optional widgets.
- Group related items together.
- Consistency should be held between pages. For example, if page 1 shows widget
  A and then widget B, page 2 should not show widget A after widget B. Always
  design pages with consideration of the whole site.
- The less widgets there are in an user interface, the better it is. A lot of
  widgets can be minimized through better product design.
- Select widgets that limits inputs to possible options only. For example, if
  there are two flags A and B. Flag B can be true if flag A is true. These
  flags should not be presented by two checkboxes which allows B to be true
  when A is false. Three radio buttons should be used instead. The first one
  being both A and B are true, second one being A is true and B is false, third
  one being both A and B are false.
- Do not have different pages on PagedBlock simply for navigation purposes.
  Use the navigation system instead because it is easier to navigate. Pages on
  PagedBlock are good for hiding advanced and optional information from the
  user because it makes those information less directly accessible to users.
- ScrollList is used for multiple instances of one type of information. If
  there can only be one instance, always use PagedBlock.
- For items with labels associated with them that needs units defined (e.g.
  disk space), always put units at the end of the label surrounded by
  parenthesis (e.g. Disk Space (MB): 10).

Text
====

- Always capitalize the first character of all words on buttons
- Always capitalize the first character of all words on labels
- Always capitalize the first character of all words on titles
- Capitalize the first character of the first word only on option labels
- Round percentage at the decimal point, so instead of 97.05%, use 97%

Wording
=======

Preferred words        | Not preferred words
-----------------------+-------------------------------------------------------
<active voice>         | <passive voice>
<full text>            | <acronym>
<full text (acronym)>  | <acronym (full text)>
<non-abbreviated>      | <abbreviated>
<positive meaning>     | <negative meaning>
access                 | policy, priviledge
add                    | create
correct                | right (means many things)
enable                 | on (means many things)
GB                     | Gigabytes, Gbytes, gb
KB                     | Kilobytes, Kbytes, kb
MB                     | Megabytes, Mbytes, mb
modify                 | edit
program                | application
reply                  | answer
server                 | host, machine
setting                | configuration, option
subnet mask            | network mask
