Visual Troubleshooting

When the code runs but doesn't look right. This guide covers common visual issues and how to describe them to Claude.

"It Looks Wrong"

Start by describing the gap

This doesn't look right.
Expected: [what you wanted]
Actual: [what you're seeing]

Be specific:

• "The button is too far left"
• "There's unexpected space below the header"
• "The text is overlapping the image"

Layout Issues

Things aren't where they should be

Common causes:

• Flexbox/Grid alignment settings
• Margin/padding issues
• Parent container constraints
• Position property conflicts

Overlapping elements

[Element A] is overlapping [Element B].
They should be [side by side / stacked / spaced apart].

Unexpected gaps or no gaps

There's too much space between [element A] and [element B].
I want them closer together.

Or:

[Element A] and [element B] are touching.
There should be space between them.

Content overflowing

The [text/image/content] is overflowing its container.
It should [wrap / scroll / be cut off].

Sizing Issues

Element too big or too small

The [element] is [too big / too small].
It should be [expected size].

Not respecting container

Image aspect ratio

The image is [stretched / squashed / cut off].
It should maintain its aspect ratio.

Text too large or small

Responsive Problems

Broken at certain sizes

The layout breaks at around [width]px.
[Describe what goes wrong]

Mobile issues

On mobile, [describe the problem].
Expected: [what should happen]
Actual: [what happens]

Columns not adjusting

The columns should [stack / reduce] on smaller screens
but they're [staying in a row / overflowing].

CSS-Specific Issues

Styles not applying

Common causes:

• Specificity conflicts
• Typo in selector
• Style being overridden
• Wrong element targeted

Hover/focus states not working

The hover state on [element] isn't working.
Nothing happens when I hover.

Animations not playing

The animation on [element] isn't playing.
Expected: [describe expected animation]
Actual: [nothing happens / partial animation]

Dark mode colors wrong

In dark mode, [element] still has [light/wrong] colors.
It should be [expected color].

SwiftUI-Specific Issues

Views not updating

I change [value] but the view doesn't update.
It should show [expected change].

Layout priorities

[View A] is taking too much space.
[View B] should have priority for space.

Safe areas

The content is [behind the notch / under the home indicator].
It should respect safe areas.

Preview vs simulator

It looks right in preview but wrong in simulator.
[Describe the difference]

Debugging Steps

1. Isolate the problem

Is this issue specific to [element] or affecting multiple things?
Help me narrow down where the problem is.

2. Check the obvious

3. Use browser dev tools (Web)

Help me use browser dev tools to debug this.
What should I look for?

4. Ask for explanation

Why might [element] be displaying like this?
What could cause [behavior]?

Describing Visual Problems

Be specific

• Bad: "It looks weird"
• Good: "The card has extra space on the right that shouldn't be there"

Reference location

• Bad: "The text is wrong"
• Good: "The heading in the top navigation is cut off on the right side"

Include context

• Bad: "It's broken"
• Good: "On screens narrower than 600px, the grid items overlap instead of stacking"

Show what you expected

• Bad: "Fix the layout"
• Good: "The sidebar should be 250px wide and the content should fill the rest"

Quick Checks

Web layout

• Is the parent container sized correctly?
• Is flexbox/grid set up right?
• Are there conflicting margins?
• Is the viewport meta tag present?

SwiftUI layout

• Is the view in the right container (VStack/HStack/ZStack)?
• Are frame constraints correct?
• Is alignment set on the stack?
• Are spacers in the right places?

General

• Is the content too long/tall for the space?
• Is something hidden behind something else?
• Is z-index/layering correct?
• Is it a caching issue? (hard refresh)

What You'll Learn

• How to describe visual problems clearly
• Common causes of layout issues
• Platform-specific debugging approaches
• Using dev tools for visual debugging
• Quick checks for common problems

Exercises

1. Take a visual issue in your current project and rewrite your description using all four "Describing Visual Problems" patterns (be specific, reference location, include context, show what you expected).
2. Run the matching quick-checks list (web or SwiftUI) against a layout that's behaving and confirm you can answer each question — this builds the mental checklist for when one breaks.
3. The next time something "looks wrong," use the "Start by describing the gap" template with concrete Expected/Actual values before asking Claude to fix it.