Blog Post

How to Report UI Bugs Effectively

You found a bug. The button is the wrong color, the spacing is off, the card does not match the Figma spec. You write: "The button looks weird on the settings page." Three days later, it is still broken — because nobody knows what "weird" means. The difference between a UI bug that gets fixed in the next sprint and one that rots in the backlog is not severity. It is the quality of the report.

Why Most UI Bug Reports Fail

Most UI bug reports describe a feeling, not a problem. "The spacing looks off." "This doesn't match the design." "The button seems wrong." These reports create a guessing game. The developer opens the page, inspects the element, and has to reverse-engineer what the reporter actually saw — and what they expected instead. Every vague report triggers a round-trip: the developer asks for clarification, the reporter re-explains, days pass. A bug that takes 10 minutes to fix takes 3 days to close because the report was incomplete.

The Anatomy of a Bug Report That Gets Fixed

Effective UI bug reports share five elements that eliminate ambiguity and let developers go straight to fixing.

• What you see — a screenshot of the specific element, plus a written description of the problem. Not "this looks wrong" but "the primary CTA button has a 4px border-radius instead of 8px."
• What you expected — a design reference: a Figma link, a screenshot of the spec, or a description of the previous working state.
• Where it happens — the exact URL, viewport size, and browser. "The homepage" is not specific enough. "https://app.example.com/dashboard at 1440x900 on Chrome 122" is.
• CSS specifics — the actual computed values versus the expected values. Padding, margin, font-size, color, border-radius — whatever is wrong.
• Severity context — is this blocking a release, visible to all users, or a cosmetic edge case? Severity determines priority.

Screenshots Are Not Enough

A screenshot without context creates more questions than it answers. Which element is wrong? What is it supposed to look like? What viewport size was the reporter using? An annotated screenshot — with the affected element highlighted and expected values noted — answers all three. Better yet, capture computed CSS values alongside the screenshot so the developer does not need to open DevTools at all. The metadata matters as much as the image: viewport dimensions, device pixel ratio, and computed styles turn a screenshot from evidence of a problem into a blueprint for the fix.

Environment Details That Actually Matter

UI bugs are often environment-specific. A layout that works at 1440px breaks at 1366px. A font that renders correctly on macOS looks different on Windows. A button that appears fine at 100% zoom clips its text at 125%.

• Browser and version — Chrome 122 and Safari 17 render CSS differently
• Operating system — font rendering varies across macOS, Windows, and Linux
• Viewport size — the exact pixel width and height, not just "desktop" or "mobile"
• Zoom level — 125% zoom is the default on many Windows laptops and causes subpixel rendering issues
• Device pixel ratio — 2x Retina displays handle borders and shadows differently than 1x screens

From Ad-Hoc to Systematic

Teams that report UI bugs consistently — same format, same level of detail, every time — ship fewer visual regressions. The goal is not a 20-field Jira template that nobody fills out. It is a lightweight habit: screenshot, expected values, environment, severity. Four things. Tools like OverlayQA capture all four automatically: click an element, and the tool extracts the screenshot, CSS values, viewport, and browser metadata in one action. The bug report writes itself.