Step one
Load It On The Page
A bookmarklet for a one off, or a script tag on a staging environment you keep returning to. It runs inside the page rather than framing it, because almost every site refuses to be framed.
WhyTho
Every element on a page is a decision somebody made, and almost none of those decisions are written down anywhere. WhyTho pins the reasoning to the element itself.
Live
Public signup
Public repository
What It Is
WhyTho is an annotator for webpages. You start it on a page with a bookmarklet or a one line script tag, select an element, and write down why that element is the way it is. A numbered pin sticks to the element, and the note is stored against a selector rather than against a screenshot or a line number.
Each note carries more than its text. It records the selector, the tag, a snippet of the element's content, the viewport width and breakpoint it was written at, a category, a status, and who wrote it. A note taken at 390px is filed as a mobile observation rather than a rule about the whole site, which matters when the same element behaves differently at two breakpoints.
Selection works the same on both ends: click on desktop, press and hold on a phone. The whole interface lives in a shadow root, so the page being annotated cannot restyle it and it cannot leak styles into the page.
The Problem It Solves
A site accumulates decisions faster than anyone documents them. An H1 phrased as a service plus a city because that is where the demand sits. A canonical pointing somewhere non obvious. A block of copy that reads awkwardly because it answers the question people actually search. Six months later the reasoning is gone, and what remains is an element that looks arbitrary to whoever inherits it.
So it gets changed. Not maliciously, just in the course of a redesign, a CMS migration, or a new writer tidying the copy. The work that produced the ranking is undone by someone who had no way of knowing it was load bearing, and nobody notices until the traffic moves.
Documentation in a separate file does not fix this, because the person about to change the element is looking at the element, not at the file. WhyTho puts the reasoning where the decision is visible.
Where It Gets Used
Four situations, all of them handover in one form or another.
- Before a redesign. Walk the templates and mark what must survive it. The do not change status exists for exactly this, and it reads as an instruction rather than a preference.
- Handing a site to a new team. An export of the notes for the pages that matter tells a new developer what is deliberate, which is the thing a repository cannot tell them.
- Recording an audit where it landed. A finding in a document is an argument. The same finding pinned to the element it changed is a record.
- Explaining a decision to a client on their own page. Pointing at the element beats describing it, especially when the disagreement is about wording.
How It Works
Four steps, and one constraint that shapes all of them.
Step two
Select The Element
Click on desktop, press and hold on touch. The generated selector prefers meaning over position: an id first, then test hooks such as data-testid, then a stable class path, and only then nth-of-type.
Step three
Write The Reasoning
A category, a status, and the note itself. The viewport is captured automatically, so the record says which breakpoint you were looking at rather than leaving that to memory.
Step four
It Saves To Your Account
Notes write through to a database keyed to your account, so the same set is there from any browser. If the network is down they are held locally and pushed on the next run.
Three engineering notes worth stating: hashed build classes, from emotion, styled components and similar, are filtered out of generated selectors, because a selector built on them breaks at the next deploy. Notes are matched back to elements on load, and a note whose element has moved is shown as unresolved rather than silently reattached to the wrong thing, since a wrong pin is worse than a missing one. And because the annotator runs on someone else's origin, it cannot hold a normal session, so it carries a per account token embedded in your own bookmarklet and every write is pinned server side to the account that token belongs to.
Who It Is For
Anyone who has to explain a page to someone who will edit it later. Developers inheriting a codebase, SEO consultants handing work back to an in house team, content teams who keep being asked why a heading is phrased that way.
It is most useful on the pages that get touched by people who did not build them, which is to say the templates.
- Not a comment system. There is no threading, no mentions and no review workflow. A note is a record, not a conversation.
- Not shared between accounts yet. One account owns its notes, and handover happens through a Markdown, CSV or JSON export. Team access is the obvious next thing and is not built.
- Not a way to annotate a site you cannot open. It runs inside the page, so you need to be able to load the page yourself.
Status And Access
It is live, anyone can sign up, and the annotator itself is free.
Status and access
- Status
- Live
- Address
- why.jakelabate.com
- Sign-in
- GitHub, or an email address with a password or a sign in link.
- Cost
- Free
- Stored data
- Your notes, against your account, behind row level security. Nothing about the pages you visit is collected beyond the notes you write.
- Without an account
- It still runs. Notes stay in that browser and can be exported by hand.
- Can you use it today
- Yes. Sign in, drag the bookmarklet to your bar, and click it on any page.
The Stack
A static front end, a small database, and one endpoint that exists only because of where the annotator has to run.
Stack
- Front end
- Static HTML, CSS and JavaScript. The annotator is a single dependency free file that builds its interface in a shadow root.
- Backend
- Supabase Postgres, plus one edge function handling pull, push and delete for token holders.
- Auth
- Supabase Auth. GitHub OAuth, email and password, or a one time sign in link.
- Storage
- Postgres with row level security scoped to the account, and localStorage on the annotated page as an offline cache.
- Hosting
- GitHub Pages, served at why.jakelabate.com.
- Repository
- Public.