A visual bug is a mismatch that affects how a page is presented: an overlapping control, clipped heading, misplaced panel, or unreadable state. A useful report shows where the mismatch appears, the conditions that produce it, and the intended result. This guide focuses on the evidence a designer or developer needs to investigate layout defects.
Identify the visual mismatch and its effect
Start with what a person can observe. “The menu covers the form’s Submit button at this width” is a visual finding. “The z-index is wrong” is a possible diagnosis. Keep those separate unless you have investigated the implementation. The report should remain useful even if the eventual cause is a long label, a font-loading change, or an unexpected container size.
| Defect | What to show |
|---|---|
| Clipping or overflow | The cut-off content and the container boundary |
| Overlapping controls | Both controls, their open state, and the blocked action |
| Unexpected wrapping | The actual text, viewport width, and intended reading order |
| Misaligned repeated components | Two comparable examples and the approved relationship |
| Unreadable state | The foreground, background, and the state that changes them |
Describe the consequence: is the action impossible, the text ambiguous, or the page simply inconsistent with an agreed design? These details help the team decide what needs immediate attention. A tiny alignment difference and a hidden purchase action can share the same screenshot format while requiring very different decisions.
Capture the conditions that change the layout
Record the release, URL, browser, operating system, viewport dimensions, zoom, and relevant state. Include the content sample when it matters, such as a long product name or translated label. A screen’s physical resolution is not necessarily the browser viewport; capture the dimensions of the area displaying the page.
- Keep menus, banners, tooltips, and dialogs in the state that exposes the issue.
- Record whether the account is signed in, whether consent has been chosen, and whether the list is empty or populated.
- Note font-loading or image-loading timing if the layout changes while you watch.
- Resize gradually and record where the mismatch begins or disappears.
- Try a second relevant browser or device when available; explicitly mark conditions you have not tested.
Chrome Device Mode and Firefox Responsive Design Mode let teams inspect different viewport sizes. Use them to narrow the conditions, then check a real device when the issue involves touch input, browser chrome, or other behavior that simulation may not reproduce.
Choose a reference that can answer the design question
Link the approved design, component specification, or documented behavior. Identify the relevant frame or section and explain the intended relationship. A screenshot from an earlier release is useful only if that release was correct. An unapproved mockup should not silently become the acceptance criterion.
Compare like conditions: the same content, viewport, zoom, and component state. If the mockup uses a two-word heading and the live page uses a sentence, first ask how the component should handle real content. The acceptance criterion may be “the title remains readable without covering the action” rather than exact line breaks at every width.
Accessibility criteria can provide a more precise reference for certain issues. W3C explains reflow and minimum text contrast in its WCAG understanding documents. Link the relevant criterion when it applies and ask for evaluation at the required scope. A screenshot alone cannot demonstrate keyboard access or complete accessibility conformance.
Attach context first, then a focused detail
Capture enough of the page to locate the issue. A close crop of a misplaced icon may hide the panel that positioned it. Attach a second detail image if necessary, label the affected element, and preserve an unedited view when markup obscures the evidence. State which image is the observed result and which is the reference.
Use a short recording when opening, scrolling, or resizing produces the defect. Begin just before the action, make the issue visible, and stop. Add a written description so the recipient can understand the finding without replaying the recording several times. A long tour of unrelated pages makes the failure harder to locate.
Visual finding: The cookie banner overlaps Continue. Conditions: Staging rc-9; 390 × 844 viewport; consent not chosen. Observed effect: The main checkout action cannot be read or selected. Reference: Continue must remain available while the consent choice is open. Evidence: Full viewport screenshot; short clip opening the banner. Verification: Repeat with banner open and closed, plus nearby widths.
Annot8 can pin the report to the affected element and attach screenshots with page and browser context. Paid plans add screen recording. Captured diagnostics can aid investigation, but they do not prove that a nearby console error caused the visual defect. Review attachments for private content before sharing.
Verify the relationship after the fix
Repeat the original conditions on the corrected build, then check nearby widths and related component states. Look for a fix that merely shifts the overflow elsewhere. If a shared component changed, sample its other uses with both short and long content. Record the outcome and build so the report has an actual verification record.
Automated screenshot comparisons can help teams notice changed presentation, but a changed image still needs interpretation. Intentional copy updates, animation timing, and dynamic data can all affect the comparison. Keep stable test data and agreed baselines, and use human review to decide whether the change violates the intended behavior.
Download the visual defect evidence worksheet (.txt)
Use the general bug report template for reproduction details
