Add QA in 3 minutes

fivepixels lets teams leave feedback on real DOM elements, restore markers after UI changes, and promote issues to GitHub when needed.

• data-report-id — restores marker position via querySelector even when the UI changes.
• Shadow Root UI — panels, overlays, and markers are isolated from host app CSS.
• localStorage or server — omit handlers for browser storage, or pass onList/onCreate/onUpdate for API persistence.

Connect project, ui, visibility, team, fields, persistence handlers, side effects, and GitHub in one place. Omit onList/onCreate/onUpdate/onDelete for localStorage-only mode.

FivePixels UI renders in an open Shadow Root (#fivepixels-root), isolated from host app styles.

document.body
  └── #fivepixels-root
        └── #shadow-root (open)
              ├── <style>  ← purged Tailwind CSS
              └── FivePixels UI (panel, overlay, markers)

• Target discovery still uses main document querySelector / elementFromPoint.
• Host Shadow DOM internals are not feedback targets by default.
• appearance light | dark | system maps to data-fivepixels-theme inside Shadow Root.

Default UI uses Tailwind utility classes. Package consumers do not import CSS files.

import { FivePixels } from "@fivepixels-js/react";

export default function App() {
  return (
    <FivePixels
      project={{
        id: "multimachine-ceo",
        env: "stage",
        version: "1.2.3",
      }}
      ui={{ appearance: "system" }}
    />
  );
}

Advanced (localStorage only)

<FivePixels
  project={{ id: "my-app" }}
  ui={{
    appearance: "system",
    showFeedbackList: false,
    visibleShortcutKeys: true,
    locale: "ko",
  }}
  visibility={{ devOnly: true }}
  team={{
    user: { id: "user-1", name: "Reviewer A" },
    reviewers: [
      { id: "1", name: "Reviewer A" },
      { id: "2", name: "Reviewer B" },
    ],
  }}
  fields={[
    { key: "message", type: "textarea", label: "Message", required: true },
    { key: "isBug", type: "checkbox", label: "bug" },
    { key: "isImportant", type: "checkbox", label: "IMPORTANT" },
  ]}
/>

Without handlers, fivepixels uses localStorage. With onList/onCreate/onUpdate, it uses your server. Use the table below to pick a starting point.

Without handler props, fivepixels uses browser localStorage. Keys are scoped by project.id and project.env.

<FivePixels project={{ id: "my-app" }} />

Data transfer (localStorage only)

When QA, PM, and designers review on the same staging build, you need shared storage. localStorage splits data per browser.

• Separate data by project and environment (stage/production)
• Everyone sees the same feedback list and markers
• Share reply and review workflows across the team

Options

• fivepixels hosting (coming soon) — one API key, no backend to build
• Self-hosted backend — store on your server via v2 handlers (onList, onListReplies, onCreate, onCreateReply, onUpdate)

The frontend talks to your backend through handlers. REST paths can follow your conventions, but request/response JSON must match the data contract.

<FivePixels
  project={{ id: "my-app", env: "stage", version: "1.2.0" }}
  onList={({ pathname }) =>
    fetch(
      `/api/projects/my-app/comments?pathname=${encodeURIComponent(pathname)}&environment=stage`,
    ).then((r) => r.json())
  }
  onListReplies={(commentId) =>
    fetch(`/api/projects/my-app/comments/${commentId}/replies`).then((r) => r.json())
  }
  onCreate={(payload) =>
    fetch("/api/projects/my-app/comments", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(payload),
    }).then((r) => r.json())
  }
  onCreateReply={(commentId, payload) =>
    fetch(`/api/projects/my-app/comments/${commentId}/replies`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(payload),
    }).then((r) => r.json())
  }
  onUpdate={(id, payload) =>
    fetch(`/api/projects/my-app/comments/${id}`, {
      method: "PATCH",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(payload),
    }).then((r) => r.json())
  }
/>

• onList returns reply_count and latest_reply only — no replies[].
• onListReplies(commentId) lazy-loads the thread on marker click.
• Replies are saved via onCreateReply single POST.
• Implement onDelete if the UI delete action is required.

Promote feedback to GitHub Issues when ready. Call the GitHub API from your app server via github.onCreate.

In view mode, markers (red item · purple group) drive the reply and review flow.

1. Create — select element, message, author, checkbox tags.
2. Marker badge — +N when reply_count ≥ 1.
3. Hover — status badge, message, author, tags; latest reply preview at bottom.
4. Click — onListReplies loads the thread, then opens reply composer (no tags on replies).
5. First reply — suggested timeline entry with denied / confirm / select.
6. denied — opens composer; sends found_error reply.
7. checkout — on latest found_error; sends suggested reply.
8. confirm — adds resolved reply; feedback status becomes resolved.

• ReportField types: textarea, checkbox.
• field_values: Record<string, string | boolean>.
• Replies are stored chronologically in the replies table; latest is the last item.
• Feedback status flow: open → git_issued → resolved → archived.
• integrations.github: { issue_number, issue_url, issued_at }.

• Use project={{ id, env, version }} instead of flat projectId / environment / appVersion.
• Use project, ui, visibility objects instead of flat deprecated props.
• Replace workspace with project.id.
• Use onList/onCreate/onUpdate/onDelete instead of removed storageAdapter.
• Use onEvent/onReply for analytics instead of legacy side-effect handlers.
• localStorage key: fivepixels:reports:v1:{projectId} or with :{environment} suffix.