5 min read
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
The [element] should be [position] but it's showing [actual position].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
The [element] should fill its container but it's [too small / too big].Image aspect ratio
The image is [stretched / squashed / cut off].
It should maintain its aspect ratio.Text too large or small
The text is [too small to read / too large for the space].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
I'm trying to style [element] but the styles aren't showing.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
Can you check if [element] has the right [property]?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