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 design 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.
Frequently Asked Questions
How do you write a good UI bug report?
A good UI bug report includes five elements: a screenshot of the issue, the expected appearance (from the design spec or design system), the actual appearance (with computed CSS values), the environment (browser, OS, viewport width), and steps to reproduce. Reports with all five elements get fixed in one pass. Reports missing any of them create back-and-forth between the reporter and the developer.
What should a UI bug report include?
At minimum: a screenshot, the URL and viewport width, the element selector or component name, the computed CSS values that are wrong (e.g., padding-top: 12px), and the expected values from the design spec (e.g., padding-top: 20px). The more specific the delta between actual and expected, the faster the fix. Vague reports like "spacing looks off" waste developer time.
Who should report UI bugs — designers or QA engineers?
Both, but at different stages. Designers should report visual discrepancies during design review of staging builds — they have the eye and the spec context. QA engineers should report visual issues found during regression testing. The key is that someone with access to the design spec verifies visual fidelity before merge, not just after launch.
What is the difference between a UI bug and a functional bug?
A functional bug means something does not work: a button does not click, a form does not submit, a page returns an error. A UI bug means something does not look right: the spacing is wrong, the color does not match, the font weight is off. Both need tickets. The difference is that functional bugs are caught by automated tests, while UI bugs require visual comparison against the design spec.