Style guide/Forms

An example form, showing an account creation screen

An example form, showing a login screen

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

An standard form element

A grouping of checkboxes

A grouping of radio buttons

A select pull-down

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

See Style guide/Color selection and accessibility#Color Selection.

Accessibility for Visually Impaired Users

See Style guide/Color selection and accessibility#Accessibility for Visually Impaired Users

General Patterns

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.

A standard form element

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.

Research References

• UX Movement: Users fill forms faster with top-aligned labels
• UX Matters: Label Placement in Forms (contains excessive eye-tracking data)
• Luke Wroblewski Top, Right or Left Aligned Form Labels
• CSS Tricks: Label Placement on Forms
• Stack Exchange (Good summary of Luke Wroblewski's research)

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:

A button grouping

[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

A button moving from disabled to active state

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.

Building buttons

Rather than creating new button styling for every extension, please reuse the styles already set up in MediaWiki. The easiest way to do this is to use jQuery UI. Here is an example of creating a grey search button with a search icon:

$( 'a#searchLink' ).button( {
    label: mw.msg( 'Search' ),
    icons: {
        primary: 'ui-icon-search'
    }
} );

To make the button green:

$( 'a#searchLink' ).addClass( 'ui-button-green' );

Colors supported in the Vector skin are green, blue, orange, and red. No other skins currently support button colors. All standard jQuery UI icons are currently supported (regardless of skin); see /resources/jquery.ui/themes/default/jquery.ui.theme.css for the full list.

If the button is tall (more than one line of text), add the 'ui-button-large' class as well.

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

An optional form element

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.

A required form element

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

An focused form element

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

A form element with a help trigger

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

A form element with an active help tooltip

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

A form element with 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

A form element with hint text

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

A form element with hint text that is focused

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.

Error Handling

See Style guide/Error handling and validation#Error_Notification_Techniques.

Special Function Elements

See Style guide/Specialized form elements.

Client-Side Validation

See Style guide/Error handling and validation#Client-Side_Validation.

Assets

PNG Format

SVG Format

Gallery

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
•