Fields guidelines

A supportive wrapper to contextualize a Form Control and support the actions it performs.

Cover

Maturity

RC

FYQ2 target

RC

Overview

The Fields wrap any Form Control and provide context via the Label, the Helper Text, and other metadata. It’s the preferred way of using forms as they are more usable and accessible out of the box—unlike bare-bones Controls.

Types

There are different types of Field components depending on their purpose. Each has different properties and uses. Here is a summary:

Name

When to use

Preview

Checkbox

A control that allows people to make single or multiple selections.

null

Choices

A selection tool to make clear, concise choices from a list of options.

null

Radio

A control that enables people to select one option from multiple presented.

null

Text Area

Allow people to enter multiple lines of text.

null

Text Input

A single-line text field. Line breaks are automatically removed from the input value.

null

Anatomy

All the elements that wrap the control are considered part of a Field.

Anatomy of a Text Input

Anatomy of a Text Input

1. Label
2. Required indicator
3. Helper text
4. Max length

Properties

Name

Values

Default

Label
Provides meaning to the control

String

-

Required

Signifies that input values is required by the control

Boolean

false

Helper text

Provides additional meaning to the control and helps with the usage

Boolean

false

Max length

Limits the amount of character control can hold

Boolean

false


How to use

Label

Label property

A label is a short text—typically one to three-word long—that helps people immediately understand what data they need to introduce.

⛔️ Avoid writing labels as instructions.

⛔️ Avoid writing labels as instructions.

People understand how a field works and that they need to fill it out to get the job done.

✅  Write labels that are brief and clear.

✅  Write labels that are brief and clear.

A label is a descriptor (“It's a title”), not a command (“You need to enter a title”).

⛔️ Avoid conversational labels.

⛔️ Avoid conversational labels.

They're not as readable and scannable as short, descriptive labels with one to three words.

✅  Write labels that are brief and clear.

✅  Write labels that are brief and clear.

A label is a descriptor (“It's a title”), not a conversation (“What title do you choose?”).

Related content:

Required

Required property

Input values can be optional or required in form controls. When it’s required, an asterisk is displayed right on the label. If the Required property is on, but the control is empty when the user tries to submit the form, an error will show up.

⛔️ Avoid marking as required in a label.

⛔️ Avoid marking as required in a label.

It makes a label less readable.

⛔️ Avoid marking as required in a placeholder.

⛔️ Avoid marking as required in a placeholder.

A placeholder vanishes immediately when a person starts typing.

⛔️ Avoid marking as required in a helper text.

⛔️ Avoid marking as required in a helper text.

You might need to use both; to provide additional details and to inform people that they need to fill out the form.

✅ When a control is required, use the Required property.

✅ When a control is required, use the Required property.

Adding an asterisk is a widely-adopted way to mark a required control. It's compact and recognizable by people.

Optional fields

Fields are optional as default and don't need a signifier.

⛔️ Avoid marking as optional in a placeholder.

⛔️ Avoid marking as optional in a placeholder.

If a person gets distracted when filling out a field, they have to put in extra effort to identify if it's optional, or not.

⛔️ Avoid using a helper text to mark as optional.

⛔️ Avoid using a helper text to mark as optional.

It might be necessary to provide additional guidance in a helper text.

⛔️ Avoid using a label to mark as optional.

⛔️ Avoid using a label to mark as optional.

Long labels will be more difficult to scan.

✅ Optional controls don't need a signifier.

✅ Optional controls don't need a signifier.

Instead, we indicate the required fields using an asterisk.

Helper text

Helper text property

A helper text provides additional guidance about a field. For example, it can inform people about what kind of data they need to enter or how data will be used.

✅ Provide additional guidance on controls that require it.

✅ Provide additional guidance on controls that require it.

⛔️ Avoid presenting exemplary content in a helper text.

⛔️ Avoid presenting exemplary content in a helper text.

In some scenarios, you will need to show both.

✅ Show exemplary content in a placeholder.

✅ Show exemplary content in a placeholder.

Use it only when necessary.

✅ Links can be placed in a helper text

✅ Links can be placed in a helper text

Ensure that the action a user will take by clicking the link is accurately described.

Related content

Max length

Max length property

Controls can have rules about how many characters they allow. Character count can be defined for all Text Inputs and Textareas and displayed at the bottom right corner, the same row as the Helper text.

Arrangement

Arrangement 1

Fields are usually displayed in forms with a variety of input controls. The standard way to stack multiple fields is vertical, but horizontal forms are allowed in some exceptions.

Vertical stack

⛔️ Avoid multiple column layouts.

⛔️ Avoid multiple column layouts.

Users tend to miss secondary columns.

✅ Single column layouts are easier to scan and complete.

✅ Single column layouts are easier to scan and complete.

There is no way users can get lost since goes from top to bottom.

Use a single-column layout. Multiple-column layouts can be confusing because people must think about the right direction to fill the form. Additionally, they are not mobile-friendly. The distance between fields should be 16px/MD.

Related content

Horizontal stack

Arrangement - Do - 2

In some cases—mainly when using filters—we can display single-row forms. The distance between fields should be 16px/MD.

Related content


Behavior

Width

Properties width

Properties width

1. Label: Left aligned and can double line even if not recommended. While growing in characters, push the “required” signifier. If the container grows, keep it stuck to the left.
2. Helper text: Left aligned and can double line. If the container grows, keep it stuck to the left.
3. Max width indicator: Do not double line and stick to the right if the container grows.

The Control defines the width of a Field. Fields hold a 100% width by default.


Quality checklist

This component passes the Release Candidate quality checklist described in our Component lifecycle.

Maturity

RC

α · Design tokens

It uses Ariane design tokens.

α · Official assets

It uses the official Ariane assets (e.g., icons and illustrations) in one of the official sizes.

α · Accessible use of color

Its color contrast ratio is at least 4.5:1 for text and interactive areas.

α · Target areas

Its interactive target areas are large enough for users to accurately select them, following the Fitts law.

α · Naming agreement

Its name is agreed upon and shared between design and development.

α · Responsive L1

Is responsive to different viewport sizes.

α · User-triggered states

If the component is interactive, all its possible user-triggered interactive states are defined.

β · Responsive L2

The responsive behavior has been reviewed and validated by the team.

β · State properties

All the possible state attributes are defined.

β · Docs L1

It has essential documentation with at least primary usage.

β · Use cases

All the uses are audited and refined.

RC · Definition agreement

Its naming and properties are audited and aligned in design and code.

RC · Accessible L1

Its accessibility is manually audited, and any significant issues are fixed.

RC · Docs L2

The documentation covers the most common use cases and is expected to be iterated during the Release Candidate phase.

RC · Storybook

Includes a Storybook playground of the component.

Stable · Stable API

The component and its API remain stable, with no breaking changes for at least one month.

Stable · Adaptive

Supports adaptive design via preference queries.

Stable · Docs L3

Detailed documentation exists for design, content, accessibility, and implementation, including do’s and dont’s.

Stable · Tooling

Tooling (such as linters, codemods, etc.) exists to help with migrations and prevent further use of alternatives.