When publishing an EPUB, validating its accessibility is a critical step to ensure compliance with the European Accessibility Act (EAA) and WCAG 2.2. The publishing industry standard tool for this is Ace by DAISY.
Ace is a fantastic open-source tool, but interpreting its HTML error reports can be incredibly daunting for production teams. Here is a plain-English guide to understanding your Ace report and fixing the most common violations.
Understanding the Ace Report Structure
When you run an EPUB through Ace, it generates a report highlighting Violations. These violations are mapped against specific WCAG success criteria and EPUB Accessibility guidelines.
Violations are categorized by severity:
- Serious / Critical: These must be fixed immediately. They represent blockers for assistive technology.
- Moderate / Minor: These are often technical best-practice failures that should be resolved to achieve full certification.
Common Ace Errors and How to Fix Them
1. Error: epub-type-has-matching-role
What it means: You used an epub:type attribute (like epub:type="chapter") to define semantics, but you didn't provide a matching ARIA role attribute. Older screen readers rely on ARIA roles, while EPUB-specific systems use epub:type.
How to fix it: Always pair them up. If your HTML has <section epub:type="chapter">, change it to <section epub:type="chapter" role="doc-chapter">.
2. Error: image-missing-alt / alt-text-is-empty
What it means: An image (<img> tag) is missing the alt attribute, or it has an empty alt attribute but isn't properly marked as decorative.
How to fix it:
- If the image contains information, add a descriptive alt tag:
alt="Chart showing..." - If it is purely decorative, use
alt=""along withrole="presentation"so the screen reader ignores it.
3. Error: heading-order-invalid
What it means: Your HTML headings skip levels. For example, jumping from an <h1> directly to an <h3> without an <h2> in between. Screen readers rely on heading levels to build an outline of the document.
How to fix it: Search your document for heading tags and ensure they nest logically: H1, then H2, then H3. Never use heading tags just to make text bold or larger—use CSS for styling instead.
4. Error: color-contrast-inadequate
What it means: The text color and the background color do not have enough contrast, failing WCAG (requires at least a 4.5:1 ratio for normal text).
How to fix it: Use a contrast checker to adjust your CSS hex codes. Darken the text or lighten the background until it passes.
5. Error: html-has-lang / valid-lang
What it means: The document does not declare what language it is written in. Screen readers need this to know which pronunciation library to load (e.g., loading a French voice vs. an English voice).
How to fix it: Ensure every XHTML file has a language declaration in its root tag: <html lang="en" xml:lang="en">.
Manual Testing is Still Required
Ace by DAISY is powerful, but it is an automated tool. It can only catch about 30–40% of WCAG violations. For example, Ace can tell you if an image has alt text, but it cannot tell you if that alt text is actually accurate. Full compliance requires human review alongside the automated report.
---
If your Ace by DAISY reports are flooded with hundreds of errors and your team lacks the technical bandwidth to fix the underlying code, schedule a free consultation with Holograph Press Works today. Let’s make your content accessible, compliant, and ready for the future.
Holograph Press Works remediates EPUB and PDF files to WCAG 2.2 AA and EPUB Accessibility 1.1 standards using our HoloRemedi platform. Every project includes official Ace and PAC3 PDF compliance reports. Request a consultation →