# Forms

Collects information from a person with the least typing and the clearest correction.

* Kind: pattern
* Page: https://design.werklist.com/patterns/forms
* Version: 2.1.2

## When to use it

* Creating a record
* Editing a record with a send button
* Public intake forms

## When not to use it

* Asking for what the record, the account or the previous step already holds
* Two columns of unrelated fields
* Saving on send and saving each change on the same screen

## Rules

* Ask only for what WerkOS cannot find out.
* Check a format when the person leaves a field they filled in. Check required answers when the form is sent.
* The send button stays enabled.
* A failed submit moves focus to the first field with an error in a form that fits the window, and to a summary with links in a longer one.
* A settings panel saves each change and says Saved. A form saves when it is sent.

## Anatomy

* Column: One column, at most 768 px, labels above the fields
* Between fields: 16 px (--space-4)
* Between groups: 32 px, each group under a short heading (--space-8)
* Pairs: Two fields on a row only when people read them as a pair. They stack below 640 px.
* Buttons: At the end of the form, secondary then primary, 8 px apart. Below 640 px they take the full width, stacked, the primary on top. (--space-2)
* Sheet on a phone: Below 640 px a form in a dialog is a sheet as tall as the space the keyboard leaves. The questions scroll, the buttons stay at the bottom, and the field being typed in stays 16 px above them.

## States

* Empty: A default is filled in where one answer suits most people
* Sent with answers to change: All errors show at once. In a form that fits the window, focus moves to the first field with an error. In a longer form, a message above the form says how many answers need a change, links to each and takes the focus.
* Sending: The primary button takes no presses and shows a spinner after one second. The answers stay as they are.
* Failed: The answers stay. An error message above the first field says what happened and takes the focus.
* Sent: The new record shows, selected, where the person expects it
* Closing with unsent answers: Ask first: Discard changes? with Discard and Keep editing

## Keyboard

* Enter in a field: Sends the form
* Cmd+Enter or Ctrl+Enter in a text area: Sends the form
* Escape: Closes a form in a dialog, and asks first when answers are unsent

## Accessibility

* Each field shows its own message, under the field.
* Text in fields stays at 16 px on a phone, and the page can still be zoomed by hand.

## Content

* The primary button names the action and the object: Add candidate, Save changes, Send offer.
* A failure says what happened, then what to do: 'The candidate was not saved. Check your connection and try again.'
* When every question is required, one sentence above the form says so, instead of a mark on each.

## Tokens

* --space-2
* --space-4
* --space-8