Anatomy
- Check Box — 24×24 px square, radius
--ds-radius-xs - Check Mark — ✓ when checked, — when indeterminate, color
--ds-color-text-white-primary - State Layer — Semi-transparent background overlay on hover/press
- Label — Descriptive text for the option
Usage Guidelines
Do ✓
- Use for multi-select scenarios (filters, bulk actions, preferences) where each option is independent
- Write labels that describe the selection outcome, not the action (e.g. "Accept terms" not "Click to accept")
- For more than 8 options, provide a "Select all" control with Indeterminate state for partial selection
- Arrange vertically, one option per row, for alignment and readability
Don't ✗
- Don't use checkboxes for mutually exclusive selection — use Radio instead
- Don't use checkboxes as instant toggles — use Switch for immediate state changes
- Don't omit labels — screen readers rely on labels to identify a checkbox's purpose
Interaction Behavior
| State | Description |
|---|---|
| Default | Default appearance, not focused |
| Hover | Mouse hover shows semi-transparent state layer around the box |
| Focus | Keyboard focus shows focus ring |
| Disabled | Fully grayed out, pointer-events: none |
Accessibility
| Requirement | Implementation |
|---|---|
| Semantic element | Radix UI @radix-ui/react-checkbox, native role="checkbox" |
| Label association | htmlFor + id — clicking the label equals clicking the box |
| Indeterminate state | checked="indeterminate" |
| Grouping | Related checkboxes grouped with <fieldset> + <legend> |

