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:

Tool	When to use	Coverage	Feedback timing
Linting	While writing code	JS, Vue, Markdown files	Real-time in editor
Storybook tests	Component development	Vue components in isolation	CI pipeline on component changes and local testing
Feature tests	Feature development	Complete user journeys (HAML + Vue + JS)	CI pipeline and local testing
Browser extension	Code review & debugging	Any page, on-demand	Manual, immediate
Monitoring	Production oversight	Key application pages	Continuous 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:

• axe for Firefox
• axe for Chrome

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 Storybook tests
• Accessibility feature tests

Accessibility best practices

Follow these best practices to implement accessible web applications:

• Quick checklist
• Accessible names for screen readers
• Icons
• When to use ARIA

Training and education

Enhance your accessibility knowledge with these resources:

• Introduction to digital accessibility course
• Accessible Web Development course

Other resources

Viewing the browser accessibility tree

• Firefox DevTools guide
• Chrome DevTools guide

Additional learning resources

• The A11Y Project - Comprehensive accessibility resource
• Awesome Accessibility - Curated accessibility materials
• Pajamas Design System Accessibility - GitLab-specific guidance