mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-20 16:16:25 +03:00
Magnus Hedemark
88e92f4472
Complete EPUB creation, editing, validation, and knowledge extraction skill for the Agent Skills open format. Built from spec research, real EPUB testing on 2.1MB commercial Apress title, and Apple Books compatibility verification on macOS 26. Scripts (11): epub-scaffold — Create valid EPUB3 with cover XHTML, Apple Books CSS epub-edit — Surgical editing (8 subcommands, epublib) epub-info — Structure/metadata dump as JSON epub-text — Clean text extraction, per-chapter or single-file epub-extract-knowledge — Heuristic + LLM extraction (env var auto-detect) epub-validate — EPUBCheck or Python fallback validation epub-images — List/extract all images with cover detection epub-batch — Multi-file processing (extract-text, validate, metadata) epub-convert — EPUB2→EPUB3 conversion with validation epub-repair — Diagnose & auto-fix common structural issues epub-cover — Add cover XHTML wrapper for Apple Books compatibility References (9): epub-format-internals.md, python-libraries.md, spec-and-validation.md, tutorials-and-guides.md, agent-capability-discovery.md, fixed-layout-epub.md, accessibility.md, media-overlays.md, apple-books-compatibility.md (NEW — verified on macOS 26) Test: 46/46 passing (test_epub_skill.sh)
128 lines
3.8 KiB
Markdown
128 lines
3.8 KiB
Markdown
# EPUB Accessibility
|
|
|
|
Accessible EPUBs can be read by people using screen readers, braille displays,
|
|
and other assistive technologies. The W3C EPUB Accessibility 1.1 specification
|
|
defines conformance requirements.
|
|
|
|
## Key Requirements
|
|
|
|
### 1. Alternative Text for Images
|
|
|
|
Every `<img>` element must have an `alt` attribute:
|
|
|
|
```xhtml
|
|
<img src="diagram.png" alt="Flowchart showing data pipeline stages"/>
|
|
```
|
|
|
|
Decorative images should use `alt=""` so screen readers skip them.
|
|
|
|
### 2. Heading Hierarchy
|
|
|
|
Headings must follow a logical nesting order — no skipping levels:
|
|
|
|
```xhtml
|
|
<h1>Chapter Title</h1>
|
|
<h2>Section</h2>
|
|
<h3>Subsection</h3>
|
|
<h2>Another Section</h2>
|
|
```
|
|
|
|
Do not use `<h4>` without a preceding `<h3>`.
|
|
|
|
### 3. Language Tagging
|
|
|
|
Every XHTML document must declare its language:
|
|
|
|
```xhtml
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
```
|
|
|
|
For language shifts within a document:
|
|
|
|
```xhtml
|
|
<p>English text <span xml:lang="fr" lang="fr">texte français</span> more English.</p>
|
|
```
|
|
|
|
### 4. ARIA Roles
|
|
|
|
ARIA landmarks help screen reader navigation:
|
|
|
|
```xhtml
|
|
<nav epub:type="toc" role="doc-toc">...</nav>
|
|
<section role="doc-chapter">...</section>
|
|
<aside role="doc-footnote">...</aside>
|
|
```
|
|
|
|
Key roles: `doc-toc`, `doc-chapter`, `doc-cover`, `doc-footnote`, `doc-glossary`,
|
|
`doc-index`, `doc-bibliography`, `doc-acknowledgments`.
|
|
|
|
### 5. Accessibility Metadata
|
|
|
|
The OPF must declare accessibility conformance:
|
|
|
|
```xml
|
|
<meta property="schema:accessMode">textual</meta>
|
|
<meta property="schema:accessMode">visual</meta>
|
|
<meta property="schema:accessibilityFeature">alternativeText</meta>
|
|
<meta property="schema:accessibilityFeature">longDescription</meta>
|
|
<meta property="schema:accessibilityHazard">none</meta>
|
|
<meta property="schema:accessibilitySummary">
|
|
This publication meets WCAG 2.0 Level AA.
|
|
</meta>
|
|
```
|
|
|
|
## Ace by DAISY
|
|
|
|
[Ace](https://daisy.org/activities/software/ace/) is the official accessibility
|
|
validator for EPUB. It checks:
|
|
|
|
- Image alt text presence and quality
|
|
- Heading hierarchy correctness
|
|
- Language declarations
|
|
- ARIA roles and landmarks
|
|
- Accessibility metadata completeness
|
|
- Color contrast (basic)
|
|
|
|
```bash
|
|
# Install: npm install -g @daisy/ace
|
|
ace book.epub --outdir ace-report/
|
|
```
|
|
|
|
The report is an HTML dashboard showing violations by type and severity.
|
|
|
|
## WCAG Alignment
|
|
|
|
EPUB Accessibility 1.1 maps to WCAG 2.x Level AA. The four principles:
|
|
|
|
| Principle | EPUB Meaning |
|
|
|-----------|-------------|
|
|
| **Perceivable** | All content has text alternatives, captions, sufficient contrast |
|
|
| **Operable** | All navigation is keyboard-accessible, no seizure-inducing content |
|
|
| **Understandable** | Language is declared, reading order is logical, predictable |
|
|
| **Robust** | Content is well-formed XHTML, compatible with assistive technologies |
|
|
|
|
## Common Failures
|
|
|
|
| Failure | Detection | Fix |
|
|
|---------|----------|-----|
|
|
| Missing alt text | Ace / manual inspection | Add `alt` to every `<img>` |
|
|
| Skipped heading levels | Ace | Re-level headings |
|
|
| Language not declared | `xml:lang` + `lang` missing on `<html>` | Add both attributes |
|
|
| No accessibility metadata | OPF missing `schema:accessibilityFeature` | Add required meta tags |
|
|
| Color-only information | Content relies on color for meaning | Add text labels or patterns |
|
|
|
|
## Script Support
|
|
|
|
Our EPUB scripts do NOT perform accessibility validation. Use Ace for that.
|
|
However, `epub-validate` checks for structural issues (XHTML well-formedness,
|
|
metadata completeness) that are prerequisites for accessibility.
|
|
|
|
`epub-edit` can help remediate some issues: adding metadata fields, injecting
|
|
CSS for contrast, or adding `alt` attributes via DOM manipulation.
|
|
|
|
## References
|
|
|
|
- W3C EPUB Accessibility 1.1: https://www.w3.org/TR/epub-a11y-11/
|
|
- W3C EPUB Accessibility Techniques 1.1: https://www.w3.org/TR/epub-a11y-tech-11/
|
|
- Ace by DAISY: https://daisy.org/activities/software/ace/
|