auditing-accessibility/
├── SKILL.md              # 主指令，触发后加载（精简）
├── references/
│   └── rules.md          # WCAG 规则目录与修复建议（按需加载）
└── scripts/
    └── scan_a11y.py      # 无障碍扫描器（执行，不载入上下文）

---
name: auditing-accessibility
description: Scans HTML, JSX, and Vue templates for common accessibility (a11y) defects — missing alt text, unlabeled inputs, empty interactive elements, duplicate ids, and invalid tabindex. Use when reviewing frontend code for WCAG compliance, before merging UI changes, or when the user mentions accessibility, a11y, WCAG, or screen-reader compatibility.
---

# Auditing Accessibility

## 何时使用
当用户需要审查前端无障碍缺陷、检查 WCAG 合规性、或在 UI 改动合入前做门禁时使用。

## 快速流程（plan → validate → execute）
复制下方清单并在执行中勾选：
\`\`\`
a11y Review Progress:
- [ ] 1. 扫描目标文件，生成 findings.json
- [ ] 2. 汇总缺陷类型与数量
- [ ] 3. 逐条修复
- [ ] 4. 重新扫描，确认 finding 数为 0 或可接受
\`\`\`

## 第 1 步：扫描（执行脚本，不要读它）
对单个文件或目录运行扫描器，输出结构化 JSON：
\`\`\`bash
python scripts/scan_a11y.py path/to/templates --format json > findings.json
\`\`\`
脚本只输出 findings，不消耗上下文 token。

## 第 2 步：解释缺陷
当用户问「这条为什么算缺陷 / 怎么修」时，阅读 [references/rules.md](references/rules.md)
中对应规则段，给出 WCAG 条目编号与修复示例。未问到就别加载。

## 第 3 步：修复后复扫（反馈闭环）
修复完必须重跑第 1 步，对比 findings.json 中 finding 数下降。任然报错就回到修复。

## 输出约定
向用户汇报时使用统一格式：
- 严重度（critical/major/minor）
- 文件:行号
- 规则编号（见 rules.md）
- 一行修复建议

# scripts/scan_a11y.py
#!/usr/bin/env python3
"""Accessibility scanner for HTML/JSX/Vue templates. Stdlib-only."""
import argparse, json, sys, glob, os
from html.parser import HTMLParser

# 仅检测这几类高频、可静态判定的问题，避免假阳性爆炸
RULES = {
    "img-alt":         ("major",   "img 缺少 alt 属性"),
    "input-label":     ("major",   "表单控件缺少关联 label"),
    "empty-interactive": ("critical", "button/a 无可访问文本"),
    "duplicate-id":    ("major",   "id 在同一文档内重复"),
    "bad-tabindex":    ("minor",   "tabindex > 0 破坏自然焦点顺序"),
    "missing-lang":    ("minor",   "html 标签缺少 lang 属性"),
}

class A11yParser(HTMLParser):
    def __init__(self, path):
        super().__init__(convert_charrefs=True)
        self.path = path
        self.findings = []
        self._ids = set()
        self._dup_ids = set()
        self._saw_html = False
        self._html_has_lang = False

    def handle_starttag(self, tag, attrs):
        d = dict(attrs)
        line = self.getpos()[0]

        if tag == "html":
            self._saw_html = True
            if "lang" in d:
                self._html_has_lang = True

        if tag == "img" and "alt" not in d:
            self.findings.append(self._mk("img-alt", line, tag))

        if tag in ("button", "a"):
            # 无文本载体（无 aria-label、无 title、且空内容稍后判断）
            if "aria-label" not in d and "title" not in d:
                # 记录待内容处理时核验，这里先标记可疑
                self.findings.append(self._mk("empty-interactive", line, tag))

        if tag in ("input", "select", "textarea"):
            labelled = ("aria-label" in d or "aria-labelledby" in d or "id" in d)
            if not labelled and d.get("type") != "hidden":
                self.findings.append(self._mk("input-label", line, tag))

        if "tabindex" in d:
            try:
                if int(d["tabindex"]) > 0:
                    self.findings.append(self._mk("bad-tabindex", line, tag))
            except ValueError:
                pass  # 非数字 tabindex 忽略，不抛错中断扫描

        if "id" in d:
            if d["id"] in self._ids:
                self._dup_ids.add(d["id"])
            self._ids.add(d["id"])

    def finalize(self):
        if self._saw_html and not self._html_has_lang:
            self.findings.append(self._mk("missing-lang", 1, "html"))
        for i in self._dup_ids:
            self.findings.append(self._mk("duplicate-id", 0, f"id={i}"))
        return self.findings

    def _mk(self, rule, line, ctx):
        sev, msg = RULES[rule]
        return {"rule": rule, "severity": sev, "line": line,
                "file": self.path, "context": ctx, "message": msg}

def collect(paths):
    files = []
    for p in paths:
        if os.path.isdir(p):
            files += glob.glob(os.path.join(p, "**", "*.html"), recursive=True)
            files += glob.glob(os.path.join(p, "**", "*.jsx"), recursive=True)
            files += glob.glob(os.path.join(p, "**", "*.vue"), recursive=True)
        elif os.path.isfile(p):
            files.append(p)
    # 目录无文件时给清晰提示，而非静默返回空
    if not files:
        sys.stderr.write(f"[warn] no html/jsx/vue files under: {paths}\n")
    return sorted(set(files))

def main():
    ap = argparse.ArgumentParser(description="Static a11y scanner (stdlib only).")
    ap.add_argument("paths", nargs="+")
    ap.add_argument("--format", choices=["json", "text"], default="json")
    args = ap.parse_args()

    all_findings = []
    for f in collect(args.paths):
        try:
            with open(f, encoding="utf-8") as fh:
                src = fh.read()
        except (FileNotFoundError, PermissionError) as e:
            # 解决而非踢皮球：跳过坏文件并记录，不中断整批
            sys.stderr.write(f"[warn] skip {f}: {e}\n")
            continue
        p = A11yParser(f)
        p.feed(src)
        all_findings += p.finalize()

    if args.format == "json":
        print(json.dumps({"total": len(all_findings), "findings": all_findings},
                         ensure_ascii=False, indent=2))
    else:
        for fnd in all_findings:
            print(f"[{fnd['severity']}] {fnd['file']}:{fnd['line']} "
                  f"{fnd['rule']} — {fnd['message']}")

if __name__ == "__main__":
    main()

python scripts/scan_a11y.py templates/login.html --format text
# [critical] templates/login.html:14 empty-interactive — button/a 无可访问文本
# [major]    templates/login.html:7  input-label — 表单控件缺少关联 label

# Accessibility Rules Reference

## 目录
- A. 图片与媒体（img-alt）
- B. 表单可访问性（input-label）
- C. 可交互元素文本（empty-interactive）
- D. 焦点顺序（bad-tabindex）
- E. 文档语言（missing-lang）
- F. 唯一标识（duplicate-id）

## A. 图片与媒体（img-alt）— WCAG 1.1.1
所有 <img> 必须有 alt。装饰性图片用 alt=""。
示例： <img src="logo.svg" alt="ACME 首页">  ✅
       <img src="spacer.gif" alt="">          ✅ 装饰性
       <img src="banner.jpg">                 ❌ 缺 alt
...（B~F 同结构展开）

{
  "skills": ["auditing-accessibility"],
  "query": "检查 templates/login.html 的无障碍问题",
  "files": ["templates/login.html"],
  "expected_behavior": [
    "运行 scan_a11y.py 生成 findings.json",
    "识别出登录按钮缺少可访问文本（empty-interactive）",
    "识别出密码输入框缺少 label（input-label）",
    "修复后重新扫描，finding 数下降"
  ]
}

# 项目级（推荐，随仓库共享给团队）
mkdir -p .claude/skills/auditing-accessibility/{references,scripts}
# 把上面三份文件分别放进去，然后：
chmod +x .claude/skills/auditing-accessibility/scripts/scan_a11y.py

# 用户级（你自己全局可用）
mkdir -p ~/.claude/skills/auditing-accessibility

<!DOCTYPE html>
<html>                              <!-- ❌ missing-lang -->
<body>
  <img src="/logo.png">             <!-- ❌ img-alt -->
  <input type="text" placeholder="用户名">   <!-- ❌ input-label -->
  <button></button>                 <!-- ❌ empty-interactive -->
</body>
</html>

python scripts/scan_a11y.py templates/login.html --format json > findings.json
# total: 4

flowchart TD
    A[启动会话] --> B[系统提示词预载所有 Skill 的 name+description<br/>第一层 · 永远在线]
    B --> C{用户提到 a11y / WCAG / 无障碍?}
    C -- 命中 --> D[Claude 读取 SKILL.md 全文<br/>第二层 · 按需]
    D --> E[执行 scripts/scan_a11y.py<br/>第三层 · 只取 stdout]
    E --> F[findings.json 可验证中间产物]
    F --> G{需要解释/修复细节?}
    G -- 是 --> H[按需读取 references/rules.md<br/>第三层 · 按需]
    G -- 否 --> I[逐条修复]
    H --> I
    I --> J[复扫 → 对比 finding 数下降]
    J --> K{finding 归零?}
    K -- 否 --> I
    K -- 是 --> L[输出汇报]
    C -- 不命中 --> M[该 Skill 消耗 0 额外 token]
    style B fill:#e8f5e9
    style F fill:#fff3e0
    style M fill:#fce4ec