On-page Overlays

On-page overlays are visual indicators that show issues directly on the webpage. Instead of reading a list of problems, you see them highlighted on the actual elements, making it easier to understand the context and impact of each issue.

How Overlays Work

When you run a scan, the extension injects lightweight overlay elements into the page:

1. Detection - The scanner identifies elements with issues
2. Positioning - Overlays are placed over the problematic elements
3. Rendering - Colored borders and badges appear without affecting page layout
4. Interaction - Click or hover to see issue details

Severity Colors

Overlay colors indicate issue severity at a glance:

Example visual mapping:

• A button with no accessible name: Red border
• Text with insufficient contrast: Orange border
• A link with generic "click here" text: Yellow border
• A heading that skips a level: Blue border

Overlay Components

The overlay system consists of three types of visual elements:

Highlighter

The primary overlay type. A colored border appears around elements with issues:

Characteristics:

• 2px solid border in severity color
• Slight background tint (10% opacity)
• Rounded corners matching element border-radius
• Does not shift element position

Cluster Badge

When multiple issues are close together (within 50 pixels), they are grouped:

Characteristics:

• Circular badge showing issue count (e.g., "3")
• Badge color matches highest severity in group
• Positioned at center of clustered elements
• Click to expand and see individual issues

Tooltip

Hovering over an overlay shows a tooltip with quick information:

Tooltip contents:

• Issue title
• Severity label
• Category (Accessibility, UX, etc.)
• "Click to select" hint

Click the tooltip to select the issue in the Side Panel and see full details.

Interacting with Overlays

Selecting an Issue

Click any overlay to select it:

1. The overlay gains a pulsing animation
2. The page scrolls to center the element
3. The Side Panel expands issue details
4. Other overlays fade slightly to highlight selection

Deselecting

Click anywhere else on the page or press Escape to deselect:

1. The pulsing animation stops
2. All overlays return to normal visibility
3. The Side Panel collapses issue details

Hovering for Preview

Hover over an overlay without clicking:

1. Tooltip appears with issue summary
2. Element gets a subtle highlight boost
3. Move away to dismiss tooltip

Clicking Through to Page

If you need to interact with the underlying element:

1. Hold Alt (Windows/Linux) or Option (Mac) while clicking
2. The click passes through to the element
3. Useful for testing interactive elements while overlays are active

Overlay Customization

Access overlay settings through the extension popup or Side Panel settings:

Toggle Overlays

Turn overlays on or off without clearing scan results:

Filter by Severity

Show only certain severity levels:

This helps focus on high-priority issues without visual noise from lower-severity items.

Opacity Settings

Adjust overlay transparency:

How Clustering Works

The overlay system automatically groups nearby issues to reduce visual clutter:

Clustering Algorithm

1. Distance check - Issues within 50 pixels of each other are candidates
2. Severity priority - Cluster badge uses highest severity color
3. Count display - Badge shows total number of grouped issues
4. Expansion - Click badge to see individual issue overlays

When Clustering Activates

Expanding a Cluster

1. Click the cluster badge
2. Individual overlays appear for each issue
3. Click any overlay to select that specific issue
4. Click elsewhere or press Escape to collapse back to badge

Pulse Animation

When an issue is selected (from overlay click or Side Panel), the overlay pulses to draw attention:

Animation behavior:

• 3 pulses over 2 seconds
• Slight scale increase (102%)
• Opacity fluctuation
• Stops after animation completes or on deselection

This helps locate the element, especially when selected from the Side Panel list rather than by clicking the overlay directly.

Performance Considerations

Overlays are designed to minimize impact on page performance:

Lightweight Rendering

• Overlays use CSS transforms (not reflow-triggering properties)
• Batch updates avoid multiple repaints
• Event delegation minimizes listener count

Memory Management

• Overlays are created on-demand after scan completes
• Hidden overlays are removed from DOM
• Scan results persist but overlay DOM elements are lazy-loaded

Disabling for Performance

On very complex pages, overlays may affect scroll performance. To disable:

1. Open extension popup
2. Toggle "Show overlays" off
3. Continue using Side Panel for issue list

Overlays and Dynamic Content

The extension handles dynamic page content:

SPA Navigation

When you navigate within a Single Page Application:

1. Overlays for the previous view are cleared
2. New scan can be triggered (manually or automatically)
3. Fresh overlays appear for new content

DOM Mutations

If page content changes after scanning:

1. Overlays for removed elements are cleaned up
2. Existing overlays may become misaligned
3. Re-scan to get accurate overlay positions

Scroll and Resize

Overlays automatically reposition:

• On window scroll: Overlays track their elements
• On window resize: Positions recalculate
• On element move: Overlay follows (with slight delay)

Troubleshooting Overlays

Overlays Not Appearing

1. Check "Show overlays" is enabled in settings
2. Verify scan completed (check Side Panel for results)
3. Check severity filters aren't hiding all issues
4. Refresh page and re-scan if DOM changed significantly

Overlays Misaligned

1. Page content may have changed after scan
2. Re-run scan to recalculate positions
3. Check for CSS animations that move elements

Overlays Affecting Page

In rare cases, overlays may interfere with page functionality:

1. Hold Alt/Option to click through overlays
2. Or toggle overlays off temporarily
3. Report persistent issues to support

Next Steps