beacon

Beacon

English · 日本語 · 한국어 · 简体中文 · 繁體中文 · Bahasa Indonesia · Tiếng Việt · ไทย · हिन्दी

Accessibility + AEO inspection plugin for Claude Code.

Beacon is a fast accessibility baseline for agent-assisted UI work: static heuristics first, live audit support when available, and report language that explains what to fix and why. It is useful in the same part of the workflow where teams use Lighthouse, axe, Pa11y, or WAVE, but Beacon is tuned for agent coding sessions, jurisdiction-aware WCAG context, Answer Engine Optimization, and human-centered explanations.

As of 2.1.0, beacon:inspect also folds in Lighthouse performance, best-practices, and SEO as supplementary signals and connects them back to accessibility through shared cross-cutting root causes — for example, an oversized DOM that slows style and layout, burdens screen-reader traversal, and hampers AI crawlability at the same time. These signals sit beside the accessibility score; they are not part of it.

Beacon is not a compliance certificate, not a legal opinion, and not a replacement for testing with disabled users. A high Beacon score means the automated checks found fewer problems in the inspected evidence. It does not prove that the product is fully accessible.

Beacon runs locally; site files stay on your machine unless you explicitly share them. The installed plugin does not change itself inside your environment. Maintainers may run offline evaluation loops and add better detectors in later releases; users benefit by updating the plugin.

What Beacon Does

Beacon provides three Claude Code commands:

Command	Use it when	What you get
beacon:inspect	You have a page, component, HTML file, or UI change to review.	A 0-100 baseline score, 10 category scores, findings, jurisdiction context notes, remediation order, and an interactive HTML report — plus an optional Performance tab (Lighthouse performance/best-practices/SEO) when a browser is available.
beacon:guide	You are about to design or code UI.	Accessible patterns, component guidance, WCAG reminders, and design tradeoffs before code is written.
beacon:advisor	You are editing HTML, CSS, JSX, TSX, Vue, or Svelte.	Contextual accessibility prompts while you work. It also runs through the Claude Code PostToolUse hook for UI file edits.

Typical usage in Claude Code:

/beacon:guide
I am building a checkout form with address autocomplete and inline validation.

/beacon:advisor
Review the modal I am editing for keyboard, focus, and screen-reader issues.

/beacon:inspect
Inspect this page for WCAG 2.2 AA, jurisdiction context, and AEO readiness.

Audit Model

Beacon uses a three-tier model.

Tier	Evidence	Strength	Important limitation
Tier 1: static scan	Files and markup patterns through scripts/static-audit.mjs.	Fast, repeatable, zero browser dependency. Good for regression baselines.	Heuristic only. It cannot compute real visibility, computed styles, runtime focus behavior, or true contrast. Hidden elements may be over-reported.
Tier 2: live audit	Browser evidence through Playwright and axe-core when available.	Stronger evidence for computed style, contrast, ARIA, visibility, and runtime behavior.	Still automated. It cannot prove task success or language clarity for real users.
Tier 3: human testing	Manual walkthroughs and tests with disabled users.	Required for cognitive load, task completion, real assistive technology behavior, and usability.	Takes planning and cannot be replaced by AI.

Tier 1 is a fast baseline, not the authority. If Tier 1 and Tier 2 disagree, prefer the live browser and axe-backed evidence. Static checks intentionally err on the side of surfacing review items, so dense real-world pages can have false positives, especially around hidden links, list structure, and anything that depends on CSS visibility.

Installation

Install from the Claude Code plugin marketplace:

/plugin install beacon@beacon

Your Claude Code config must include beacon in extraKnownMarketplaces:

"beacon": {
  "source": {
    "source": "github",
    "repo": "chiehweihuang/beacon"
  }
}

Plugin facts:

Field	Value
Name	beacon
Version	2.1.0
Repository	chiehweihuang/beacon
License	MIT
Author	chiehweihuang

First Inspection

Run beacon:inspect after a substantial UI change or against a page you want to evaluate.

Beacon can produce:

• audit-results.json: structured audit data and findings.
• a11y-report-*.html: an interactive human-readable report.
• before/after comparison when a previous audit JSON is supplied.

Use the score as a triage signal: