cloudinary-community / cloudinary-community/next-cloudinary

Improve a11y and usage for docs homepage

Open
#628 1 comment 0 reactions 0 assignees View on GitHub
hacktoberfest hacktoberfest2025
Dominant language
JavaScript
Stars
300
Forks
137
Avg merge
3m
Merged PRs (30d)
2

Description

Problem

The docs homepage currently exposes usability barriers that affect keyboard-only users, screen reader users, and people using touch devices.

What I changed

- Added semantic landmarks (``, ``, ``) to make page structure explicit for assistive tech.
- Added concise alt text for "Cloudinary App Gallery" images.
- Ensured clear, visible focus styles for keyboard navigation.
- Increased CTA touch targets to ~44×44px to improve tap usability on mobile.
- Honored `prefers-reduced-motion` to reduce motion for users who opt out.

Why this is important

- Better experience for screen reader and keyboard users — faster navigation and clearer content description.
- Improves tap accuracy on mobile for CTAs and reduces accidental misses.
- Reduces friction for contributors and reviewers by enabling the docs to run locally.

How to review / acceptance criteria

1. Pull the branch and run the docs locally: `cd docs && pnpm install && pnpm dev`.
2. On the homepage:
- Use Tab to navigate and confirm focus rings are visible and contrast is high.
- Verify gallery images have meaningful alt text (screen reader or inspect markup).
- Confirm CTAs are at least ~44×44px (inspect element or test on a mobile device / emulation).
3. Run an automated accessibility scan (Lighthouse or axe) — high-severity issues for the homepage should be reduced.
4. Confirm the docs build locally without import resolution errors.

Files of interest
- `docs/pages/index.mdx`
- `docs/pages/_document.js`

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.