@a11y-context/cli

A11y Context Project is a repo-scoped installation kit that helps AI coding assistants generate more accessible UI code by enforcing retrieval and application of accessibility best practices (patterns + global rules) before code is produced.

This package provides a CLI that installs and manages the A11y Context “kit” files inside your repositories.

Status: Early preview. Commands and templates are evolving and may change between versions.

What it does

When you run this CLI in a repository, it can:

• Add a small .a11y-context/ config area to your repo
• Install repo instruction files for supported AI clients (Cursor, Claude Code, GitHub Copilot, Android Studio Gemini, Gemini CLI, etc.)
• Configure retrieval mode:
  • MCP-first with docs fallback (recommended)
  • MCP-only
  • Docs-only (RAG / indexed docs)
• Run basic “doctor” checks to confirm the kit is present and configured

The end goal is consistent: the assistant should retrieve A11y Context best practices before generating UI code, then apply “Must Haves” / “Golden Pattern” requirements in the output.

Quickstart

Run from the root of the repository you want to enable.

Defaults

• --mode defaults to auto (hybrid: MCP-first + docs fallback)
• --clients: all (default) or a comma-separated list (e.g. cursor,claude,copilot)
• --stack is required (prevents wrong-stack guidance)

Install the kit (required: --stack)

npx @a11y-context/cli init --stack web/react

Install for a subset of clients (optional)

npx @a11y-context/cli init --stack web/react --clients cursor,claude,copilot

Why: since mode defaults to auto, make the simplest command not include --mode.

Common flags (may expand over time):

• --mode: auto (MCP-first + docs fallback), mcp, or docs
• --stack: e.g. web/react, android/compose
• --clients: install for specific clients (planned; not final)

Configure docs retrieval (RAG / indexed docs)

If you plan to use docs-only mode, or you want docs fallback for auto mode, you’ll need a docs base URL your AI client (or your org’s retriever) can access from your indexing setup.

npx @a11y-context/cli config --docsBaseUrl https://YOUR_DOCS_SITE

Run checks

npx @a11y-context/cli doctor

How it fits into your workflow

A11y Context has two main layers:

• Enforcement: repo instruction files require “retrieve best practices before writing code”

• Retrieval: best practices can be retrieved via:

  • MCP server tooling (structured, deterministic), and/or

  • indexed documentation (RAG)

auto = Hybrid MCP-first + docs fallback.

The intent is:

1. Try MCP first

2. If MCP isn’t available, fall back to docs retrieval

3. Avoid mixing sources in a single response unless explicitly required

Development

npm install
npm run dev -- --help
npm run build
node bin/a11y-context.js --help

Local install test (without publishing)

npm link
mkdir -p /tmp/a11y-context-test && cd /tmp/a11y-context-test
a11y-context --help
a11y-context init --mode auto --stack web/react

Unlink when done:

npm unlink -g @a11y-context/cli

Repository structure

• src/ — CLI implementation

• src/commands/ — command handlers (init/config/doctor)

• templates/ — file templates copied into target repos

  • templates/clients/ — client-specific instruction file templates

  • templates/common/ — shared templates/config

• bin/ — executable wrapper that runs the compiled CLI

License

TBD (recommend MIT for open-source).