We built a small feature this week that explains a term to a reader the first time it shows up in a post. It was built with a real problem in it, and the reason is more interesting than the bug itself.
What it was supposed to do
The idea was straightforward: the first time a post says "AI teammate," a reader who wants more context can get a short definition without leaving the page. Hover over it, see the definition, keep reading. Simple, and it checked out fine by hand.
What was actually wrong
It checked out fine because it was checked by hand, with a mouse. The component was hover-only, which means it had no way to open on a touch screen at all. Not worse on mobile, not fiddly on mobile, genuinely unreachable on mobile, because there's no hover state to trigger on a phone.
That's not a small miss. Most web traffic in general is mobile, and there's no reason blogs would be an exception. The feature, as built, would have explained the category to whoever happened to be checking it with a mouse, and stayed unreachable to everyone checking it with a thumb. It looked finished. It worked when you checked it the way you'd naturally check it, at a desk, with a mouse. It just didn't work on the device most readers would actually be holding.
The bug wasn't in the code path anyone checked. It was in the assumption about who'd be doing the checking.
What we changed
The first fix attempt was a reasonable guess: assume the synthetic mouse event browsers fire on a tap was opening the popup, and a click handler was immediately toggling it shut afterward. Plausible, worth trying. It changed nothing. The bug failed exactly the same way after the fix as before.
The second attempt didn't guess. It instrumented the actual sequence of events firing on a real tap and read them in order: pointer enters, pointer down, pointer up, pointer leaves, then a synthetic mouse-enter, then focus, then the click. Focus was opening the popup before the click handler ever ran, so the click handler was closing something focus had just opened a moment earlier. Once the real order was visible, the fix was obvious: stop the click handler from toggling something focus already opened.
Real tap support went in alongside it: tap opens the definition, tapping outside or pressing escape closes it, hover and keyboard still work for anyone using those. Verified on an actual touch-only device profile, not assumed to work because the code looked like it should.
The second bug, and the harder one to verify
A related issue turned up in the same pass: the popup could run off the edge of the screen, horizontally if a term fell near the end of a line, vertically if a term sat high on the page. Both got a fix. Verifying the vertical one took four attempts, and the first three failed because the test was wrong, not the code.
The first attempt used an automated test tool's built-in hover, which quietly scrolls the page to bring the element into view first, so there was no way to control where the term actually sat on screen. The result meant nothing before the test even ran. The second attempt tried to simulate the interaction directly and nothing opened at all, because the framework listens for a different, related signal that the simulated one doesn't reliably produce. The third attempt checked a computed style property to see whether the popup had flipped position, and got a clean, consistent answer every time: flipped, in all eight cases tested. That answer was wrong. The property reports the browser's resolved value on an element that's already positioned, not the instruction that would actually reveal what happened, so it returned the same false answer regardless of what was really on screen. It looked like a real result because it was consistent. A test that fails the same way every time is easy to mistake for a working test.
The fourth attempt stopped trusting an indirect signal and measured the actual geometry instead: whether the popup's edge landed above or below the term's edge, in pixels. Unambiguous, and it settled it, across multiple terms and scroll positions, the popup flips when it needs the room and stays put when it doesn't.
A related case, with a different outcome
The same touch assumption showed up in a similar feature elsewhere, and it didn't fail the same way twice. A hover gloss on the same term lives on twenty-four links in the help center, with the identical touch problem, no hover state to trigger. But there, tapping the term does something rather than nothing: it navigates to the full definition article instead of going silent. Same root assumption, two different outcomes, because one component happened to be a link underneath and the other wasn't.
Why this is worth writing down
Nobody missed this by being careless. It's the natural result of building and checking on the same kind of device, which is easy to do without noticing you're doing it. But the sharper lesson isn't about testing on more devices. It's that a plausible guess at a cause produced a fix that changed nothing, and a test that failed consistently turned out to be measuring the wrong thing entirely rather than reporting a real result. Both times, the thing that actually worked was refusing to trust an indirect signal and measuring the real thing directly instead.
This is also just what the team that built this feature looks like when the work is a bug fix instead of a deadline: written up honestly, including the parts that didn't work on the first, second, or third try.