## Purpose Perform an in-depth accessibility evaluation of the redesigned navigation prior to removing the option to toggle back to the old navigation. <details> <summary>Previous efforts</summary> - [Super sidebar accessibility review](https://gitlab.com/gitlab-org/gitlab/-/issues/394793 "Super sidebar accessibility review") (May 1, 2023) - [Navigation Accessibility Review](https://gitlab.com/gitlab-org/gitlab/-/issues/382850 "Navigation Accessibility Review") (Dec 22, 2022) </details> **Note:** Another evaluation is necessary because the design, structure, and features have continued to evolve. ## Evaluation ### Environment In order to capture as broad configuration as possible to test all conditional content in the navigation a MR https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132319 with review app https://gitlab-review-navigation-qyvkke.gitlab-review.app/ has been created. This MR mocks conditions for rendering content to ensure as much content is visible as possible. ### Process 1. Set up GDK to match the [testing configuration](#gdk-testing-configuration). 2. Review evaluation [categories](#categories) and familiarize yourself with the applicable contexts, interaction, and criteria related to the category. 3. Perform the evaluation while recording and verbalizing your goals, actions, expectations, and results. While automated testing with validators and axe DevTools can test a number of items, most will be done manually and all will require manual validation. Recommended test procedures will be noted in the epic for each category. 4. List findings in the table in the sub-epic description. Break down findings into issues or MRs. Be sure to include reference material, remedies, and a timestamp link to the evaluation recording when possible. 5. Apply [accessibility labels](#accessibility-labels) and assess severity so fixes can be prioritized. **A note on recording:** The purpose of recording the evaluation is so that others can understand the process you went through and what you were trying to achieve, and also so that you can capture things in the moment without stopping and go back later to reference it while documenting findings. A video doesn't have to capture every single process, especially when repeated (like checking contrast for every theme), but it should be sufficient enough that another reviewer could repeat your process or better validate a finding. Videos can be published to GitLab Unfiltered with internal access only. ### GDK testing configuration 1. In the Admin Area make adjustments that will impact the navigation sidebar: - Add an Ultimate license to get access to all features [http://127.0.0.1:3000/admin/application_settings/general](http://127.0.0.1:3000/admin/application_settings/general) 2. Turn on these feature flags if they are not on by default: - `super_sidebar_logged_out` 3. Use the {-projectName -}for testing since it has necessary features enabled. ### Navigation configuration and behavior The following configuration and behaviors should be considered during testing. Each evaluation category epic will list out applicable items. <details> <summary>Configuration</summary> - When no items pinned in groups and projects - When impersonating another user - When on SaaS - When using GitLab Next - When on Self Managed - When unauthenticated - When the screen height is limited (400px) - When an integration (Jira) in the sidebar is configured - When on an Ultimate trial - When Learn GitLab is enabled - When a project or group has a long name that becomes truncated References * [User impersonation](https://docs.gitlab.com/ee/administration/admin_area.html#user-impersonation) * [Simulate a SaaS instance](https://docs.gitlab.com/ee/development/ee_features.html#simulate-a-saas-instance) * [Configure Jira integration](https://docs.gitlab.com/ee/integration/jira/configure.html#configure-the-integration) * [Simulate Ultimate trial](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126022#how-to-set-up-and-validate-locally) * [Turn on Learn GitLab](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111324#how-to-set-up-and-validate-locally) * [Force Next badge to appear](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113104#how-to-set-up-and-validate-locally) </details> <details> <summary>Behavior</summary> - Revealing tooltips - Expanding / collapsing dropdowns collections - Pinning / unpinning items - Reorganizing pins - Sending users to a new page - Opening a modal - Hiding the sidebar - Peeking the sidebar - Locking the sidebar in place to keep the sidebar visible - Hovering to expose flyouts </details> ### Categories Evaluations are broken down into the following categories that include high level criteria. More specific details, along with tooling, can be found in the sub-epic for each category. <details> <summary>Visual</summary> - Colors have sufficient contrast. - Color isn't the only means for conveying information. - States (hover, focus, active) are distinguishable. - Text remains readable and layout doesn't break when scaled up. - Text wrapping and truncation do not impact reading (also consider translations). </details> <details> <summary>Keyboarding</summary> - Ensure that all content and functionality in the navigation can be accessed and used with a keyboard alone, without relying on mouse or touch input. - Ensure that keyboard focus follows a logical and meaningful order within the navigation menu. - Ensure that there are no keyboard traps. </details> <details> <summary>Content and semantics</summary> - Use semantic markup ([W3C validator](https://validator.w3.org/)). - Correct use of headings (if present). - The DOM order should match reading order. - Use [ARIA](https://www.w3.org/TR/wai-aria-1.2/) correctly, and only as needed for roles and relationships. - Use plain language when possible ([Readability Analyzer](https://datayze.com/readability-analyzer.php)). </details> <details> <summary>Screen readers</summary> - Assistive technology (AT) should be able to accurately communicate content and interaction to a user. - Include alternate content (text) for graphics, like icons, where appropriate. - Form elements, like search, must be labeled. - Button and link purpose must be clear. - Avoid repeating general actions like "unpin" without qualifying their association. - Icon-only buttons must be announced with meaningful text. - Use correct semantic page structure and landmarks. - States and changes in the UI should be communicated. - A user should understand what the result of an action will be, and what has happened as the result of an action. - Touch interaction will be tested in iOS along with VoiceOver. </details> ### Related component accessibility audits Components used in the navigation may already have known accessibility issues that are documented. Reference the following if you encounter something component related: - [Button accessibility audit](https://gitlab.com/groups/gitlab-org/-/epics/7310) - [Modal accessibility audit](https://gitlab.com/groups/gitlab-org/-/epics/6945) - [Tooltip accessibility audit](https://gitlab.com/groups/gitlab-org/-/epics/7294) - Dropdowns were updated since the above audits were completed and do not have a new audit to reference ### Accessibility labels Here are the available labels along with their description. The gitlab~2677490 label is always applied, but since that triggers the SUS label, be sure to also apply ~"SUS::Non-impacting" so SUS reporting isn't impacted. <details> <summary>Severity labels</summary> - gitlab~20822961 The user experience is degraded for users with certain disabilities or using certain assistive technologies, but users can still accomplish tasks. - gitlab~20822944 Prevents some users from performing non-critical tasks, or where the user experience is seriously degraded for users with certain assistive technologies. - gitlab~20822930 Prevents some users from performing critical tasks. A workaround may exist, but not without creating frustration and inefficiency. - gitlab~20822926 Prevents some or all users from performing critical tasks with no possible workaround. </details> ## Scope The following identifies items that are in and out of scope for the evaluation. <details> <summary>In scope</summary> - New navigation in the current state as of {-reviewDate-} - Navigation color themes available in user preferences (with the exception of the alpha dark mode) - Windows High Contrast Mode - Collapsed and peek states/interaction - Navigation contexts: Your work, project, group, admin area, user profile, user settings, explore and wherever is available to an unauthenticated user. - Testing all inputs: mouse, keyboard, and touch. - Testing across breakpoints where appearance or behavior changes. </details> <details> <summary>Out of scope</summary> - Search/command modal - Breadcrumb - Dark mode - Page content surrounding navigation that isn't impacted as a result of the navigation update. </details> ## Reviewers - @aregnery - @sdejonge - @jeldergl ## Resources - [Using Combined Expertise to Evaluate Web Accessibility](https://www.w3.org/WAI/test-evaluate/combined-expertise/), W3C - [Accessibility Testing](https://racheleditullio.com/projects/accessibility-testing/), Rachel Tullio - [Accessibility monitoring: How we test](https://www.gov.uk/guidance/accessibility-monitoring-how-we-test), GOV.UK - [A Web Accessibility Assessment Hands-on Tutorial](https://dequeuniversity.com/videos/web/testing/case-study), Deque - [Screen Reader Keyboard Shortcuts and Gestures](https://dequeuniversity.com/screenreaders/), Deque - [Browsing with a desktop screen reader](https://tetralogical.com/blog/2021/09/29/browsing-with-a-desktop-screen-reader/) (also read the other posts linked at the beginning of the article)