The role vocabulary
role= is a closed, controlled vocabulary of 53 recognized UI structures — button, nav-bar, card, dialog, and friends. Tagging a node with a role changes no pixels; it makes the file self-describing, the <nav>-vs-<div> distinction for .gui. Any machine, AI, or tool reading the file knows what a node is without guessing — which is what the Comprehensible quality level measures.
A role qualifies by appearing in at least one platform reference system — the Component Gallery for web, Apple's Human Interface Guidelines for iOS, Material Design for Android. Each role declares a reach: how far down its subtree its meaning documents the content (full = the whole subtree, 2 = a two-level grammar like table → row → cell, 1 = one chrome level, then the payload labels itself).
| Role | Reach | Platforms | Description |
|---|---|---|---|
accordion | 1 | web · ios · android | Vertically stacked sections, each with a header that reveals or hides content below it. AKA: disclosure, collapsible, expandable, expansion-panel |
action-sheet | full | ios · android | Modal sheet sliding up from the bottom presenting a list of contextual actions. AKA: bottom-sheet, action-menu |
alert | full | web · ios · android | Inline message communicating a status — informational, success, warning, or error. AKA: warning, error-message, info-message |
avatar | full | web · ios · android | Circular or rounded image representing a person or entity. AKA: profile-image, user-photo, profile-picture |
badge | full | web · ios · android | Small count or status label overlaid on or beside another element. AKA: counter-badge, notification-badge, pip |
banner | full | web · ios · android | Prominent strip promoting content, a sale, or an announcement. AKA: promo-banner, announcement-banner, info-banner |
breadcrumb | full | web · android | Horizontal trail showing the current page's location in the site or app hierarchy. AKA: path-navigation, crumbs, page-path |
button | full | web · ios · android | Tappable element that triggers an action. AKA: primary-button, secondary-button, cta, action-button |
card | 1 | web · ios · android | Contained surface grouping related content and optional actions. AKA: content-card, panel, tile |
carousel | 2 | web · ios · android | Horizontally scrollable series of cards or images, showing one or a few items at a time. AKA: media-carousel, slider-gallery, slideshow |
checkbox | full | web · ios · android | Binary selection control for toggling an option on or off. AKA: checklist-item, tick-box |
chip | full | web · ios · android | Compact tag used for filtering, selection, or labelling. AKA: filter-chip, suggestion-chip, tag, label |
color-picker | full | web · ios · android | Control for selecting a color from a palette or spectrum. AKA: color-selector, color-swatch |
combobox | full | web | Text input combined with a filterable dropdown list of suggestions. AKA: autocomplete, searchable-select, typeahead |
command-palette | 1 | web | Full-screen overlay with a search input for quickly finding and triggering commands or navigation. AKA: command-menu, quick-actions, spotlight |
context-menu | full | web · ios · android | Floating list of actions anchored to a specific element or tap position. AKA: right-click-menu, overflow-menu, action-menu |
date-picker | full | web · ios · android | Control for selecting a date, or date range, from a calendar view. AKA: calendar-picker, date-input, date-selector |
dialog | 1 | web · ios · android | Modal overlay requiring user interaction before returning to the main flow. AKA: modal, popup, confirmation-dialog |
divider | full | web · ios · android | Horizontal or vertical line used to separate sections of content. AKA: separator, rule, hr |
drawer | 1 | web · ios · android | Panel that slides in from a screen edge, overlaying content without replacing it. AKA: side-sheet, bottom-sheet, slide-over, panel |
dropdown-menu | full | web · ios · android | Floating list of options anchored to a trigger, for navigation or actions. AKA: menu, pulldown-menu, select-menu |
empty-state | 1 | web · ios · android | Placeholder shown when a list or view has no content, guiding the user to an action. AKA: zero-state, blank-state, no-results |
file-uploader | full | web | Area for selecting or dropping files for upload. AKA: dropzone, file-input, drag-and-drop-upload |
floating-action-button | full | web · ios · android | Circular button fixed above content, representing the primary action on a screen. AKA: FAB, primary-action-button |
full-screen-overlay | 1 | web · ios · android | A view that occupies the entire screen, typically presented modally over another screen. AKA: immersive-modal, full-screen-modal, sheet |
gallery | 2 | web · ios · android | Grid of images or media thumbnails displayed in a uniform tiled layout. AKA: media-grid, image-grid, photo-grid, mosaic |
hyperlink | full | web · ios · android | Inline text that navigates to another location when activated. AKA: link, anchor, text-link |
item-indicator | full | web · ios · android | Row of dots or marks showing position within an ordered set of items — slides, steps, pages, or images. AKA: page-control, dot-indicator, step-indicator, carousel-indicator, slider-dots |
launch-screen | full | ios · android | Full-screen view shown while an app is loading, typically displaying a logo or brand mark. AKA: splash-screen, loading-screen, intro-screen |
loading-indicator | full | web · ios · android | Visual cue that an operation is in progress. AKA: spinner, loader, activity-indicator, progress-spinner |
navigation-menu | 2 | web · ios · android | A set of links or destinations used to move between sections of an app or site. AKA: nav-menu, site-nav, side-nav, navigation-drawer |
pagination | full | web · android | Numbered page controls for navigating through a multi-page dataset. AKA: pager, page-navigator, page-controls |
popover | full | web · ios · android | Small floating panel anchored to a trigger element, for supplementary information or a compact form. AKA: popup, flyout, floating-panel |
progress-indicator | full | web · ios · android | Bar or ring showing how much of a process has completed. AKA: progress-bar, progress-ring, determinate-progress |
radio-button | full | web · ios · android | Single-selection control where only one option from a group can be chosen. AKA: radio, radio-option, radio-group |
search-bar | full | web · ios · android | Input field dedicated to searching or filtering content. AKA: search-field, search-input, search-box |
segmented-control | full | web · ios · android | A set of mutually exclusive options displayed as connected segments, one selected at a time. AKA: segmented-button-group, button-group, tab-toggle |
select | full | web · ios · android | A control that shows a single chosen value and opens a list for changing it. AKA: dropdown, dropdown-select, picker |
sidebar | 2 | web · ios · android | Persistent vertical panel on the side of the screen containing navigation or contextual tools. AKA: navigation-rail, side-navigation, left-nav, side-panel |
skeleton | full | web · ios · android | Placeholder shapes shown while content is loading, matching the rough layout of the expected content. AKA: content-placeholder, loading-skeleton, ghost, shimmer |
slider | full | web · ios · android | A track with a draggable thumb for selecting a value within a continuous range. AKA: range-slider, scrubber, input-range |
stepper | full | web · ios · android | A control with increment and decrement buttons for adjusting a numeric value. AKA: quantity-stepper, number-stepper, increment-decrement, counter |
switch | full | web · ios · android | Toggle control that switches a setting between on and off. AKA: toggle, toggle-switch |
tab-bar | full | web · ios · android | Row of tabs for switching between top-level sections of an app. AKA: tabs, bottom-navigation, bottom-tab-bar, tab-strip |
table | 2 | web · ios · android | Grid of rows and columns presenting structured data. AKA: data-table, data-grid |
text-area | full | web · ios · android | Multi-line text input for longer freeform content. AKA: multiline-input, multi-line-text-field, textarea |
text-field | full | web · ios · android | Single-line input for entering short text values. AKA: input-field, text-input, form-field |
time-picker | full | web · ios · android | Control for selecting a time value. AKA: time-selector, clock-picker, time-input |
toast | full | web · ios · android | Brief notification that appears temporarily, typically at the bottom of the screen. AKA: snackbar, notification-toast, flash-message |
toolbar | 1 | web · ios · android | A horizontal row of action controls contextually relevant to selected content or the current view. AKA: app-bar, command-bar, action-bar, formatting-bar |
tooltip | full | web · ios · android | Small label that appears on hover or long-press to explain a control or provide context. AKA: hint, info-tip, hover-label |
top-navigation-bar | 1 | web · ios · android | Persistent bar at the top of a screen showing the title and primary actions. AKA: nav-bar, app-bar, header, header-bar |
tree | 2 | web | Hierarchical list of expandable and collapsible nodes representing nested content. AKA: tree-view, hierarchy-view, folder-tree |