@sdm/qa-overlay

A QA feedback overlay for React apps.
Click on any element, and a structured GitHub Issue is created — right from the screen where the problem was found.

Why?

QA feedback typically goes through a painful cycle: take a screenshot, post it on Slack, and hope someone turns it into a proper issue. Context gets lost, reproduction environments are missing, and feedback slips through the cracks.

qa-overlay creates the issue right where the problem happens.

For Designers

• What you see is what gets reported — Click the problematic element and a screenshot is captured automatically. No more "it's that button on the second row."
• AS-IS / TO-BE structure — Describe the current state and the expected state separately, so your intent is communicated clearly.
• Set priority directly — Choose urgent / high / medium / low and it maps straight to issue labels.
• No more Slack-to-issue relay — Your feedback becomes a GitHub Issue instantly. Nothing gets lost.

For Developers

• Environment info collected automatically — Browser, OS, viewport, screen resolution, pixel ratio, color scheme, and language are all recorded in the issue. No more asking "what browser are you on?"
• DOM context included — The clicked element's CSS selector, DOM path, tag name, and text content are attached, so you can pinpoint the exact location immediately.
• AI-agent friendly — Issues are stored in a structured format on GitHub, so AI coding agents like Claude can read the issue and understand what needs to be fixed — no interpretation needed.
• Version-based issue tracking — A parent issue is auto-created per app version, and each feedback is linked as a sub-issue. You can see the full QA status at a glance per release.

Features

• Hotkey toggle — Cmd+Shift+. (Mac) / Ctrl+Shift+. (Windows/Linux)
• Element selection — Hover to preview, click to select
• Auto screenshot — Captures the selected element and attaches it to the issue
• GitHub Issue creation — Labels, assignees, sub-issues, and Projects v2 integration
• Auto environment capture — Browser, OS, resolution, viewport, color scheme, etc.

Install

pnpm add @sdm/qa-overlay

Usage

Client (React)

import { QaOverlay } from '@sdm/qa-overlay';

function App() {
  return (
    <>
      <QaOverlay
        version="1.2.0"
        user={{ email: '[email protected]', role: 'QA' }}
        assignees={['octocat']}
        onSubmit={async (params) => {
          const res = await fetch('/api/qa-feedback', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(params),
          });
          return res.json(); // { issueUrl: string }
        }}
      />
      {/* your app */}
    </>
  );
}

Server (API Route)

import { submitQaFeedback } from '@sdm/qa-overlay/server';

// Next.js API Route example
export async function POST(request: Request) {
  const params = await request.json();

  const result = await submitQaFeedback(
    {
      token: process.env.GITHUB_TOKEN!,
      repo: 'owner/repo',
      projectId: 'PVT_xxxxx', // optional
    },
    params
  );

  return Response.json(result);
}

API

<QaOverlay> Props

| Prop | Type | Required | Description | |---|---|---|---| | onSubmit | (params: QaSubmitParams) => Promise<{ issueUrl: string }> | Yes | Feedback submit handler | | version | string | Yes | Current app version (used for issue grouping) | | user | { email: string; role: string } | - | Reporter info | | metadata | Record<string, string> | - | Additional metadata | | assignees | string[] | - | GitHub Issue assignees |

submitQaFeedback(config, params)

Server-side function that creates a GitHub Issue with full QA metadata.

GitHubConfig:

| Field | Type | Required | Description | |---|---|---|---| | token | string | Yes | GitHub Personal Access Token | | repo | string | Yes | "owner/repo" format | | projectId | string | - | GitHub Projects v2 node ID |

Returns: { issueUrl, issueNumber, parentIssueNumber }

How It Works

1. Activate QA mode with the hotkey
2. Click an element on the page
3. Fill out the feedback form (summary, priority, AS-IS / TO-BE)
4. On submit: screenshot is captured, GitHub Issue is created
5. Issue is auto-linked as a sub-issue under the version parent

Development

pnpm install
pnpm build     # build
pnpm dev       # watch mode

License

Private