Core Concepts
Roles, States & Actions
The three pillars of the CUP vocabulary — 59 roles, 16 states, 15 element actions + 2 session actions.
Roles
CUP defines 59 ARIA-derived roles that map cleanly to every platform's native accessibility API. Each role has a 2-4 character short code used in compact format.
States
CUP defines 16 state flags. Only active/truthy states are listed — absence means the default state.
| State | Code | Meaning |
|---|---|---|
busy | bsy | Element is loading or processing |
checked | chk | Checkbox or radio is checked |
collapsed | col | Expandable element is collapsed |
disabled | dis | Element is not interactive |
editable | edt | Content can be edited |
expanded | exp | Expandable element is open |
focused | foc | Element has keyboard focus |
hidden | hid | Element is not visible |
mixed | mix | Indeterminate checkbox state |
modal | mod | Dialog is modal |
multiselectable | msel | Multiple items can be selected |
offscreen | off | Element is outside the viewport |
pressed | prs | Button is pressed/active |
readonly | ro | Value cannot be changed |
required | req | Field is required |
selected | sel | Item is selected |
Actions
CUP defines 15 element-level actions that map to native platform APIs.
| Action | Code | Parameters | Description |
|---|---|---|---|
click | clk | — | Click or invoke the element |
doubleclick | dbl | — | Double-click the element |
rightclick | rclk | — | Open context menu |
longpress | lp | — | Long-press (touch) |
toggle | tog | — | Toggle checkbox or switch |
type | typ | value: string | Type text into a field |
setvalue | sv | value: string | Set element value directly |
scroll | scr | direction: up|down|left|right | Scroll a container |
select | sel | — | Select an item |
expand | exp | — | Expand a collapsed element |
collapse | col | — | Collapse an expanded element |
increment | inc | — | Increment slider/spinner |
decrement | dec | — | Decrement slider/spinner |
focus | foc | — | Move keyboard focus |
dismiss | dsm | — | Dismiss dialog/popup |
Additionally, two session-level actions are available:
| Action | Parameters | Description |
|---|---|---|
press | keys: string | Send keyboard shortcut (e.g. ctrl+s) |
wait | ms: number | Delay between batch actions (50-5000ms) |