Components
Radio Button - 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 - Radio button labels don’t contain HTML
- Decision date: November 12, 2026
Context
When teams add extra HTML elements inside a radio button label, people have to process more than the option they’re choosing. See
Decision
The Design System team decided not to allow HTML inside radio button labels. Labels stay plain text. Teams that need to give more information use hint text, content before the radio button group, or a Details component, or they rewrite the label. See Keep radio button 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 radio button labels need to move that content elsewhere.