Design-and-Code / Design-and-Code/support

Improve accessibility: add automated a11y checks to CI and fix low-contrast / keyboard focus issues

Open
#1,737 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
No language data
Stars
16
Forks
4
PR merge metrics
No merged PRs in 30d

Description

### Description of the bug

## Summary
Several UI accessibility problems have been reported (e.g. low contrast on FAQ expand buttons, awkward spacing affecting readability). To prevent regressions and make contributions easier for people with disabilities, add automated accessibility checks to the repository CI and fix the most visible accessibility issues.

## Problems observed
- Low contrast on FAQ expand buttons makes them hard to see for low-vision users.
- Some interactive elements lack clear keyboard focus outlines and/or ARIA attributes.
- Small spacing and badge layout issues can reduce scannability for screen magnifier users.

(Existing related issues for reference: "Low Contrast on FAQ Expand Buttons", "Awkward spaces between badges".)

## Proposed solution
1. Add automated accessibility testing to CI:
- Integrate `axe-core` or `axe-core/cli` (or GitHub Action like `dequelabs/axe-action`) into the repository's GitHub Actions workflow to run on PRs and main branch builds.
- Fail PR checks only for high-severity violations (or surface them as warnings depending on repo policy) to avoid blocking community contributions.
2. Fix immediate visual/a11y problems:
- Increase contrast ratio for FAQ expand buttons and any other elements below WCAG AA (contrast ratio >= 4.5:1 for normal text, >= 3:1 for large text).
- Ensure all interactive elements have visible keyboard focus styles (outline or box-shadow) and are reachable via keyboard.
- Add ARIA attributes where needed (e.g., `aria-expanded`, `aria-controls` for collapsible content) and ensure semantic HTML is used.
3. Add documentation and a checklist for contributors:
- Update `CONTRIBUTING.md` or add `ACCESSIBILITY.md` describing a11y expectations and how to run local a11y tests.
- Provide a short checklist for PRs (e.g., run `npm run lint`, run accessibility checks, run keyboard navigation).

## Implementation notes / commands
- Example GH Action (pseudo):
```yaml
name: a11y-check
on: [pull_request]
jobs:
axe:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
- run: npm ci
- run: npx @axe-core/cli --save --target=./public/index.html

### Working Environment (e.g. operating system, browser, device)

Chrome
Ubuntu
VPS

### Please add screenshots (if applicable)

0

### Add any other context about the problem here

0

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.