Gemini API でアクセシビリティ監査を自動化する — 誤検出に振り回されない設計

# pip install google-genai playwright pydantic
# playwright install chromium
 
from __future__ import annotations
 
import json
import hashlib
from typing import Literal
 
import google.genai as genai
from google.genai import types
from playwright.sync_api import sync_playwright
from pydantic import BaseModel, Field
 
client = genai.Client(api_key="YOUR_GEMINI_API_KEY")

CONTRAST_PROBE = """
() => {
  const srgb = (c) => {
    const v = c / 255;
    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
  };
  const luminance = ([r, g, b]) =>
    0.2126 * srgb(r) + 0.7152 * srgb(g) + 0.0722 * srgb(b);
 
  const parse = (s) => (s.match(/[\\d.]+/g) || []).map(Number);
 
  // 透明な背景は祖先へ遡って解決する（ここを省くと全て白扱いになる）
  const effectiveBg = (el) => {
    let node = el;
    while (node && node !== document.documentElement) {
      const c = parse(getComputedStyle(node).backgroundColor);
      if (c.length >= 3 && (c[3] === undefined || c[3] > 0)) return c.slice(0, 3);
      node = node.parentElement;
    }
    return [255, 255, 255];
  };
 
  const ratio = (a, b) => {
    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
    return (hi + 0.05) / (lo + 0.05);
  };
 
  const out = [];
  for (const el of document.querySelectorAll('p, a, span, li, button, h1, h2, h3, h4, label')) {
    const text = (el.innerText || '').trim();
    if (!text) continue;
    const cs = getComputedStyle(el);
    if (cs.visibility === 'hidden' || cs.display === 'none') continue;
 
    const size = parseFloat(cs.fontSize);
    const bold = parseInt(cs.fontWeight, 10) >= 700;
    // 大きなテキストの定義: 24px 以上、または 18.66px 以上かつ太字
    const isLarge = size >= 24 || (size >= 18.66 && bold);
    const required = isLarge ? 3.0 : 4.5;
 
    const r = ratio(parse(cs.color).slice(0, 3), effectiveBg(el));
    if (r < required) {
      out.push({
        selector: el.tagName.toLowerCase() + (el.id ? '#' + el.id : ''),
        text: text.slice(0, 60),
        ratio: Math.round(r * 100) / 100,
        required,
        font_px: size,
      });
    }
  }
  return out;
}
"""
 
 
def measure_contrast(url: str) -> list[dict]:
    """コントラスト比を実測する。AI は一切介在しない。"""
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page(viewport={"width": 1280, "height": 720})
        page.goto(url, wait_until="networkidle")
        violations = page.evaluate(CONTRAST_PROBE)
        browser.close()
    return violations

TARGET_SIZE_PROBE = """
() => {
  const MIN = 24;
  const out = [];
  for (const el of document.querySelectorAll('a, button, input, select, [role="button"]')) {
    const r = el.getBoundingClientRect();
    if (r.width === 0 || r.height === 0) continue;      // 非表示要素は対象外
    if (r.width < MIN || r.height < MIN) {
      out.push({
        selector: el.tagName.toLowerCase(),
        label: (el.innerText || el.getAttribute('aria-label') || '').slice(0, 40),
        width: Math.round(r.width),
        height: Math.round(r.height),
      });
    }
  }
  return out;
}
"""

class Violation(BaseModel):
    criterion: str = Field(description="WCAG 達成基準番号（例: 1.1.1）")
    severity: Literal["critical", "major", "minor"]
    selector: str = Field(description="問題箇所を特定できる CSS セレクタ")
    excerpt: str = Field(description="該当要素のマークアップ抜粋（120文字以内）")
    reason: str = Field(description="なぜ達成基準を満たさないのか")
    fix: str = Field(description="具体的な修正案。可能ならコード片で")
 
 
class SemanticAudit(BaseModel):
    violations: list[Violation]
    uncertain: list[str] = Field(description="人間の確認が必要と判断した箇所")
 
 
SEMANTIC_PROMPT = """あなたは WCAG 2.2 の監査担当者です。
以下の HTML について、**文脈を読まなければ判断できない項目だけ** を検査してください。
 
検査する項目:
- 2.4.4 リンクの目的: 「こちら」「詳細」など、リンク先が推測できないテキスト
- 1.1.1 代替テキストの妥当性: alt が空でないが、内容を説明していないもの
  （例: alt="image1", alt="写真"）
- 1.3.1 情報と関係性: 見出しに見えるが h1-h6 でない要素、表に見えるが table でない要素
- 3.3.2 ラベル: フォーム項目のラベルが操作内容を説明していないもの
- 1.4.1 色の使用: 「赤い項目は必須です」のように色だけで意味を伝える記述
 
検査しない項目（別レイヤーで実測済み）:
- コントラスト比、要素の寸法、alt 属性の有無、lang 属性の有無
 
確信が持てない箇所は violations ではなく uncertain に入れてください。
推測で違反を作らないでください。
 
HTML:
{html}
"""
 
 
def audit_semantics(clean_html: str) -> SemanticAudit:
    response = client.models.generate_content(
        model="gemini-2.5-flash",
        contents=SEMANTIC_PROMPT.format(html=clean_html),
        config=types.GenerateContentConfig(
            temperature=0.0,          # 監査は創造性を必要としない
            seed=42,                  # 再実行時の揺れをさらに抑える
            response_mime_type="application/json",
            response_schema=SemanticAudit,
        ),
    )
    return SemanticAudit.model_validate_json(response.text)

LANDMARKS = ["header", "nav", "main", "aside", "footer", "form"]
MAX_CHARS = 12000
 
 
def split_by_landmark(page) -> list[tuple[str, str]]:
    """ランドマーク単位で HTML を分割する。長すぎる main はさらに section で割る。"""
    chunks: list[tuple[str, str]] = []
    for tag in LANDMARKS:
        for i, handle in enumerate(page.query_selector_all(tag)):
            html = handle.evaluate("el => el.outerHTML")
            if len(html) <= MAX_CHARS:
                chunks.append((f"{tag}[{i}]", html))
                continue
            for j, sub in enumerate(handle.query_selector_all("section, article")):
                sub_html = sub.evaluate("el => el.outerHTML")
                chunks.append((f"{tag}[{i}]>section[{j}]", sub_html[:MAX_CHARS]))
    return chunks

def _focus_clip(page, pad: int = 24) -> dict:
    """フォーカス中の要素の周囲だけを切り出す矩形を返す。"""
    box = page.evaluate(
        "() => { const r = document.activeElement.getBoundingClientRect();"
        "  return {x: r.x, y: r.y, width: r.width, height: r.height}; }"
    )
    return {
        "x": max(box["x"] - pad, 0),
        "y": max(box["y"] - pad, 0),
        "width": box["width"] + pad * 2,
        "height": box["height"] + pad * 2,
    }
 
 
def capture_focus_states(url: str, steps: int = 8) -> list[bytes]:
    """Tab を押しながらフォーカス状態を連続撮影する。"""
    shots: list[bytes] = []
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page(viewport={"width": 1280, "height": 720})
        page.goto(url, wait_until="networkidle")
        for _ in range(steps):
            page.keyboard.press("Tab")
            page.wait_for_timeout(120)   # 遷移アニメーションの完了を待つ
            focused = page.evaluate("() => document.activeElement?.tagName")
            if not focused or focused == "BODY":
                break
            shots.append(page.screenshot(clip=_focus_clip(page)))
        browser.close()
    return shots
 
 
def review_focus_visibility(shots: list[bytes]) -> str:
    parts = [types.Part.from_bytes(data=s, mime_type="image/png") for s in shots]
    parts.append(
        "各画像は Tab 操作で移動したフォーカス位置の拡大図です。"
        "フォーカスされた要素の輪郭が背景から視覚的に判別できるかを、"
        "画像ごとに『判別できる／判別しにくい／判別できない』の三択で答え、"
        "理由を一文で添えてください。コントラスト比の数値は推定しないでください。"
    )
    response = client.models.generate_content(
        model="gemini-2.5-pro",
        contents=parts,
        config=types.GenerateContentConfig(temperature=0.0),
    )
    return response.text

def fingerprint(v: dict) -> str:
    """行番号や本文の揺れに影響されない指紋を作る。"""
    key = f"{v['criterion']}|{v['selector']}|{v.get('reason', '')[:40]}"
    return hashlib.sha256(key.encode("utf-8")).hexdigest()[:16]
 
 
def diff_against_baseline(current: list[dict], baseline_path: str) -> dict:
    try:
        with open(baseline_path, encoding="utf-8") as f:
            known = set(json.load(f)["fingerprints"])
    except FileNotFoundError:
        known = set()
 
    seen = {fingerprint(v): v for v in current}
    new_ids = set(seen) - known
    fixed_ids = known - set(seen)
 
    return {
        "new": [seen[i] for i in new_ids],
        "fixed_count": len(fixed_ids),
        "total": len(seen),
    }

# a11y-suppress.yml
- criterion: "1.1.1"
  selector: "img.decorative"
  reason: "装飾画像。role=presentation を付与済み"
  expires: "2026-12-31"   # 期限を切って、恒久的な言い訳にしない

# .github/workflows/a11y.yml
name: accessibility
 
on:
  pull_request:
    paths: ["app/**", "components/**", "styles/**"]
 
jobs:
  audit:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
 
      - run: pip install google-genai playwright pydantic && playwright install --with-deps chromium
 
      - name: Run audit
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: python scripts/a11y_audit.py --url "${{ vars.PREVIEW_URL }}" --baseline .a11y/baseline.json
 
      # 終了コード 2 = 決定論レイヤーの新規 critical のみ
      # 終了コード 1 = 判断レイヤーの新規違反（レポートのみ）
      - name: Comment findings
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const body = fs.readFileSync('.a11y/report.md', 'utf8');
            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body,
            });

REPORT_PROMPT = """以下は 1 ページのアクセシビリティ監査結果です。
Markdown のレポートを作成してください。
 
構成:
1. 概要（3 行以内。新規違反の件数と、最も重い項目のみ）
2. 新規の critical（実測値付き。表形式）
3. 新規の major / minor
4. 人間の確認が必要な項目（uncertain と視覚フラグ）
5. 既知の違反の残数と前回比
 
規則:
- 実測値（contrast ratio, target size）は与えられた数値をそのまま転記し、丸めないこと
- 推測で数値を補わないこと
- 修正案は該当箇所の CSS / HTML 片で示すこと
 
対象: {url}
実測結果: {measured}
意味的監査: {semantic}
差分: {diff}
"""
 
 
def build_report(url: str, measured: dict, semantic: dict, diff: dict) -> str:
    response = client.models.generate_content(
        model="gemini-2.5-flash",
        contents=REPORT_PROMPT.format(
            url=url,
            measured=json.dumps(measured, ensure_ascii=False)[:6000],
            semantic=json.dumps(semantic, ensure_ascii=False)[:6000],
            diff=json.dumps(diff, ensure_ascii=False)[:3000],
        ),
        config=types.GenerateContentConfig(temperature=0.2),
    )
    return response.text