a11y-check
Accessibility audit, scoped to the surfaces a product actually has. Detects web / rendered_markdown / terminal / native_app / video_audio / document / headless, then applies only the criteria that bind. WCAG 2.1 AA in full for web; not at all for headless.
haabe · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add haabe/mycelium --skill a11y-check技能说明
name: a11y-check description: "Accessibility audit, scoped to the surfaces a product actually has. Detects web / rendered_markdown / terminal / native_app / video_audio / document / headless, then applies only the criteria that bind. WCAG 2.1 AA in full for web; not at all for headless." metadata: instruction_budget: "26" framework_dependency: "mycelium" framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."
Accessibility Audit
Evaluate user-facing work against the criteria that BIND TO ITS SURFACES. Accessibility is a design constraint, not a polish step (Downe Principle 11) — and an instrument aimed at a surface the product does not have measures nothing while looking like a failure.
STEP 1 — SURFACE GATE. Run this BEFORE the checklist, every time.
The checklist below is written for web pages. Most products are not web pages. Detect which
user-facing surfaces this product actually has, from the repository, and evaluate ONLY the criteria
that bind to them. Profiles and detection hints: engine/canvas-guidance.yml#surfaces —
web · rendered_markdown · terminal · native_app · video_audio · document · headless.
A product commonly has several. State which you found and how, in the output.
THE RULE THAT DECIDES EVERY RATING:
| situation | rating |
|---|---|
| the surface is ABSENT | n/a — and say which surface is missing |
| the surface is PRESENT and you measured it | pass / partial / fail on the evidence |
| the surface is PRESENT and you did NOT measure it | not-assessed — a real gap, it could have been measured |
MARKING A CRITERION fail BECAUSE ITS SURFACE DOES NOT EXIST IS A CATEGORY ERROR. It
manufactures a defect out of a product's shape, and a done-bar built on it fails for a reason no
work can fix.
MEASURED, WHICH IS WHY THIS SECTION EXISTS. On 2026-09-03 this skill's checklist was applied to
Mycelium — a terminal product with markdown docs — and Downe principle 11 was rated fail, with
the entry stating plainly: "NOT TESTED, which is this principle's own fail criterion... WCAG 2.1 AA
is largely the wrong instrument for a terminal product." A delivery bar failed on an instrument
that could not bind. Re-run 2026-09-04 under the surface gate: every applicable criterion passed,
and the rest were n/a by absence of surface rather than unmeasured.
THREE CONSTRAINTS, OR THIS GATE BECOMES A WAIVER MACHINE. Declaring a surface costs work; declaring its absence costs a word, and accessibility has a long history of being waived on exactly such grounds.
- Detect from artifacts and RECORD THE EVIDENCE — say what you looked for and where. An
n/awhose basis is "the agent decided" is not a finding and cannot be falsified later. n/amust never read aspassin a total. "6 pass / 3 n/a" is honest; "9 of 15 clear" is the thing this rule exists to stop.- FLOOR: every shipped product has at least one human surface — its docs, at minimum. A
fully-
n/aaccessibility result is a DETECTOR BUG, not a clean bill. Treat that run as broken.
AND SURFACES SCOPE THE SUB-CHECKS, NEVER THE PRINCIPLE. Downe P11 "Be usable by everyone" is
broader than perceptual access: it covers cost, language, literacy, required prior knowledge and
availability. A terminal product may be n/a on keyboard navigation and still FAIL P11 on
jargon that gates a newcomer. Bind WCAG's sub-checks to surfaces; never hand the principle itself
an n/a.
HEADLESS IS THE SHARP CASE. An API or library has no human surface, so WCAG does not bind at all. What binds instead — error-message clarity, documentation quality — lives under other Downe principles. Do not rate a headless product on interface criteria.
STEP 2 — WCAG 2.1 AA Checklist by Principle
Applies in full to web. Partially to rendered_markdown, native_app, document. Barely to terminal. Not at all to headless.
1. Perceivable
- All images have meaningful alt text (or alt="" for decorative)
- Video has captions; audio has transcripts
- Color is never the sole indicator of meaning
- Color contrast: 4.5:1 normal text, 3:1 large text
- Content is readable at 200% zoom without horizontal scroll
- Text spacing can be adjusted without loss of content
2. Operable
- All interactive elements reachable via keyboard (Tab/Shift+Tab)
- Visible focus indicators on all focusable elements
- No keyboard traps (can always Tab away)
- Skip navigation link for repetitive content
- Page titles are descriptive and unique
- Focus order matches visual order
- Touch targets are at least 44x44 CSS pixels
3. Understandable
- Language of page is declared (lang attribute)
- Form inputs have associated labels
- Error messages identify the field and describe the fix
- Instructions don't rely solely on sensory characteristics
- Navigation is consistent across pages
4. Robust
- Valid HTML (no duplicate IDs, proper nesting)
- ARIA used correctly (roles, states, properties)
- Custom components expose name, role, value to assistive tech
- Status messages use aria-live regions
Automated Testing Tools (by stack)
| Stack | Tool | Command |
|---|---|---|
| React/Web | axe-core | npx axe <url> or axe-core in tests |
| Any web | Lighthouse | npx lighthouse <url> --only-categories=accessibility |
| Any web | pa11y | npx pa11y <url> |
| CI/CD | axe-linter | Add to CI pipeline |
Common Violations and Fixes
| Violation | Fix |
|---|---|
| Missing alt text | Add descriptive alt or alt="" for decorative |
| Low color contrast | Increase contrast ratio to 4.5:1 minimum |
| Missing form labels | Add <label for="id"> or a |