recursica-skill-segmented-control
Rules for the Recursica segmented control, the horizontal single-select — when to use a segmented control instead of radio buttons, a dropdown, tabs, or chips, orientation and fill width, the 2 to 5 option limit, and radio-group accessibility. Use for view switchers, inline filters, and mode toggles. Not for multi-select — see recursica-skill-chip; not for parts of one whole — see recursica-skill-tabs.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- recursica-skill-segmented-control
- license
- MIT
- metadata
- { "author": "hi@borderux.com", "version": "0.2.0" }
- description
- Rules for the Recursica segmented control, the horizontal single-select — when to use a segmented control instead of radio buttons, a dropdown, tabs, or chips, orientation and fill width, the 2 to 5 option limit, and radio-group accessibility. Use for view switchers, inline filters, and mode toggles. Not for multi-select — see recursica-skill-chip; not for parts of one whole — see recursica-skill-tabs.
03 SKILL.md 正文
Segmented control
A segmented control is a horizontal radio group. The persona selects exactly one of 2 to 5 options, and every option is visible at once. For example, a "List" and "Grid" control switches how a page of orders is shown.
When to use a segmented control
-
The persona selects exactly one option, and the options sit side by side in a row. A segmented control is the house component for a horizontal single-select. Never lay out radio buttons in a horizontal row.
-
The screen needs a toggle outside the page's content. A switch belongs only in the page's content. Use a segmented control for every two-state control in these places:
- application chrome (the header, navigation and footer around the content)
- a filter bar
- a toolbar
In application chrome, show icons in the segmented control instead of text labels. The standard example is a control that switches between light mode and dark mode. See
recursica-skill-layouts-and-templatesfor where application chrome sits. -
The choice has 2 to 5 options, with short labels.
-
The choice switches a view or a mode, such as list or grid, or daily or weekly. The options are closely tied to the content on the screen.
-
The persona filters content where the content is shown. The filter is too simple for a dropdown or a modal. For example, "Open" and "Closed" above a table of orders.
When not to use a segmented control
| Instead of a segmented control | Use |
|---|---|
| More than five options | A vertical radio group. Use a dropdown for more than 7 ± 2 options. |
| The persona may choose more than one option | Selectable chips for a horizontal layout, or a checkbox group for a vertical layout. |
| The labels are long or complex | A vertical radio group. Long labels do not fit the compact layout of a segmented control. |
| The options are parts of one whole, and each part has separate content | Tabs, which give each part a separate URL. See recursica-skill-tabs. |
| Switching to another option causes a heavy reload or changes data | A control with an explicit submit action, such as an "Apply" button, and feedback. |
| The choice is on or off, in the page's content | A switch or a checkbox. See recursica-skill-selection-controls. |
Never switch to tabs when a segmented control grows past five options. Use a vertical radio group or a dropdown instead.
- Tabs hold the parts of one whole, such as the "Details" and "History" sections of one order.
- A segmented control holds the options of one single-select field, such as "Daily" or "Weekly".
Tabs never replace a segmented control, and a segmented control never replaces tabs.
Variants
Use only the segmented control variants and options that the knowledge MCP server lists for the theme (the design a designer sets in Theme Forge: the token values, the components, and each component's variants, states and sizes). A designer can add variants and options in Theme Forge, so each theme can differ. Get the list with the server's component_api tool, and use the names the code uses. Never invent a variant or an option.
The rules below describe each option by role, such as "the horizontal orientation". The names in the standard UI kit (the unchanged UI kit in the official Recursica release) are examples only.
- A segmented control has two parts: the control and the segments. The control is the whole group of options. A segment is one option in the group. In the standard UI kit, the two parts are
segmented-controlandsegmented-control-item. - The control has an orientation variant, with a horizontal option and a vertical option. Always use the horizontal option. The orientation rule under "Rules" gives the reason. In the standard UI kit, the variant is
orientation, with the optionshorizontalandvertical. - The control has a fill-width variant, and fill width is off by default. In the standard UI kit, the variant is
fill-width, with the optionsfalseandtrue. With fill width on:- the control stretches to the width of the container the control sits in, such as a card
- the segments share the control's width equally
- Each segment has a selection variant, with a selected option and an unselected option. In the standard UI kit, the variant is
selection-states, with the optionsselectedandunselected. - A segment may show a leading icon.
Rules
Give a segmented control 2 to 5 options. The general guideline for the number of options in a choice is 7 ± 2. The 2-to-5 limit overrides the guideline for a segmented control. The limit is tighter because a segmented control is horizontal and compact. recursica-skill-selection-controls sets this rule.
Use the horizontal orientation, even when the theme's UI kit has a vertical orientation. A segmented control is the house component for a horizontal single-select, and for no other layout. recursica-skill-selection-controls names the radio group as the vertical single-select, with the options stacked one above another. Build a vertical single-select as a radio group.
Write each segment label in one or two words, such as "Daily" or "Last week". If a label needs more than two words, use a different control.
Keep one option selected at all times. A segmented control never shows with no option selected. The control is a single-select field with a default option. Choose the default option by the pre-selection rules in recursica-skill-selection-controls.
Save segmented control changes in the same mode as every other part of the application. See recursica-skill-design-system-conventions.
- If the application saves selection changes immediately, save the segmented control's changes immediately too.
- If the application saves all changes together, save the segmented control's changes with all the other changes.
- Never give a segmented control a separate save mode.
Switching to another option must be quick and must not be destructive. If a switch would be slow or destructive, use a control with an explicit submit action and feedback instead.
A segmented control used as a toggle follows every rule in this skill. A segmented control with two options is still a segmented control, not a switch. The rules include:
- 2 to 5 options
- one option always selected
- quick switching that is not destructive
Give every icon-only segment a name, such as "Grid view" for a grid icon. An icon alone does not say what the segment does. See the screen reader rules below.
Never turn on fill width to fit more options. A segmented control with fill width on still has a limit of 5 options.
Accessibility
The rules below add to the accessibility baseline in recursica-skill-design-system-conventions, including the focus ring, which every Recursica component follows.
Build a segmented control as a radio group. The most common mistake is a row of buttons where only color marks the selected button. A row of buttons fails in two ways:
- A screen reader does not announce the color.
- A persona using a keyboard has to tab through every segment.
Screen readers
- A screen reader must announce the segmented control as a group of radio options with exactly one option selected. A screen reader must not announce the segmented control as a group of buttons.
- Give the group an accessible name (the name a screen reader reads out for a control) that says what the persona is choosing, such as "View" or "Date range". Without the accessible name, a persona using a screen reader hears the options but not what the options are for.
- A screen reader announces each segment's label, and whether the segment is selected. The selected state must be available in code.
recursica-skill-design-system-conventionsforbids showing the selected state by color alone. - An icon-only segment must have an explicit accessible name. A screen reader does not announce the icon.
- A screen reader must not announce a leading icon beside a label. The leading icon is decorative.
- If a selection changes the screen content, a persona using a screen reader must be able to perceive the change. A persona using a screen reader who hears nothing after a selection cannot know the view changed.
Keyboard and non-mouse navigation
- The group is a single tab stop (a place the Tab key lands). The Tab key moves focus into the segmented control and then out of the segmented control. The Tab key does not step through every segment. Do not add a tabindex to any single segment.
- The arrow keys move the selection within the group, in the direction of the orientation.
- The Left and Right arrow keys move the selection in a horizontal control.
- The Up and Down arrow keys move the selection in a vertical control.
- The Home key moves to the first segment, and the End key moves to the last segment.
- Keep each change of selection quick and not destructive. The arrow keys select every segment on the way. For example, pressing Right twice from "Daily" selects "Weekly" and then "Monthly". Use a different control for a slow or destructive switch.
- When the persona tabs into the group, focus lands on the selected segment, not on the first segment.
- Focus and selection must look different. Focus can be on one segment of the group while a different segment is selected. Both the focus and the selection must be visible.
Styling set by tokens
Never set or override the segmented control's styling. The theme sets every visual property of the segmented control, such as size, spacing, borders, colors and animation. Do not add extra containers or spacers to change the segmented control's look. If the theme does not give a look the design needs, report the missing look as a design-system gap. See recursica-skill-design-router.
Related skills
recursica-skill-selection-controls— when to use a segmented control, the rules shared with radio groups, pre-selection, and when a change is saved.recursica-skill-working-memory— the research basis for the limits on the number of options.recursica-skill-design-system-conventions— one behavior mode for the whole system, and never showing meaning in only one way.recursica-skill-forms— label placement and validation when the segmented control is a form field.
Open questions
- When to use fill width. No rule says where a segmented control with fill width on is used.
- A disabled segment. No rule says whether a single segment may be disabled, or how a disabled segment looks. Confirm with the user only when the theme has no disabled state.
- A segmented control as a form field. No rule says whether a segmented control may be a labeled form field instead of a view switcher. No rule says where the label goes if a segmented control may be a form field.
- Screens narrower than desktop size. Five short labels may not fit on a narrow screen.
recursica-skill-responsive-layoutsets the rules below the tablet breakpoint. No rule says what a segmented control does when the labels do not fit.
Pre-flight checklist
- [ ] Exactly one option can be chosen, and one option is always selected.
- [ ] The segmented control has 2 to 5 options, each with a label of one or two words.
- [ ] A choice with more than five options uses a vertical radio group or a dropdown, not tabs.
- [ ] The segmented control saves changes in the same mode as every other part of the application.
- [ ] Switching is quick, and selecting an option causes no slow reload and no destructive change.
- [ ] A screen reader announces the group as a radio group with an accessible name and one option selected.
- [ ] The selected state is available in code and is not shown by color alone.
- [ ] Every icon-only segment has an explicit accessible name.
- [ ] The group is one tab stop. The arrow keys move the selection, and no single segment has a tabindex.
- [ ] Focus lands on the selected segment when the persona tabs in.
- [ ] A persona using a screen reader can perceive every content change that switching causes.
- [ ] Every variant, option, and state is one the theme's UI kit lists, and no variant or option is invented.
- [ ] The orientation is horizontal, and every vertical single-select is a radio group.
- [ ] No styling is set or overridden on the segmented control.
- [ ] No container or spacer is added to change the segmented control's look.
- [ ] Open questions were asked about, not decided: when to use fill width, a disabled segment when the theme has no disabled state, a segmented control as a labeled form field, and behavior below desktop size.
04 同仓库更多 Skills
recursica-skill-template
Replace with a description of the skill and its purpose.
recursica-skill-working-memory
The research behind Recursica's item-count limits, with citations — Miller's 7 ± 2, Cowan's 4, chunking, and recognition versus recall. Use when a decision turns on how many options, navigation items, or chips to show at once, or to justify or challenge a count. Not for choosing a control — see recursica-skill-selection-controls.
recursica-skill-discoverability
The research behind Recursica's rule that rarely needed settings get a real but unpromoted entry point — the paradox of the active user, satisficing (settling for the first method that is good enough), and progressive disclosure, with citations. Use when deciding whether to hide, promote, or build a configuration or customization feature, or to justify that choice. Not for item counts — see recursica-skill-working-memory.
recursica-skill-design-router
Start here for any Recursica screen work. The router says what to decide in what order, which skill owns each decision, which rule wins when two rules conflict, and when to confirm with the user instead of guessing. Load the router first to design, build, review, or refactor a screen, page, panel, or flow, or when rules seem to disagree or no rule applies. The router routes, and the owning skill holds the rules.
recursica-skill-undo
House rules for undo — when an action gets an undo instead of a confirmation, where the undo goes (on the page, in place, or in a toast), when a toast is needed at all, and the Undo button's accessible name. Use whenever an action can be reversed, or when choosing between an undo and a confirmation. Not for building the toast that holds an Undo button — see recursica-skill-toast. Not for the confirmation modal — see recursica-skill-buttons-links.
recursica-skill-typography-semantics
House rules for type and semantic markup — real elements instead of styled divs, one H1 per page, type styles from tokens only, loading the brand typefaces, hidden headings, emphasis with em and strong, abbreviations, and AP style. Use for headings, body copy, emphasis, and the markup under a visual hierarchy. Not for naming — see recursica-skill-names-and-terms.