OpenParable
Skip to content
← Back to skills

A11y

Design
a11y

A11y is an Agent Skill for design published in the Houseofmvps/ultraship repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Accessibility audit + auto-fix (WCAG 2.2 A/AA). Scans built/static HTML for screen-reader, keyboard, and structure failures, fixes the deterministic ones, and escalates to a rendered scan for contrast and focus. Use when the user wants to check or improve accessibility, fix WCAG issues, or pass an a11y review.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Houseofmvps/ultraship/blob/HEAD/skills/a11y/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/a11y, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Accessibility Audit + Auto-Fix (WCAG 2.2)

AI builders ship accessibility violations by default — missing alt text, unlabeled inputs, icon-only buttons, no lang, broken heading order. These are legally consequential (ADA, EU Accessibility Act) and most are deterministically detectable and fixable. This skill finds them AND fixes them.

Process

Phase 1: Scan

Run the static scanner on the project (point it at built/exported HTML, e.g. dist/, build/, out/, .next/, or public/):

node ${CLAUDE_PLUGIN_ROOT}/tools/a11y-scanner.mjs <project-directory>

Parse the JSON: findings[] ({ file, severity, category, rule, message }), summary (counts by severity), and scores.a11y (0–100, or null when no HTML found).

Many pages, each needing fixes? Escalate to a dynamic Workflow (describe the audit and include the word "workflow") so scan → fix → verify runs across pages in parallel instead of one at a time.

Phase 2: Report

Present findings grouped by rule, highest severity first. Map each to its WCAG criterion (already in the message). Make clear which are auto-fixable now vs which need a rendered scan (Phase 4).

Phase 3: Fix (use the Edit tool on the source files)

Apply the deterministic fix for each finding. Do not invent content — for alt text and labels, derive from nearby context (filename, heading, surrounding copy, name/placeholder); if genuinely ambiguous, ask the user rather than guessing.

RuleFix
html-missing-lang / html-empty-langAdd lang="en" (or the document's real language) to <html>
img-missing-altAdd alt="<concise description>" from context; use alt="" only if the image is purely decorative
input-image-missing-altAdd alt="<what the button does>"
control-missing-labelAdd a <label for="id">, or aria-label/aria-labelledby. A placeholder is NOT a label — keep it but add a real label
button-no-textAdd visible text, or aria-label="<action>" for icon-only buttons
link-no-textAdd link text, or aria-label; if it wraps an icon, give the icon alt/aria-label
link-generic-textRewrite "click here"/"read more" to state the destination ("Read the pricing guide")
positive-tabindexChange to tabindex="0" (or remove) and fix order via DOM order
viewport-zoom-disabledRemove user-scalable=no / maximum-scale=1 from the viewport meta
duplicate-idMake each id unique (and update its label/aria references)
broken-aria-referencePoint aria-labelledby/aria-describedby/for at a real element id, or add the missing element
empty-headingRemove the empty heading or give it text
heading-skipInsert the missing level or demote the heading so levels don't jump
missing-titleAdd a descriptive <title> in <head>
missing-main-landmarkWrap the primary content in <main>

Phase 4: Escalate to a rendered scan (contrast, focus, reading order)

The static scanner cannot see computed styles or focus behavior. When a URL or running dev server is available, run a rendered audit — these tools need no install (npx fetches them) and cover color contrast (WCAG 1.4.3), focus visibility, and ARIA state:

# Pa11y (axe + htmlcs runners). Use --runner axe for axe-core rules.
npx --yes pa11y --standard WCAG2AA <url>

# or the axe CLI directly
npx --yes @axe-core/cli <url>

If the project uses Playwright (Ultraship bundles the Playwright MCP), prefer injecting axe-core into the live page for per-component results. Report contrast and focus findings the static pass could not catch.

Phase 5: Verify

Re-run the scanner and report before/after scores.a11y:

node ${CLAUDE_PLUGIN_ROOT}/tools/a11y-scanner.mjs <project-directory>
node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <project-dir> a11y <score>

Key Principles

  • Fix, don't just audit. Every deterministic finding gets a concrete fix applied.
  • Zero false positives. The scanner only flags source-visible failures; never "fix" something it didn't flag without confirming it's real.
  • Decorative vs meaningful. alt="" is correct for decorative images — don't add fake descriptions to them.
  • Static + rendered together. The scanner catches structure/labels/alt; the rendered pass (Phase 4) catches contrast and focus. A real a11y pass needs both.