-
-
Measured with 21 checks: 2 of 20 before the exorcism, 21 of 21 after. axe-core finds 0 either way.
-
Same task, keyboard only. Plain Kiro build: stuck in the dialog. Built from Skeleton Key: Escape closes it.
-
The exorcism: Kiro audits the running app with our a11y MCP tools, fixes 15 problems and re-checks.
Inspiration
95.9% of the top million home pages fail WCAG (WebAIM Million 2026), and more than 1 in 4 US adults has a disability (CDC). AI now writes a growing share of the web, and it repeats the same mistakes at scale.
I'm a DHS Section 508 Trusted Tester. The failures I find most are not the ones scanners catch. They're behaviour: focus lost after a step change, errors nobody announces, dialogs you can't escape. So I asked: what if the AI that writes the code already knew the rules, and could test the running app itself?
What it does
Skeleton Key is a lean React + TypeScript starter that is accessible by default, plus an accessibility "brain" for Kiro:
- Accessible primitives: page shell with a skip link and landmarks, focus moved to the heading on every route change, one shared screen-reader announcer, and Button, Link, Field, Dialog, Toast and Tabs components that follow the ARIA Authoring Practices.
- Contrast-checked design tokens for light and dark themes, and a reduced-motion toggle.
- Steering that encodes WCAG 2.2 AA as rules Kiro follows on every task.
- A Trusted Tester agent (read-only) that reviews code with the Section 508 method and reports criterion, severity, location and fix.
- Hooks that review components against the rules whenever they're edited or created.
a11y-mcp, our own MCP server withaudit_page,keyboard_walk,page_outlineandcheck_contrast, so Kiro can test the running app. Published on npm asskeleton-key-a11y-mcp.- Property-based accessibility tests with fast-check, and an auto-generated Accessibility Conformance Report (VPAT 2.5 style) for each app.
Two very different apps are built on the same skeleton: Grimoire, a searchable spellbook catalogue, and Seance, a three-step booking form.
The proof. Kiro, given the same plain prompt with no Skeleton Key, built a séance booking app that passes axe-core with 0 violations. Seance also has 0. On 21 scripted checks for screen reader, keyboard, vision, wording and motion users, the plain build passes 2 of 20 and Seance passes 21 of 21.
The exorcism. Pointed at that plain app with one reusable prompt (scripts/exorcise.txt), Kiro audited the running page with our MCP tools, fixed 15 problems without changing the design, re-ran the tools, and wrote EXORCISM.md, including what it could not verify. After: 21 of 21, still 0 axe violations.
How I built it
Spec-first, entirely with Kiro. I wrote the steering docs (product, accessibility, tech, structure). Kiro turned each brief into a spec: requirements in EARS notation citing the WCAG success criterion each one satisfies, a design doc, and a task plan. There are eight specs: skeleton, a11y-brain, a11y-mcp, a11y-pbt, acr-report, new-app-script, grimoire and seance. Kiro then implemented the tasks.
I drove Kiro through the Kiro CLI in non-interactive mode, one batch of tasks at a time, with Claude Code orchestrating the runs. After each batch, Claude Code independently re-ran lint, types, tests and contrast checks, and fed any problems back to Kiro as review fixes, so Kiro made every code change. When Claude Code's scripted checks found a real bug in Seance (a pointer click on Next lost to a layout shift), it wrote a bug report and Kiro fixed it with regression tests.
Challenges
- Scanners can't see behaviour. Both séance apps score 0 on axe, so we built 21 behaviour checks (focus, announcements, contrast over gradients, colour-only cues, motion) to measure what matters.
- Tests can lie about accessibility. jsdom doesn't implement
inertor real focus, so a Dialog can pass unit tests and still be broken. We added real-browser Playwright tests for focus trap, inert background and focus return. - "Accessible" components can still hurt users. Kiro first gave inline errors
role="alert", which passes scanners but makes a screen reader read every error at once. Announcements moved to the error summary only. - Dark-mode contrast. The accent purple passed for UI (3.62:1) but failed for text, so we split a dedicated link token (7.43:1).
Accomplishments
- Over 1,000 automated tests: skeleton 180, Grimoire 319, Seance 424 unit + 47 end-to-end, a11y-mcp 113. Zero axe violations across the apps.
- An MCP server other Kiro users can install with one line of config.
- An exorcism that's measured, not claimed: 2 of 20 → 21 of 21.
What I learned
Steering is where expertise compounds. Once the WCAG rules lived in steering, Kiro stopped making the mistakes instead of me catching them. And giving the agent tools to test the running app (MCP) turned "it should be accessible" into "it checked".
What's next
npm create skeleton-key, Vue and Svelte variants, and the Trusted Tester agent packaged so any Kiro project can install it.
Links
- Demo video: https://youtu.be/YHQ4HcWfiLI
- Live demo: https://hassank007.github.io/skeleton-key/
- MCP server on npm: https://www.npmjs.com/package/skeleton-key-a11y-mcp
- Measurements:
docs/baseline-comparison.mdin the repo
Built With
- axe-core
- fast-check
- kiro
- mcp
- node.js
- playwright
- react
- typescript
- vite
- vitest