Building accessible messages in Braze

Understand why accessibility is important to consider in your marketing content, and how you can build accessible messages in Braze. For more guidance, check out our Accessible Messaging Foundations course on Braze Learning.

Marketing content that excludes people with disabilities, even unintentionally, can prevent millions of people from interacting with your brand. Accessibility in marketing is about making it easy for everyone to experience your marketing, receive and understand your communication, and have the opportunity to invest in or become a fan of your product, service, or brand.

When designing your messaging, take the extra time to consider how you can make your designs accessible to all your customers.

Accessibility at Braze

Supporting accessible communication means staying open, curious, and willing to learn. At Braze, we care about helping people connect—and we know that making room for everyone is part of doing that well. Accessibility is not something we ever consider “done,” and we welcome the chance to keep learning.

If you have feedback about the accessibility of Braze or messages sent from Braze, we’d love to hear from you. Open the Support menu in the global header and select Share feedback to send us your thoughts.

Areas of disability to consider

This section is partially adapted from W3C: Diverse Abilities and Barriers.

• visual
• hearing
• physical
• cognitive

Best practices

Creating accessible content doesn’t have to be overwhelming. Small, thoughtful choices can make a big difference. This section walks through practical tips that help more people successfully read, navigate, and interact with your messages. Whether you’re adjusting your copy, styling your buttons, or adding alt text to images, each tweak adds up to a more inclusive experience. Let’s dig in.

Content

Structure and flow

Let’s start with the foundation. When your content has a clear structure, it’s easier for everyone to follow—especially people who rely on screen readers or keyboard navigation.

• Break your content into sections: Using headings, bullet points, and lists helps people quickly understand and scan your content—even when they’re in a hurry.
• Don’t skip heading levels: Headings give your content structure, helping readers quickly understand how sections relate to each other. When you skip heading levels (for example, jumping straight from an H2 to an H4), you break this logical structure. This makes it harder for users, especially those using screen readers, to navigate and understand your message clearly. Always follow a logical, sequential hierarchy of headings (H1 to H2 to H3, and so on) to make sure your content stays organized, accessible, and easy for everyone to follow.

Readability

Once your structure is in place, the next step is making sure your words are actually easy to read. This means keeping things simple, scannable, and comfortable to read across devices and user needs.

• Write short, clear sentences: Short sentences are easy for everyone to understand, especially people using screen readers or who have trouble processing complex information. Write to a United States seventh-grade reading level. You can use resources such as Hemingway App to check your text’s reading level.
• Choose readable font sizes and spacing: Text that’s too small can be hard to read—especially on mobile. Use at least 14px for body text. Make headings larger so users can clearly see the difference. Extra spacing between lines (around 1.5 line-height) and paragraphs improves readability, especially for people with visual or cognitive needs.
• Avoid justified text: Justified text creates uneven spacing between words, making reading difficult for people with dyslexia or cognitive disabilities. Consider making content that wraps to more than two lines aligned left for left-to-right languages or aligned right for right-to-left languages.
• Use bold, italic, and uppercase text sparingly: Emphasizing too much text makes reading difficult—especially for people with dyslexia or visual impairments. Keep it simple.

Clarity and usability

Finally, let’s talk about the finer details—the things that help users not just see your content, but understand and interact with it.

• Clearly label links and buttons: Make sure your link and button text clearly explains what happens next. It helps people using screen readers or navigating with a keyboard know what to expect.
• Go easy on symbols and emojis: Special characters and emojis can make your content playful, but they can be confusing when read by screen readers. Use them sparingly, and make sure they don’t replace clear, descriptive text.
• Test for truncation: Always test your copy by sending a test message to a device to make sure your text isn’t truncated. If your message is being cut off, this hurts both you and the user, since it prevents your content from reaching your users.

Buttons

Use buttons to indicate an action, such as sending a form or playing a carousel. If you’re navigating to a new URL, consider using a link instead.

Write clear, action-oriented text

Similar to link text, button labels should clearly describe the action. Effective button text is specific and action-oriented. For example, “Submit Order” clearly tells users what will happen when they click, whereas simply “Submit” can be ambiguous. Each label should precisely describe its intended action, so screen readers and all users can easily understand and predict the outcome when interacting with your buttons.

Keep button text concise to prevent truncation. If a button’s text is too long, it may be cut off with an ellipsis instead of wrapping.

Use sufficient color contrast

Button text must be easy to read against the button’s background color. Check that your button text meets WCAG 2.2 AA contrast minimums:

• 4.5:1 contrast ratio for normal-sized text (most buttons)
• 3:1 contrast ratio for large text (typically above 18pt)

High contrast helps buttons remain readable and clickable for everyone, including users with visual impairments or those viewing your message in challenging environments. For more guidance, see the Color contrast section.

Make buttons easy to tap

Make sure your buttons (and links) are big enough and spaced far enough apart for users on mobile devices. Small or crowded tap targets can be frustrating or impossible for users with motor disabilities to interact with.

Links

Use links for navigation, like directing users to an external page.

• Write descriptive link text
• Avoid styling links like buttons

Write descriptive link text

Write link text that clearly describes where the link will take the user. Screen reader users often skip from link to link as a way of skimming through content, so make sure your link text can stand on its own. Avoid phrases like “click here,” “more,” and “click for details,” as they are ambiguous when read out of context.

For example, consider how you might write a link to view a weather report.

As with all content, keep it straightforward with as few extra words as possible.

Avoid styling links like buttons

Braze drag-and-drop editors output semantic HTML by default, so links aren’t styled like buttons there. However, if you’re working with custom HTML or making code-level changes, keep this in mind:

• Links (<a>) respond to the Enter key.
• Buttons (<button>) respond to both the Enter and Space keys.

Styling a link to look like a button can confuse people who navigate with a keyboard—they might try pressing Space and expect it to work.

Use the right element for the action:

• Use <button> for actions, like submitting a form or opening a modal.
• Use <a> for navigation, such as linking to another page or file.

1
2
3
4
5
<!-- Recommended: A true button for an action -->
<button type="button">Download report</button>

<!-- Not recommended: A link styled as a button -->
<a href="#" class="btn">Download report</a>

Images

Provide alt text

Alternative text (alt text) is a short description of the content or function of an image that screen readers and other assistive technologies provide to users. For every meaningful image, write descriptive alt text so users who can’t see the visuals still understand your message or call to action.

Avoid images of text

Whenever possible, avoid placing text inside images—screen readers can’t read image-based text, and users can’t easily adjust font size or color for better visibility. Consider these tips:

• Remove text where you can: Move any descriptive or promotional text from the image onto a text field in your message instead. This way, users can resize or recolor it as needed using their device or browser preferences.
• Test for readability and contrast: If you must keep text in the image, follow color contrast best practices and use a large scale font. This means text should be at least 18 points (about 24 pixels) for non-bold text or 14 points (about 18 pixels) if it’s bold. Using these sizes helps text remain legible without forcing users to zoom in, and it improves the overall contrast and readability of the content. Test to confirm it’s still legible on smaller screens.
• Provide alt text: For essential text that must remain in the image, include alt text describing the words.

When images contain text that can’t be edited, users with visual impairments lose the flexibility to make reading adjustments. By separating text from images, you help more users read and interact with your message comfortably.

Tips for writing alt text

• Describe what’s actually in the image
• Keep it short, yet specific
• Avoid “image of” or “picture of”
• Reflect text that appears in the image
• Stick to relevant context—no extra marketing jargon
• Consider the image’s purpose

Describe what’s actually in the image

Screen reader users rely on alt text to understand the content or function of an image. Avoid generic “marketing speak” that doesn’t match what’s visually shown.

Keep it short, yet specific

Concise alt text makes it easier for users to process. Include enough detail to convey purpose but skip any fluff. As a general rule, keep alt text to 125 characters or less. If anything more than a brief phrase or sentence is necessary, consider using one of the long description methods from W3C.

Avoid “image of” or “picture of”

Screen readers already announce an image. Jump right into describing the subject.

Reflect text that appears in the image

If an image includes essential text, put that information in the alt text so users don’t miss it.

Stick to relevant context—no extra marketing jargon

Don’t pad alt text with SEO terms or calls to action not directly related to the image. Provide value for those who can’t see the image.

Consider the image’s purpose

If an image is functioning like a link or call-to-action, describe the intended action (“Shop,” “Link to,” “Sign up”), not just the label or product shown.

If the image doesn’t have a purpose, make that known too. Decorative images, like logos, should have an empty alt tag (alt="") so screen readers know to skip announcing it. Without it, usually the image file name is read instead.

Videos

Videos are engaging, but if they’re not accessible, you risk excluding part of your audience. Use the following tips to make your video content more inclusive:

• Provide closed captions
• Provide playback controls
• Avoid auto-play
• Avoid flashing or strobing content

Provide closed captions

Include closed captions with your videos so users can follow along with the dialogue, sound effects, and other audio content. Captions help:

• People who are Deaf or hard of hearing
• Viewers watching in a sound-off environment
• Non-native speakers who prefer to read along

Closed captions can be toggled on or off, allowing users to choose what works best for them.

Provide playback controls

Make sure your embedded video includes accessible playback controls—such as play, pause, mute, and seek—so users can interact with it in the way that works best for them.

Avoid auto-play

Whenever possible, avoid setting videos to play automatically. Auto-play can be jarring or disorienting for:

• Users relying on screen readers or keyboard navigation
• People with motion sensitivity
• Anyone in a quiet environment (like a workplace or late-night setting)

Let users choose when to play a video by including clear controls.

Avoid flashing or strobing content

Don’t include videos with flashing or strobing effects, especially at a high frequency. These can trigger seizures in users with photosensitive epilepsy and cause discomfort for others.

Color contrast

Sufficient color contrast helps ensure your messages are easy to read for everyone, including people with low vision or those viewing your content in bright or challenging conditions. Aim for contrast ratios that comply with WCAG 2.2 AA level requirements:

• 4.5:1 contrast ratio for normal text (think body text, buttons, and links)
• 3:1 contrast ratio for large text (think headings and larger labels)

You can test your color choices using the WebAim Contrast Checker Tool.

Custom HTML

If you use any custom HTML in your messaging:

• Use semantic HTML. This means using the correct HTML elements for their intended purpose instead of styling one element to look like another. Most HTML elements have their own accessibility support built in.
• Set the lang attribute within your HTML to identify the language that your content is in. Screen readers use different sound libraries for each language based on the pronunciation and characteristics of that language. If this isn’t specified, a screen reader assumes the content is written in the default language that the user chose when setting up the screen reader. If the message isn’t actually in the default language, then the screen reader might not pronounce the message correctly.

1
<html lang="en-us">

• Use ARIA attributes to give extra context. These attributes provide additional information to assistive technologies, helping to clarify the role, state, or properties of UI elements that may otherwise be unclear.

ARIA attributes

When you’re using custom code in Braze editors, you can use Accessible Rich Internet Applications (ARIA) to provide extra accessibility support for users who rely on assistive technology. ARIA roles and attributes help screen readers interpret your content more clearly, especially when you’re using elements that don’t convey meaning on their own (like <div> or <span>).

Here are a few examples that are especially useful in messaging contexts:

• aria-label
• aria-labelledby
• aria-hidden=”true”
• role=”presentation”
• aria-live=”polite”

aria-label

aria-label adds an accessible name to elements that don’t have visible text. If you’re using an icon with no text (like a trash can or “X” for close), someone using a screen reader won’t know what it does—unless you label it. aria-label gives that icon a voice.

1
2
3
<button aria-label="Close message">
  <svg ...></svg>
</button>

aria-labelledby

aria-labelledby connects an element to something that already has a visible label. So if you have a banner or region that should be read out loud with a title, you can use aria-labelledby to tell assistive technology, “Hey, use that heading over there to name this part.”

1
2
<h2 id="banner-title">Important Update</h2>
<div role="region" aria-labelledby="banner-title">...</div>

aria-hidden=”true”

aria-hidden="true" hides things from screen readers. It’s helpful for text or visuals that don’t convey important meaning—like a sparkle, checkmark, or emoji used purely for style.

This keeps the experience cleaner for screen reader users, who otherwise might hear redundant or confusing content. It’s also useful for hiding things like offscreen accordion content that hasn’t been expanded yet.

1
<span aria-hidden="true">✔️</span>

In general, it’s better to use alt="" for decorative images and icons rather than aria-hidden="true". While semantic HTML is widely supported by all screen readers and assistive software, ARIA support varies. Even if you use aria-hidden you should still include an empty alt attribute.

role=”presentation”

role="presentation" tells assistive tech to ignore layout-only elements, like design tables. For example, emails often use tables just to line things up. Without this role, screen readers might assume your layout is a data table and start reading out row and column numbers.

1
<table role="presentation">...</table>

Emails created in the email drag-and-drop editor have presentational elements automatically marked with the ARIA attribute role="presentation".

aria-live=”polite”

aria-live="polite" announces updates when content changes without needing user interaction. Use it when you display dynamic updates within a message, like successes, errors, or other notifications.

1
<div aria-live="polite">Your preferences have been saved.</div>