Leave the note on the thing
A reviewer presses C and clicks anything on the page. The comment pins to that element, not to a pixel position, so it stays in place at any window width. Others reply, resolve it or open an issue from it without leaving the page.
Where the thread opens turned out to matter more than how the pin looks. It used to open in the toolbar’s panel in the corner, away from the element it was about. Now it opens beside its pin, with reply, resolve and the agent handover still in reach.
I prototyped three pin styles on the same page with worst-case threads: a 27-character username, a four-comment thread, two notes on neighbouring elements. I expected to pick one. Each won somewhere different, so all three stayed as a setting. Bubble suits dense pages. Marked shows the kind of note before you read it. Margin keeps the page readable for visitors, but needs a hover to show what a tab points at.
A numbered dot where the comment was made. Compact, but says nothing until it’s opened.
Ship feedback straight from the page
Reviewers pin comments to the parts of a Pages site they care about. Every thread lives in GitHub Discussions, next to the code.
Getting started
Add the script to your deploy step. The reusable workflow turns on Discussions too.
npx pages-feedback initWhat you get
- Pins Comments stay attached to the element, not the pixel.
- Search Find any page in under 50ms.
- Deploy previews Review every branch before it ships.
Open a pin to read its thread where it was left. The page, people and threads are synthetic, taken from the playground experiment; nothing here posts to GitHub.
A comment should survive the next build
Prototypes change between crits. That’s what they’re for. A comment that was right on Tuesday’s build can point at nothing on Thursday’s, or at the wrong thing.
So each thread stores four ways to find its element, tried in order: a stable id, a CSS selector, the element’s text and role, then an xpath. It also records the commit it was written against, so a reviewer can tell when a note is older than the page they’re looking at.
The selector on its own was the trap. When two cards swap places, “the second card” still matches, just the wrong one. The resolver now refuses a selector match whose text has changed and falls through to the text. A thread that matches nothing is kept and flagged, because quietly dropping someone’s feedback is worse than showing it out of place.
The next build renames the setup heading’s id, removes the callout and swaps two cards.
Ship feedback straight from the page
Reviewers pin comments to the parts of a Pages site they care about. Every thread lives in GitHub Discussions, next to the code.
Getting started
Add the script to your deploy step. The reusable workflow turns on Discussions too.
npx pages-feedback initWhat you get
- Pins Comments stay attached to the element, not the pixel.
- Search Find any page in under 50ms.
- Deploy previews Review every branch before it ships.
What the Discussion stores for thread 4
<!-- pagefeedback:{
"v": 1,
"path": "/docs/intro/",
"selector": "main > section:nth-of-type(3) > ul > li:nth-of-type(2)",
"fallbacks": {
"text": "Search Find any page in under 50ms.",
"role": "listitem",
"xpath": "./main[1]/section[3]/ul[1]/li[2]"
},
"offset": {
"x": 0.12,
"y": 0.22
},
"viewport": 1440,
"rev": "9f3e1a0"
} -->The order is id, selector, text and role, then xpath. A thread that matches none of them is kept and flagged, not dropped. Synthetic page; the resolver is the toolbar’s own.
Hand the agent a brief, not a screenshot
I didn’t build a backend. Threads are Discussions in the repo the prototype deploys from, labelled by kind, with the anchor kept in a hidden comment in the body. Anyone with access to the repo can read and search them there, and they outlast the tool. Installing it is a script tag and a repo setting, which matters when the person adding it is a designer.
Because the feedback already sits next to the code, handing it on is short. Open threads copy out as markdown: the element’s current id and selector, the text the reviewer saw, where to search the repo, and the whole conversation. If a thread was found by a fallback, the brief says so and gives the element as it reads on today’s build.
People and agents read the same thread. A designer settles a question with a reviewer, then hands over the agreed change without rewriting it as a ticket. The agent replies by thread number, so each note can be closed against the change that answered it.
# Feedback to address: /docs/intro/ (build a1b2c3d)
## 1. [Feedback] Open · https://github.com/acme/handbook/discussions/41
**HTML id:** `#setup`
**Element:** `main > section:nth-of-type(2) > h2#setup`
**Text:** "Getting started"
**Source hint:** search the repo for `id="setup"` or the text above
**Thread:**
- @alice: This heading is too close to the hero on mobile.
- @bob: Agree, 16px more spacing would fix it.
## 3. [Question] Open · https://github.com/acme/handbook/discussions/43
**HTML id:** none on this element
**Element:** `main > section:nth-of-type(2) > aside`
**Text:** "Heads up: device codes expire after 15 minutes."
**Source hint:** search the repo for the text above
**Thread:**
- @mei: Is it 15 minutes on Enterprise too? I thought it was configurable.
## 4. [Feedback] Open · https://github.com/acme/handbook/discussions/44
**HTML id:** none on this element
**Element:** `main > section:nth-of-type(3) > ul > li:nth-of-type(2)`
**Text:** "Search Find any page in under 50ms."
**Source hint:** search the repo for the text above
**Note:** written against build 9f3e1a0.
**Thread:**
- @alice: The search icon looks blurry on retina screens.
## 5. [Feedback] Open · https://github.com/acme/handbook/discussions/46
**HTML id:** none on this element
**Element:** `main > section:nth-of-type(2) > pre`
**Text:** "npx pages-feedback init"
**Source hint:** search the repo for the text above
**Thread:**
- @sam: This command should copy with one click.
## Instructions
Make the minimal change to resolve each thread. Reply with a summary per thread number.Pick threads and the brief rewrites itself. Each one carries the element’s id, its selector, the text a person saw and where to look in the repo. Threads are synthetic; the format is the toolbar’s own.
What it still asks of people
Every reviewer needs a fine-grained GitHub token with access to that one repo, pasted into the toolbar once. That’s a real barrier for people outside engineering, and it’s the first thing I’d remove.
Anchors can still lose their way. A heading rewritten with a new id and new words has nothing left to match, so its thread shows as orphaned until someone reattaches it.
I haven’t measured whether decisions get made faster. What I can say is narrower. Feedback from people who couldn’t make the crit now arrives on the page, against a build, where the next person can find it.