The Incident That Started Everything
In 2023, I was six weeks into a website redesign project for a client. The development work was done in two. The remaining four weeks were spent managing feedback. By the end, I had 47 separate email threads, a folder full of screenshots with red arrows drawn in Preview, two PDF documents with annotations that referenced elements I could no longer find after the layout changed, and a shared Google Doc where both of us had commented on each other's comments.
The client wasn't difficult. The process was broken. There was no good tool that let a non-technical client point at something on a live website and say "this, specifically, needs to change" — and deliver that information to a developer in a way that didn't require translation.
I wanted something a 60-year-old business owner could use without a tutorial — one button on the page, click on what you want to comment on, type your feedback, done. So I built Annotiq.
What Annotiq Actually Does
Annotiq installs on any website with one line of JavaScript. When a client visits the site, they see a small feedback button. They click it, click anywhere on the page to pin a comment, type their feedback, and submit. That's it. No login required for the client. No browser extension. No tutorial needed.
The developer receives the comment in their Annotiq dashboard, alongside the exact page URL, a screenshot of the page at the moment of submission, the element that was clicked (identified by CSS selector), the client's browser, screen resolution, and device type. Everything needed to reproduce the exact context without a single follow-up email.
The Technical Problems Nobody Warns You About
Building a Widget That Works on Every Website
This sounds straightforward. It is not. A widget loaded into a third-party website is fighting for space with whatever that site is already running. Four problems appear immediately.
Content Security Policy (CSP). Many modern websites define a CSP header that restricts which external scripts can run and which domains they can communicate with. A widget that makes API calls to annotiq.io will be blocked by any site with a restrictive CSP unless the developer explicitly allowlists the domain. This is documented clearly, but it catches clients on strict hosting setups (certain managed WordPress hosts, for example) and requires an exception to be added.
z-index conflicts. The feedback button needs to float above all other content. But some websites set z-index values in the tens of thousands on their navigation, modal overlays, or cookie banners. The widget uses an extremely high z-index value and an isolated Shadow DOM for the button and comment panel, which prevents CSS leaking in either direction.
Font inheritance.If the widget renders inside the page's DOM without isolation, it inherits whatever font the host page is using — which can break the widget's layout entirely when the page uses a very large or unusual base font size. The Shadow DOM approach solves this too: the widget has its own scoped styles that are completely independent of the host page.
Zero dependencies, non-negotiable.The widget script cannot bundle React, Vue, or any other framework. You cannot ask a client's production website to load an additional 130KB of JavaScript framework just to support a feedback button. The entire widget is vanilla JavaScript, minified to under 12KB.
Context Capture: Giving Developers Everything They Need
A comment without context is almost as useless as an email. When a client submits feedback, Annotiq captures the full context automatically: the exact page URL and pathname, the scroll position at the time of the click, viewport dimensions, device type, and browser. The developer sees not just what the client said, but exactly where they were and what they were seeing.
Tracking page pathname separately from the full URL was an important data model decision. It means feedback can be grouped sensibly — all comments on /about together, all comments on /pricingtogether — regardless of query string variations.
The Dashboard and Feedback Token System
The developer-facing dashboard is a Laravel application. Projects map to websites; each project groups feedback by page URL and pathname. Developers can resolve comments individually or in bulk, and the full comment history stays visible with timestamps and status — so there's an audit trail of every revision round, not just the current open items.
Feedback tokens are one of the more thoughtful features in the system. Rather than giving clients direct access to the full project, you generate a shareable link with configurable access — including allowed origin restrictions. This means you can send a client a link that only activates the widget on your staging domain, not on production. Tokens can be revoked instantly.
Alongside comments, Annotiq supports a Q&A system via the widget: clients can ask questions directly on the page, and developers can answer from the dashboard. This removes one more category of back-and-forth email.
| Old Workflow | With Annotiq |
|---|---|
| Client takes screenshot → annotates in Preview/Paint → emails file | Client clicks element → types comment → submits in 10 seconds |
| Developer decodes vague annotation → emails for clarification | Developer sees exact element, URL, screenshot, browser info instantly |
| Multiple email threads per page, per revision round | All feedback in one dashboard, threaded by page and element |
| No record of what changed between revisions | Full comment history with timestamps and status (open/resolved) |
What I'd Do Differently
The Shadow DOM decision was right but came late — I spent time debugging z-index and font inheritance issues that the Shadow DOM approach solved immediately once I implemented it. It should have been the starting architecture, not the fix. Any embeddable widget should start with full style isolation; retrofitting it is painful.
The real user insight that shifted the product: the person whose problem you're solving is the developer, not the client. The client just needs something simple enough to use without asking questions. The developer needs structured, actionable data. Every product decision should be evaluated through that lens — "does this make the developer's workflow better?" rather than "is this impressive for the client to see?"
The 47-email project that started all of this? We re-ran the next revision round of that same client's site using an early version of Annotiq. It took three sessions instead of six weeks. The client said, unprompted, that it was "the easiest website project I've ever been part of." That was the validation I needed.