Components
Checkbox - Design decisions
What is an ADR?
We use the ADR (Architecture Decision Record) to structure design decision documentation. Each ADR covers three things: the context that prompted the decision, the decision itself, and its consequences — including trade-offs and any open questions.
ADR 001 - Checkbox labels don’t contain HTML
- Decision date: November 12, 2026
Context
When teams add extra HTML elements inside a checkbox label, people have to process more than the option they’re choosing. See
Decision
The Design System team decided not to allow HTML inside checkbox labels. Labels stay plain text. Teams that need to give more information use hint text, content before the checkbox group, or a Details component, or they rewrite the label. See Keep checkbox labels simple for the guidance.
Consequences
Positive:
- Interaction targets are predictable.
- Screen reader reading and navigation flow stay simple.
- Options are easier to understand and choose between.
Negative / watch items:
- Teams with HTML in checkbox labels need to move that content elsewhere.