a11y-video

Two agent skills for Claude Code and Codex that turn a web page into short, narrated, captioned videos. a11y-demo films a first-pass accessibility test with the real VoiceOver in Safari: each barrier is named with its WCAG criterion, fixed in the code, and heard again on camera, then written up as a plain-language report. demo-video makes a narrated walkthrough of a real flow in any web app, for customer feedback.

See the examples Use it in a project Source on GitHub

See it first

The examples are finished reports made with a11y-demo, each with its videos, captions and transcripts:

Three WCAG criteria, heard with VoiceOver: a chart with no text alternative, links that all say “Read more”, and switches a screen reader can't find, on small example pages. The quickest to watch, about six minutes.
Testing a home page with VoiceOver: a real site, step by step, through the structure, the keyboard, a reading pass, the controls and a task.
The same test, told by two voices: a tester who uses VoiceOver and a reviewer who names each criterion and the fix.

What each skill does

a11y-demo: a filmed screen-reader test

Ask your agent to “film a VoiceOver test of your page”. It scripts the scenes, voices the narration before filming so VoiceOver and the narrator never talk over each other, drives the real VoiceOver in Safari (through Guidepup) while recording the screen and VoiceOver's own audio, and cuts each step into a video with captions for every voice. When a take shows a barrier, it names the WCAG criterion, fixes the code, checks the fix by ear and films the re-test. It ends with a report: the brief, the videos, and what still needs testing with people with disabilities. macOS only.

demo-video: a narrated product walkthrough

Ask for “a demo video of a flow”. A gated recipe: intake, a capability check, the script, isolated demo data, human-paced screen capture, a storyboard pick, a local Kokoro voice, the edit, a second-by-second film review and the final renders. Works with any web app you can run locally.

Use it in a project

Copy the skills, agents and tools into the root of the project you want to film. From a clone of this repository, this copies the committed files only:
```
git archive HEAD .claude .agents .codex agents tools | tar -x -C /path/to/your-project
```
It overwrites files of the same name, so merge by hand if the project already has .claude/, .codex/ or agents/ folders.
Install the tools, in the project:
```
cd tools/demo-video && npm install && npx playwright install chromium
```
For a11y-demo, also:
```
cd tools/a11y-demo && npm install
```
then the one-time Mac setup in .claude/skills/a11y-demo/references/setup.md: VoiceOver automation, Safari's settings, and BlackHole to record VoiceOver's audio.
Check what else is missing:
```
tools/demo-video/doctor.sh
```
(doctor.ps1 on Windows.) It lists anything else to install, such as ffmpeg and the Kokoro voice.
Ask the agent, for example “film a VoiceOver test of http://localhost:3000/”, or “make a demo video of the sign-up flow”. The intake asks the rest: which pages and builds, who will watch, how the app runs.

Start from an example: each example's folder holds the files that made it (the scenes the runner plays, the narrator's lines, and the films that cut the videos). Copy one into a work folder and rewrite it for your page.

What's in the repository

Path	What it is
`.claude/skills/a11y-demo/`	The accessibility-test skill (`SKILL.md`) and its references
`tools/a11y-demo/`	The VoiceOver scene runner, the compose step, the report builder, the examples list and a static server for before-and-after builds
`.claude/skills/demo-video/`	The walkthrough skill, its references and templates
`tools/demo-video/`	Recorder, voice, builder, cut and QA scripts
`.claude/agents/`, `.codex/agents/`, `agents/workflow/`	The storyboarder, film-reviewer and reference-breaker agents, and the instructions they follow
`examples/`	Finished a11y-demo reports, one per folder, with their videos and the files that made them

Add an example

Build the report into a folder under examples/, with its videos, captions and transcripts beside it, then list it:

node tools/a11y-demo/report.mjs examples/my-test/report.json examples/my-test/index.html
node tools/a11y-demo/examples-index.mjs

report.mjs writes the page and the folder's README.md, with a still for each video. examples-index.mjs rebuilds the examples list from every report.json.