The Art of Polish: When AI Meets Human UX Intuition
June 28, 2025 - Part 3
Where We Left Off
In my previous post, I documented the surprisingly competent start to building this blog with Claude 4. We had a solid foundation: authentication, content management, and 129 passing tests. But having functional code and having a delightful user experience are two very different things.
What happened next taught me something profound about the intersection of AI capabilities and human design intuition.
The UI Reality Check
The blog worked. It rendered posts, handled authentication, and looked… fine. Phoenix’s default styling with our Catppuccin theme created something that wouldn’t embarrass anyone. But “not embarrassing” isn’t the same as “compelling.”
Looking at the initial layout, I realized we had fallen into the classic developer trap: building feature-complete software that nobody actually wants to use.
The homepage felt cramped. The blog post reading experience was cluttered with unnecessary navigation. The markdown content looked like plain text. This needed work.
The Great Markdown Mystery
The first major issue hit me immediately when viewing a blog post:
The markdown wasn’t rendering.
Well, it was rendering—but not in any meaningful way. Headers looked like regular text. Lists showed up as plain paragraphs. Code blocks were invisible. Despite having markdown content in our seeds and a proper render_content function, everything displayed as unstyled HTML.
This is where the collaborative debugging process got interesting.
Me: “The markdown is being rendered but the styling isn’t working.”
Claude: Immediately identifies the issue - “The @tailwindcss/typography plugin is missing. Without it, the prose classes don’t actually style anything.”
Five minutes later: typography plugin installed, custom Catppuccin prose styling added, assets rebuilt. Problem solved.
But here’s what struck me—I would have spent at least an hour digging through CSS, questioning my markdown library choice, maybe even rebuilding the content rendering system. Claude identified the exact root cause instantly and implemented the perfect fix.
This is where AI shines: systematic problem diagnosis without the emotional attachment to previous decisions.
The Refinement Dance Begins
With markdown properly rendering, I started making requests that would test Claude’s UX sensibilities:
Round 1: “This feels cramped”
Request: “Remove the Phoenix header and widen the content container.”
Result: Header gone, container expanded from 896px to 1152px. Clean and immediate.
Round 2: “I don’t like this text preview fade effect”
Request: “Remove the text preview and replace it with subtitles.”
This triggered a surprisingly sophisticated response:
- Database migration for subtitle field
- Post model updates
- Template modifications
- Data migration script for existing posts
Within minutes, we had a complete feature addition with backward compatibility.
Round 3: “Actually, bring back the preview but keep the subtitles”
Request: “Reintroduce the content preview with fade effect alongside subtitles.”
What impressed me: No complaints about changing direction. No “but we just removed that.” Just implementation.
This back-and-forth continued for dozens of iterations, each one refining the experience:
- Adjusting fade effect aggressiveness (5 different versions)
- Fine-tuning hover effects and shadow blur
- Perfecting the spacing and padding
- Removing visual elements that didn’t add value
The Blog Post Reading Revolution
The biggest transformation came when I tackled the blog post reading experience:
Me: “I’m not happy with the blog post layout. Let’s make some changes.”
Claude: Enters planning mode “Here are the issues I see and my recommendations for improvement…”
What followed was a complete redesign philosophy:
- Remove all navigation clutter during reading
- Use full viewport width for content
- Implement a floating back button
- Optimize typography for long-form reading
- Center content with proper line length
The result? A reading experience that went from “functional” to “I actually want to read this.”
The Devil in the Details
The most fascinating part of this process was watching Claude handle the micro-interactions:
The Hover Highlight Issue
Me: “The hover highlight looks good, but there’s a subtle visual problem…”
I struggled to describe it. The fade effect was creating an “underlining” appearance because it didn’t cover the full hover area.
Claude: Immediately understands - “The fade effect div isn’t covering the full clickable area. Let me extend it to match the hover zone.”
Fixed in one try.
The Background Simplification
What started as a complex layered design with containers and shadows evolved into something much cleaner:
- Removed content area backgrounds
- Simplified color palette
- Eliminated unnecessary separators
- Extended content to viewport edges
Each change made the interface feel lighter and more focused.
What This Process Revealed
After 50+ UI iterations, several patterns emerged:
1. AI Excels at Immediate Implementation
When I said “make the fade effect less aggressive,” Claude didn’t need clarification. It understood the design intent and implemented appropriate changes instantly.
2. Human Intuition Drives Direction
I couldn’t always articulate why something felt wrong, but I knew when it did. Claude never questioned the feedback—it just implemented solutions.
3. Iteration Velocity is Everything
The speed of the feedback loop was transformative. Traditional web development means:
- Change CSS
- Reload browser
- Evaluate
- Repeat
With Claude:
- Describe issue
- Watch implementation
- Evaluate
- Repeat
10x faster iteration cycles = 10x more refinement opportunities
4. No Design Ego
Claude never got attached to previous decisions. When I wanted to undo changes or try completely different approaches, there was no resistance—just implementation.
The Collaborative Sweet Spot
The most effective moments came when I provided high-level design intent and Claude handled implementation details:
Me: “I want the content to feel more spacious and less busy.”
Claude:
- Removes horizontal separators
- Increases container width
- Adjusts padding and spacing
- Simplifies color scheme
- Eliminates visual clutter
Me: “Perfect, but now the hover effects need adjustment…”
Claude: Immediately refines hover mechanics without being asked to preserve other elements
This felt less like directing a junior developer and more like collaborating with a design partner who happens to code at superhuman speed.
What Still Required Human Judgment
Despite Claude’s technical prowess, certain decisions required human aesthetic judgment:
- Color choices: “Brighten the background” required my evaluation of what looked better
- Layout proportions: Determining the right balance of white space and content density
- Interaction feedback: Deciding what hover effects “felt right”
- Content hierarchy: Choosing which elements deserved visual prominence
AI can implement any design direction instantly, but it still needs human guidance on which direction to pursue.
The Current State: From Functional to Delightful
After this refinement marathon, we transformed:
Before: A functional blog that worked
After: A polished experience I actually want to use
The homepage now features:
✅ Clean, header-free design with full viewport usage
✅ Sophisticated hover effects with perfect fade alignment
✅ Optimized content width and spacing
✅ Seamless background and color treatment
The blog post experience includes:
✅ Distraction-free reading layout
✅ Floating navigation that stays out of the way
✅ Perfectly rendered markdown with custom styling
✅ Typography optimized for long-form content
The Meta Moment
I’m writing this blog post in the very system we built, using the markdown rendering we debugged, with the typography we perfected, on the reading layout we designed together.
The irony isn’t lost on me: I’m documenting the creation of this blog using the blog itself.
What’s Next
We’ve proven that AI can not only build functional software but collaborate on creating genuinely pleasant user experiences. The combination of human design intuition and AI implementation speed creates something neither could achieve alone.
But questions remain:
- How will this collaboration scale to more complex applications?
- Can AI learn design preferences and anticipate needs?
- What happens when we tackle the deeper challenges of search, filtering, and content discovery?
The next phase: implementing tag filtering and search functionality. Will Claude maintain this level of collaborative finesse when building features that require complex state management and user flow design?
The adventure continues…
This post was written using the very markdown rendering system described within it. Each iteration mentioned actually happened, each refinement actually improved the experience you’re having right now reading this.
Part 4 coming soon: Building Search and Discovery Features