How Your Contentstack Model Shapes Your Accessibility Readiness

Failing an accessibility audit doesn’t just mean failing to check a WCAG checkbox. It also means legal exposure, potential litigation, and a product that excludes users, your competitors will happily serve.

Most teams treat accessibility as a frontend fix, but by the time the frontend renders your content, half the decisions are already locked in by the CMS. Your CMS sits between your content authors and your output layer, and the choices it makes about how fields are structured and how alt text is handled either give your frontend the raw material to comply with accessibility requirements or guarantee it can't.

Understanding where the CMS's responsibility ends, and the frontend's begins, is the only way to build a defensible, auditable accessibility posture.

In this article, we’ll look at what that looks like for Contentstack, including which Contentstack controls are responsible, what your frontend code is responsible for, and how to structure your content model so accessibility is considered from the beginning.

Key Takeaways

• Accessibility failures in headless CMS implementations are usually due to content-model issues, not frontend issues.

• Contentstack's built-in Description field returns as file.description in the Delivery API and maps directly to the HTML alt attribute.

• Heading hierarchy breaks when editors can apply any heading level to body copy, but restricting H1, H2, and H3 from Rich Text Editor fields fixes this at the model level.

• Oshyn helps enterprise teams build Contentstack content models that meet WCAG 2.1 Level AA requirements, ensuring accessibility is built in from the beginning.

The WCAG Baseline

This post references WCAG 2.1 Level AA, the most common accessibility standard for public-facing websites, which covers perceivability, operability, understandability, and robustness.

The CMS vs. the Frontend: Who Is Responsible for What?

Alt Text for Assets

WCAG 2.1 — SC 1.1.1 Non-text Content (Level A)

All non-text content presented to the user has a text alternative that serves the equivalent purpose. Purely decorative content is implemented so it can be ignored by assistive technology.

The problem with relying on file names

When an editor uploads an image to Contentstack and adds it to a File field, only the asset URL is stored. By default, there is no alt text.

The tempting shortcut is to fall back to the filename, which the Delivery API returns as file.filename. That fails SC 1.1.1 for a structural reason, not a cosmetic one: a text alternative must be authored by someone who understands what the image communicates in this context. A filename is a storage artifact. It was produced by a camera, an export preset, or a designer's save dialogue — never by someone describing the image's purpose to a user who cannot see it.

Anti-pattern: relying on asset filename as alt text

DSC00312-cropped-final-FINAL.jpg is not a text alternative. Neither is superman_logo_PNG8.png, even though it looks descriptive — it names the file, not what the image conveys. Note that file.filename and file.description are two distinct fields in the Delivery API response. Rendering the filename into alt is an active decision your frontend makes, not an innocent default. Never auto-generate alt from filename.

The right pattern: a dedicated alt text field

Contentstack assets have a built-in Description field. Fill it when you upload the image — it is returned as file.description in the Delivery API and maps directly to the HTML alt attribute. No extra field on the content type is needed:

function BlogHero({ post }) {
  return (
	<figure> 
  	<img
    	src={post.cover_image.url}
    	alt={post.cover_image_alt || ''}
    	// Empty string = decorative image (screen reader skips it)
  	/> 
  	{post.cover_image_alt && (
    	<figcaption> {post.cover_image_alt}</figcaption> 
  	)}
	</figure> 
  );
}

Empty alt for decorative images.

If an image is purely decorative (a background texture, a divider illustration), the alt text field should be left empty, and your frontend should render alt="" — not omit the attribute. Screen readers skip images with empty alt text; they announce images with no alt attribute.

What the fix looks like in practice

In the Contentstack training stack, the character content type stores a profile image in a file field. Filling the asset's Description with “Crest of the House of El, symbolizes hope” and binding it to alt is the entire fix — no schema change, no new field, one editor action.

Superman character page. The <img> element has an alt attribute — a screen reader announces the image's filename with no further context.

Fix step 1: add a description to the asset in Contentstack

Contentstack asset editor for superman_logo_PNG8.png. The Description field is filled with “Crest of the House of El, symbolizes hope.” This value is returned as file.description in the Delivery API response.

Fix step 2: map file.description to the alt attribute

After: image with meaningful alt text

Superman character page after the fix. DevTools confirms the <img> element now carries a descriptive alt attribute sourced directly from the Contentstack asset.

Asset Description vs. a custom alt text field

Contentstack assets include a built-in Description field, accessible as file.description. For most cases, this is sufficient — one place to write it, every context that uses the asset benefits. Add a separate profile_image_alt field on the content type only when the same asset needs different alt text depending on context (e.g., a logo that is decorative on the homepage but informative on the About page).

Structured Content and Heading Hierarchy

Why heading order matters

Screen reader users navigate pages using headings as landmarks. If your page goes H1 H3 H2, the structure is broken. Contentstack does not enforce heading order — that is a content modeling and editorial discipline problem.

Model heading fields explicitly

Avoid a single Rich Text field where editors can insert any heading they like. Instead, expose heading levels as explicit fields:

Restrict heading levels in the Rich Text Editor.

Contentstack's Rich Text Editor allows editors to insert headings by default. Configure the RTE toolbar to disable H1, H2, and H3 within body copy fields — those levels should only come from dedicated heading fields. This prevents the heading hierarchy from being broken when an editor formats a paragraph as an H1.

Link Text and Calls to Action

Anti-pattern: “Click here” and “Read more”

If your CTA content type has a field called button_text and editors fill it with “Click here”, every link on the page has the same accessible name. Screen reader users who navigate by links hear a list of identical “Click here” announcements.

The fix is a descriptive CTA model:

<a
  href={cta.cta_url}
  aria-label={cta.cta_aria_label || undefined}
>
  {cta.cta_label}
</a>

Media: Video and Audio

If your Contentstack stack stores video or audio assets, build your content type to support captions and transcripts:

SEO Metadata and Open Graph (Bonus Accessibility)

SEO metadata is not purely an accessibility concern; well-structured metadata also helps screen readers and assistive tools that rely on page metadata.

Global Field: SEO

Define a Global Field called seo and include it in every content type. This ensures consistent metadata across the site without duplicating schema.

Editorial Guidelines You Should Publish Internally

Everything above is a modeling decision a developer makes once. The rules below are decisions an editor makes every day, and no content model can enforce them. This is where most accessibility regressions actually come from — not from a missing field, but from a correctly modeled field filled badly.

Publish this as a table in your team's style guide rather than a list of dos. The middle column is the part that makes it stick: editors follow rules they understand the consequences of, and ignore rules that read as arbitrary house style.

Make the rule visible where the decision is made

Contentstack lets you set help text and instructions on every field in the content type builder. A style guide nobody opens changes nothing; “Describe what the image conveys. Do not start with `Image of'. Leave empty if decorative.” sitting under the Description field changes behavior on the first upload. Move as many of these rules as you can out of the document and into the field definition.

Testing Accessibility

Contentstack itself is not the thing to test — your rendered frontend is. Run these tools on your published pages:

Automated tools are a floor, not a ceiling

Auditing a modern web application with automated scanners alone is like critiquing a novel with a spellchecker. It will catch the misspellings, and it will tell you nothing about whether the book works.

Automated tools catch roughly 30–40% of WCAG issues. The remaining 60% can only be found by someone who understands how a person actually operates assistive technology. That is a skill, not a checkbox — and it is the single biggest gap on most teams shipping accessible software. If nobody on the project can drive a screen reader, your audit has a 60% blind spot that no budget for tooling will close.

What the scanner cannot determine

The limitation is structural, not a question of tool quality. A scanner reads the DOM at one point in time. It cannot form an intent, traverse an interface, or judge whether what it heard matched what was meant.