Maturity
Overview
Types
🎖️ Checkbox Field — preferred
The Checkbox Field is a Field composition that wraps a Checkbox Control. This component is meant to be used alone, containing all the necessary elements to make the control usable and accessible.
The following documentation speaks mainly to the Checkbox Control but also covers parts of the Checkbox Field. For more general information on the Field, check out the Field guidelines.
⚠️ Checkbox Control — use with caution
The Checkbox Control is bare-bones and doesn’t include a Label or Helper Text. Never use it alone but as part of other parent components, like Table rows or Cards.
Anatomy
A Checkbox Control is an interactive area where users can select and deselect content.
Properties
The following properties are jointly defined by design, engineering, and UX writing to speak a common language
|
Name |
Values |
Default |
|---|---|---|
|
Disabled Disables all interactions |
boolean |
False |
|
ReadOnly Disables interaction and focus and signifies it |
boolean |
False |
|
Empty |
boolean |
True |
|
Error Signifies that input value is required to allow users to progress |
String |
- |
|
Indeterminate |
Boolean |
False |
How to use
Please, note that this control is meant for isolated usage (Checkbox Field) or as part of another component (Checkbox control). For checkbox groups, we plan to incorporate Selection groups soon. In the meantime, we’re here to support you.
Checkbox Control
This control should always be used as part of other components, providing context for the action the user is performing.
Checkbox Field
The Value Label should help people immediately understand what information is selected when activating the control.
Behavior
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
Indeterminate variant
When the property Indeterminate is True indicates that selection has been made for some, but not all, elements on the list.
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. A 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.
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.
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.