# A11y

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-houseofmvps-ultraship-a11y`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Houseofmvps](https://agentstack.voostack.com/s/houseofmvps)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Houseofmvps](https://github.com/Houseofmvps)
- **Source:** https://github.com/Houseofmvps/ultraship/tree/main/skills/a11y
- **Website:** https://www.npmjs.com/package/ultraship

## Install

```sh
agentstack add skill-houseofmvps-ultraship-a11y
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/`):

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/a11y-scanner.mjs 
```

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.

| Rule | Fix |
|---|---|
| `html-missing-lang` / `html-empty-lang` | Add `lang="en"` (or the document's real language) to `` |
| `img-missing-alt` | Add `alt=""` from context; use `alt=""` only if the image is purely decorative |
| `input-image-missing-alt` | Add `alt=""` |
| `control-missing-label` | Add a ``, or `aria-label`/`aria-labelledby`. A `placeholder` is NOT a label — keep it but add a real label |
| `button-no-text` | Add visible text, or `aria-label=""` for icon-only buttons |
| `link-no-text` | Add link text, or `aria-label`; if it wraps an icon, give the icon `alt`/`aria-label` |
| `link-generic-text` | Rewrite "click here"/"read more" to state the destination ("Read the pricing guide") |
| `positive-tabindex` | Change to `tabindex="0"` (or remove) and fix order via DOM order |
| `viewport-zoom-disabled` | Remove `user-scalable=no` / `maximum-scale=1` from the viewport meta |
| `duplicate-id` | Make each `id` unique (and update its label/aria references) |
| `broken-aria-reference` | Point `aria-labelledby`/`aria-describedby`/`for` at a real element id, or add the missing element |
| `empty-heading` | Remove the empty heading or give it text |
| `heading-skip` | Insert the missing level or demote the heading so levels don't jump |
| `missing-title` | Add a descriptive `` in `` |
| `missing-main-landmark` | Wrap the primary content in `` |

### 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:

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

# or the axe CLI directly
npx --yes @axe-core/cli 
```

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`:

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/a11y-scanner.mjs 
node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save  a11y 
```

## 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Houseofmvps](https://github.com/Houseofmvps)
- **Source:** [Houseofmvps/ultraship](https://github.com/Houseofmvps/ultraship)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/ultraship

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-houseofmvps-ultraship-a11y
- Seller: https://agentstack.voostack.com/s/houseofmvps
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.