Maturity
Overview
Types
🎖️ Choices Field — preferred
The Choices Field is a Field composition that wraps a Choices Control. This is the preferred component as it has all the elements needed to make the control usable and accessible.
The following documentation speaks mainly to the Choices Control. For more general information on the Field, check out the Field guidelines.
⚠️ Choices Control — use with caution
The Choices Control is bare-bones and doesn’t include a Label or Helper Text. It is composed of a set of Choice Item controls.
Anatomy
Choice Item Control
Choice Item Control should never be used in isolation.
The Choice Item control is composed of a Checkbox/Radio Control and a Value Label.
Properties
|
Name |
Values |
Default |
|---|---|---|
|
Value Label |
String |
- |
|
Disabled Disables all interactions |
boolean |
False |
|
ReadOnly Disables interaction and focus and signifies it |
boolean |
False |
|
Empty |
boolean |
True |
|
Error Signifies that choice item selection is required to allow users to progress |
String |
- |
|
Type |
single-select | multi-select |
single-select |
|
Description |
boolean |
False |
Choices Control
A Choices Control is composed of two or more Choice Item Controls.
Properties
|
Name |
Values |
Default |
|---|---|---|
|
Error |
String |
- |
|
Group heading |
Boolean |
False |
|
Orientation |
Vertical | Horizontal |
Vertical |
How to use
Preselecting content
Whether or not to preselect options in the Choices Control can assist users in making the most appropriate choice for their particular context.
Value Labels and Descriptions
Value Labels describe choices; descriptions provide detailed meaning. While Value Labels are mandatory, Descriptions are optional and must be used sparingly.
Value Label
Description
Related content
Single-select vs. Multi-select
Choices inherit their functionality from Checkboxes and Radios. To enable the selection of multiple items from a list, we use the Multi-select option. Similarly, we would use the Single-select option if we only want to allow users to select a single item from the list.
Disabled and ReadOnly
The Disabled and ReadOnly attributes have been consistently applied across all selectable items in this context, ensuring uniformity in their usage
Number of choices
The number of choices in the Choice Field is restricted to a range of two to six options. This limitation ensures that any text or error messages are displayed in close proximity to their respective labels, making the selection process more intuitive.
Orientation
The Choices Control offers flexibility in displaying options, adapting to Vertical (default) and Horizontal orientations based on use cases. The Vertical orientation is preferred for scalability, content variety, and viewport sizes.
Sizing and Spacing
We use standard sizing and spacing for all interactive controls to improve the experience depending on the information density and make our interface more accessible, predictable, and easy to use.
Related content
Full-width
The Vertical Choices Control is designed to adjust its width to fit within its parent container while accounting for any padding. Once it reaches the maximum width allowed by the container, the Value Label will automatically wrap to the next line, causing the height of the container to increase as needed.
The Horizontal Choices Control is designed to keep always in one line, in a way that Choice Items never stack. The Value label gets truncated depending on the available space in the container.
Min-width
The Choices Control is set to have a minimum width of 120px. Suppose the container's width exceeds this limit and the Value Label extends beyond the available space. In that case, the label will be truncated, losing any text that extends beyond the limit.
Behavior
Choice Item Control States
The state of a component can depend on properties set before people can interact with it. We call them state properties. Differentiating them from the user-triggered states allows us to combine them, creating richer states that cover the whole interaction spectrum.
Related content
Default variants
Error variants
ReadOnly variant
When the property ReadOnly is True, people can’t edit the control. ReadOnly displays values in an accessible way so that users can read them. ReadOnly control can be focused and hovered but can’t be interacted with.
Disabled variant
When the property Disabled is True, users can't edit the control. A Disabled control cannot be focused or hovered.
Choices Control states
The state of a component can depend on properties set before people can interact with it. We call them state properties. Differentiating them from the user-triggered states allows us to combine them, creating richer states that cover the whole interaction spectrum.
Related content
Default variants
Error variants
Quality checklist
This component passes the following requirements 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.