How to report UI bugs designers won't dispute

You file a ticket that says "the checkout button looks off". Two days later the designer replies: "Looks fine to me." The developer adds: "Cannot reproduce." The ticket is closed.

Nothing was wrong with your eye. The problem was your evidence. A UI bug report is an argument, and "looks off" is not an argument. This guide shows you how to turn a feeling into a fact.

Short version

• Never write "looks off". Write the number you measured and the number the spec says.
• Name the design file frame and paste a direct link to it.
• Take a measurement screenshot with browser DevTools open so the pixel value is visible.
• Put design and build side by side in one image.
• Check states too, not just the default look: hover, focus, disabled, empty, error.
• If the spec itself is wrong, that is a design change request, not a bug. Route it differently.

---

Why "this looks off" gets rejected

A designer reading "looks off" has no way to check your claim. They open the page, glance at it, and it looks normal. They are not being difficult. They have nothing to compare.

Every strong UI bug report answers the same three questions:

1. What does the spec say? The design file value.
2. What does the build do? The measured value in the browser.
3. Where can I see both? A link to the frame and a link to the page.

If your report answers all three, there is nothing left to dispute. The gap is either real or it is not, and anyone can check in 30 seconds.

---

The three UI bug types

Almost every visual bug falls into one of three buckets. Naming the bucket helps the developer know where to look.

1. Spacing and size mismatch

The element is the wrong size, or the space around it is wrong. This is the most common type and the easiest to prove, because you can measure it.

Weak: Button padding looks small

Strong: Primary button padding is 12px top, spec says 16px

Note the shape: what you measured, then what the spec says. Two numbers, no opinion.

2. Design token mismatch

A design token is a named value from the design system, like a colour or a font weight. Instead of writing #111827 everywhere, teams give it a name such as --color-text-primary. When the build hard-codes a value instead of using the token, you get a near-miss that is hard to see but easy to prove.

Weak: Heading colour looks a bit light

Strong: Heading uses #1F2937, token --color-text-primary is #111827

Font weight is the same story. A heading set to weight 500 instead of 600 looks "slightly thin" but reads as a real defect once you name the numbers.

Strong: Section heading renders at font-weight 500, the H3 style in the design system is 600

3. Missing or wrong state

A state is how an element looks in a specific situation: hover (pointer over it), focus (selected by keyboard), disabled, empty (no data yet), and error. Designers spec these states, and builds skip them constantly, because you only see them if you go looking.

Strong: Focus ring missing on the email input at https://staging.example.com/signup — press Tab from the name field and no outline appears

That last part matters. Say how to trigger the state, or the reader will not see what you saw.

---

Reference the exact design frame

"Check the design" is not a reference. Design files have hundreds of frames, and half of them are old.

Give three things:

1. The frame path, exactly as it is named: Checkout / Payment / Desktop
2. A direct link to that frame, copied from the design tool, not a link to the file root.
3. The component name if the bug is in a shared component, such as Button / Primary / Default.

Write it like this in your ticket:

Spec: Checkout / Payment / Desktop, component Button / Primary / Default Build: https://staging.example.com/checkout/payment

Now the reader opens two tabs and compares. That is the whole job of a UI bug report.

Also check the frame's last edit date. If the design changed after the build shipped, the developer is not at fault, and your ticket should say so.

---

How to take a measurement screenshot

A screenshot of the page proves nothing on its own. A screenshot with the measurement visible proves everything.

Here is the fastest way in Chrome or Edge:

1. Open the page at the size the design was made for. If the frame is Desktop, use a 1440px wide window. A bug that only exists at 1280px is a different bug.
2. Right-click the element and choose Inspect. DevTools opens with the element selected.
3. Look at the Styles panel on the right and scroll to the box model diagram at the bottom. It shows padding, border, and margin in pixels.
4. Take the screenshot with DevTools still open, so the numbers are in the image.
5. Circle or arrow the number that is wrong. One mark, not five.

If your team uses a ruler or pixel overlay extension, that works too. The rule is simple: the number must be in the image, not only in your sentence.

For colours, click the small colour square next to a color value in DevTools. It shows the exact hex. Paste that hex into your report.

---

Show design and build side by side

One image with both versions ends most arguments before they start.

Keep it simple. Put the design frame on the left, cropped to the element, and the build screenshot on the right, cropped the same way. Use the same zoom level on both, or the comparison is useless. Label each side: "Spec 16px" and "Build 12px".

Avoid red overlays stacked on the screenshot. They are hard to read, and people end up arguing about the overlay alignment instead of the bug.

---

Say what the spec says versus what the build does

This is the core sentence of every UI bug report. Get it right and the rest is detail.

The shape:

[Element] on [page] is [measured value]. Spec [frame name] says [spec value].

Here is what that fixes in practice.

Every row in the right column has a page URL, a measured value, and a spec source. Copy that pattern.

Collecting the surrounding evidence takes longer than writing the sentence. Tools like Crosscheck capture the screenshot, console logs, network requests, and browser details straight from the page, so you only add the measurement and the frame link by hand.

---

Bug or design change request

This distinction saves a lot of bad feeling between teams.

It is a bug when the build does not match the spec. The design says 16px, the build ships 12px. Someone made a mistake in code. This goes to the developer, in the bug tracker, with the evidence above.

It is a design change request when the spec itself is wrong. The build matches the design exactly, but the result is bad: the text is unreadable at 12px on mobile, or the error message is cut off in German. Nobody wrote wrong code. The design needs a decision.

Sending a design change request to a developer as a "bug" is how tickets bounce for a week. The developer checks the spec, sees the build matches, and closes it as invalid.

Route it like this:

1. Compare build to spec first. Always.
2. If they differ, file a bug against the build. Include frame link and measurement.
3. If they match but the result is still wrong, file it as a design request. Describe the user impact, not the pixel value: "Error text at 12px is unreadable on a 360px phone screen."
4. If you are unsure which it is, say so in one line: "Build matches spec, but flagging because the contrast may fail WCAG AA." That sentence gets a fast answer from the designer.

---

A short checklist before you file

Read your ticket and confirm each item:

1. Does it name the exact element and page URL?
2. Does it contain a measured value with a unit, or a hex code, or a font weight number?
3. Does it name the spec value and where that value comes from?
4. Is there a link to the exact frame, not the file root?
5. Does the screenshot show the measurement, not just the element?
6. Did you check the states: hover, focus, disabled, empty, error?
7. Is this a build mistake or a design decision, and did you route it accordingly?

Seven yeses and your ticket is very hard to argue with.

---

Frequently asked questions

What if I cannot open the design file? Ask for view access, or ask the designer to paste the spec values into the ticket. A UI bug with no spec source usually turns into a long comment thread.

Do I need to measure every small difference? No. Measure anything you would defend in a review. A 1px difference is often rounding from the browser and is not worth a ticket.

What if the design file has no state defined? Then it is not a bug yet. File it as a question or a design request: "No focus state is specced for the email input. What should it be?"

Should one ticket cover several UI bugs on the same page? Only if they share one root cause, such as one component used in five places. Otherwise file separately, because they may be fixed by different people.

How do I report a bug that only appears at certain screen widths? Put the width in the title and the report: "Plan cards overlap at 1024px width". Then include the window size in your screenshot so it can be reproduced exactly.