Tactual

Analysator für die Navigationskosten von Screenreadern. Misst, wie schwierig es für Nutzer von assistiven Technologien ist, interaktive Ziele im Web zu entdecken, zu erreichen und zu bedienen.

Was es tut

Bestehende Barrierefreiheits-Tools prüfen die Konformität — ist das ARIA korrekt? Ist das Kontrastverhältnis ausreichend?

Tactual misst die Navigationskosten — wie viele Aktionen benötigt ein Screenreader-Nutzer, um den Checkout-Button zu erreichen? Was passiert, wenn er darüber hinaus navigiert? Kann er überhaupt entdecken, dass er existiert?

Es funktioniert durch das Erfassen von Playwright-Barrierefreiheits-Snapshots, das Erstellen eines Navigationsgraphen und die Bewertung jedes Ziels unter einem Profil für assistive Technologien.

Installation

# For CLI usage
npm install tactual playwright

# For MCP server usage (AI tools)
npm install tactual playwright @modelcontextprotocol/sdk

Playwright und @modelcontextprotocol/sdk sind optionale Peer-Dependencies. Playwright wird für die CLI und die Seitenanalyse benötigt. Das MCP SDK ist erforderlich, um den tactual-mcp-Server auszuführen. Beides wird nicht benötigt, wenn Sie nur die Bibliotheks-API mit vorab erfassten Zuständen verwenden.

Schnelleinstieg

CLI

# Analyze a URL (default profile: generic-mobile-web-sr-v0)
tactual analyze-url https://example.com

# Analyze with a specific AT profile
tactual analyze-url https://example.com --profile voiceover-ios-v0

# Explore hidden UI (menus, tabs, dialogs, disclosures)
tactual analyze-url https://example.com --explore

# Output as JSON, Markdown, or SARIF
tactual analyze-url https://example.com --format json --output report.json
tactual analyze-url https://example.com --format sarif --output report.sarif

# Compare two analysis runs
tactual diff baseline.json candidate.json

# List available AT profiles
tactual profiles

# Run benchmark suite
tactual benchmark

# Initialize a tactual.json config file
tactual init

Bibliotheks-API

import { analyze, getProfile } from "tactual";
import { captureState } from "tactual/playwright";
import { chromium } from "playwright";

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto("https://example.com");

const state = await captureState(page);
await browser.close();

const profile = getProfile("generic-mobile-web-sr-v0");
const result = analyze([state], profile);

for (const finding of result.findings) {
  console.log(finding.targetId, finding.scores.overall, finding.severity);
}

MCP-Server

Tactual enthält einen MCP-Server für die Nutzung durch KI-Agenten:

# Start the MCP server (stdio transport — default)
tactual-mcp

# Start with HTTP transport (for hosted platforms, remote clients)
tactual-mcp --http              # listens on http://127.0.0.1:8787/mcp
tactual-mcp --http --port=3000  # custom port (or set PORT env var)
tactual-mcp --http --host=0.0.0.0  # bind to all interfaces (default: 127.0.0.1)

Verfügbare MCP-Tools:

Einrichtung durch KI-Tool

Installieren Sie zuerst die erforderlichen Pakete in Ihrem Projekt:

npm install tactual playwright @modelcontextprotocol/sdk

Claude Code — fügen Sie dies zu .mcp.json in Ihrem Projektstammverzeichnis hinzu:

{
  "mcpServers": {
    "tactual": {
      "type": "stdio",
      "command": "npx",
      "args": ["tactual-mcp"]
    }
  }
}

GitHub Copilot — fügen Sie dies zu .copilot/mcp.json oder ~/.copilot/mcp-config.json hinzu:

{
  "mcpServers": {
    "tactual": {
      "type": "stdio",
      "command": "npx",
      "args": ["tactual-mcp"]
    }
  }
}

Cursor / Windsurf / Cline — gleiches Format in der MCP-Konfiguration Ihres Editors:

{
  "mcpServers": {
    "tactual": {
      "command": "npx",
      "args": ["tactual-mcp"]
    }
  }
}

Direkt (globale Installation) — wenn Sie npx nicht verwenden möchten:

npm install -g tactual playwright
tactual-mcp  # starts the MCP server on stdio

GitHub Actions

Verwenden Sie die Composite-Action aus dem GitHub Actions Marketplace:

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - name: Analyze accessibility
        uses: tactual-dev/tactual@v0.2.1
        with:
          url: https://your-app.com
          explore: "true"
          fail-below: "70"

Die Action installiert Tactual und Playwright, führt die Analyse aus, lädt SARIF in das GitHub Code Scanning hoch und lässt den Build fehlschlagen, wenn die durchschnittliche Punktzahl unter dem Schwellenwert liegt. Gibt average-score und result-file für nachgelagerte Schritte aus.

Oder verwenden Sie die CLI direkt für mehr Kontrolle:

- name: Install Tactual
  run: npm install tactual playwright

- name: Install browsers
  run: npx playwright install chromium --with-deps

- name: Run accessibility analysis
  run: npx tactual analyze-url https://your-app.com --format sarif --output results.sarif --threshold 70

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Konfiguration

CLI-Flags

Options:
  -p, --profile <id>              AT profile (default: generic-mobile-web-sr-v0)
  -f, --format <format>           json | markdown | console | sarif (default: console)
  -o, --output <path>             Write to file instead of stdout
  -d, --device <name>             Playwright device emulation
  -e, --explore                   Explore hidden branches
  --explore-depth <n>             Max exploration depth (default: 3)
  --explore-budget <n>            Max exploration actions (default: 50)
  --explore-max-targets <n>       Max accumulated targets before stopping (default: 2000)
  --exclude <patterns...>         Exclude targets by name/role glob
  --exclude-selector <css...>     Exclude elements by CSS selector
  --focus <landmarks...>          Only analyze within these landmarks
  --suppress <codes...>           Suppress diagnostic codes
  --top <n>                       Show only worst N findings
  --min-severity <level>          Minimum severity to report
  --threshold <n>                 Exit non-zero if avg score < N
  --config <path>                 Path to tactual.json
  --no-headless                   Headed browser (for bot-blocked sites)
  --timeout <ms>                  Page load timeout (default: 30000)
  --probe                         Run keyboard probes (focus, activation, Escape, Tab)
  --wait-for-selector <css>       Wait for selector before capturing (for SPAs)
  --wait-time <ms>                Additional wait after page load
  --storage-state <path>          Playwright storageState JSON for authenticated pages
  --summary-only                  Return only summary stats, no individual findings
  -q, --quiet                     Suppress info diagnostics

tactual.json

Erstellen Sie diese mit tactual init oder manuell:

{
  "profile": "voiceover-ios-v0",
  "exclude": ["easter*", "admin*", "debug*"],
  "excludeSelectors": ["#easter-egg", ".admin-only", ".third-party-widget"],
  "focus": ["main"],
  "suppress": ["possible-cookie-wall"],
  "threshold": 70,
  "priority": {
    "checkout*": "critical",
    "footer*": "low",
    "analytics*": "ignore"
  }
}

Die Konfiguration wird automatisch aus dem Arbeitsverzeichnis erkannt (tactual.json oder .tactualrc.json). CLI-Flags werden mit den Konfigurationseinstellungen zusammengeführt und überschreiben diese.

AT-Profile

Profile definieren die Kosten jeder Navigationsaktion, die Gewichtung der Bewertungsdimensionen, costSensitivity (skaliert die Zerfallskurve der Erreichbarkeit) und kontextabhängige Modifikatoren. Siehe src/profiles/ für Implementierungsdetails.

Bewertung

Jedes Ziel erhält einen 5-dimensionalen Bewertungsvektor:

Die Gewichtung der Dimensionen variiert je nach Profil:

Zusammengesetzt: Gewichtetes geometrisches Mittel: overall = exp(sum(w_i * ln(score_i)) / sum(w_i)) - interopRisk. Jede Dimension wird vor dem Logarithmus auf 1 gesetzt, um log(0) zu vermeiden. Das bedeutet, dass eine Null in einer beliebigen Dimension die Gesamtpunktzahl stark nach unten zieht — man kann nicht bedienen, was man nicht erreichen kann.

Schweregradbänder:

Diagnostik

Tactual erkennt und meldet, wenn eine Analyse möglicherweise unzuverlässig ist:

Exploration

Das --explore-Flag aktiviert die begrenzte Zweig-Exploration:

• Öffnet Menüs, Tabs, Einblendungen, Akkordeons und Dialoge

• Erfasst neue Barrierefreiheitszustände aus versteckter UI

• Markiert entdeckte Ziele als requiresBranchOpen

• Respektiert Budgets für Tiefe, Aktionsanzahl, Zielanzahl und Neuheit

• Safe-Action-Richtlinie blockiert destruktive Interaktionen

Die Exploration ist nützlich für Seiten mit signifikanter versteckter UI (z. B. Dropdown-Menüs, Tab-Schnittstellen, modale Dialoge).

Explorationskandidaten werden vor der Iteration nach einem stabilen Schlüssel (Rolle + Name) sortiert, sodass der gleiche Seiteninhalt über verschiedene Läufe hinweg die gleiche Explorationsreihenfolge erzeugt.

Explorationsbudgets

SPA-Framework-Erkennung

Tactual erkennt, wann SPA-Inhalte gerendert wurden, bevor der Barrierefreiheitsbaum erfasst wird. Erkannte Frameworks: React, Next.js, Vue, Nuxt, Angular, Svelte und SvelteKit. Generische HTML5-Inhaltssignale (Landmarks, Überschriften, Navigation, Links) werden ebenfalls geprüft. Für SPAs, die nicht durch die automatische Erkennung abgedeckt sind, verwenden Sie --wait-for-selector (CLI) oder waitForSelector (MCP/API), um einen CSS-Selektor anzugeben, der anzeigt, dass Ihre App hydriert wurde.

Nach der anfänglichen Framework-Erkennung verwendet Tactual konvergenzbasiertes Polling — wiederholtes Snapshotten des Barrierefreiheitsbaums, bis sich die Zielanzahl stabilisiert —, was unabhängig vom Framework funktioniert.

Interop-Risiko

Tactual enthält einen statischen Snapshot von ARIA-Rollen/Attribut-Unterstützungsdaten, die von a11ysupport.io und dem ARIA-AT-Projekt abgeleitet wurden. Rollen mit bekannten Lücken in der AT/Browser-Unterstützung erhalten eine Interop-Risikostrafe.

Empfehlungen zum Ausgabeformat

Alle Nicht-SARIF-Formate geben eine zusammengefasste Ausgabe aus: Statistiken, gruppierte Probleme und die schlechtesten Ergebnisse (begrenzt auf 15). SARIF ist auf 25 Ergebnisse begrenzt. Wenn die Ausgabe abgeschnitten ist, erscheint oben ein Hinweis.

Für die MCP-Nutzung ist sarif das Standard- und empfohlene Format. Verwenden Sie summaryOnly: true für einen minimalen Gesundheitscheck (~835 Bytes: Statistiken, Schweregradzählungen, Top 3 Probleme).

Kalibrierung

Tactual enthält ein Kalibrierungs-Framework (src/calibration/, exportiert als tactual/calibration) zur Abstimmung der Bewertungsparameter anhand von Ground-Truth-Datensätzen. Siehe docs/CALIBRATION.md für Details.

Entwicklung

npm install                    # Install dependencies
npm run build                  # Build with tsup
npm run test                   # Run unit + integration tests
npm run test:benchmark         # Run benchmark suite
npm run typecheck              # TypeScript type checking
npm run lint                   # ESLint

Sicherheit

Browser-Sandboxing

Tactual führt Playwright immer mit aktiviertem Standard-Chromium-Sandboxing aus. Es deaktiviert niemals die Websicherheit und modifiziert nicht das Sicherheitsmodell des Browsers. Alle Seiteninteraktionen finden innerhalb der Standard-Chromium-Prozess-Sandbox statt.

Safe-Action-Richtlinie

Wenn die Exploration aktiviert ist (--explore), klassifiziert Tactual interaktive Elemente in drei Stufen, bevor sie aktiviert werden:

Dies ist eine schlüsselwortbasierte Heuristik — sie kann keine semantische Täuschung erkennen (z. B. einen "Speichern"-Button, der tatsächlich Daten löscht) oder das serverseitige Verhalten untersuchen. Führen Sie die Exploration für den Produktionseinsatz immer in vertrauenswürdigen oder sandboxed Umgebungen aus.

URL-Validierung

Alle URLs werden vor der Navigation validiert. Private/interne IP-Bereiche und Nicht-HTTP(S)-Schemata werden standardmäßig abgelehnt.

Lizenz

Apache-2.0