DEV Community

Cover image for Stop Guessing Where Your Accessibility Issues Are: Unleash the WICK-AG-Lens Chrome Extension to Target Them on the Spot 🎯
Sebastian Clavijo Suero
Sebastian Clavijo Suero

Posted on

Stop Guessing Where Your Accessibility Issues Are: Unleash the WICK-AG-Lens Chrome Extension to Target Them on the Spot 🎯

#a11y #frontend #testing #tools

Table of Contents

ACT 1: EXPOSITION

 
Let's be brutally honest. For many teams, accessibility testing feels like eating vegetables. We know it matters. We want to do the right thing. But it almost always gets pushed to the very end of the meal (or sprint, either way). It becomes a chore, an afterthought, or worse, a massive QA bottleneck right before release.

Why? The feedback loop is broken.

Developers write code, push it, and maybe later a CI pipeline throws an error. Or a QA engineer logs a ticket with a vague description like, "Screen reader does not read this button." Then begins the tedious dance of inspecting the DOM, hunting for the exact element, and trying to remember the specific WCAG rule that was violated. The friction is incredibly high.

A while back, I introduced a Cypress plugin called wick-a11y, read the release article here. Think of it as your John Wick style ally for smashing accessibility barriers inside your E2E tests. It is great for guarding your pipeline. But what about before you even push your code? What if you could see accessibility issues as clearly as a glaring UI bug while you are actively developing?

Enter WICK-AG-Lens: Accessibility Inspector extension.
 

 
It is a brand new free and open-source Chrome browser extension designed to eliminate the friction between writing code and testing for accessibility. No more digging through console logs. No more guessing. Just immediate visual feedback directly within your page layout.


 

ACT 2: CONFRONTATION

 
Building an accessibility inspector is not just about throwing rules at a page. It is about how that information is presented to developers, QA testers, and accessibility professionals so they can actually use it. WICK-AG-Lens was engineered around a few core philosophies to drastically reduce your cognitive load.

Features Overview

 

1. Show, Don't Just Tell (Visual Highlighting)

Context is everything. Instead of printing a sterile list of errors in a DevTools console, WICK-AG-Lens draws highly visible bounding boxes and color-coded badges directly over the target elements on your page. Seeing a <button> without a label visually highlighted right where it sits in the layout immediately tells you how to fix it. Reading a console error requires mental translation.


 

2. The Separation of Concerns: Violations vs. Informative

A major source of fatigue in accessibility tooling is noise. To combat this, I divided the 40 independent audits into two distinct tabs: actionable violations and structural information checks.

Automated tools cannot understand intent. A script can easily verify that a focus path exists and check the order of tabindex attributes. But it takes a human to look at that highlighted path on the screen and realize the focus jumps wildly from the header, down to the footer, and back up to the main navigation. A machine sees valid code. A human sees a terrible user experience. By separating these tabs, developers can ruthlessly hunt real bugs in the Violations tab, while accessibility professionals and QA can explore the architecture in the Informative tab without the noise.


 

3. Strict WCAG Criteria Filtering

Not every project targets the same compliance standard. WICK-AG-Lens includes a dynamic filter bar allowing you to specifically toggle target WCAG Versions (2.0, 2.1, 2.2) and Conformance Levels (A, AA, AAA). The UI and execution engine will instantly adapt, hiding irrelevant audits or specific legend criteria (like differing AA vs. AAA contrast thresholds) so you only see exactly what you are testing for.


 

4. Immediate Context & Interactive Panels

Clicking on any badge on the page opens an interactive panel. This panel tells you exactly what the tool highlighted, why it is important for users with disabilities, and provides the exact CSS selector or logic applied to identify them.


 

5. Precision Element Locators

There is also a "View Elements" button in the DevTools panel. This opens a modal containing the list of all DOM elements identified by the accessibility audit. From there, you just click the crosshair icon next to an element and the extension instantly scrolls the affected element into view, marking it with a highly visible pulsating ring.


 

6. Intuitive, Organized UI & Built-In Documentation

The extension is designed for maximum configuration in a simple way. The panel utilizes expandable/collapsible category groups to keep your workspace clean and focused. It is fully keyboard-friendly. Plus, if you ever need a refresher on a rule, a complete documentation modal is embedded directly inside the extension, so no need to leave the browser or search a wiki to understand the technical bounds.


 

7. Built for the Modern Web (Shadow DOM & Iframes)

The modern web is a messy place. The scanner utilizes custom deep bottom-up traversal logic to pierce standard open web components to evaluate encapsulated markup. It also fully traverses the internal DOM of same-origin iframes, so you aren't left blind when inspecting complex widgets.
 

8. Zero-Friction Ticketing (One-Click Reporting)

QA engineers and testers spend half their lives writing bug tickets. WICK-AG-Lens includes a one-click reporting feature that instantly copies formatted text reports of all active audits and their findings directly to your clipboard. You just click the button, paste the clean text into Jira or GitHub, and move on.

 

 

Audit Library and Ruleset

WICK-AG-Lens performs 40 independent audits. Here is exactly what it is looking for under the hood:

 

Tab 1: Violations and Warnings

Keyboard Navigation

  • Unfocusable Clickables: Flags generic elements with onclick handlers lacking tabindex and role. Keyboard users cannot tab to or activate these elements.
    • Severity: Critical
    • WCAG Alignment: 2.1.1 Keyboard (2.0 A)
    • Badge Output: "Unfocusable Clickable"
  • Disabled Focus Outlines: Parses page CSS via heuristic evaluation to find focusable elements where outline: none is applied on focus without a fallback. Sighted keyboard users rely entirely on focus rings.
    • Severity: Critical
    • WCAG Alignment: 2.4.7 Focus Visible (2.0 AA)
    • Badge Output: "Disabled Focus Ring (Heuristic)"
  • Tabindex Violations: Flags elements with tabindex > 0, overriding natural DOM focus order and creating unpredictable navigation paths.
    • Severity: Serious
    • WCAG Alignment: 2.4.3 Focus Order (2.0 A)
    • Badge Output: tabindex="{val}"
  • Accesskey Attributes: Flags explicit accesskey usage, which often conflicts with native browser or screen reader shortcuts.

Images & Media

  • Missing Alt Text: Flags <img> elements completely lacking an alt attribute. Screen readers will read the raw filename if missing.
  • Uncaptioned Video: Flags <video> elements lacking nested <track> elements for captions.
  • Redundant Alt Text: Flags alt attributes containing words like "image" or "photo". Screen readers automatically announce images, making prefixes redundant.

Forms & Controls

  • Unlabeled Form Inputs: Flags form controls missing <label> wrappers, aria-label, or for attributes.
  • Empty Buttons: Flags buttons with no text, aria-label, or child image alt. Screen readers will only announce 'Button'.
  • Placeholder as Label: Flags inputs relying solely on placeholders for their accessible name.

Links & Navigation

  • Empty Links: Flags <a> tags lacking readable text or accessible names.
  • Suspicious Link Targets: Flags anchor tags acting as buttons (href="#" or javascript:) without a button role, which breaks spacebar operability.
  • Generic Link Text: Flags ambiguous link text like "Click Here" or "Read More" using exact word boundaries.
  • Unwarned New Window Links: Flags target="_blank" links lacking text or ARIA warnings, which unexpectedly disorients users.
    • Severity: Moderate
    • WCAG Alignment: 3.2.5 Change on Request (2.0 AAA)
    • Badge Output: 'target="_blank" (No Warning)'

ARIA & Semantics

  • Focusable in Aria-Hidden: Flags elements that receive keyboard focus but are hidden from Assistive Technologies via aria-hidden="true" on the element or an ancestor, creating a "ghost focus" trap.
  • Invalid ARIA State: Flags elements marked with aria-invalid="true" indicating validation errors.
  • Prohibited Author Names: Flags presentation or none roles that improperly contain aria labels, breaking semantics.

Structure and Document

  • Auto-playing Media: Flags audio/video with autoplay enabled, which conflicts with screen reader announcements.
  • Heading Hierarchy Errors: Flags skipped sequential levels or fake structural classes to maintain logical document outlines.

Visual & Contrast

  • Text Color Contrast: Calculates the effective contrast ratio between visible text and its backing container, dynamically factoring in font-size and weight for large-text thresholds.

 

Tab 2: Informative and Structure

Keyboard Navigation

  • Tabindex (Comparison): Highlights all tabindex usages simultaneously to provide a visual map of the programmatic focus strategy.
  • Display Focus Order: Traces and numbers the natural sequential path of focusable elements, dynamically flagging elements hidden from AT.
    • WCAG Alignment: 2.4.3 Focus Order (2.0 A)
    • Badge Output: #{counter}: <{tag}> or #{counter}: <{tag}> (Hidden from AT)

Images & Media

  • Display Image Alternatives: Extracts and visually prints the alt text for all <img> elements.
  • Captioned Video: Highlights video elements that correctly implement <track> captions.
  • Iframe Context & Titles: Extracts explicitly defined titles from embedded iframes.
    • WCAG Alignment: 4.1.2 Name, Role, Value (2.0 A)
    • Badge Output: title="{title}", "Hidden Iframe", or "Missing Title"

Forms & Controls

  • Form Field Descriptions: Identifies supplemental instructional text linked to inputs via aria-describedby or title.
  • Fieldsets & Captions: Highlights visual grouping containers and their titles.
  • Touch Target Sizes: Computes the exact width and height pixel boundaries of interactive elements to catch undersized targets.

Links & Navigation

  • Warned New Window Links: Highlights target="_blank" links that correctly include accessible warnings.

ARIA & Semantics

  • ARIA Roles & Attributes: Maps all elements utilizing an explicit role definition.
  • ARIA Live Regions: Maps dynamic aria-live injection containers.
  • Required Fields: Maps mandatory inputs enforced via HTML5 required or aria-required.
  • Aria-Expanded State: Maps expandable widgets, color-coded by true or false state.
  • Aria-Controls: Highlights elements that dictate the visibility of remote DOM elements.
  • Aria-Owns: Highlights elements establishing parent/child relationships outside the DOM tree.

Structure & Document

  • Valid Heading Order: Maps the standard, sequential H1 to H6 structure.
  • Landmark Regions: Maps native HTML5 and ARIA structural containers.
  • Table & Grid Structure: Highlights native tables, captions, headers, and custom div-based grids.
  • Lists and List Items: Maps unordered, ordered, and glossary lists and children.
  • Language Definitions: Maps the root document language declaration alongside inline phonetic shifts.

 

Limitations and Technical Bounds

Before you dive in, it is important to understand the technical boundaries of what an automated browser extension can and cannot do:

  • Visibility & Occlusion: It strictly ignores hidden elements (display: none, inert, hidden, etc.) to perfectly match the native accessibility tree, but it cannot calculate 3D visual occlusion (e.g., an element covered by a high z-index modal).
  • Shadow DOM & Iframes: It successfully pierces open Web Components and same-origin iframes. Closed shadow roots and cross-origin iframes (like embedded third-party videos) remain inaccessible due to strict browser security policies.
  • Contrast Heuristics: Contrast is calculated via computed DOM styles. While it dynamically computes thresholds based on font size and weight, elements layered over complex images or CSS gradients are automatically flagged for 'Manual Check'.
  • Filter Isolation: WCAG version and conformance filters are strictly isolated. Selecting '2.2' does not automatically include '2.1' or '2.0'. You must explicitly check all versions and levels you wish to evaluate for your current analysis.  

ACT 3: RESOLUTION

 
Accessibility is not just a checkbox to tick off before a release. It is about making the web work for everyone. But that doesn't mean the process of building accessible software has to be painful.

With wick-a11y guarding your Cypress pipelines and WICK-AG-Lens riding shotgun in your browser, you have a pretty solid duo to keep the noise down and the quality up. The goal is to catch these barriers early, fix them fast, and get back to building cool things.

Don't wait around. Install the extension, pull up your favorite notoriously inaccessible website, and watch the badges light up like a hit list. No bloated audits, just sharp, uncompromising accessibility inspection.

Install WICK-AG-Lens from the Chrome Web Store

The entire blueprint is open-source on GitHub at sclavijosuero/wick-ag-lens. If it gets the job done, pay the bounty with a star on the repository. Otherwise, I might be forced to call my friend Johnny to set things straight. 😎

Cheers!

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

You can also connect with me on my new YouTube channel: https://www.youtube.com/@SebastianClavijoSuero

If you'd like to support my work, consider buying me a coffee, and I get my boost to keep learning and sharing cool stuff with all of you.

Thank you for your support!
Buy Me A Coffee

Top comments (0)