Accessibility

Accessibility is important for users who use screen readers or rely on keyboard-only functionality to ensure they have an equivalent experience to sighted mouse users.

We aim to conform to level AA of the World Wide Web Consortium (W3C) Web Content Accessibility Guidelines 2.1.

How our accessibility tools work together

GitLab uses a comprehensive, multi-level approach to ensure accessibility compliance. Each tool serves a specific purpose in our development workflow, working together to provide complete coverage from development to production:

ToolWhen to useCoverageFeedback timing
LintingWhile writing codeJS, Vue, Markdown filesReal-time in editor
Storybook testsComponent developmentVue components in isolationCI pipeline on component changes and local testing
Feature testsFeature developmentComplete user journeys (HAML + Vue + JS)CI pipeline and local testing
Browser extensionCode review & debuggingAny page, on-demandManual, immediate
MonitoringProduction oversightKey application pagesContinuous monitoring

When to use which tool

During development:

  1. Start with linting: get immediate feedback while writing code.
  2. Add Storybook tests: ensure components work in isolation.
  3. Include feature tests: validate complete user experiences.
  4. Use browser extension: debug specific issues or review changes.

For different file types:

  • Vue/JS files: Linting + Storybook tests + Feature tests
  • HAML files: Feature tests + Browser extension (linting not supported)
  • Complete pages: Feature tests + Browser extension + Monitoring

New components

  1. Create comprehensive Storybook stories covering all component states.
  2. Ensure Storybook tests pass before integration.
  3. Test manually with keyboard navigation and with a screen reader.

New features

  1. Identify mission-critical user journeys.
  2. Write feature tests that cover these journeys completely.
  3. Focus on testing critical UI states and interactions.

Existing code

  1. Prioritize high-traffic areas and critical user flows.
  2. Add tests incrementally as you work on related features.
  3. Use monitoring data to identify areas needing attention.

Linting for accessibility defects

You can enable linting for accessibility defects with a free VS Code plugin - axe Accessibility Linter. We strongly recommend that to everyone contributing to GitLab that use VS Code.

To enable linting:

  1. Open VS Code editor
  2. Go to Extensions
  3. Search for “axe Accessibility Linter” and install the plugin

The GitLab repository includes axe-linter.yml configuration that maps Pajamas Design System components to native HTML elements, significantly increasing linter coverage.

Storybook component testing

Storybook tests use axe-playwright to automatically test Vue components for accessibility violations.

Component’s tests run in CI on any Vue or JavaScript file change and block merges when it finds violations. However, it only tests components that have Storybook entries and they need to be up-to-date.

Feature testing

Feature tests with axe-core-gem provide the most comprehensive accessibility testing by validating complete user experiences.

They cover all our frontend architecture (HAML, Vue, JS) and allow checks at any step of a user journey. Though they may be resource heavy.

Browser extensions

Use axe DevTools browser extensions for immediate accessibility feedback:

There is no setup required. You get a full page scan with resources on how to fix violations. Highlighting feature will help you identify the elements in question. A paid pro version offers guided testing and component-specific scans.

Accessibility monitoring

Our Sitespeed setup with axe extension provides ongoing accessibility monitoring with minimal setup.

You can see SiteSpeed Report for the latest run against staging in GitLab Browser Performance Tool.

Automated accessibility testing

For detailed implementation guidance, see our automated testing guide:

Accessibility best practices

Follow these best practices to implement accessible web applications:

Training and education

Enhance your accessibility knowledge with these resources:

Other resources

Viewing the browser accessibility tree

Additional learning resources