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.

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.

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").