Fields guidelines

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

The following documentation is common for all the Form Fields.

Maturity

FYQ2 target

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.
Choices	A selection tool to make clear, concise choices from a list of options.
Radio	A control that enables people to select one option from multiple presented.
Text Area	Allow people to enter multiple lines of text.
Text Input	A single-line text field. Line breaks are automatically removed from the input value.

Anatomy

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

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

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.

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.

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

⛔️ 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.

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

Related content:

UI Text Patterns

Learn more about the Label text pattern

Required

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.

It makes a label less readable.

⛔️ Avoid marking as required in a placeholder.

A placeholder vanishes immediately when a person starts typing.

⛔️ 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.

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.

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.

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

⛔️ Avoid using a label to mark as optional.

Long labels will be more difficult to scan.

✅ Optional controls don't need a signifier.

Instead, we indicate the required fields using an asterisk.

Helper text

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.

⛔️ Avoid presenting exemplary content in a helper text.

In some scenarios, you will need to show both.

✅ Show exemplary content in a placeholder.

Use it only when necessary.

✅ 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

UI Text Patterns

Learn more about the Description text pattern

Max length

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.

Limiting the character count is considered an edge case. Use sparingly.

Arrangement

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.

Users tend to miss secondary columns.

✅ 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

Product Space

Create balance, organize information, and make our designs easier to scan and use.

Horizontal stack

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

Related content

Product Space

Create balance, organize information, and make our designs easier to scan and use.

Behavior

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

α · 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.