UCDL Accessibility Use Case Definition Language
Contents

Writing Accessibility Use Case Tests with @afixt/usecase-runner

Part 3: Role Tokens — How to Target Elements

Role tokens tell the runner what kind of element to look for. They map to Playwright's accessibility-first locator methods. The curated list covers the concrete ARIA 1.2 widget, composite, structure, landmark, live-region, and window roles — 61 tokens in total. Common ones:

Token Finds HTML Examples
button Buttons <button>, <input type="submit">, [role="button"]
link Links <a href="...">
field Form inputs by label <input> + <label>, aria-label, aria-labelledby
checkbox Checkboxes <input type="checkbox">, [role="checkbox"]
radio Radio buttons <input type="radio">, [role="radio"]
switch Two-state toggles [role="switch"]
select Dropdowns <select>, [role="combobox"]
combobox ARIA comboboxes [role="combobox"] (no <select> fallback)
option Listbox/select items <option>, [role="option"]
slider Sliders <input type="range">, [role="slider"]
progressbar Progress indicators <progress>, [role="progressbar"]
heading Headings <h1>–<h6>, [role="heading"]
tab Tab controls [role="tab"]
tablist Tab containers [role="tablist"]
tabpanel Tab content panels [role="tabpanel"]
dialog Modal dialogs <dialog>, [role="dialog"]
alertdialog Confirmation dialogs [role="alertdialog"]
menu/menubar/menuitem Menus [role="menu"], etc.
tree/treeitem/treegrid Tree pattern [role="tree"], etc.
grid/gridcell Grid pattern [role="grid"], [role="gridcell"]
listbox Multi-select lists [role="listbox"]
text Any visible text Matches by text content, not role
image Images <img>, [role="img"]
table/row/cell Table structure <table>, <tr>, <td>
main Main landmark <main>, [role="main"]
banner/contentinfo Page header/footer landmarks <header>, <footer> (when top-level)
navigation Nav landmarks <nav>, [role="navigation"]
complementary Aside landmark <aside>, [role="complementary"]
region Generic landmarks <section aria-label="...">, [role="region"]
search/form Landmark variants <search>, <form aria-label="...">
alert/log/status Live regions [role="alert"], [role="status"]
toolbar/tooltip UI affordances [role="toolbar"], [role="tooltip"]

See spec.md §1.4 for the complete normative list.

The accessible name is optional for role-based targets. Use no-name forms when asserting existence-by-role alone:

- locate: main # any main landmark
- locate: role "tablist" # any tablist (custom-role form)
- verify: count navigation is 1 # exactly one navigation landmark

field (uses getByLabel) and text (uses getByText) still require a name — they have no "any element" mode.

Custom or app-defined ARIA roles for anything not in the curated list:

- locate: role "custom-treegrid" name "File Browser"
- locate: role "feed" # name optional here too

Scoping with within (or inside)

When a page has multiple elements with the same role and name, use within to scope to a parent landmark. inside is an accepted synonym:

- locate: field "Email" within region "Sign Up"
- activate: button "Submit" within dialog "Confirm Delete"
- locate: link "Edit" within row "John Smith"
- locate: link inside navigation "Breadcrumb" # `inside` synonym