The short answer
A useful responsive issue report names the route, viewport width in CSS pixels, content, and interaction that expose the problem. Explain the expected behavior at that width, then verify the fix at nearby widths and with the same content.
1. Find the width where the problem starts
Open the actual flow and slowly narrow the browser. Record the first width where an action disappears, a label overlaps, or a panel creates unwanted horizontal scrolling. “Broken on mobile” could describe several different layouts and gives an implementer little to reproduce.
Record the viewport in CSS pixels rather than the screenshot’s exported pixel dimensions. Include browser zoom and any important browser details. If you found the issue on a physical device, include its orientation and test the same task there again after a fix. Device names alone do not identify the available layout space.
2. Include the content and state
Use the same long name, validation message, or populated table that exposed the issue. A screenshot of an empty screen may hide the condition that broke the original layout. Replace private information with fictional content of a similar length before sharing it.
Describe the interaction as well as the final picture. A navigation drawer might cover the action only after opening a submenu. A form might work until an error appears. Record the shortest sequence that reaches the state, and distinguish a reproducible failure from an intermittent observation.
Route: /projects/new
Viewport: 390 CSS px wide, 100% browser zoom
State: project name contains 70 characters
Steps: enter the name, leave Owner empty, select Create
Observed: the validation row pushes Create outside the panel
Expected: the message wraps and Create remains reachable
Preserve: validation rules, labels, and existing button variants
Verify: repeat at 390px, then check 360px, 430px, and desktop3. Define the responsive intent
Say which relationship should survive as the screen gets smaller. For example, the action should remain after the field it submits, the menu should remain dismissible, and a label should stay associated with its control. These constraints are clearer than an isolated request to reduce padding.
Avoid requiring every table to fit into one narrow column. Some content needs a two-dimensional presentation. Decide whether the appropriate response is wrapping, a simpler summary, a different layout, or a clearly bounded scroll region. W3C’s reflow guidance describes the accessibility requirement and its exceptions; one screenshot does not establish conformance.
4. Check the original state and its neighbors
An agent can make one viewport look correct by introducing a rule that fails just above it. Repeat the original task and inspect widths on either side of the reported failure. Check a second consumer if the change touches a shared layout or control.
Keep the verification note with the accepted correction. CRRT can preserve a selected element and visual feedback for a coding-agent handoff. The reviewer should still confirm the result in the running product and record any device or interaction that remains untested.
- Use the same content and validation state as the report.
- Check keyboard access and whether actions remain reachable.
- Confirm the desktop layout still follows the approved design.
- Separate new observations from the original issue before closing it.
Common questions
Is testing common phone and desktop widths enough?
It is a useful start, but layouts can fail between preset sizes. Check near the width where the problem appears and repeat the real interaction.
Should every horizontal scrollbar be removed?
No. Some content, including certain tables and diagrams, needs two-dimensional layout. Identify whether scrolling is necessary, bounded, and understandable.
Sources & further reading
Written with AI assistance. Tool references checked against the linked documentation on November 2, 2026. Examples are starter templates to adapt and review in your own project.