dbs-a11y-pilot

Framework-agnostic accessibility wrapper that inspects the live DOM, watches route changes, and produces human-friendly suggestions plus AI-ready prompts.

Installation

npm install dbs-a11y-pilot

Quick Start

React

import { AccessibilityProvider } from 'dbs-a11y-pilot/react';

function App() {
  return (
    <AccessibilityProvider>
      <Router />
    </AccessibilityProvider>
  );
}

Vue

import { createApp } from 'vue';
import App from './App.vue';
import { createAccessibilityPlugin } from 'dbs-a11y-pilot/vue';

const app = createApp(App);
app.use(createAccessibilityPlugin());
app.mount('#app');

Vanilla

import { initAccessibilityPlugin } from 'dbs-a11y-pilot';

const plugin = initAccessibilityPlugin();
plugin.start();

Configuration

| Option | Default | Description | | --- | --- | --- | | scanOnInit | true | Run audit immediately after initialization. | | scanDebounceMs | 250 | Debounce delay for processing DOM mutations. | | rootSelector | document | Root node or selector for scoping audits. | | rules | built-ins enabled | Toggle individual rule execution and severity overrides. | | autoFix | { enabled: false, safeOnly: true } | Control generation and application of safe patches. | | ai | { enabled: false, redact: true } | Configure AI prompt generation and providers. | | overlay | { enabled: true, showOnDevOnly: true } | Dev overlay UI controls. | | maxNodesToInspect | 5000 | Ceiling for nodes inspected per audit cycle. | | reportCallback | undefined | Hook receiving aggregated issues. | | fileHintsProvider | undefined | Callback returning source file hints per node. | | logger | console | Custom logger implementation. |

CLI

npx dbs-a11y-pilot-cli ./dist/index.html --format json

AI Integration

• Disabled by default.
• Enable via ai.enabled = true and provide endpoint/apiKey.
• Redaction strips emails, phone numbers, tokens by default.

Prompt Template

[Context]
Project: {projectName || 'unknown'}
FileHint: {fileHint || 'no-file-hint'}
RuleId: {ruleId}
WCAG: {wcag.join(', ')}
Severity: {severity}
DOMSnippet: {domSnippet}
RenderedText: {renderedText || 'n/a'}
ElementSelector: {selector}

[Task]
You are an expert frontend engineer and a11y specialist. Provide a minimal, safe code change to fix the issue described above. Keep behavior and layout intact. If a code patch is risky, explain and give step-by-step safe manual changes. Output:
1) A short explanation.
2) A code patch in unified diff format (or a focused code snippet).
3) Tests or manual verification steps.

[Constraints]
- Do not remove functionality.
- Keep ARIA usage to recommended patterns.
- If network or external assets are required mention them explicitly.

Generated prompts redact sensitive content when ai.redact is true.

Auto-fix

Safe diff suggestions are generated for issues like missing alt, aria-label, and basic label relationships. Enable automatic application with care by setting autoFix.enabled = true.

Safe patches emit unified diff payloads when the library can deterministically modify markup. Unsafe fixes produce guidance only.

Troubleshooting

• Overlay hidden? Ensure overlay.enabled = true and environment is non-production or set showOnDevOnly = false.
• SSR warning? Check for typeof window !== 'undefined' before calling initAccessibilityPlugin.
• Performance? Increase scanDebounceMs or limit scope with rootSelector.

Security & Privacy

• No network calls without explicit opt-in (ai.enabled).
• Review prompts before sending to third-party services; redact sensitive data.

Contributing

1. npm install
2. npm run dev
3. npm run test

Tests & CI

• npm run lint
• npm run test
• npm run build

GitHub Actions workflow runs lint/test/build on pushes and publishes to npm when tagging v*.*.* with NPM_TOKEN configured.

Publishing

1. Set package metadata (name/version/description) in package.json.
2. Ensure keywords include accessibility terms (already configured).
3. npm run build && npm run build:types
4. npm login
5. npm publish --access public

CI automation mirrors these steps on tag pushes.

License

MIT