QA Overlay

A visual QA tool for marking issues on web pages during review. Drop pins on any page element, add notes, and export for analysis.

Features

• Drop numbered pins on any page element
• Add optional notes to each pin
• Pins persist across page reloads (localStorage)
• Export all notes as JSON for review
• Works with any website or web app
• Zero dependencies
• Keyboard shortcuts for quick access

Installation

Option 1: CDN / Direct Script

<!-- Add to your HTML -->
<link rel="stylesheet" href="https://unpkg.com/qa-overlay/dist/qa-overlay.css">
<script src="https://unpkg.com/qa-overlay/dist/qa-overlay.js"></script>
<script>
  QAOverlay.init();
</script>

Option 2: npm Package

npm install qa-overlay

// ES Modules
import { QAOverlay } from 'qa-overlay';
import 'qa-overlay/css';

QAOverlay.init();

// CommonJS
const { QAOverlay } = require('qa-overlay');
// Note: You'll need to import the CSS separately in your build process

QAOverlay.init();

Option 3: Download Files

Download qa-overlay.js and qa-overlay.css from the dist/ folder and include them in your project.

Usage

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl+Shift+Q | Toggle QA mode on/off | | Ctrl+Shift+E | Export notes to clipboard as JSON | | Ctrl+Shift+C | Clear all notes | | Escape | Close modal or deactivate QA mode |

Mouse Actions

• Click anywhere on the page (when QA mode is on) to drop a pin
• Right-click a pin to delete it
• Hover over a pin to see its note

API

// Initialize the overlay
QAOverlay.init();

// Toggle QA mode programmatically
QAOverlay.toggle();

// Get all notes
const notes = QAOverlay.getNotes();

// Get notes for current page only
const pageNotes = QAOverlay.getPageNotes();

// Export as JSON string
const json = QAOverlay.exportJSON();

// Clear all notes
QAOverlay.clearNotes();

// Check status
QAOverlay.isActive();      // Is QA mode on?
QAOverlay.isInitialized(); // Has init() been called?

// Clean up (remove from DOM)
QAOverlay.destroy();

Note Data Structure

Each note contains:

interface QANote {
  id: string;           // Unique identifier
  pageUrl: string;      // Full URL
  pagePath: string;     // Path portion only
  x: number;            // Page X coordinate
  y: number;            // Page Y coordinate
  scrollY: number;      // Scroll position when placed
  viewportX: number;    // Viewport X coordinate
  viewportY: number;    // Viewport Y coordinate
  viewportWidth: number;  // Browser width when placed
  viewportHeight: number; // Browser height when placed
  note: string;         // User's note text
  timestamp: string;    // ISO timestamp
}

Framework Integration

Astro

---
// src/components/QAOverlay.astro
---
<link rel="stylesheet" href="/qa-overlay.css">
<script src="/qa-overlay.js"></script>
<script>
  QAOverlay.init();
</script>

React

import { useEffect } from 'react';
import { QAOverlay } from 'qa-overlay';
import 'qa-overlay/css';

function App() {
  useEffect(() => {
    QAOverlay.init();
    return () => QAOverlay.destroy();
  }, []);

  return <div>Your app</div>;
}

Vue

<script setup>
import { onMounted, onUnmounted } from 'vue';
import { QAOverlay } from 'qa-overlay';
import 'qa-overlay/css';

onMounted(() => QAOverlay.init());
onUnmounted(() => QAOverlay.destroy());
</script>

Next.js

// app/layout.js or pages/_app.js
'use client';
import { useEffect } from 'react';

export default function Layout({ children }) {
  useEffect(() => {
    // Dynamic import to avoid SSR issues
    import('qa-overlay').then(({ QAOverlay }) => {
      import('qa-overlay/css');
      QAOverlay.init();
    });
  }, []);

  return <>{children}</>;
}

AI-Assisted QA with Claude

QA Overlay works great with Claude Code's browser tools for automated visual QA. Export your pins and Claude can analyze what each pin is pointing at.

Workflow

1. Enable QA mode (Ctrl+Shift+Q)
2. Click to place pins on issues
3. Export pins (Ctrl+Shift+E)
4. Share the JSON with Claude
5. Claude uses browser tools to identify what each pin points at

Important: Viewport Matching

For accurate pin analysis, Claude's browser viewport must match the viewport where pins were created. Each pin stores its viewportWidth - Claude will detect mismatches and ask you to resize.

Mobile pins (< 768px viewport) require the browser to be resized to that width, as responsive layouts change element positions.

Development

# Clone the repo
git clone https://github.com/mattmacrocket/qa-overlay.git
cd qa-overlay

# Build dist files
npm run build

License

MIT