Storyblok Raises $80M Series C - Read News

Skip to main content

Providing Context & Structure: (ARIA) Landmarks

Try Storyblok

Storyblok is the first headless CMS that works for developers & marketers alike.


On May 13th, 2024, Storyblok started gradually rolling out a new design for its Visual Editor. Therefore, the Visual Editor product screenshots depicted in this resource may not match what you encounter in the Storyblok App. For more information and a detailed reference, please consult this FAQ on the new Visual Editor design.

Just like we are visually providing structure - by adding content blocks, creating a page layout and creating a corporate design with recognizable UI, we also need to provide structure semantically. Our code should convey meaning behind the scenes if you will. This is very important for screen reader users, as they likely get less use out of your visual cues. It’s also very beneficial for search engine optimization as Google’s crawlers scan the page similarly to screen readers. 

Section titled Landmarks

Bear with me, but if you plan to visit Paris, you will likely check out the Eiffel Tower, right? That’s Paris’ most famous landmark. You might even go as far as saying throughout the city, it helps you with orientation. Transferring this example from our physical world to web development, you can also consider landmarks as something that provides structure and meaning. 

HTML Landmarks 

Using semantic HTML elements, we can add meaning to each element on our page. This gives context to screen readers and helps screen reader users browse pages more efficiently. There are over 100 semantic HTML elements; here are a few examples that work like landmarks on your page: 

  • <main> : includes the most important content of your page
  • <footer>:  footer for its nearest ancestor
  • <nav>: represents a section of a page whose purpose is to provide navigation links
  • <aside> : content only indirectly linked to the main information on the page 
  • <h1> - <h6>: Headline levels

By structuring your page into these landmark areas, screen reader users can navigate faster and skip to specific sections rather than having to go through all content before reaching what they are looking for. 

ARIA Landmark Roles 

In some cases, providing context through HTML Elements might not be possible. Maybe you are dealing with legacy code that has to be preserved, maybe you have a very complex content structure. This is when ARIA landmark roles come in. 


ARIA is short for Accessible Rich Internet Applications and is part of the Web Content Accessibility Guidelines. Especially for dynamic applications, ARIA can be used to make content accessible to users with disabilities. It provides a framework for adding attributes to identify features for user interaction.

Example web content showing different landmarks

Aria Landmarks on an example page by W3

Like with Semantic HTML, ARIA landmark roles are used to organize and structure your page. If there are areas of your page that can not sufficiently be defined through HTML, you can add landmark roles, by adding the role= … attribute. Attributes include: 

These roles can help users of screen readers navigate your page more efficiently. But use them sparingly and only if there is no other option. The number one rule of ARIA is - just like in the Fight Club - to not use ARIA (unless really necessary). Too many landmarks will add a lot of noise that will make it challenging to filter out the relevant information. 

VoiceOver Rotor showing different Landmarks

VoiceOver Rotor showing different Landmarks

Section titled Using Landmarks in a Headless CMS

Ensuring that landmarks are used correctly is primarily a matter of front-end implementation. That being said, the component approach of a headless CMS should generally favour the semantic use of HTML elements and, therefore already result in less need for ARIA landmark roles. There are a few things that you can do in a headless CMS like Storyblok to ensure the correct use of landmarks. The goal should be to make it as difficult as possible to create inaccessible content by limiting how and where components are used and sharing context with everyone involved. 

Build an accessible content structure

While of course the idea of a headless CMS is to be flexible and free when building new pages, there are a few things you can do to make sure all this happens in an accessible fashion:

  • Develop your components with landmark structures in mind: stick to semantic code as much as possible and provide context with ARIA roles only were needed. Below, you can find two examples, one with semantic HTML, the other without:
Featured Article Section
    <h3>First article</h3>
    <p> Some Teaser Text for first article</p>
    <h3>Second article</h3>
    <p> Some Teaser Text for second article</p>
    <h3>Third article</h3>
    <p> Some Teaser Text for third article</p>

Featured Article Section with Semantic HTML

Featured Article Section
<div class="FeaturedArticleSection">
  <div class="ArticleContainer">
    <div clas="Headline">First article</div>
    <span class="TeaserText">Some Teaser Text for first article</span>
  <div class="ArticleContainer">
    <div clas="Headline">Second article</div>
    <span clas="Headline">Some Teaser Text for second article</span>
  <div class="ArticleContainer">
    <div clas="Headline">Third article</div>
    <span clas="Headline">Some Teaser Text for third article</span>


Featured Article Section without Semantic HTML

  • Limit what bloks can be used in which content type or nestable blok. 
In the block library, you can limit what components can be nested within each other.

Full control by restricting which components can be inserted within each other.

  • Give each blok and field a meaningful name to hint at how it should be used. In addition, you can add a description for editors to provide context how a field can be used. 
When editing the field, you can add a description for context.

Adding a description can provide context for some fields.

  • While Storyblok provides you with the opportunity to write markdown in rich text fields, use this power very wisely. Generally speaking, we want to completely decouple the presentation from the content in a headless CMS. This would also mean keeping all your code within your codebase and not adding any styling within individual fields, as it is very difficult to maintain. You can disable the use of markdown in richtext fields in the field settings. If you are curious about this topic, you can find out more in this article on creating an accessible Website with Storyblok.  
  • In your frontend, make sure only one <main> element is rendered per page. 
  • Your <header> and <footer> elements should ideally not be nested bloks and highly limited in the way they can be used on your page. Especially for components containing important information, which will not necessarily be changed often, permissions and roles come in very handy to manage access. 
  • Communicate the importance of sticking to set guidelines for accessibility & SEO sake. 
  • Use manual and automated tests to ensure accessibility. 

Section titled Conclusion

Landmarks provide crucial context for users of screen readers and other assistive tech. Making sure our code is semantically correct and structured logically will improve user experience and as an added bonus, enhance your SEO scores. Semantic code is your best option when structuring your content and components, but when needed, there are ARIA landmark roles to fill the gaps. 

While much of the implementation lies in the front end, be sure to use Storyblok’s capabilities to lower the threshold for accessible content creation and enable your team to build inclusive experiences on the web. 


Josefine Schaefer

Josefine Schaefer

Josefine is a frontend engineer with a passion for JavaScript, web accessibility and community-building. Before entering the tech industry, she worked as a communications specialist - nowadays, she combines these skills with her curiosity for technology and works as a Developer Relations Engineer at Storyblok.