Hygraph Accessibility Checklist 2026 | WCAG 2.1 AA & EAA Compliance
Last updated: 2026-07-22
Hygraph is a GraphQL-native headless CMS used for marketing sites, documentation, product catalogs, and multi-market content operations. Like every headless system, it separates the content from the presentation, which means accessibility is decided in two places that are easy to keep out of sync: the schema and editorial workflow inside Hygraph, and the front-end code that queries the API and renders the result. Teams typically audit the front end, fix what the automated scanner reports, and never look at the content model, so the same problems reappear with every new entry an editor publishes. The schema is where most of the durable wins are. If an asset or image field has no accompanying alt text field, or has one that is optional and unexplained, editors will publish images with no text alternative forever and no front-end fix can recover the missing information. If a rich text field lets editors choose any heading level, entries arrive with H1s embedded in body content or sections that skip from H2 to H4, and whatever the page template wraps them in will produce a broken outline. Localized content adds another layer: Hygraph's localization gives you per-locale field values, but unless the front end sets the language attribute from the locale being rendered, screen readers read translated text with the wrong voice and pronunciation rules. Media assets uploaded through the API arrive without captions or transcripts unless the model demands them. Because Hygraph powers commercial sites serving EU customers, the European Accessibility Act applies to the published experience, and enterprise buyers increasingly ask for WCAG 2.1 AA conformance documentation covering the whole content pipeline. This checklist covers both halves: what to change in the content model and what to enforce in the rendering layer.
Common Accessibility Issues
Hygraph assets carry a filename and optional metadata, and many schemas reference an asset directly from a content model with no dedicated alt text field. Editors then upload product shots, diagrams, and hero images with no text alternative, and the front end renders an image element with an empty or filename-derived alt attribute. Screen reader users hear a filename or nothing at all where information should be.
Add an explicit alt text field to the model wherever an image is referenced, with help text explaining that it should describe the information the image conveys in context, not repeat the caption. Make it required for content images and provide a clear decorative toggle that renders an empty alt attribute for purely ornamental art. Never auto-fill it from the filename or the title field, since that produces text that reads as noise.
The rich text editor typically exposes every heading level, so an article body arrives containing its own H1 while the page template also renders an H1 for the title, or an editor drops to H4 for a subsection because it looked the right size. Once rendered, the page has multiple top-level headings and skipped levels, and screen reader users lose the outline they rely on to navigate long content.
Restrict the rich text field's available heading levels so the body can only start at the level below whatever the template renders, usually H2, and document the rule in the field's help text. In the renderer, map rich text heading nodes to the correct tags for the surrounding template rather than passing them through blindly, and validate published entries so a skipped level is caught before it ships.
Hygraph localization stores per-locale values for the same entry, but the front end often hardcodes the document language or inherits whatever the default build sets. German or Japanese content then renders inside a page declared as English, so screen readers apply English pronunciation rules to it and the result is unintelligible. Mixed-language snippets inside an otherwise translated page have the same problem at a smaller scale.
Set the page language attribute from the locale being queried on every render, including static builds where the locale is known at build time. Where a passage within an entry is in a different language than the page, mark that passage with its own language attribute so assistive technology switches voices. Verify by loading each locale and checking the rendered document language rather than assuming the routing handles it.
Media uploaded to Hygraph as assets or referenced from an external host arrives as a file reference with no associated caption track or transcript unless the model asks for one. Product demos, onboarding videos, and recorded talks then publish with no captions for deaf and hard-of-hearing users and no transcript for anyone who cannot or does not want to play audio.
Add caption file and transcript fields to any model that references video or audio, and make captions required before an entry can publish. Render caption tracks in the player and expose the transcript as real text on the page, not as a downloadable file only. For content with meaningful visual information not covered by the narration, plan for audio description alongside the captions.
Call-to-action and link components in a schema commonly pair a URL field with a short label field, and editors fill the label with 'Read more', 'Learn more', or 'Click here' across dozens of entries. Screen reader users listing the links on a page get a column of identical text with no way to tell the destinations apart, and the same labels repeat across every card in a listing.
Add help text and, where practical, validation encouraging link labels that describe the destination, such as 'Read the 2026 accessibility report'. In card and listing components, compose the accessible name from the item title rather than the shared label, so each link is distinguishable even when the visible text is short. Reserve a truly generic label only where the surrounding context is programmatically associated.
Teams run an automated scan on the deployed site, fix what it reports in the component code, and consider the work done. Because the underlying model still allows missing alt text, arbitrary heading levels, and uncaptioned media, every entry published afterwards reintroduces the same failures, and the site's accessibility slowly degrades between audits with no code change to blame.
Treat the content model as part of the accessibility surface: required alt text, constrained heading levels, required captions, and help text that explains why. Add publish-time validation or a review step for these fields, and give editors a short written guide with examples. Re-scan after fixing the model so the remaining front-end issues are the only ones left.
Hygraph-Specific Tips
- Fix accessibility in the content model first, because a schema that allows a failure will keep producing it no matter how good the front-end components are.
- Constrain the heading levels available in rich text fields so editors physically cannot introduce a second H1 or skip a level.
- Drive the rendered page language attribute from the Hygraph locale on every route, including statically generated pages.
- Write field help text in plain language explaining what good alt text and good link labels look like, since editors are the ones who decide quality at scale.
- Test a real published page with a keyboard and screen reader for each locale, not just the default one, because localization problems only appear in the translated builds.
Recommended Tools
axe DevTools
A browser extension that audits the rendered front end for missing alt attributes, heading order problems, and language attribute errors, giving you a fast read on which failures originate in the content rather than the components.
WAVE Browser Extension
Overlays structural information on the page so you can see the heading outline produced by rich text entries and spot generic repeated link text across listings built from Hygraph collections.
NVDA
A free Windows screen reader for confirming that localized pages are announced in the right voice, that alt text reads sensibly in context, and that media captions and transcripts are reachable.
Frequently Asked Questions
Whose job is accessibility in a headless setup, the CMS or the front end?
Both, and splitting the responsibility clearly is what makes it stick. The front end owns the rendered markup: semantic elements, focus management, contrast, keyboard support, and correct rendering of whatever the API returns. Hygraph owns whether the information needed for accessibility exists at all: alt text, captions, transcripts, sensible heading levels, and descriptive link labels. No amount of front-end work can invent alt text that an editor never wrote, and no amount of good content survives a component that drops it. Assign both halves explicitly or each team assumes the other has it covered.
How do I stop editors from breaking the heading structure in rich text?
Constrain the tool rather than relying on training alone. Configure the rich text field to expose only the heading levels that make sense below the template's own heading, which for a typical article body means starting at H2. Add help text stating the rule and why it matters. In the renderer, map heading nodes to the correct level for the surrounding context instead of passing the editor's choice through untouched, so even an unusual entry produces a valid outline. Then spot-check published pages with a headings tool, since a constrained field plus a mapping layer catches nearly everything but not entries migrated in through the API.
Further Reading
Other CMS Checklists
Get our free accessibility toolkit
We're building a simple accessibility checker for non-developers. Join the waitlist for early access and a free EAA compliance checklist.
No spam. Unsubscribe anytime.