Creating an Issue

OverlayQA lets you annotate any element on a live page to create an issue with full technical context. Click or drag on the page to place a pin, describe the problem, and optionally let AI draft the issue details for you.

Enter Annotation Mode

Open the OverlayQA sidebar and click Create Issue (or the annotation button in the toolbar). The page enters annotation mode: your cursor changes and a full-page screenshot is automatically captured in the background for reference.

Place a Pin

There are two ways to mark the element you want to report:

Screenshot Pin (Click and Drag)

Click and drag on the page to draw a selection area. This creates a screenshot pin that captures a cropped screenshot of the selected region. Use this when you want to highlight a specific visual area, such as misaligned spacing or a color mismatch.

Element Pin (Click)

Click on any element without dragging. This creates an element pin anchored to that DOM element. OverlayQA automatically captures the element's CSS selector, tag name, classes, and computed styles (font size, color, padding, margin, background color, border radius, and more).

Fill in Issue Details

After placing a pin, a popover opens with the issue form. Fill in the following fields:

Description — Describe the issue. This is the primary field. Write what's wrong and AI will suggest the rest.
Title — A short name for the issue. If you leave this blank, OverlayQA generates one from your description.
Type — Choose from Design Bug, Design Gap, Design Debt, or Accessibility. You can also create custom types.
Severity — Choose Critical, High, Medium, or Low. You can also create custom severity levels.

AI Issue Drafting

As you type a description (minimum 10 characters), OverlayQA's AI analyzes the captured element and your description to suggest a title, type, severity, and expanded description. When suggestions appear, click Apply All to accept them, or continue editing manually.

AI suggestions work best with element pins, since the AI can analyze the element's visual appearance and CSS properties alongside your description.

Auto-Save

Issues auto-save as you edit. After the initial save, any changes to the title, description, type, or severity are saved automatically with a short delay. You'll see a "Saved" indicator in the popover header when changes are persisted.

What Gets Captured

Every issue automatically includes technical context that your team needs to reproduce and fix the problem:

Screenshot — Cropped to the selected area or element.
CSS selector — The element's unique selector path.
Computed CSS values — Font size, color, padding, margin, background, border radius, and more.
Page URL — The exact page where the issue was found.
Viewport dimensions — Browser window size at the time of capture.
Browser and OS — Chrome version and operating system.
Figma frame link — If a Figma frame is linked to the project.

Exit Annotation Mode

Click Done in the annotation toolbar to exit. Any unsaved pins are saved automatically before the mode closes. Your pins remain visible on the page and appear in the sidebar's issue list.