Kwark. Design System
Open Kwark

Segmented control

Two or three mutually exclusive views or modes, all in sight, chosen with one press and moved through with the arrow keys.

ComponentsSelectionIn the app
Where to look · Character library
Learn this method · Character method
When · Calendar date
On a phone: full width, 44px
<div style="display:grid;gap:8px;justify-items:start"><span class="kw-label">Where to look · Character library</span>
<div class="kw-segment" role="radiogroup" aria-label="Where to look"><button type="button" role="radio" aria-checked="true">Library</button><button type="button" role="radio" aria-checked="false" tabindex="-1">My presets</button><button type="button" role="radio" aria-checked="false" tabindex="-1">From a character</button></div></div>
<div style="display:grid;gap:8px;justify-items:start"><span class="kw-label">Learn this method · Character method</span>
<div class="kw-segment" role="radiogroup" aria-label="Learn this method"><button type="button" role="radio" aria-checked="false" tabindex="-1">Understand</button><button type="button" role="radio" aria-checked="true">Watch</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Evidence</button></div></div>
<div style="display:grid;gap:8px;justify-items:start"><span class="kw-label">When · Calendar date</span>
<div class="kw-segment" role="radiogroup" aria-label="When"><button type="button" role="radio" aria-checked="true">On a date</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Follows the shoot</button></div></div>
<div style="display:grid;gap:8px;width:min(100%,375px)"><span class="kw-label">On a phone: full width, 44px</span>
<div class="kw-segment kw-segment--fill" role="radiogroup" aria-label="Manage pages"><button type="button" role="radio" aria-checked="true">Pages</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Order</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Hidden</button></div></div>

What it is

The app’s Segmented (components/ui/Segmented.tsx, styled by .k-seg in system.css) shows two or three choices side by side and marks the current one with a raised ground. Its own comment states the limit: two or three: more than that is a list, not a switch. It is in the Character module (Where to look: Library, My presets, From a character; Learn this method: Understand, Watch, Evidence; Manage pages) and on calendar dates (On a date / Follows the shoot).

When to use

  • Switching the view or the source of one panel: what you see changes, nothing is saved.
  • A mode with two or three named options inside a form.

When not to

  • Four or more options: Tabs for sections of content, a Select for values.
  • Steps in a process: progress steps, never segments.
  • On or off: a Switch.

Behaviour

  • One press chooses; the panel under it changes at once.
  • The arrow keys move the choice and the focus (it is a radio group), wrapping at the ends.
  • Labels are short words, the same width class: Library, My presets. If one option is conditional (Watch only when there are videos), leave it out rather than disabling it, as the app does.
  • On a phone it is the one 40–48px band allowed above the content (Decision 0016), 44px tall, full width.

Library · My presets · From a character, the current one raised, no shadow.

Do

Five segments that wrap to two lines, or a selected segment lit with a coloured glow.

Don’t

Anatomy

  1. Track: 2px padding, 1px --k-line, 10px corners, --k-surface.
  2. Segment: 30px (44 on a phone or touch), 0 16px, 8px corners, Poppins 500 12px (14px on a phone), --k-text-2, no wrapping.
  3. Chosen: --k-raise ground and --k-text. No shadow, no border, no colour.
  4. Hover: the label steps to --k-text. Pressed: a faint --k-raise before release.
  5. Focus: 2px --k-focus ring 2px off the segment.
  6. Phone: .kw-segment--fill stretches the track and shares the width equally.

Tokens

Token Light Dark
--k-raise #f1f5f9 #252525
--k-surface #ffffff #1a1a1a
--k-line #e2e8f0 rgba(255, 255, 255, .1)
--k-text #0f172a #e3e3e3
--k-text-2 #5b6779 #9ca3af
--k-focus #0f172a #f4f4f5
--k-radius-card 10px
--k-tap 44px
--k-fs-meta 12px

React

In the Kwark app: import { Segmented } from '@/components/ui/Segmented'.

<Segmented<'library' | 'mine' | 'copy'> label="Where to look" value={door} onChange={setDoor}
  options={[{ value: 'library', label: 'Library' }, { value: 'mine', label: 'My presets' },
    { value: 'copy', label: 'From a character' }]} />
Prop Type Notes
value T extends string The current option.
options readonly { value: T; label: string }[] Two or three. More is a list, not a switch.
label string Names the radiogroup.
onChange (value: T) => void Called on click and on arrow keys.

HTML and CSS

Works anywhere with kwark.css.

<div style="display:grid;gap:8px;justify-items:start"><span class="kw-label">Where to look · Character library</span>
<div class="kw-segment" role="radiogroup" aria-label="Where to look"><button type="button" role="radio" aria-checked="true">Library</button><button type="button" role="radio" aria-checked="false" tabindex="-1">My presets</button><button type="button" role="radio" aria-checked="false" tabindex="-1">From a character</button></div></div>
<div style="display:grid;gap:8px;justify-items:start"><span class="kw-label">Learn this method · Character method</span>
<div class="kw-segment" role="radiogroup" aria-label="Learn this method"><button type="button" role="radio" aria-checked="false" tabindex="-1">Understand</button><button type="button" role="radio" aria-checked="true">Watch</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Evidence</button></div></div>
<div style="display:grid;gap:8px;justify-items:start"><span class="kw-label">When · Calendar date</span>
<div class="kw-segment" role="radiogroup" aria-label="When"><button type="button" role="radio" aria-checked="true">On a date</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Follows the shoot</button></div></div>
<div style="display:grid;gap:8px;width:min(100%,375px)"><span class="kw-label">On a phone: full width, 44px</span>
<div class="kw-segment kw-segment--fill" role="radiogroup" aria-label="Manage pages"><button type="button" role="radio" aria-checked="true">Pages</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Order</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Hidden</button></div></div>

Keyboard (from Segmented.tsx)

Key Does
Tab Into the group, onto the chosen segment (roving tabindex: only it is 0).
Right / Down Next option, chosen and focused; wraps.
Left / Up Previous option; wraps.
Home / End First / last option.

Roles and names

  • role="radiogroup" with an aria-label (Where to look); each segment is role="radio" with aria-checked.
  • When the control switches between panels of one page, the panel it shows follows it directly in the reading order.
  • Chosen is shown by ground and text colour together; screen readers hear checked.

Rules

  • Never put more than three options in a segmented control.
  • Must show the selected state with surface and text colour, never a glow or shadow.
  • Must implement arrow keys with roving tabindex, as the shared Segmented does.
  • Always leave out an option that does not apply rather than disabling it.
  • Always make it 44px tall and full width on a phone.

AI readiness test

Task. Let the Outline switch between cards, list and timeline.

Give the agent. Segmented control, Tabs.

Constraint. The current view stays visible; it must work on a phone.

A reliable answer

  • Shared Segmented with three options
  • radiogroup with aria-checked and roving tabindex
  • Arrow keys move and choose
  • 44px full width on a phone
  • Not a dropdown

Give this Markdown to your coding agent or share its URL.

Open .mdllms.txt
Loading…