Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Dev Accessibility Guidelines
Guidelines for Maintaining Accessibility in the Roundcube Web Client
This document describes a list of rules and best practices for all developers creating UI components for the Roundcube webmail and plugins in order to improve the accessibility of the web application for people using assistive technologies.
A collection of important references and sources regarding accessibility with notes concerning the Roundcube UI.
- 1.1.1 Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose
<label>elements for each form element
- or set the
titleattribute where no label element is available
- 1.3.1 Info and Relationships: Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
ARIA11: Using ARIA landmarks (
aria-labelattributes) on UI blocks
- ARIA17: Using grouping roles to identify related form controls
- H71: Providing a description for groups of form controls using fieldset and legend elements
- H48: Using ol, ul and dl for lists or groups of links
- H51 Using table markup to present tabular information
- ARIA2: Identifying a required field with the aria-required property
- 1.4.4 Resize text: Except for captions and images of text, text can be resized without assistive technology up to 200 percent without loss of content or functionality.
- C28: Specifying the size of text containers using em units
- 1.4.8 Presentation: For the visual presentation of blocks of text
- C23: Specifying text and background colors of secondary content such as banners, features and navigation in CSS while not specifying text and background colors of the main content
- 2.1.1 Keyboard: All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes.
- G202: Ensuring keyboard control for all functionality
- Proper tabindex
- 2.4.7 Focus Visible
- Checkboxes for list selection!
- 2.4 Content structure
- 2.4.6 Headings and Labels: Headings and labels describe topic or purpose.
- Alternatively, use ARIA
- Annotate different sections of the screen (e.g. toolbar, messages list, folders, preview)
- 2.4.10 Section Headings: Section headings are used to organize the content.
- H64 Using the title attribute of the frame and iframe elements
- 2.4.8 Location: Information about the user's location within a set of Web pages
- G128: Indicating current location within navigation bars
- 3.2.3 Consistent Navigation: Navigational mechanisms that are repeated on multiple Web pages within a set of Web pages occur in the same relative order each time they are repeated
- 3.2.4 Consistent Identification: Components that have the same functionality within a set of Web pages are identified consistently.
- 3.3 Input Assistance
- 3.3.1 Error Identification: If an input error is automatically detected, the item that is in error is identified and the error is described to the user in text
- 3.3.2 Labels or Instructions: Labels or instructions are provided when content requires user input.
- 3.3.5 Help: Context-sensitive help is available.
- Basic rules for Building Accessible Applications with WAI-ARIA
- Use native markup when possible.
- Apply the appropriate roles.
- Preserve semantic structure.
- Build relationships.
- Set states and properties in response to events.
- Support full, usable keyboard navigation.
- Synchronize the visual interface with the accessible interface.
Screen Readers and Assistive Technology Tools
- Accessibility Evaluation Toolbar for Firefox
- Juicy Studio Accessibility Toolbar for Firefox
- Fangs Screen Reader Emulator for Firefox
- Chrome Accessibility Developer Tools
- Web Accessibility Toolbar (WAT) for Internet Explorer
- Safari + Voiceover (Mac)
Suggested Best Practices for Roundcube Developers
1. Keyboard Navigation
Every UI element SHALL be operable with the keyboard. That includes:
- Receiving focus using the tab key
- Clearly indicate focused status
- Action is executable by pressing enter or space
- Instructions are available if keyboard navigation for a specific widget differs from the standard actions
2. Annotated Content Structure
- The individual areas of the application UI SHALL be annotated with section headers and/or appropriate
- The order and nesting of elements in the DOM should be reasonable for a top-down reading although elements are absolutely positioned with CSS.
3. Full Link Texts for Icon Buttons
Links which are rendered as graphical buttons with icons SHALL have full and explaining link texts nonetheless. Hide the text with
text-indent:-5000px when rendering an icon button with CSS backgrounds or leave the link tag empty and set the
4. Labelled Input Elements
Each input element (e.g. text box, drop-down selection, etc.) SHALL be clearly labelled with a description about the expected information to be entered. Either using
<label> elements or
5. Expanded State in Control Buttons
For buttons expanding/collapsing hidden UI elements or opening menus, set the
aria-expanded attribute according to the state of the controlled element. This can be for buttons opening menus or toggling some hidden options.
A button which opens a popup menu should use the following attributes:
<a ... onclick="return rcmail.command('menu-open','<menu-id>',this,event); aria-haspopup="true" aria-expanded="false" aria-owns="<menu-element-id>">
And containers representing a popup menu typically look like this:
<div id="menu-id" class="popupmenu" aria-hidden="true"> <h3 id="aria-label-menutitle" class="voice">A Sample Menu</h3> <ul id="menu-element-id" class="toolbarmenu" role="menu" aria-labelledby="aria-label-menutitle"> <li role="menuitem"><roundcube:button command="..." /></li> <li role="menuitem"><roundcube:button command="..." /></li> </ul> </div>
6. Autocompletion Elements
For text elements that trigger autocompletion suggestions on keypress, add the following attributes:
aria-autocomplete="list" aria-expanded="false". Upon results being displayed, add
aria-owns="<listbox-id>" to the input element and reset them once the list is hidden again. The arrow keys shall then move through the suggestions and either Enter or Tab copies the selected item into the text box. In order to make screen readers speak the selected item, set the
aria-activedescendant="<selected-option-element-id>" attribute to the input element.
Read Marco's Easy ARIA Tip #7 for more in-depth information.
7. Use common Widget Objects
- For hierarchical lists:
- For record lists:
- For buttons:
<roundcube:button command="..." />in skin templates
- For menus:
- For dialogs:
rcmail.show_popup_dialog()or jQuery UI
- For tabbed UI elements, use jQuery UI
8. Updating Status Texts Declared as Live Region
Parts of the UI that get updated during the interaction with the application (e.g. display of "Messages 1 to 20 of 356") should have the aria-live attribute to let screen readers read changes to the user.
For updated status texts, the following attributes are appropriate:
Methods to Verify Accessibility
Open the page in your browser. Use the Tab and/or Arrow keys to move focus through the UI. Check the following:
- Every button and form element should be reachable using the keyboard.
- Focused element should be clearly visible/highlighted. You should always know which element has the focus.
- Action of the UI elements (e.g. button click) can be executed by the keyboard (by hitting Enter or Space).
- When an action opens a menu or a dialog, the first element of that menu/dialog should get the focus.
- Esc closes menus and dialogs and sets focus back to the opening button.
Content Structure and Section Headings
In Firefox's Web Developer Toolbar select CSS > Disable Styles > Disable All Styles.BR Check the document structure for
- Correct Headings (h1 - h6). The page requires at least one h1
- Sane order of the UI components
- Every button should be accessible as textual link
- Complex forms should be structured with
Landmarks and Frame Title
In Firefox's Juicy Studio Accessibility Toolbar, select ARIA > Document Landmarks.BR Check the annotated areas for correct assignments:
- There should be one
- Navigational elements should be labelled with
- Search boxes should have the role
In Internet Explorer's Web Accessibility Toolbar select Frames > Frame Name / Title.BR Check that every iframe has a meaningful title set.
Listings as HTML List Elements
In Internet Explorer's Web Accessibility Toolbar select Structure > List Elements.BR
Check if all listings, especially hierarchical ones are represented with
Data Table Structure
In Internet Explorer's Web Accessibility Toolbar select Tables > Show Data Tables.BR
Check if all column and row headers are correctly marked up with
In Firefox's Accessibility Evaluation Toolbar, select Navigation > Tata Tables.BR Navigate through the table using the Left/Right/Up/Down buttons and check the headers and content listing.
Icons with Title Attributes
Every UI element represented by an icon or color graphic should have a descriptive
To check, move the mouse over every icon and wait for the tooltip to show up.
Labelled Form Elements
Every form input element should have a linked
<label> element or
<label>elements, open the page in your browser and click on the text describing an input field. If correctly linked, the input field gets the focus upon click on the label.
- If there's no visible text describing the form element, move the mouse over the element and wait for the
titleto be displayed as tooltip.
Enable Chromevox in Chrome or Voiceover on Mac OS X. Use the keyboard to navigate through the application and listen to the voice output. The spoken element is highlighted in the browser window. Voiceover also has an option to mute audio speech and displays the text on the screen.
Questions and Answers
Role or additional actions for messages (loading, confirmation, errors)?::
aria-alertdialog to Identify Errors. BR
ARIA Roles Set
role="alert" for spoken messages and
role="status" for non-spoken background status information. BR
Roundcube's internal message system (
rcmail.display_message(...) already implement these.
Best order of content blocks (topnav, toolbar, folders, messages)?:: ?
Toolbar navigation (focus shift) with cursor keys?:: Marco’s accessibility blog posts suggest to navigate with cursor keys in toolbars. Are Roundcube's toolbars really of the type where that would be expected?
Unordered TODOs in Current UI Implementation
- Describe UI blocks with section headings or
- Add proper
titleattributes to iframes ✓
- Make toolbar buttons and folders/messages list items accessible by keyboard (tab); highlight focused item ✓
- Declare buttons that open a popup menu with
- Indicate selected state in task list with
- Extend list and treelist widgets with ARIA attributes like
- Add (hidden) submit buttons to search boxes ?
- Keyboard navigation in popup menus: ✓
- Focus first item when opening menu (from keyboard event) ✓
- Hide popup menus again when tabbing away ✓
<th>tags for table headers ✓
- Allow tabbing into message list and activate keyboard navigation ✓
- Describe keyboard navigation for list widget (in hidden text block?) ✓
- Annotate Quota display with descriptive text ✓
- Make the compose address book listing a
- Check screen reading of autocompletion popup ✓
- Make the contacts listing a
- Annotate tabbed view in contact view/edit with ARIA attributes ✓
- Check form element/label assignments ✓
- Flag required fields
- Improve form validation feedback