DesignKit: design tools and components

Playground

Design system

Size Orientation

md / vertical

comfortable

Digest cadence

Daily Fast status rhythm. Weekly Lower-noise update cadence.

Family: Choice
Complexity: core
Status: stable
Mathematical fixtures: 12

choicesingle-selectgroup

Overview

Use radio buttons when users need to compare all choices before selecting one.

Aliases

radio buttons

Foundations

Spacing,Type and scale,Proof system

When to use

Use RadioGroup when the number of options is small enough to display together.
Use descriptions when the difference between options needs a short explanation.

When not to use

Do not use RadioGroup for many options; use Select or Combobox.
Do not use RadioGroup for rapid segmented view switching; use SegmentedControl.

Structural parts

radio group

group

Wraps the full set of mutually exclusive choices.

single radio option

item

Each selectable option with label and optional description.

Public interface

Props
Name	Type	Default	Description
`value`	`string`	`—`	Controlled selected value.
`items`	`Array<{ value: string; label: string; description?: string; disabled?: boolean }>`	`—`	Available radio options.
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	Chooses how the options are laid out.
`label`	`string`	`—`	Visible group label.
`description`	`string`	`—`	Supporting helper copy for the full group.
`error`	`string`	`—`	Problem copy for validation or blocked flows.
`required`	`boolean`	`false`	Marks the group as required.
`disabled`	`boolean`	`false`	Disables the whole group.
`name`	`string`	`—`	Native radio group name.
`size`	`'sm' \| 'md'`	`'md'`	Chooses the size recipe.
`onChange`	`(detail: { value: string }) => void`	`—`	Runs when selection changes.
`theme`	`ThemeContract`	`—`	Sets the theme used to resolve component styles.

Events
Name	Payload	Description
`change`	`{ value: string }`	Fires with the selected option value.

Slots
Name	Description
`default`	`RadioGroup` is data-driven and does not expose option slots.

Variants, sizes, and states

Variants

vertical: Stacked options with more room for descriptions.
horizontal: Compact single-line grouping for shorter labels.

Sizes

sm: Compact group
md: Default group size

States

unselected: No option chosen
selected: One option chosen
disabled: Whole group or item disabled

Accessibility

Semantics

Uses native radio inputs inside a labeled radio group.

Keyboard

Arrow keys move selection within the group according to native radio behavior.

Screen readers

Group label and option descriptions remain associated with the radios.

Checklist

Verify that the control has an accessible name.
Verify that keyboard focus is visible in every state and size.
Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-radio-group-gap: clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-radio-group-item-gap: clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-radio-group-hit-size: 44px

legend

--dk-radio-legend-color: #16181c
--dk-radio-legend-size: clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-radio-legend-weight: 600

item

--dk-radio-item-gap: clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

control

--dk-radio-control-bg: #f2f5fb
--dk-radio-control-border: #95989d
--dk-radio-control-size: 20px
--dk-radio-control-border-width: 1.5px
--dk-radio-focus-ring-color: #2072e4

mark

--dk-radio-mark-bg: #2072e4
--dk-radio-mark-size: 10px

itemLabel

--dk-radio-item-label-color: #16181c
--dk-radio-item-label-size: clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-radio-item-label-weight: 600

itemDescription

--dk-radio-item-description-color: #16181c
--dk-radio-item-description-size: clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

description

--dk-radio-description-color: #16181c
--dk-radio-description-size: clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

error

--dk-radio-error-color: #cc272e
--dk-radio-error-size: clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

Examples

Starter

Cadence selection

A small mutually exclusive option set.

<RadioGroup label="Digest cadence" items={cadenceItems} value="daily" />

Common patterns

Compact horizontal set

Horizontal orientation fits short labels.

<RadioGroup orientation="horizontal" items={sizeItems} value="md" />

Edge cases

Explained options

Descriptions help when the options are subtle.

<RadioGroup label="Review cadence" items={[{ value: 'daily', label: 'Daily', description: 'Fast status rhythm.' }, { value: 'weekly', label: 'Weekly', description: 'Lower-noise update cadence.' }]} />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

default (orientation=vertical|size=sm)

pass

orientation=vertical|size=sm

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

horizontal (orientation=horizontal|size=sm)

pass

orientation=horizontal|size=sm

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

default (orientation=vertical|size=md)

pass

orientation=vertical|size=md

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

horizontal (orientation=horizontal|size=md)

pass

orientation=horizontal|size=md

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

default (orientation=vertical|size=lg)

pass

orientation=vertical|size=lg

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

horizontal (orientation=horizontal|size=lg)

pass

orientation=horizontal|size=lg

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

selected (orientation=vertical|size=sm)

pass

orientation=vertical|size=sm

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

selected (orientation=horizontal|size=sm)

pass

orientation=horizontal|size=sm

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

selected (orientation=vertical|size=md)

pass

orientation=vertical|size=md

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

selected (orientation=horizontal|size=md)

pass

orientation=horizontal|size=md

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

selected (orientation=vertical|size=lg)

pass

orientation=vertical|size=lg

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

selected (orientation=horizontal|size=lg)

pass

orientation=horizontal|size=lg

Evidence: mathematical
Coverage: complete (3 / 3 declared kinds evaluated)
Declared: contrast, target, optionRow
Evaluated: contrast, target, optionRow
Contrast: 65.1 Lc
Target: 44 px
Rows: 44 px

Related components and foundations

Binary setting with on and off states.

Compact single-choice control for switching modes.

SegmentedControl

Compact single-choice control for switching modes.

Select

Single-choice field with a triggered list of options.

Checkbox

Independent choice with checked and indeterminate states.

Spacing

Relate component padding and layout gaps through shared spacing steps.

Type and scale

Generate type sizes and spacing from a modular ratio.

Proof system

Inspect calculated component checks and their coverage.

Chip

Compact selectable label with an optional dismiss action.

Checkbox

Independent choice with checked and indeterminate states.

Switch

Binary setting with on and off states.

SegmentedControl

Compact single-choice control for switching modes.