DatoCMS Accessibility Checklist 2026 | WCAG 2.1 AA & EAA Compliance
Last updated: 2026-07-26
DatoCMS is a GraphQL-based headless CMS used for marketing sites, product catalogs, documentation, and multi-locale content operations, usually paired with a framework like Next.js, Nuxt, or Astro on the front end. Like every headless system, it splits accessibility across two places that drift apart quickly: the content schema and editorial workflow inside DatoCMS, and the front-end code that queries the Content Delivery API and renders the result. Most teams audit only the deployed front end, fix whatever the automated scanner flags in their components, and never revisit the model, so the same problems return with every new record an editor publishes. The schema is where the durable wins live. DatoCMS assets do carry per-locale default alt and title metadata, but that metadata is easy to leave blank, and single-asset or gallery fields on a model often reference images with no explicit, required alt field of their own, so editors publish product shots and hero images with no text alternative. The Structured Text field is another common source of failures: it lets editors insert any heading level, so records arrive with an embedded H1 that collides with the template title, or a jump from H2 to H4 that breaks the outline screen reader users rely on. Localization compounds the risk, because DatoCMS stores per-locale field values but the front end frequently hardcodes the document language, so translated content is announced with the wrong pronunciation. Because DatoCMS powers commercial sites serving EU customers, the European Accessibility Act applies to the published experience, and enterprise buyers increasingly request WCAG 2.1 AA documentation covering the whole pipeline. This checklist covers both halves: what to change in the content model and what to enforce in the rendering layer.
Common Accessibility Issues
DatoCMS assets have optional default alt and title metadata, and single-asset or gallery fields on a model commonly reference images without a dedicated, required alt field. Editors upload product images, diagrams, and hero art with the metadata left blank, and the front end then renders an image element with an empty or filename-derived alt attribute. Screen reader users hear a filename or nothing where information should be.
Add an explicit alt text field wherever a model references an image, and mark it required for informative images, with help text explaining that it should describe what the image conveys in context rather than repeat the caption. Provide a clear decorative toggle that renders an empty alt attribute for purely ornamental art. When you rely on the asset's default alt metadata, enforce that it is filled before publish rather than trusting editors to remember, and never auto-populate it from the filename.
The Structured Text editor exposes multiple heading levels, so a body field 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 through the structured-text renderer, the page has multiple top-level headings or skipped levels, and screen reader users lose the outline they use to navigate long content.
Restrict the heading nodes allowed in the Structured Text field so the body can only begin at the level below whatever the template renders, usually H2, and document the rule in the field help text. In your renderer, map heading nodes to the correct tag for the surrounding template rather than passing the editor's choice through untouched, and validate published records so a skipped level is caught before it ships.
DatoCMS localization stores per-locale values for the same record, but the front end often hardcodes the document language or inherits whatever the default build sets. German, French, or Japanese content then renders inside a page declared as English, so screen readers apply English pronunciation rules 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 statically generated pages where the locale is known at build time. Where a passage within a record 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 instead of assuming the routing handles it.
DatoCMS provides a responsive image query that returns srcset, sizes, and a base64 placeholder, and teams wire it into an image component that focuses on performance and forgets to pass the alt value through, or renders the placeholder in a way that hides the real image from assistive technology. The result is fast-loading images that screen readers cannot describe.
Ensure the image component always outputs the alt text from the asset or model field on the final image element, not only on a wrapper. Confirm the low-quality placeholder is decorative and does not carry its own conflicting alt text. Reserve explicit width and height so the layout does not shift as images load, which helps users with low vision and cognitive disabilities who are disoriented by content that jumps.
Call-to-action blocks in a DatoCMS model usually 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 records. 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 collection listing.
Add help text, and validation where practical, 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 record 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 with the link.
Teams run an automated scan on the deployed site, fix what it reports in component code, and consider the work finished. Because the model still allows blank alt metadata, arbitrary heading levels, and generic link labels, every record published afterward reintroduces the same failures, and the site's accessibility 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, and help text that explains why. Add publish-time validation or a review step for these fields, give editors a short written guide with examples, and re-scan after fixing the model so the remaining front-end issues are the only ones left.
DatoCMS-Specific Tips
- Fix accessibility in the content model first, because a schema that allows a failure will keep producing it no matter how good your front-end components are.
- Constrain the heading nodes available in Structured Text so editors physically cannot introduce a second H1 or skip a level.
- Drive the rendered page language attribute from the DatoCMS locale on every route, including statically generated pages.
- When using the responsive image query, confirm your image component always forwards the alt text to the final image element, not just a wrapper.
- Test a real published page with a keyboard and screen reader for each locale, not only the default one, because localization problems appear only 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 DatoCMS content rather than your components.
WAVE Browser Extension
Overlays structural information on the page so you can see the heading outline produced by Structured Text records and spot generic repeated link text across listings built from DatoCMS 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 responsive images are described rather than skipped.
Frequently Asked Questions
Does DatoCMS give assets alt text automatically?
DatoCMS assets have per-locale default alt and title metadata fields, but they are optional and blank until someone fills them, so they are not automatic in any meaningful sense. Editors routinely upload images and skip the metadata, and any model that references an asset without its own required alt field will happily publish images with no text alternative. Treat the default metadata as a starting point you must enforce: make alt required for informative images, add a decorative toggle for ornamental art, and block publishing when a content image has no description. Do not auto-fill alt from the filename, which produces text that reads as noise to screen reader users.
How do I stop editors from breaking the heading structure in Structured Text?
Constrain the tool rather than relying on training alone. Configure the Structured Text field to allow 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 your structured-text 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 record produces a valid outline. Then spot-check published pages with a headings tool, since a constrained field plus a mapping layer catches nearly everything except records imported 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.