Allows users to enter short pieces of text.

A text field

Provide a user somewhere to enter a limited length piece of text. There should be some indication of how much text is expected (but not necessarily a hard limit).

The text field allows users to enter short pieces of text.

The field should take focus when clicked, or when the tabbed into (see Forms).

It has a number of states it can be in

• Default - this is just the form field being present on the page before the user interacts with it at all. Input typed will not appear in the field at this point, since the field does not have focus.
• Empty - If no text has been entered into the field, then it may show some placeholder text. Placeholders should only ever be used to help indicate the appropriate format for the input, but even then their use is discouraged - such instructions should appear in the label, or in help text near the field, where they won't disappear when the user starts to type.
• Hover - The mouse pointer should also change to a caret style pointer. The border should not change colour. No caret appears in the field. Typed input does not appear in the field as it does not yet have focus.
• Focus - The border changes colour, a caret appears in the field, and typed input will now appear in the field at the caret. Standard key behaviours should work, such as Home/End.
• Disabled - The field is not accepting input. It cannot gain focus, so cannot accept input.
• Error - The field input is not valid. An error message should indicate what the problem is, and how to rectify it.
• Success - The input is valid, a message may provide reassurance that the input is acceptable. It's rare for this to be useful - the lack of an error should be enough to indicate input is acceptable.

To make forms easier to fill in, it's useful to be able to give the user clues about what is expected. One important clue is how much are they expected to type.

Form fields should indicate this by their size - which should be large enough to contain the expected input, with a little spare for comfort.

Detailed description, including

• Behaviours
• Appearance
• Any logic or calculations that are part of the component (e.g. in what circumstances would a checkbox show as indeterminate)
• Anatomy

Text Fields work well for short pieces of text, typically in a form. They typically don't need validation - if they do then they're probably a more specific type of text field, such as a date or email address.

Text Fields work well for short pieces of text, typically in a form. They typically don't need validation - if they do then they're probably...

Describe the context when this component is most appropriate. Something like

Widgets work best when...

Describe when it may be less appropriate, even though it might technically work. For example, (for radio buttons)

Don't use radio buttons if there are more than about 5 options. When there are too many options they take up too much UI space. It also becomes harder to see which option is currently selected when there are too many options.

Don't mentions the alternatives here (they belong in the Alternatives section below) this should all be about the component in question. Instead explain how this component fails in specific (or perhaps extreme) scenarios.

At the moment there are only two sizes available, "Default" and "Small".

List any variations, with illustrations where feasible. If there are multiple dimensions of variations (for example, different size and different colours) then it's not necessary to list every possible combination, but just give a representative sample.

It's important to describe when the various variations would be used.

Any related components. These are not alternatives, but might be:

• Often used with (e.g. a Table might often be used with a Pagination component)
• Depends on (e.g. a Dialog depends on a Button)
• Is depended on by (e.g. Button is required for a Dialog)

Any accessibility issues which this component raises. This should be design-focussed for this section, not technical. (Technical accessibility issues should be documented in the Implementation Guidance tab).

Mention any implementations here, with links to the repository and specific code where possible. E.g.

• HTML & CSS (in Storybook) which uses the design-system-scss repository (in Github), specifically _progress.scss

Document the various classes available here. For components which have a more complex HTML structure, describe the class structure across the entire component.

For example, for the progress bar component, the HTML structure is

<div class="ul-progress -medium">
        <div class="ul-progress__message">Submitting...</div>
        <div class="ul-progress__status">33% complete</div>
        <div class="ul-progress__bar">
          <div class="ul-progress__barComplete" style="width: 33%"></div>
        </div>
      </div>
      

Template: This is an example only. The progress bar documentation my change in future!

Describe any CSS variables which should affect the component. For example, ones used to set colours, border radius and so on.

Describe any semantic HTML which should be used when implementing this. This may be used inside a component, but should be respected for accessibility reasons. e.g. for the Progress Bar

This should be implemented using the HTML progress element, like so:

<progress id="file" max="100" value="70">70%</progress>
      

Any other accessibility guidance should be shown here, for example ARIA attributes.

Alternative CSS for screen readers should also be indicated here.

Describe any testing which should be done on the implementation.