Skip to main content
Vol. 1.0 — No. 4A11yEngine Remediator EditionJuly 2026
⚡ THE A11YENGINE
developer reference

Custom Rules & Heuristics

A11yEngine pairs standard `axe-core` compliance checks with **10 proprietary local heuristic rules** to audit user interaction patterns, focus safety, and secure PII compliance.

Rule 1 — custom-focus-outline-reset

Invisible Keyboard Focus Indicator

HighSC 2.4.7 (Focus Visible) — Level AA

Flags elements that override the browser's default focus indicator (using outline:none, outline:0, or focus:outline-none) without declaring a visible fallback ring. Sighted keyboard navigators lose track of their position on the page.

❌ Non-Compliant Implementation
<button class="bg-[#111111] text-white focus:outline-none">
  Complete Purchase
</button>
✓ Remediation Code (Tailwind/HTML)
<button class="bg-[#111111] text-white focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">
  Complete Purchase
</button>
Rule 2 — custom-tabindex-improper

Hardcoded Positive Tabindex

MediumSC 2.1.1 (Keyboard) — Level A

Detects element declarations with positive tabindex attributes (tabindex > 0). Hardcoding positive tabindex values disrupts the natural top-down sequential reading and tabbing flow. Keep values to 0 or -1.

❌ Non-Compliant Implementation
<a href="/pricing" tabindex="3">Pricing</a>
<a href="/checkout" tabindex="1">Checkout</a>
✓ Remediation Code (Tailwind/HTML)
<a href="/pricing">Pricing</a>
<a href="/checkout">Checkout</a>
Rule 3 — custom-keyboard-nav-missing

Unreachable Clickable Custom Control

HighSC 2.1.1 (Keyboard) — Level A

Catches non-interactive elements (like <div> or <span>) that have click listeners or role="button"/"link" attributes but lack a tabindex attribute, rendering them completely unreachable via keyboard navigation.

❌ Non-Compliant Implementation
<div onclick="submitOrder()" role="button">
  Buy Now
</div>
✓ Remediation Code (Tailwind/HTML)
<div onclick="submitOrder()" role="button" tabindex="0" onkeydown="if(event.key==='Enter'||event.key===' '){event.preventDefault();submitOrder();}">
  Buy Now
</div>
Rule 4 — custom-aria-icon-missing

Icon-Only Control Lacks Description

CriticalSC 1.3.1 (Info and Relationships) & SC 4.1.2 — Level A

Flags links and buttons containing only SVG, icons, or vector glyphs with no textual label or aria-label attributes. Screen reader users will only hear "button" or "link" without context.

❌ Non-Compliant Implementation
<button>
  <svg class="w-4 h-4" fill="none" ...></svg>
</button>
✓ Remediation Code (Tailwind/HTML)
<button aria-label="Delete item permanently">
  <svg class="w-4 h-4" fill="none" ...></svg>
</button>
Rule 5 — custom-accessible-name-mismatch

Visible Label Mismatch in ARIA Name

MediumSC 2.5.3 (Label in Name) — Level A

Identifies custom controls where the visible text string is not included inside the aria-label attribute. Speech-to-text (voice control) software users who attempt to vocalize the button name will fail to activate it.

❌ Non-Compliant Implementation
<button aria-label="Submit credit details to bank">
  Pay Now
</button>
✓ Remediation Code (Tailwind/HTML)
<button aria-label="Pay Now and submit credit details">
  Pay Now
</button>
Rule 6 — custom-autoplay-media

Autoplay Sound / Video Block

HighSC 1.4.2 (Audio Control) — Level A

Flags audio or video elements configured to autoplay sound. Autoplay audio overrides screen reader voices, making it impossible for blind users to navigate the screen to locate the pause button.

❌ Non-Compliant Implementation
<video src="/assets/intro.mp4" autoplay></video>
✓ Remediation Code (Tailwind/HTML)
<video src="/assets/intro.mp4" controls></video>
Rule 7 — custom-video-captions-missing

Video Component Lacks Subtitles/Captions

HighSC 1.2.2 (Captions - Prerecorded) — Level A

Flags video player elements that do not contain a child <track kind="captions"> or <track kind="subtitles"> node, restricting access for deaf or hard-of-hearing audiences.

❌ Non-Compliant Implementation
<video controls src="/assets/intro.mp4">
</video>
✓ Remediation Code (Tailwind/HTML)
<video controls src="/assets/intro.mp4">
  <track default kind="captions" srclang="en" src="/captions_en.vtt" label="English Captions">
</video>
Rule 8 — custom-vague-link-text

Vague Descriptive Link Labels

MediumSC 2.4.4 (Link Purpose - In Context) — Level A

Flags links labeled with generic terms like "click here", "read more", or "learn more". Visually impaired users browsing a list of isolated page links cannot identify where they lead.

❌ Non-Compliant Implementation
<a href="/docs/api">Click Here</a> to view docs.
✓ Remediation Code (Tailwind/HTML)
<a href="/docs/api">View the API Documentation</a>.
Rule 9 — custom-skip-link-missing

Missing "Skip to Main Content" Bypass

MediumSC 2.4.1 (Bypass Blocks) — Level A

Flags pages with navigation headers or sidebars that lack a hidden skip bypass link as the first focusable child, forcing keyboard users to tab through all menus on every page load.

❌ Non-Compliant Implementation
<body>
  <nav><!-- Lots of links --></nav>
  <main id="main-content">
✓ Remediation Code (Tailwind/HTML)
<body>
  <a href="#main-content" class="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 bg-indigo-600 text-white p-2">Skip to Main Content</a>
  <nav><!-- Lots of links --></nav>
  <main id="main-content">
Rule 10 — pii-scrubber

PII Scrubbing Validation Filter

System / SecurityEnterprise Data Safety (Local)

Checks and sanitizes raw DOM strings inside the content sandbox before passing elements to AI systems, automatically redacting credentials, cards, CVVs, and email fields.

❌ Non-Compliant Implementation
<input type="password" name="user_password" value="secret123" />
✓ Remediation Code (Tailwind/HTML)
<input type="password" name="user_password" value="[REDACTED_PII]" />