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.
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:
- Start with linting: get immediate feedback while writing code.
- Add Storybook tests: ensure components work in isolation.
- Include feature tests: validate complete user experiences.
- 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
- Create comprehensive Storybook stories covering all component states.
- Ensure Storybook tests pass before integration.
- Test manually with keyboard navigation and with a screen reader.
New features
- Identify mission-critical user journeys.
- Write feature tests that cover these journeys completely.
- Focus on testing critical UI states and interactions.
Existing code
- Prioritize high-traffic areas and critical user flows.
- Add tests incrementally as you work on related features.
- 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:
- Open VS Code editor
- Go to Extensions
- 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:
- Introduction to digital accessibility course
- Accessible Web Development course (coming in Q3 FY26)
Other resources
Viewing the browser accessibility tree
Additional learning resources
- The A11Y Project - Comprehensive accessibility resource
- Awesome Accessibility - Curated accessibility materials
- Pajamas Design System Accessibility - GitLab-specific guidance