NSW Email Design System

Accessibility for email developers

Every government email must be readable, understandable and actionable – for everyone. This includes people using screen readers, high-contrast modes or keyboard navigation.

Globally, more than 285 million people live with visual impairments, and 36 million are blind. Colour vision deficiency affects 1 in 12 men and 1 in 200 women. This is a significant group we cannot overlook.

Accessible emails are not just inclusive – they also reduce legal risk. The Web Content Accessibility Guidelines (WCAG), referenced in Australian law, set the minimum standard.

Common challenges in HTML email

Unlike websites, HTML emails rely on nested tables, simplified CSS and inconsistent client support. Without care, this can:

disrupt reading order
hide meaning shown only by colour
leave images inaccessible without alt text

Key practices recommended by Campaign Monitor and Vision Australia include:

logical reading order
semantic headings
sufficient contrast
meaningful link text

Accessibility by default

The NSW Email Design System embeds accessibility into email templates by default. Here are some essential techniques:

Use semantic structure

Use real headings (<h1> to <h3>) and lists. Use role="presentation" or role="none" on layout tables so screen readers ignore visual structure.

<table role="presentation" width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td>
      <h2>Feature highlight</h2>
      <p>Short intro text that explains the section.</p>
    </td>
  </tr>
</table>

Set language and wrapper roles

Define the page language and use role="article" with aria-roledescription="email".

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>NSW Monthly Update</title>
  </head>
  <body>
    <div role="article" aria-roledescription="email">
      <!-- email content -->
    </div>
  </body>
</html>

Support right-to-left (RTL) languages

Use dir="rtl" on containers where needed to ensure correct reading order and alignment.

<table role="presentation" width="100%" dir="rtl" cellpadding="0" cellspacing="0">
  <tr>
    <td align="right">
      <h2>مرحبا بك</h2>
      <p>هذا قسم باللغة العربية.</p>
    </td>
  </tr>
</table>

Apply accessible colour and contrast

Use colour combinations that meet WCAG AA contrast ratios: 4.5:1 for normal text and 3:1 for large text. Never rely on colour alone to convey meaning. Underline links for clarity.

<p>
  For details, see our
  <a href="https://digital.nsw.gov.au/features" style="color:#00558B; text-decoration:underline;">
    new features page
  </a>.
</p>

Provide meaningful alt text

Use descriptive alt text for informative images.
Use alt="" and role="presentation" for decorative images.

<!-- Informative image -->
<img src="https://example.com/team.jpg" width="640" height="360"
     alt="NSW project team presenting the new dashboard">

<!-- Decorative image -->
<img src="https://example.com/divider.png" width="640" height="24"
     alt="" role="presentation">

Create touch-friendly calls to action

Ensure buttons meet the minimum 24x24 CSS pixel target size (recommended: ~44x44px) and maintain AA contrast.

<a href="https://digital.nsw.gov.au/register"
   style="
     display:inline-block;
     padding:14px 28px;
     background:#00558B; /* ensure AA contrast with the text */
     color:#FFFFFF;
     font-size:16px;
     font-weight:700;
     line-height:1;
     text-decoration:none;
     border-radius:8px;
   ">
  Register now
</a>

Use responsive design helpers

Use classes like .mobile-12 and .mobile-center to stack content on smaller screens and preserve reading order.

<!-- Two columns that stack on mobile -->
<table role="presentation" width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td class="mobile-12" width="50%" style="padding:12px;">
      <h3>Update</h3>
      <p>Key news item goes here.</p>
    </td>
    <td class="mobile-12" width="50%" style="padding:12px;">
      <h3>Action</h3>
      <p><a href="https://example.gov.au" style="text-decoration:underline;">Start now</a></p>
    </td>
  </tr>
</table>

<!-- Center on mobile -->
<p class="mobile-center" style="margin:0;">
  <a href="https://example.gov.au/book" style="text-decoration:underline;">Book an appointment</a>
</p>

Add meta tags for client support

Disable auto-detection for phone numbers and enable dark mode support using meta tags.

<head>
  <meta charset="utf-8">
  <meta name="format-detection" content="telephone=no, date=no, address=no, email=no, url=no">
  <meta name="color-scheme" content="light dark">
  <meta name="supported-color-schemes" content="light dark">
  <title>Service NSW — Reminder</title>
</head>

Ensure motion safety

Avoid flashing animations. Use finite loops and descriptive alt text for animated GIFs.

<!-- Subtle, finite-loop GIF with descriptive alt.
     Avoid flashing more than 3 times per second. -->
<img src="https://example.com/celebrate.gif" width="600" height="200"
     alt="Celebrating the 2025 launch (subtle confetti animation)">
<p style="margin:8px 0 0 0; font-size:14px; color:#444;">
  Animation loops briefly, then stops.
</p>

Always include a plain-text version

Include a well-structured plain-text alternative to improve compatibility across clients and assistive technologies.

NSW Digital Newsletter
Key updates inside.
Register now: https://digital.nsw.gov.au/register
Unsubscribe: https://digital.nsw.gov.au/unsubscribe

Run accessibility audits

Automated audits

Use tools like Axe and Lighthouse CI to catch common WCAG 2.1 issues.

# Pre-build docs
npm run build

# Run Axe on static HTML in ./docs
npm run a11y:axe

# Run Lighthouse CI (lhci) against ./docs
npm run a11y:lighthouse

Steps:

From the project root, build the docs if they are not up to date:
Run npm run a11y:axe or npm run a11y:lighthouse
Checks for WCAG 2.1 A and AA issues.
Review the console output and accessibility score, and resolve any reported issues for each compiled email.

Note: Axe and Lighthouse primarily target WCAG 2.1 rules. Use them to catch broad issues, then manually confirm WCAG 2.2 specifics (e.g., target size and focus states) where email client constraints apply.

How to interpret accessibility audits for HTML emails

Automated accessibility tools like Axe and Lighthouse are built for websites. When used on HTML emails, they may flag issues that don't apply to the email environment.

One common example is the meta viewport warning. Most responsive HTML emails include this line in the <head> section:

<meta name="viewport" content="width=device-width, initial-scale=1">

This tag helps mobile devices scale the content correctly in some email clients, particularly Apple Mail. However, many email clients ignore or strip this tag altogether—so it's not essential for rendering and often not relied upon to fix layout issues.

Why some audit warnings are safe to ignore

Many email clients use their own rendering engines or modify HTML before displaying it. As a result:

Meta viewport warnings are safe to ignore, as the tag is widely unsupported or irrelevant in most email clients.
Other website-specific issues (such as missing <html> or <main> landmarks) may not apply, because email clients don't support full HTML5 semantics or browser-style accessibility APIs.

Always check email-specific support first

Before suppressing any audit warnings, verify whether the flagged issue affects email accessibility or is only relevant for websites.

These trusted resources can help you assess email client support and accessibility:

Can I Email. (n.d.). Email Client Support. (accessed on 1 September 2025)
HTML Email Check. (n.d.). HTML Email Check. (accessed on 1 September 2025)

Use these tools to decide whether an issue affects real users in real email clients–not just websites. This approach ensures that you don't overlook genuine accessibility barriers while avoiding irrelevant warnings.

Manual checks

Automated tools miss some issues. Also perform manual checks:

Navigate the templates using only the keyboard
Test with a screen reader (e.g., VoiceOver, NVDA)
View in high-contrast mode
Check semantic structure and colour contrast

Developer responsibilities

Even with accessible frameworks, developers must ensure:

Clear, descriptive headings and subject lines
Descriptive link text (not just 'click here')
Meaning is not conveyed by colour alone
Focus outlines are visible
Meaningful and appropriates alt text is used
Correct use of semantic tags
Proper lang and dir attributes
Touch targets are preserved
Layout works at 200% zoom

These choices require human judgement – but the right tools make them easier.

Build once. Reach everyone.

Accessible emails ensure government messages reach all Australians. Start with WCAG–aligned defaults and design with empathy.

WCAG-aligned quick reference

Perceivable

Make sure everyone can perceive your content:

Provide text alternatives for images and other non-text content.
Use strong colour contrast between text and background.
Ensure content is usable if images are turned off.
Support zooming and text reflow without loss of content or function.

Operable

Make content easy to navigate and use:

Ensure all content works with a keyboard (no mouse needed).
Use clear focus indicators and accessible link styles.
Use large, easy-to-tap targets for links and buttons.
Avoid flashing content that could trigger seizures.

Understandable

Help users understand and interact with content:

Use a consistent, predictable layout and navigation.
Write in plain language.
Provide clear labels, instructions and error messages.

Robust

Ensure compatibility with current and future technologies:

Use semantic HTML that communicates structure and meaning.
Test content with screen readers and other assistive technologies.
Offer a plain-text version where practical.

Sources

Can I Email. Email Client Support. (accessed on 1 September 2025)
A11y Collective. Creating accessible emails: step-by-step guide (n.d.). Coding accessible emails. (accessed on 1 September 2025).
World Wide Web Consortium (W3C) (2024). (n.d.). Web Content Accessibility Guidelines (WCAG) 2.2. (accessed on 17 June 2025).
Litmus. (n.d.). The Ultimate Guide to Accessible Emails. (accessed on 1 September 2025).
Email on Acid. (n.d.). Email Accessibility. (accessed on 1 September 2025).
HTML Email Check. (n.d.). HTML Email Knowledge Base. (accessed on 1 September 2025).
Swift Digital. (n.d.). 6 Tips for Accessible Email Content. (accessed on 1 September 2025).
UW–Madison. (n.d.). HTML Email Accessibility and Usability. (accessed on 1 September 2025).
MailerSend. (n.d.). Email Accessibility Best Practices. (accessed on 1 September 2025).

Accessibility for email developers

Every government email must be readable, understandable and actionable – for everyone. This includes people using screen readers, high-contrast modes or keyboard navigation.

Accessible emails are not just inclusive – they also reduce legal risk. The Web Content Accessibility Guidelines (WCAG), referenced in Australian law, set the minimum standard.

Common challenges in HTML email

Unlike websites, HTML emails rely on nested tables, simplified CSS and inconsistent client support. Without care, this can:

disrupt reading order
hide meaning shown only by colour
leave images inaccessible without alt text

Key practices recommended by Campaign Monitor and Vision Australia include:

logical reading order
semantic headings
sufficient contrast
meaningful link text

Accessibility by default

The NSW Email Design System embeds accessibility into email templates by default. Here are some essential techniques:

Use semantic structure

Use real headings (<h1> to <h3>) and lists. Use role="presentation" or role="none" on layout tables so screen readers ignore visual structure.

<table role="presentation" width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td>
      <h2>Feature highlight</h2>
      <p>Short intro text that explains the section.</p>
    </td>
  </tr>
</table>

Set language and wrapper roles

Define the page language and use role="article" with aria-roledescription="email".

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>NSW Monthly Update</title>
  </head>
  <body>
    <div role="article" aria-roledescription="email">
      <!-- email content -->
    </div>
  </body>
</html>

Support right-to-left (RTL) languages

Use dir="rtl" on containers where needed to ensure correct reading order and alignment.

<table role="presentation" width="100%" dir="rtl" cellpadding="0" cellspacing="0">
  <tr>
    <td align="right">
      <h2>مرحبا بك</h2>
      <p>هذا قسم باللغة العربية.</p>
    </td>
  </tr>
</table>

Apply accessible colour and contrast

Use colour combinations that meet WCAG AA contrast ratios: 4.5:1 for normal text and 3:1 for large text. Never rely on colour alone to convey meaning. Underline links for clarity.

<p>
  For details, see our
  <a href="https://digital.nsw.gov.au/features" style="color:#00558B; text-decoration:underline;">
    new features page
  </a>.
</p>

Provide meaningful alt text

Use descriptive alt text for informative images.
Use alt="" and role="presentation" for decorative images.

<!-- Informative image -->
<img src="https://example.com/team.jpg" width="640" height="360"
     alt="NSW project team presenting the new dashboard">

<!-- Decorative image -->
<img src="https://example.com/divider.png" width="640" height="24"
     alt="" role="presentation">

Create touch-friendly calls to action

Ensure buttons meet the minimum 24x24 CSS pixel target size (recommended: ~44x44px) and maintain AA contrast.

<a href="https://digital.nsw.gov.au/register"
   style="
     display:inline-block;
     padding:14px 28px;
     background:#00558B; /* ensure AA contrast with the text */
     color:#FFFFFF;
     font-size:16px;
     font-weight:700;
     line-height:1;
     text-decoration:none;
     border-radius:8px;
   ">
  Register now
</a>

Use responsive design helpers

Use classes like .mobile-12 and .mobile-center to stack content on smaller screens and preserve reading order.

<!-- Two columns that stack on mobile -->
<table role="presentation" width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td class="mobile-12" width="50%" style="padding:12px;">
      <h3>Update</h3>
      <p>Key news item goes here.</p>
    </td>
    <td class="mobile-12" width="50%" style="padding:12px;">
      <h3>Action</h3>
      <p><a href="https://example.gov.au" style="text-decoration:underline;">Start now</a></p>
    </td>
  </tr>
</table>

<!-- Center on mobile -->
<p class="mobile-center" style="margin:0;">
  <a href="https://example.gov.au/book" style="text-decoration:underline;">Book an appointment</a>
</p>

Add meta tags for client support

Disable auto-detection for phone numbers and enable dark mode support using meta tags.

<head>
  <meta charset="utf-8">
  <meta name="format-detection" content="telephone=no, date=no, address=no, email=no, url=no">
  <meta name="color-scheme" content="light dark">
  <meta name="supported-color-schemes" content="light dark">
  <title>Service NSW — Reminder</title>
</head>

Ensure motion safety

Avoid flashing animations. Use finite loops and descriptive alt text for animated GIFs.

<!-- Subtle, finite-loop GIF with descriptive alt.
     Avoid flashing more than 3 times per second. -->
<img src="https://example.com/celebrate.gif" width="600" height="200"
     alt="Celebrating the 2025 launch (subtle confetti animation)">
<p style="margin:8px 0 0 0; font-size:14px; color:#444;">
  Animation loops briefly, then stops.
</p>

Always include a plain-text version

Include a well-structured plain-text alternative to improve compatibility across clients and assistive technologies.

NSW Digital Newsletter
Key updates inside.
Register now: https://digital.nsw.gov.au/register
Unsubscribe: https://digital.nsw.gov.au/unsubscribe

Run accessibility audits

Automated audits

Use tools like Axe and Lighthouse CI to catch common WCAG 2.1 issues.

# Pre-build docs
npm run build

# Run Axe on static HTML in ./docs
npm run a11y:axe

# Run Lighthouse CI (lhci) against ./docs
npm run a11y:lighthouse

Steps:

From the project root, build the docs if they are not up to date:
Run npm run a11y:axe or npm run a11y:lighthouse
Checks for WCAG 2.1 A and AA issues.
Review the console output and accessibility score, and resolve any reported issues for each compiled email.

How to interpret accessibility audits for HTML emails

Automated accessibility tools like Axe and Lighthouse are built for websites. When used on HTML emails, they may flag issues that don't apply to the email environment.

One common example is the meta viewport warning. Most responsive HTML emails include this line in the <head> section:

<meta name="viewport" content="width=device-width, initial-scale=1">

Why some audit warnings are safe to ignore

Many email clients use their own rendering engines or modify HTML before displaying it. As a result:

Meta viewport warnings are safe to ignore, as the tag is widely unsupported or irrelevant in most email clients.
Other website-specific issues (such as missing <html> or <main> landmarks) may not apply, because email clients don't support full HTML5 semantics or browser-style accessibility APIs.

Always check email-specific support first

Before suppressing any audit warnings, verify whether the flagged issue affects email accessibility or is only relevant for websites.

These trusted resources can help you assess email client support and accessibility:

Can I Email. (n.d.). Email Client Support. (accessed on 1 September 2025)
HTML Email Check. (n.d.). HTML Email Check. (accessed on 1 September 2025)

Manual checks

Automated tools miss some issues. Also perform manual checks:

Navigate the templates using only the keyboard
Test with a screen reader (e.g., VoiceOver, NVDA)
View in high-contrast mode
Check semantic structure and colour contrast

Developer responsibilities

Even with accessible frameworks, developers must ensure:

Clear, descriptive headings and subject lines
Descriptive link text (not just 'click here')
Meaning is not conveyed by colour alone
Focus outlines are visible
Meaningful and appropriates alt text is used
Correct use of semantic tags
Proper lang and dir attributes
Touch targets are preserved
Layout works at 200% zoom

These choices require human judgement – but the right tools make them easier.

Build once. Reach everyone.

Accessible emails ensure government messages reach all Australians. Start with WCAG–aligned defaults and design with empathy.

WCAG-aligned quick reference

Perceivable

Make sure everyone can perceive your content:

Provide text alternatives for images and other non-text content.
Use strong colour contrast between text and background.
Ensure content is usable if images are turned off.
Support zooming and text reflow without loss of content or function.

Operable

Make content easy to navigate and use:

Ensure all content works with a keyboard (no mouse needed).
Use clear focus indicators and accessible link styles.
Use large, easy-to-tap targets for links and buttons.
Avoid flashing content that could trigger seizures.

Understandable

Help users understand and interact with content:

Use a consistent, predictable layout and navigation.
Write in plain language.
Provide clear labels, instructions and error messages.

Robust

Ensure compatibility with current and future technologies:

Use semantic HTML that communicates structure and meaning.
Test content with screen readers and other assistive technologies.
Offer a plain-text version where practical.

Sources

Can I Email. Email Client Support. (accessed on 1 September 2025)
A11y Collective. Creating accessible emails: step-by-step guide (n.d.). Coding accessible emails. (accessed on 1 September 2025).
World Wide Web Consortium (W3C) (2024). (n.d.). Web Content Accessibility Guidelines (WCAG) 2.2. (accessed on 17 June 2025).
Litmus. (n.d.). The Ultimate Guide to Accessible Emails. (accessed on 1 September 2025).
Email on Acid. (n.d.). Email Accessibility. (accessed on 1 September 2025).
HTML Email Check. (n.d.). HTML Email Knowledge Base. (accessed on 1 September 2025).
Swift Digital. (n.d.). 6 Tips for Accessible Email Content. (accessed on 1 September 2025).
UW–Madison. (n.d.). HTML Email Accessibility and Usability. (accessed on 1 September 2025).
MailerSend. (n.d.). Email Accessibility Best Practices. (accessed on 1 September 2025).

Command Palette

Command Palette

Accessibility for email developers

Common challenges in HTML email

Accessibility by default

Use semantic structure

Set language and wrapper roles

Support right-to-left (RTL) languages

Apply accessible colour and contrast

Provide meaningful alt text

Create touch-friendly calls to action

Use responsive design helpers

Add meta tags for client support

Ensure motion safety

Always include a plain-text version

Run accessibility audits

Automated audits

Steps:

How to interpret accessibility audits for HTML emails

Why some audit warnings are safe to ignore

Always check email-specific support first

Manual checks

Developer responsibilities

Build once. Reach everyone.

WCAG-aligned quick reference

Perceivable

Operable

Understandable

Robust

Sources

Accessibility for email developers

Common challenges in HTML email

Accessibility by default

Use semantic structure

Set language and wrapper roles

Support right-to-left (RTL) languages

Apply accessible colour and contrast

Provide meaningful alt text

Create touch-friendly calls to action

Use responsive design helpers

Add meta tags for client support

Ensure motion safety

Always include a plain-text version

Run accessibility audits

Automated audits

Steps:

How to interpret accessibility audits for HTML emails

Why some audit warnings are safe to ignore

Always check email-specific support first

Manual checks

Developer responsibilities

Build once. Reach everyone.

WCAG-aligned quick reference

Perceivable

Operable

Understandable

Robust

Sources