Prototype comments: Feedback on Coded Prototypes, Saved in GitHub

At S&P Global, the team’s prototypes were deployed from one repository, so anyone could open them in a browser. A design file has comments. A deployed prototype had none, so feedback had to be written up somewhere else, away from the screen it was about.

The team already worked in GitHub, so I put the comments there. I built the first version near the end of my contract and tested it on the team’s GitHub Enterprise. The version on this page is my own rewrite, published as open source.

One script tag, every page. The deploy step adds the panel to every prototype page, so nobody sets anything up per prototype. It works whatever the prototype is built with, and it follows page changes in single-page apps.

Threads, and a reply in progress

Every thread is a GitHub discussion. The page goes into the title, like “[/checkout] Pay button has no loading state”, so the list still reads well on GitHub. Replies, reactions, edits and resolving go straight from the browser to GitHub under the reviewer’s own account, so notifications and @mentions work the way the team already knows.

prototype page ──▶ GitHub Discussions      reads and writes, as the reviewer
      │
      └── sign-in only ──▶ worker ──▶ GitHub ──▶ back to the page

The only server is a small worker that handles sign-in and stores nothing.

Signing in uses the reviewer’s GitHub account. There are no separate accounts or passwords. Access comes from GitHub, so only people who can see the repository can read or leave feedback.

No comment backend. GitHub already handles accounts, permissions, storage and notifications, and the team was already there. The trade-off is GitHub’s rate limit: fine for a team, wrong for a public website.

A GitHub App, not an OAuth App. OAuth permissions can’t be narrowed to discussions, so commenting would have needed access that can also change code. A GitHub App gets discussions and nothing else.

Sign-in by redirect, not a popup. GitHub’s sign-in page stops a popup from handing the token back to the page that opened it. So the page redirects, the token comes back in the part of the address browsers never send to a server, and it is cleared right away.

Kept apart from the prototype. The panel brings no framework and keeps its styles in a shadow root. The prototype’s CSS can’t break the panel, and the panel can’t break the prototype.

• Pin a comment to a spot on the screen, not just to the page
• Show new comments without reopening the panel