An open source design system that's fully customizable and agent ready
schema_version: 1 template_version: 1 kind: family id: family:action-groups authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-26 owners: [cixzhang] review_triggers: [behavior, interaction, accessibility] verified_by: [ packages/core/src/hooks/useMenuPress.test.tsx, packages/core/src/hooks/menuPressGesture.test.ts, ] members: [ component:DropdownMenu, component:DropdownMenuSubMenu, component:ContextMenu, component:Selector, component:MultiSelector, component:DateInput, component:DateTimeInput, component:TimeInput, component:AlertDialog, component:ButtonGroup, component:ToggleButtonGroup, component:Toolbar, component:Banner, component:Toast, component:TopNavMenu, component:SideNavHeading, component:TopNavHeading, component:TabMenu, component:DateRangeInput, component:NavHeadingMenu, component:BreadcrumbItem, ] architecture: [architecture:interaction-modality] contributing: []
deciding_specs: [spec:AST-094/DEC-17]
Action groups contract
{
"scope": "global",
"triggers": {
"interaction": ["FR1", "FR2", "FR3", "FR4", "FR5"]
}
}
Intent
A person can press one action in a group of sibling actions, slide across the others while the highlight follows, and act on the one they lift on, the same way in every group, with SegmentedControl as the one named exception. Every member gets the behavior from one shared implementation, or menus and Selector's and MultiSelector's options from the menu press model, so no member builds its own.
Membership rule
A component is a member when it renders a set of two or more sibling momentary, toggle, or option actions that a person chooses one of. Members today:
- menus: DropdownMenu, ContextMenu, and their sub-menus, the navigation
menus of TopNav (TopNavMenu), SideNavHeading, TopNavHeading, and
NavHeadingMenu; and
BreadcrumbItem's
menu, which renders DropdownMenu items; - TabMenu's menu of tab options;
- option lists: Selector's and MultiSelector's options, and the wheels of DateInput, DateTimeInput, and TimeInput;
- AlertDialog's actions;
- ButtonGroup and ToggleButtonGroup;
- DateRangeInput's presets, one labeled group of preset buttons;
- Toolbar's buttons; a field inside a toolbar is skipped;
- the action rows of Banner and Toast when a row has two or more sibling actions.
Action rows in a Dialog's footer, a Card's footer, or any LayoutFooter get
the behavior by composing ButtonGroup.
A component built later that matches the rule joins by the rule, including an action sheet, a tab bar or navigation bar, a filter-chip group, and a rating.
SegmentedControl is a named exception: this family's rule does not bind it.
These are not members:
- text inputs and InputGroup as a whole, whose input keeps the caret and selection and whose addons belong to that input rather than forming a group;
- TabList, whose scrollable rows need a drag to scroll and whose tabs switch views;
- Pagination and Stepper, inline page controls in the page flow rather than a menu;
- TopNavMegaMenu's panel, a browsing grid of links in a
role="group", not a menu (component:TopNavMegaMenuFR5); - SideNavItem's collapsed-rail flyout, a popover of the item's navigation rows, not a menu;
- Popover itself, a surface whose content owns its role; a menu inside it follows its own component;
- Calendar's day grid, a two-dimensional date grid with its own keyboard and range-selection model, which a slide to commit would break;
- RadioList, CheckboxList, and SelectableCard, whose rows and cards sit in scrolling lists;
- Token chips, which are removable and have no group control.
- the suggestion lists of Typeahead (also Tokenizer's), CommandPalette, and the chat composer's trigger menu, whose focus stays in the text input, as a text input's does.
Shared owner
One shared, internal implementation gives every member other than menus and
Selector's and MultiSelector's options FR1–FR5
(architecture:interaction-modality INV13); those get them from
module:DropdownMenu/useMenuPress. No member keeps another copy.
Canonical concepts
- Action group: two or more sibling actions a person chooses one of.
- Held pointer: a press that has not lifted, tracked across the group.
- Lifted action: the enabled action under the pointer when it lifts.
Cross-component invariants
- FR1 — The lift decides. Under the touch presentation (
spec:AST-094FR13), in a member, a press on an action that slides across its siblings acts on the action the pointer lifts on, through that action's own activation; a press that never leaves its action acts on it. One gesture acts at most once (spec:AST-094FR26). After a slide, focus does what a click on the lifted action does. A mouse press acts as the platform's native button does: on the action it began on, released over that action. - FR2 — The highlight follows the pointer. While the pointer is held, the
enabled action under it is highlighted, at most one at a time, and nothing
is highlighted over a disabled action, a gap, or outside the group
(
spec:AST-094FR27). - FR3 — Sliding off cancels. A press that lifts outside the group acts on
nothing; a second finger ends the gesture with nothing acting (
spec:AST-094FR28), as a lost focus or a cancelled pointer does (spec:AST-094FR44). Whether a member that opened for the gesture stays open stays with the member. - FR4 — A toggle group toggles only the lifted action. In a toggle group, only the action lifted on toggles; sliding across never toggles the actions passed over.
- FR5 — A finger and a pen, one target rule. Under the touch presentation
the behavior applies to a finger and a pen; a mouse press acts as FR1 says.
While it tracks, a group keeps one
pointerdownlistener on its element, cancelable where the member needs it, adds document listeners only during a press and removes them at the release, and may arm one per-document click swallower from the release until that gesture's click; nothing else is idle (spec:AST-094FR19, FR24). The 44 px target is each member's hit expansion under a coarse pointer only. Keyboard and assistive-technology behavior is unchanged.
Allowed component variation
- What an action does on activation, and how a member shows its highlight, stay with the member.
- Menus keep their own opening and handoff (
spec:AST-094FR29), their press and drag under every pointer, and their scrolling rules; FR1's touch scope and FR5 do not change them. - Selector's and MultiSelector's options keep the menu press model's press
and drag under every pointer (
component:SelectorFR7); FR1's touch scope and FR5 do not change them. - A wheel is a scroll container: a drag scrolls it, as it does today, and a tap acts on the option under it; only a press that does not scroll tracks.
Representative matrix
| Member and state | Shared invariant | Deliberate variation |
|---|---|---|
| DropdownMenu / slide from row to row | the lifted row acts; one row lit at a time | opening and handoff stay the menu's (FR29) |
| AlertDialog / slide from Cancel | the lifted action runs; a lift outside does nothing | the actions' order and stacking stay local |
| ToggleButtonGroup / slide across three | only the lifted toggle changes | single or multiple selection stays the group's |
| Toolbar with a field / slide across | buttons track; the field is skipped | which controls a toolbar holds stays local |
Adoption and exceptions
| Components or surface | Required adoption |
|---|---|
| Menus and Selector's and MultiSelector's options | Follow FR1–FR5 through module:DropdownMenu/useMenuPress. |
| TopNav's, SideNavHeading's, TopNavHeading's, NavHeadingMenu's, BreadcrumbItem's, and TabMenu's menus | Follow FR1–FR5 through module:DropdownMenu/useMenuPress, as menus. |
| Date and time wheels | Follow FR1–FR5 through the shared implementation. |
| AlertDialog's actions | Track the actions only. |
| ButtonGroup, ToggleButtonGroup, Toolbar | Track sibling buttons; a field inside is skipped; toggles follow FR4. |
| DateRangeInput's presets | Track the preset buttons only. |
| Banner and Toast action rows | Track only a row with two or more sibling actions. |
These are required outcomes, not a claim of completed adoption. The excluded components listed under the membership rule are not exceptions to approve; they are outside the family.
Verification map
| Contract | Verification | Representative members and states |
|---|---|---|
| FR1–FR3 | Shared-implementation tests and each member's pointer-stream tests | a slide across a menu, AlertDialog's actions, a ButtonGroup; a lift outside |
| FR4 | ToggleButtonGroup pointer-stream tests | a slide across three toggles; only the lifted one toggles |
| FR5 | Member tests with a mouse, a pen, a finger, the keyboard, and a screen reader | a 44 px target under a coarse pointer only; unchanged keyboard and screen-reader paths |
Decision links
spec:AST-094/DEC-17— every group of sibling actions tracks a held pointer the same way.
DEC-1 — The slide across actions is for touch only
Decider: cixzhang, 2026-11-03
The slide-across press runs under the touch presentation only. A desktop mouse press behaves as a native button does: only the pressed action activates, with no drag across the others.
Rejected: every pointer.
Open questions
None.
Content boundary
This file owns action-group membership and the shared press, slide, and lift behavior. It does not duplicate component prop tables, what each action does, menu opening, or the shared implementation's thresholds.