A useful UI bug report lets another person reach the same interface state, see the problem, and determine whether a fix resolves it. Include the exact build, relevant viewport, reproduction steps, expected and actual behavior, visual evidence, and acceptance criteria.
Copy the template below into your issue tracker. The worked examples are illustrative; they do not describe defects found in a tested product.
Copy this UI bug report template
Remove fields that do not help reproduce the issue. A theme-dependent contrast problem needs the theme; an overlapping sticky footer needs viewport height. Record what you actually observed, and leave unknown information labeled unknown.
Example 1: A long name covers a row action
This illustrative report isolates a content-dependent layout failure.
Title: Project list: long project name covers the row menu at narrow widths.
Environment: Review preview at revision <commit>, viewport 390 × 844 CSS pixels, 100% zoom, light theme. Record the actual browser and OS versions when reproducing.
Preconditions: A project exists with the name “International partner onboarding and documentation workspace.” The reviewer can access the project list.
Steps:
- Open the project list.
- Set the viewport to the recorded width and height.
- Locate the row with the long project name.
- Attempt to open its actions menu.
Actual behavior: The project name extends across the menu control. The control is partially covered and cannot be reliably selected in the affected area.
Expected behavior: The project name wraps or truncates according to the row's documented design. The menu remains visible and operable. Attach the reference row or acceptance criterion.
User impact: A person with a long project name cannot reliably access rename and archive actions from the list.
Evidence to attach: A screenshot of the full list at the recorded viewport and a crop showing the affected row. These attachments are instructions for using the example, not supplied test evidence.
Acceptance criteria:
- The long-name case leaves the menu visible and operable.
- A short project name retains the intended alignment.
- The row behaves correctly at the next relevant layout breakpoint.
- The selected wrapping or truncation behavior matches the reference.
Do not prescribe overflow-hidden as the report's expected behavior. That is one possible implementation decision, and it might conceal content the design intends to show. State the outcome first.
Example 2: A modal action becomes unreachable
This illustrative report focuses on a state change inside a height-constrained surface.
Title: Invite dialog: validation message pushes the submit action below the reachable area.
Environment: Review preview at revision <commit>, viewport 1280 × 600 CSS pixels, 100% zoom. Record the actual browser, OS, and theme.
Preconditions: The reviewer can invite teammates. The dialog begins with empty fields.
Steps:
- Open the invite dialog.
- Enter an invalid email address.
- Submit the form to display validation feedback.
- Attempt to reach the submit action using the dialog's intended scrolling behavior.
Actual behavior: The validation message increases the form height. The submit action moves below the visible dialog boundary, and the dialog provides no way to scroll to it.
Expected behavior: The validation message and the submit action remain reachable within the available viewport. Attach the dialog behavior specification or the approved component example.
User impact: The user cannot see the action needed to complete the invitation after correcting the address.
Evidence to attach: A recording from opening the dialog through displaying the error, plus a screenshot that includes the dialog boundary.
Acceptance criteria:
- The action remains reachable after the validation message appears.
- Longer validation copy remains readable.
- Keyboard navigation can reach the action with visible focus.
- The initial dialog state still follows the intended layout.
Make the evidence match the claim
A crop establishes a local detail; a full screenshot establishes where that detail appears. Include both when the surrounding layout explains the failure. Use a recording when the problem depends on a transition, scrolling, or the order of actions.
Avoid calling a source-code suspicion a reproduced visual defect. Write “possible overflow based on the width constraint; render not yet checked” until you have observed the result. Keep console errors only when they help explain or reproduce the reported issue.
Put the template where reviews happen
GitHub repositories can offer issue templates when contributors create an issue, so teams can make this format part of their normal reporting process. GitHub issue documentation
Use the design QA checklist to find issues and this template to document each confirmed failure. If findings originate in Design Bug Bot, preserve the evidence and verify proposed changes against the report's acceptance criteria.