> For the complete documentation index, see [llms.txt](https://docs.horizon.ipaper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.horizon.ipaper.io/accessibility/template-guidelines.md).

# Template guidelines

Guidelines for making templates accessible

{% hint style="info" %}
Note: This is not a definite guideline of how exactly to do it, it's a collection of things to keep in mind.
{% endhint %}

## Accessibility overview

In order to make templates accessible, there are a few things to keep in mind. Most users of screen readers are visually impaired, so images and text elements that aren't descriptive, are not very helpful. Take a price for example, if it just says "499,-" and nothing else, then most screen readers will simply read the numbers, "499". This isn't helpful because it could be a price, a product id, a model, a size and much more. In order to make it accessible it should either contain a currency or the word price, or it should have an aria label and description.

Using `aria-label` and `aria-description` can be difficult, because their use depends on the screen reader you use. For NVDA `aria-label` is only read if the element has no immediate text

```html
<p aria-label="I am an empty tag"></p> // label will be read
<p aria-label="I am an empty tag">I have text</p> // label will be ignored and text be read
```

For Mac's VoiceOver it's a little more complicated, it reads the label depending on the html tag. `<span>` seems to ignore the label, however tags like `<p>`, `<h1-5>`, `<div>` reads out the label.

```html
<span aria-label="some label">I have text</span> // label is ignore and text is read
<p aria-label="some label">I have text</p> // label and text is read
```

However, `aria-description` is a little more simple. NVDA always reads the description, VoiceOver never reads the description. There are a few posts saying that the newest VoiceOver does read some labels, but we can't rely on that yet.

```html
<span aria-description="yay">I have text</span> // only read by NVDA
```

One important side-note on navigating a webpage using screen readers, \~90% of users navigate using headings and find them very or somewhat helpful. This means that the main way to go through a website is `h1-h5` tags.

Please see the following survey <https://webaim.org/projects/screenreadersurvey10/>

## Template a11y

Specifically for Horizon templates, there are a few things to keep in mind.

1. CTAs should have label/description to explain what they do or what they're supposed to do. E.g. a basket button should have a label/description reading "Add to basket"
2. Text fields should have label/description explaining what they are. If it's a price, the label/description should say fx. "Price in DKK" or maybe just "Price".
3. Titles should be headings `h1-h5` so they can be easily navigated to and give a good overview of the page
4. images should have alt attributes describing what they contain, this could be a product title

Below is an image from an example leaflet and the red text shows elements which should have a label/description or specific html tag

<figure><img src="https://2666012125-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTiKkO2apMzIcxKwKiV1%2Fuploads%2FXVSlyu30bOu0z2slBxOg%2FScreenshot%202025-01-20%20155158.png?alt=media&amp;token=eb042042-2fa0-43ba-994f-699d02e89a1d" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.horizon.ipaper.io/accessibility/template-guidelines.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
