Style guide/Forms

This document is a work in progress.

This document serves as a form style guide for MediaWiki developers. It is intended to encourage development of a standard user experience for forms.

One of the goals of this document is to engender positive experiences for users. Forms need not be listless or boring; rather, even the most minor of forms should be energetic and interesting.

This document is focused on user-interactive forms. It does not cover style or best practices related to other elements of the user experience (such as tabulated data, or interactive lists).

Field Elements


A single form can consist of one or more visible fields (there may be non-visible fields, such as hidden submission buttons for single field forms like a search box). Each field can have additional sub-elements, and their presence or absence is often form-specific.

Common elements include:


 * Label - The element label. This is nearly always required.
 * Input Mechanism - This is the field's input. This can be a text field, checkbox, select list, etc.
 * Required or Optional Notifier - This indicates an element's required status
 * Error Notification - This is an indicator to the user that there is a problem with the value placed within the element.
 * Help Trigger - This is an icon or other actionable element that indicates to the user that additional information about the field is available.
 * Instructions - This is typically a short sentence or two explaining what the field does and any parameters required.
 * Hint - This is typically example text designed to help the user understand the type of data the element takes. Hints differ from instructions in that they are usually placed within the input mechanism.

A Note on Color Selection
Color selection within user-interfaces can be tricky. It is helpful to understand how human beings react to various colors and the psychological reasons behind these reactions.

Color can be divided into two broad categories: "warm" and "cool". As a rule of thumb, warm colors are those with lots of red and yellow in their makeup; cool colors are those with any blue. Browns are warm; greys and blacks are percieved as "cool".


 * Warm: Red, Orange, Yellow, Brown
 * Cool: Blue, Green, Purple, Grey

The color red requires special consideration. No other color demands attention as much as red because human beings are biologically wired to respond to the color red as a stressor. There are measurable, biological effects to its presence (such as increased heart rate). Quite simply, this is because of the color of human blood. We know, innately, that "red" equals "bad" and demands immediate attention.

Likewise, Green is percieved as being positive. Green is the color of life (trees, grass, etc.). Human culture has elevated the color green to one meaning "forwardness" and "safety."

Yellow is a difficult color to work with in computers. Computer monitors (and television sets) do not generate the color yellow because pixels are comprised of only three colors: red, green, and blue. Any yellow color is technially generated as a low-intensity brown (with green, red, and white pixels firing in a moire pattern).

Alert Color versus Chrome Color
Since different sites have different color schemes, colors that attract attention can be different. Accordingly, we will refer to color types in the following manner:


 * Chrome color is color that falls to the background of the user's perception. Chrome color is seen and understood to be part of the site's "operating system" and does not attract attention.
 * Alert color is color that rises to the front of the user's perception. Alert color invites attention and exploration.

Most MediaWiki installs that use the Monobook or Vector skins will have a primary "chrome" color scheme of greys and blues. In this case, "alert" colors will have to be warm. In contrast, skins that are warmer in nature will use cooler colors for alerts.

Accessibility for Visually Impaired Users
There are many things to think about when designing forms that can be used effectively by users with various types of visual impairment.

Color blindness
There are several forms of color-blindness and they have subtle differences. This can be difficult to design for.

In general, avoiding the use of color as the only indicator of something in a form is best practice. Varying color intensity and lightness is key when designing indicators.

Poor eyesight
Subtle visual elements are often lost on users with poor eyesight. If something is important, it should be visually elevated. Elements of 5 pixels in size are usually too small to be easily distinguished; use 16 or more pixels in such cases.

Color intensity contrast is important in this regard. Two opposite colors can appear the same if they have the same intensity (amount of white).

Dyslexia
While not technically a vision impairment, certain design choices can wreck havoc to individuals with dyslexia.

Dyslexic individuals can have difficulty reading text on colored backgrounds when the intensity of the text color approaches that of the background.

Blocks of text should never be centered or justified. This creates a "gutter" effect which can appear as a moire pattern. Always use aligned text (left for left-to-right languages; right-aligned for right-to-left languages).

Other things to avoid include the use of capitals for emphasis, italics, and serif fonts.

Field Layout
Forms should be laid out vertically in a single column. Human beings understand progress in forms as being vertically driven. Multiple columns are discouraged.

This is not a hard-and-fast rule, however; in some cases multiple columns can be utilized but this should be rare and typically only applied to a single form element grouping (such as "Password" and "Confirm Password").

Label Position
Generally, field labels should be placed above the field that they are referring to. The field element (input, select box, checkbox grouping, etc.) should be slightly indented below the label. Sufficient white space shall be applied beneath the element grouping to distinguish it from other elements on the page.

Labels are placed above for the following reasons:


 * Localization. Translated labels may be significantly longer in other languages. Further, left-to-right languages (e.g., Arabic) naturally work better this way.
 * Human Eye Behavior. Human beings naturally group elements in vertical proximity together. Continual Left-to-Right eye tracking is stressful.

An exception to this lies within single-element checkboxes, which case the label is to be placed on the same line as the checkbox, and immediately to the right.

Checkboxes vs. Multi-Select
The use of select elements with the multi attribute is discouraged. In cases where the user can select multiple options from a discrete set, a checkbox grouping is suggested instead.

The drawbacks of the "multi select" are many but two primary reasons stand out:


 * 1) The element is rarely used. As a result, not many users innately understand how they work.
 * 2) Not all values are typically visible to the user. Additional scrolling is required. Again, users may not understand the control.

Buttons
For short forms with only one button, it is advised to place the button directly below the last field element and left aligned. Human eye tracking runs vertically and placing the button at the bottom is most natural psychologically.

However, for forms with multiple buttons, the buttons should be grouped together and right aligned at the bottom. This creates a psychological "break" in the flow and causes the user's short term memory to reset, allowing them to process the activity they are undertaking.

When there are multiple buttons, the order of the buttons should always follow the following pattern:




 * [destructive event] [reset event] [neutral event] [continuation event]


 * A destructive event is one that will cancel the activity. All changes are lost.  Destructive buttons should be colored red.  Note that "back" buttons within wizards are not destructive; they are reset or neutral.
 * A reset event is one where the form is returned to the default state. All changes are lost. Reset buttons should be colored grey or neutral.  The use of reset buttons is strongly discouraged. There should be a significantly strong use case for them to ever appear.
 * A neutral event is one where work will not be lost but the form will not be completed. Example: running a spell check, or in-page previews. Neutral buttons should be colored grey or neutral.
 * A continuation event is moving to the next screen. This is typically a submission action but may be moving to the next page in a wizard. Continuation buttons should be colored green.

Text should rarely, if ever, be used for button actions. It is tempting to display "cancel" events as text but this should be avoided where possible; users have been trained to see buttons as actionable events and text links as data events.

Disabled Buttons
If a form should not be submitted until certain criteria are met (e.g., filled out completely), the continuation (submit) button should be disabled. Upon readiness, the button should become active and change color to indicate readiness.

Button Labels
In general, buttons should say exactly what they are doing and always re-stress what is happening. "Submit" is bad; "Save Changes" is better. "Cancel" is bad; "Discard Changes" is better.

Button Iconography
Button iconography is not required but is always a nice touch.

With the exception of continuation buttons, iconography should be placed to the left of the button text. Continuation button iconography should be placed to the right.

In general, icons on continuation buttons should be arrows pointing right. Buttons that take the user backwards in a series of steps should be arrows pointing left. Buttons that are purely destructive should have trashcan icons. Other iconography should dependant upon the function.

It is acceptable to only include iconography on continuation buttons.

Required and Optional Fields
In the past, common practice has been to indicate on a form when fields are required and assume all non-required fields are optional. However, over the past 20 years, users have been educated to assume that most fields are required and that few are optional (since this is generally true).

Indicating both optional and required fields is overkill, so only the least common type is to be indicated. Thus, if a form has 6 fields and only 2 are optional, the two optional entries should be indicated. If a form has only one required field, that should be called out.

For very short forms (such as a login form), it is not necessary to place any indications.

For long forms (more than 5 fields), a short notice should be given at the top indicating the general state (e.g., "All field are required", or "All fields are optional except where noted", etc.).

Display
Optional fields should be indicated with a text string, "(Optional)", directly after the field name. This should be in a smaller font and in a lower-intensity color.

Required fields should be indicated with a text string, "(Required)", directly after the field name. This should be in a smaller font and a red color.

Required fields should have no other identifying marks (such as stars or icons) as this clutters the display and can be mis-interpreted as an error condition mark.

Focus Behaviors
When a text element is focused (has the cursor in it), its border should change color to indicate that it is active. Many modern browsers do this automatically.

Help Triggers
Help triggers are intended to be in-form as tooltips and not designed to bring the user to another screen or open windows. Help triggers require the use of Javascript.

A help icon is placed immediately to the left of the element label. This is a small question mark icon. Hovering over it will cause a tooltip to appear with additional information.

In forms where the majority of elements have a help trigger, it is best practice to include one for every field for completeness' sake.

When a help trigger is present, the element's label should also trigger the tooltip. Help icons are small targets while labels are large targets.

Tooltip Behaviors
Tooltips should always have arrows. The arrows should be obvious and relatively large so that individuals with poor eyesight can readily connect the help text with the element that it is referencing (otherwise, they appear as random blobs of text without context).

Tooltips should never obscure the field that they are attached to. As such, the gravity should be northward. In some cases, a southward gravity may be applied (if the trigger is below the element in question, but this should be rare).

Instructions
Some form elements will benefit by the inclusion of a short set of instructions. Instructions should be placed on a line below the field name and above the input mechanism in a smaller, greyed font.

Field-level instructions should be short and too the point. If additional information is necessary, a link should be provided for more information. This link can activate a tooltip or open further information in a new window or tab. Active links within instructions should always be underlined.

Clicking on a "more information" link should never load in the same window, causing the user to lose their changes.

Hint Behaviors
Some form elements can benefit from the presence of data "hints". Hints help the user to decide at a glance the type of data a field takes.

Hint text should be placed within the input mechanism. It should be a light color and the text should be as generic as possible (e.g., "username@domain.com" or "(123) 123-1234").

When a field with hint text achieves focus (when the cursor is placed within it), the hint text should become even lighter. Once the user starts typing or inputs data, the hint text should disappear.

If the user clears the field, the hint text should return.

Hint behaviors should be done exclusively with HTML5 placeholder attributes. Older browsers will not support this.

Banner Notification
A banner notification that informs the user that an error has occurred should always appear, regardless of other error display mechanisms. This banner should inform the user that the action failed and that they (the user) should correct the specific errors below.

Optionally, a list of specific errors may be included in the banner. If the list of errors is greater than 2 or 3, however, the list should be omitted.

If the error is not tied to a specific field (e.g., "Failed to connect to the database"), then the error must be included in the error notification banner. If the errors are only system-level, then the user should not be prompted to fix them (but may be prompted to try again later or contact an administrator).

Field Local Error Notification
If at all possible, errors should be associated with the fields they are connected to with an error string that helps the user understand what happened and how to correct the error.

Fields with errors should be called out with an obvious icon to the left of the input mechanism. It should be vertically aligned with the input mechanism (below the label and any help trigger icon).

The icon should be at least 16x16 pixels in size (a red asterisk is not acceptable).

Where possible, the input mechanism should have a red border. This should be at least 2 pixels in thickness but no more than three.

Depending on the form layout and the developer's whim, field level errors can be displayed horizontally or vertically - or even a mix within the same form.

In horizontal alignment, the error list is displayed to the right of the input element. Horizontal aligments are especially good for select boxes or checkbox groupings.

In vertical alignment, the error list is displayed directly beneath the element's input mechanism. This is often the most developer-friendly way to display the error.

Special Function Elements
From time to time, an interface will call for a specialized control element. These elements duplicate the functionality of existing elements (such as radio button sets) but are easier for the user to understand.

(This section will likely be broken out into its own page as more specialized controls are added to it.)

Toggle Controls
A toggle control is a specialized control that can take the place of a single checkbox. Normally, the psychology of a checkbox indicates only a "positive" toggle (the options are "active" or null). In cases where the choice is binary, a toggle is useful.

(Note that a toggle is semantically the same as a radio set with only two options.)

Toggles should have obvious, written values ("enable" and "disable", "on" and "off", etc.). The values should exist within the "bed" of the toggle so as to reduce user confusion as to what the value is set to.

Choice of color for the toggle bed should be carefully considered. Generally, the "negative" state can be left neutral (grey) while the "positive" state should be colored green. In cases where the negative state requires strong consideration (for example, disabling a security measure), the negative bed can should be given an alert color (red or orange).

Call-to-Action Control


A call-to-action control is not really a form "element" in that it is part of a form; rather, it is a control that drives the user to engage in an activity (usually filling out another form).

User activities which are considered desirable can be elevated as "calls to action." These controls are interesting to the user in some way or another: they are usually brightly colored (alert colors) and invite exploration and attention.

In most MediaWiki installs, "redlinks" are considered a lightweight form of a call-to-action (note comments below about color). Another canonical example in many web applications is "create an account."

Careful consideration must be applied when choosing color for calls-to-action. In general, "cool" colors (such as blues, greens, and purples) fall "into the background" and are ignored by the user (unless the site is primarly designed with warm colors).

Alert colors (warm) are best. However, color selection is radically limited to the color orange.


 * Yellow colors as generated by computer monitors are weak choices. Monitors (and televisions) do not easily produce color in the yellow spectrum (pixels are RGB only).  Yellow is further a poor choice because of its low intensity.
 * Red colors are psychological stressors to human beings. Humans are hard-wired to recognize the color as "bad".

Scaled Thermometer
A scaled thermometer is a display element that is usually used when displaying the average of several values. Scaled thermometers have set values on a pointilist range (e.g., 1 through 5, or 1 through 10, etc.).

When displaying values such in a thermometer, the actual, real value being displayed should be included as a number before the thermometer itself.

If there is additional metadata that could be important (such as the number of entries used in the calculation of the thermometer's value), this should appear below the thermometer, right aligned, and in a smaller font of less-intense color.

Unscaled Thermometer
Unscaled thermometers are useful when the values to be displayed are vague.

If there is a value judgement that can be applied to the value displayed on the thermometer, both color and text should be used to indicate the value. "Bad" values are red, "moderate" values orange, and "good" values should be green. The text displayed is contextual based upon the display element's purpose.

If there is no value judgement to an unscaled thermometer (there is no "good" or "bad" value), then the color should be a more intense chrome color.

Star Bar


A star bar is a control designed for user input within a set "Likert" scale (e.g., numbers between 1 and 5, or 1 and 10, etc.). The user selects the value by clicking on the value they most prefer. A star bar is a modified version of a radiobutton set.

When building a star bar, it is important to understand the various states that a star bar can exist in:


 * Unset State - this is the star bar before any user interaction
 * Hover State - this is the star bar's appearance as the user is interacting with it directly
 * Set State - this is the star bar's appearance once the user has interacted with it but before the values have been saved
 * Saved State - this is the star bar's appearance after results have been saved to the server.

Since color alone should never be an indicator of state alone, unselected stars should be of smaller size than selected stars.

Hover state should be differentiated than set or saved state. This is most easily accomplished by altering the background. Keep in mind that many users will have poor eyesight, so indicators should be bold and obvious.

Hover and set states should utilize an alert color. Saved states should utilize chrome colors.

Since many controls of this nature necessitate the ability for the user to "clear" previous ratings, a control must be included to empty the value. A trash can is an ideal icon for this purpose; clicking on it will reset the value to "0".

Note that it is not necessary to utilize stars for this control; circles or even squares can be just as effective, depending on context.

Progress Monitor
Wizard interfaces - multi-step forms - can benefit greatly from a progress monitor. This is an indication control that provides feedback to the user concerning the steps required or available in the wizard as well as where they are within the wizard's process.

Progress monitors should never compete for attention with the individual steps in the wizard. They should utilize chrome colors exclusively.

If possible, all steps should be displayed. Optional steps can be marked as such, but otherwise steps are assumed to be required.

If the user is required to make a branching choice during the course of the wizard, the progress monitor should be updated to reflect the new position and addtional steps. If steps are removed as a result of this action, they should not be displayed.

Ideally, the progress monitor should be "hot". Clicking on a completed step will bring the user back to that step (with no loss of session information). Passing back through a previously-completed step will overwrite that data with new information.

It is not necessary to number steps within a progress meter.

Text-Only Progress Monitors
A variation on this control is to include a vertical list of steps. This list should be located on the right side of the user's screen and appear as bullet points. The monitor in this case should be colored as chrome.

Live Validation Elements
Certain field elements can benefit from "live validation". In these instances, the value entered by the user is immediately checked for validity through Javascript (either using page-local tests or server requests). These types of fields allow the user to correct known errors without submitting the form and are a powerful usability enhancement.

Live validation events are triggered when the field element loses focus. Validation successes and errors appear in-line with the form element and have icons to draw the user's attention to the result.

Live validation works best with horizontal style error placements.

Live Validation Examples
Here are two examples of live validation behavior.

Password Validity
A common aspect to creating a user account involves creating a password and ensuring its accuracy. This takes two fields: password and confirm password. Both may be checked for validity.

The "Password" field can be checked for password strength and updated instantly. The "Re-Enter Password" field can be checked to ensure its value is the same as the one entered previously.

User Name Selection
User name selection can be a difficult process, especially if the desired username is popular.

If the user name is valid and acceptable, then this is validated as positive. If it is invalid (too short, or has special characters), this can be marked invalid with an error message. If it is taken, this can also be displayed (along with optional suggestions, e.g., "Jimbo Wales29").