How to Fix EPUB Accessibility Issues (Step-by-Step)

You've scanned your EPUB and found accessibility issues. Now what? This guide walks through the most common violations and how to fix each one, whether you prefer automated tools or manual editing.

Before You Start

Make a backup copy of your EPUB. Always keep the original file untouched while you work on fixes. EPUB files are ZIP archives, if something goes wrong during editing, you want to be able to start over.

You'll also want the scan report from your accessibility checker (DAISY Ace or a tool like Rahatt) open alongside your editor so you can work through issues systematically. If you're not sure what these violations mean, start with our EPUB Accessibility 101 overview.

Fix 1: Missing Accessibility Metadata

What the violation means: Your EPUB's content.opf file doesn't declare its accessibility features. Without these declarations, retailers and assistive technology can't determine what the book supports.

How to fix it manually:

Open your EPUB (rename .epub to .zip and extract), find content.opf, and add the following inside the <metadata> section:

<meta property="schema:accessibilitySummary">
  This publication has been evaluated for accessibility.
</meta>
<meta property="schema:accessibilityHazard">none</meta>
<meta property="schema:accessibilityFeature">structuralNavigation</meta>
<meta property="schema:accessibilityFeature">alternativeText</meta>
<meta property="schema:accessMode">textual</meta>
<meta property="schema:accessMode">visual</meta>

Adjust these values based on your book's actual content. If you have images without alt text, don't claim alternativeText until you've added it.

The automated approach: Tools like Rahatt inject this metadata automatically when you use the fix feature. The metadata is tailored to your book's actual content.

Fix 2: Broken Heading Hierarchy

What the violation means: Your XHTML files use headings in a non-sequential order, for example, jumping from <h2> to <h4> without an <h3> in between. This confuses screen readers that use heading levels for navigation.

How to fix it manually:

Search your XHTML files for all heading tags. Map out the current hierarchy:

h1 - Book Title
  h2 - Chapter 1
    h4 - Section 1.1  ← Should be h3
  h2 - Chapter 2

Change the incorrect heading levels so they step down by one at a time:

h1 - Book Title
  h2 - Chapter 1
    h3 - Section 1.1  ← Fixed
  h2 - Chapter 2

The rule is simple: you can skip levels going up (h3 back to h1 is fine), but never going down (h2 to h4 is invalid).

The automated approach: The Rahatt enhanced patcher scans all XHTML files in your EPUB and corrects heading jumps automatically. It tracks the heading stack and downgrades any heading that skips a level.

Fix 3: Missing Image Alt Text

What the violation means: Your EPUB contains <img> tags without alt attributes, or with empty alt text on images that convey meaningful content.

How to fix it manually:

Find every <img> tag in your XHTML files and add an alt attribute:

<!-- Before -->
<img src="images/chart.png" />

<!-- After -->
<img src="images/chart.png" alt="Sales growth chart showing 40% increase from Q1 to Q4 2025" />

Good alt text should:

• Be concise, aim for under 125 characters
• Describe the content, not the file ("Sales chart" not "chart.png")
• Use active voice and be objective
• Include any visible text in the image
• Skip prefixes like "Image of" or "Picture of"

For detailed guidance on handling different image types, see our complete alt text guide.

For decorative images (borders, ornaments, spacers), use empty alt text:

<img src="images/divider.png" alt="" />

This tells screen readers to skip the image entirely.

The automated approach: Rahatt's AI-powered alt text feature uses a vision model to analyze each image in context, it reads the surrounding text, captions, and figure labels to generate relevant descriptions. You review and edit each suggestion before applying.

Fix 4: Insufficient Link Contrast

What the violation means: Links in your EPUB don't have enough visual contrast against surrounding text. WCAG requires a 4.5:1 contrast ratio between link color and background color.

How to fix it manually:

Find your CSS stylesheet(s) in the EPUB and update the link styles:

/* Before - common problem (light blue on white) */
a { color: #6699cc; }

/* After - WCAG AA compliant */
a {
  color: #0066cc;
  text-decoration: underline;
}

The text-decoration: underline is important, it provides a non-color visual indicator, which is required for links that rely solely on color to be distinguishable.

The automated approach: The Rahatt patcher appends WCAG-compliant link styles to your existing CSS files, using #0066cc which provides a 4.5:1+ contrast ratio.

Fix 5: Missing Language Declaration

What the violation means: Your XHTML files don't specify the document language, which screen readers need to select the correct pronunciation rules.

How to fix it manually:

Add the lang and xml:lang attributes to your XHTML root elements:

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops"
      lang="en"
      xml:lang="en">

Change en to the appropriate BCP 47 language code for your book's primary language.

Rebuilding Your EPUB

If you made manual edits, you need to repackage the EPUB:

1. Make sure the mimetype file is the first entry in the ZIP and is stored uncompressed
2. ZIP the remaining files (META-INF, OEBPS/content, etc.)
3. Rename the .zip back to .epub

The mimetype requirement is critical. Most ZIP tools compress by default, which will produce an invalid EPUB. Use this command:

zip -X0 book.epub mimetype
zip -rX9 book.epub META-INF OEBPS

Verifying Your Fixes

After applying fixes, scan the EPUB again. Your risk score should drop significantly. A well-fixed EPUB typically goes from a Medium or High risk score down to Low (0-19).

If issues remain, work through them one at a time. The most impactful fixes, in order:

1. Accessibility metadata (biggest single improvement)
2. Heading hierarchy
3. Alt text for images
4. Link contrast
5. Language declarations

Re-uploading to Amazon

Once your scan shows a clean result:

1. Log into your KDP dashboard
2. Navigate to the affected book
3. Upload the fixed EPUB as a new version
4. Amazon will re-review the file (usually 48-72 hours)

Don't change your title, description, or pricing, just replace the file. This preserves your existing reviews and sales history while clearing the quality flag. If you're unsure whether your book has been flagged, read our guide on how to check if Amazon is suppressing your book.