Cross-Platform Mappings
How CUP's 59 roles map to native accessibility APIs on each platform.
Overview
CUP defines 59 canonical roles derived from ARIA. Each role maps to one or more native accessibility identifiers per platform. The complete mapping table is maintained in mappings.json in the protocol specification.
Entries with ? indicate context-dependent mappings where the CUP SDK uses heuristics to determine the correct role.
Common mappings
| CUP Role | Windows (UIA) | macOS (AX) | Linux (AT-SPI2) | Web (ARIA) |
|---|---|---|---|---|
button | Button | AXButton | ROLE_PUSH_BUTTON | button |
checkbox | CheckBox | AXCheckBox | ROLE_CHECK_BOX | checkbox |
textbox | Edit | AXTextField | ROLE_ENTRY | textbox |
link | Hyperlink | AXLink | ROLE_LINK | link |
img | Image | AXImage | ROLE_IMAGE | img |
list | List | AXList | ROLE_LIST | list |
listitem | ListItem | AXGroup? | ROLE_LIST_ITEM | listitem |
menu | Menu | AXMenu | ROLE_MENU | menu |
menuitem | MenuItem | AXMenuItem | ROLE_MENU_ITEM | menuitem |
dialog | Window? | AXWindow:AXDialog | ROLE_DIALOG | dialog |
tab | TabItem | AXRadioButton? | ROLE_PAGE_TAB | tab |
table | Table | AXTable | ROLE_TABLE | table |
slider | Slider | AXSlider | ROLE_SLIDER | slider |
progressbar | ProgressBar | AXProgressIndicator | ROLE_PROGRESS_BAR | progressbar |
combobox | ComboBox | AXComboBox | ROLE_COMBO_BOX | combobox |
window | Window | AXWindow | ROLE_FRAME | window |
heading | Text? | AXHeading | ROLE_HEADING | heading |
generic | Pane?|Custom | AXGroup?|AXUnknown | ROLE_PANEL | generic |
radio | RadioButton | AXRadioButton | ROLE_RADIO_BUTTON | radio |
switch | CheckBox? | AXCheckBox? | ROLE_TOGGLE_BUTTON? | switch |
State mappings
States map more directly across platforms since they represent universal UI concepts (focused, disabled, expanded, etc.). The CUP SDK normalizes platform-specific state representations into the 16 canonical state flags.
Action mappings
Actions map to native platform APIs:
| CUP Action | Windows | macOS | Linux | Web |
|---|---|---|---|---|
click | Invoke pattern | AXPress | DoAction("click") | element.click() |
type | SetValue + SendKeys | AXValue set | EditableText.SetText | input.value = |
scroll | ScrollItem pattern | AXScrollBar | DoAction("scroll") | element.scroll() |
toggle | Toggle pattern | AXPress | DoAction("toggle") | element.click() |
expand | ExpandCollapse | AXShowMenu | DoAction("expand") | aria-expanded |
select | SelectionItem | AXPress | DoAction("select") | element.click() |
Extending mappings
CUP's role mappings also include Android and iOS platforms, with mappings to android.widget.* classes and iOS accessibility traits respectively. See the full mappings.json for the complete 6-platform table.