Basics

All fields must be wrapped into a div or fieldset with the class form-fields. They should be used for a single concern - for example for a select field, a radio button set, or just single text input fields. These wrapper will added necessary margins and are the bearers of the context of field(s). In practice, they are quite similar to the ones used in Twitter Bootstrap.

When marking up forms and using labels and fieldset you should remember that:

  • div's should never be children of labels
  • fieldset's should never be children of labels
  • a label element can contain at most one input, button, select, textarea or keygen

All of the above go against the html5 spec, so there is no guaranteed browser behaviour.

Labels

A label element does not have any styles; use the strong tag to get correct CSS and label tag to get the correct focus behaviour.

Example forms

First Example Form
Preferred Primary Address
Addresses Home Address:

Required wrappers

All forms require the .form class. The selector itself is not styled to allow for some flexibility in form usage (so hidden/temp forms don't affect layout or rendering for example).

Each form field or group of related form fields (like an address) should be wrapped in a .form-fields div or fieldset (if appropriate). This wrapper class defines layouts of fields and is required in even the simplest forms.

Form controls

Text field

Select field

Augmented Select field (Select 2)

You also **HAVE TO** define the following select in your form for it to work with rails. Don't forget to use the no-js-show class on it to avoid showing this to normal users.

Selected values: {{ selectDemo.currentlySelected.people }}

Radio buttons

Default
Disabled

Checkboxes

Textareas

Form meta

Everything that gives more context to a field or it's state.

Descriptions

Generic body text for forms. Any text within a form and wrapped into a p or span tag will look like this. Use paragraphs if you want bottom margin and spans if not. This is how text for radios and checkboxes should be marked up as well.

The text within a form is a bit smaller.

Soft descriptions

This is a variant of the description meant to be a bit more in the background, but still not hidden behind an event. Intend for sign-up forms.

Note that you need to add a class for this style, while the normal description receives it's style because it's within a form.

Fine things will happen if you fill out the above.

Validation hints

These contain specific requirments for a field, ie. how they should be formatted or what should the input contain (ie. minimum length) and are displayed only on field focus.

For groups of inputs like checkboxes and radios use descriptions, labels and the required "*" to indicate validaton requirments.

Purpose hints

Purpose hints, as the name suggests should clarify anything about a field that might be ambigeous. It is not a place for lengthy explanations - these should be contained in descripton text or in extreme cases, external pages.

The hints can placed next to a label or field.

Choose a color Be sure to choose one that you REALLY like.

Required fields

The required element is purely stylistic and can be put anywhere where you can put a span tag with the right class, if needed.

For required inputs, remember to add the required

Errors

Error are represented as smaller flash messages and are meant to sit beside a label marking a group of fields (or just a single field)

Note that inside labels, the form-error class is on a span and not a div, which is not allowed by the html5 spec (a label expects phrasing not flow content).

Options Please choose one of the below

Layout and grouping

Block-level fields are our default display, and will make each form field and any corresponding labelling text display vertically one after the other

Block

Inline

Joined (only for form-inputs)

Name

Stacked (only for form-inputs)

Name

Radios and checkboxes with strong tags as descriptions

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis au.

Accessibility

Fieldsets & Legends

You should always include <fieldset> tags that section out your forms into meaningful related "chunks". Each fieldset should also have a <legend> that describes its contents. Although our fieldsets and legends are hidden on regular devices, this helps users on assistive devices understand the context of the form controls contained within each fieldset. Many screen readers will also read out the legend associated with each form control within a fieldset after each tab of the keyboard, so that a particular control can always be referenced back to its legend.

ARIA Attributes

Although we visually indicate required and invalid fields, many assistive technologies cannot necessarily infer this information from the presentation. This is where ARIA attributes come in - they provide us attributes we can use for indicating that form controls are required or invalid:

  • The aria-required attribute should be applied and set to "true" to a form element to indicate to an assistive device that it is required to complete the form.
  • The aria-invalid attribute should be applied to indicate to an assistive device which data fields have incorrect data, so that the user knows they have entered invalid data.