coding

>Debug with Screenshots

debuggingscreenshotsvisual
Source:▶Claude Code Masterclass: From Beginner to Expert|@CS Dojo

You've been staring at your code for hours, and something's clearly wrong with your UI, but you can't quite put your finger on it. The layout is broken, colors are off, or maybe there's a weird spacing issue that's driving you crazy. Instead of trying to describe the visual problem in text, there's a much better approach: show Claude Code exactly what you're seeing.

Claude Code can analyze screenshots directly, making visual debugging faster and more accurate than traditional text-based descriptions. This capability transforms how you troubleshoot UI issues, layout problems, and visual bugs.

Taking Effective Debug Screenshots

The key to successful visual debugging starts with capturing the right screenshot. You want to show Claude Code the complete context of your problem, not just a tiny slice.

Capture the full browser window when dealing with web applications. This gives Claude Code important context about viewport size, browser chrome, and how elements relate to each other:

# On macOS: Cmd + Shift + 4, then spacebar to capture full window
# On Windows: Windows + Shift + S for snipping tool
# On Linux: Screenshots app or gnome-screenshot

Include your developer tools if they're relevant to the issue. A screenshot showing both your broken UI and the console errors provides comprehensive debugging context:

// Example: If you're debugging this React component
function BrokenCard({ title, content }) {
  return (
    <div className="card">
      <h2>{title}</h2>
      <p>{content</p>  {/* Missing closing brace - causes render issues */}
    </div>
  );
}

Take a screenshot that shows both the malformed output and any console errors. Claude Code can spot the connection between syntax errors and visual problems.

Structuring Your Visual Debug Request

Once you have your screenshot, the way you frame your request makes a huge difference in the quality of help you'll receive.

Start with a clear problem statement before sharing the image:

I'm having trouble with my CSS grid layout. The items aren't aligning properly and there's unexpected spacing. Here's what I'm seeing: [screenshot]

Current CSS:
```css
.grid-container {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 20px;
  padding: 20px;
}

.grid-item {
  background: #f0f0f0;
  padding: 15px;
  border-radius: 8px;
}

This approach gives Claude Code both the visual evidence and the relevant code context needed to provide targeted solutions.

Include your expected behavior alongside the screenshot. You might say: "The cards should be equal height and evenly spaced, but as you can see in the screenshot, the third card is shorter and there's extra space on the right."

Common Visual Debugging Scenarios

Layout Issues: Screenshot your broken layouts and include the relevant CSS. Claude Code can spot issues like incorrect flexbox properties, grid configuration problems, or positioning conflicts that cause visual chaos.

/* This might look fine in code but create visual problems */
.sidebar {
  position: fixed;
  width: 250px;
  height: 100vh;
  background: #333;
  z-index: 1000;
}

.main-content {
  margin-left: 250px; /* What if viewport is smaller? */
  padding: 20px;
}

A screenshot immediately reveals if your sidebar is covering content on smaller screens or creating horizontal scroll issues.

Color and Theming Problems: Screenshots capture color rendering issues that are impossible to describe accurately in text. Claude Code can analyze contrast problems, color scheme conflicts, or theme switching bugs.

Mobile Responsiveness: Take screenshots at different viewport sizes to show how your responsive design breaks. Claude Code can suggest specific media query adjustments based on what it sees going wrong.

Advanced Screenshot Debugging Techniques

Before and After Comparisons: When you make changes that break something, include screenshots of both the working state and the broken state. This helps Claude Code understand what changed and suggest targeted fixes.

Multi-Device Screenshots: If you're dealing with cross-device compatibility issues, include screenshots from different devices or browsers. Claude Code can spot device-specific problems and recommend appropriate solutions.

Animation and Interaction Issues: For problems with animations or interactions, take screenshots at different states. Show the starting position, mid-animation, and end state to help Claude Code understand timing or transition issues.

/* Animation that might cause visual problems */
.button {
  transition: transform 0.3s ease;
}

.button:hover {
  transform: scale(1.1) rotate(5deg);
  /* This might cause layout shifts or clipping */
}

A screenshot showing the button in its hovered state might reveal that it's getting cut off by its container.

Pro Tips for Screenshot Debugging

Annotate when necessary: Use your OS's built-in annotation tools to highlight specific problem areas in your screenshots. A red arrow pointing to a misaligned element saves Claude Code from guessing what you're concerned about.

Include relevant browser information: If you're dealing with browser-specific issues, mention which browser and version you're using alongside your screenshot. Different rendering engines can cause identical code to display differently.

Show the code in context: Don't just share a screenshot and ask "fix this." Include the specific code that's generating the visual output. Claude Code works best when it can see both the visual result and the source code.

Capture error states: If your app shows error messages, loading states, or empty states that look wrong, screenshot those too. These edge cases often reveal important usability and design problems.

Common Pitfalls to Avoid

Screenshots that are too zoomed in: If you crop too tightly, you remove important context. Claude Code might not be able to understand how your problem element relates to its parent containers.

Forgetting to include responsive issues: Don't just screenshot your desktop view. Mobile and tablet layouts often reveal different problems that need different solutions.

Mixing multiple problems: If you have several visual issues, create separate screenshots for each problem. This helps Claude Code provide focused solutions rather than trying to address everything at once.

What's Next

Once you've mastered visual debugging with screenshots, you can expand into more advanced debugging techniques. Consider exploring Claude Code's ability to analyze network request screenshots for API debugging, or combine visual debugging with code analysis for complex full-stack issues.

You might also want to learn about systematic debugging workflows that combine screenshots with console output analysis, making your debugging process even more efficient and comprehensive.

←cd ~/tips