Session 10: When Things Break

Duration: 2 hours
Prerequisites: Sessions 1-9 completed
You'll need: Leigher project, willingness to break things

---

Why This Session Matters

You've shipped a feature. You know the workflow works.

But things will break. Claude will get confused. Builds will fail. Git will conflict.

The difference between a designer who ships occasionally and one who ships confidently is knowing what to do when things go wrong.

This session teaches you:

• What problems you can fix yourself
• What problems need engineering help
• How to recover and move forward

---

Part 1: Common Failures (30 min)

Failure Type 1: Claude Generates Wrong Output

Symptoms:

• Component doesn't match your design
• Wrong colors, spacing, or patterns used
• Structure is completely off

Why it happens:

• Figma selection wasn't clear
• Documentation is missing or vague
• Claude made assumptions that were wrong

You can fix this:

Try describing more specifically:

That's not quite right. The card should have:
- 20px padding (not 16px)
- The shadow from our card pattern
- The title above the description, not beside it

If Claude keeps getting it wrong, check your documentation:

• Is the pattern documented in component-patterns.md?
• Are the tokens in design-tokens.md?
• Is there a conflicting rule in CLAUDE.md?

Failure Type 2: Claude Gets Confused

Symptoms:

• Claude starts referencing files that don't exist
• Responses become repetitive or circular
• Claude claims it made changes that didn't happen

Why it happens:

• Context window is overloaded
• Previous conversation led down wrong path
• Project state doesn't match what Claude thinks

You can fix this:

Reset the conversation:

Let's start fresh. Ignore everything we discussed before.

I want to create a [component]. Here's exactly what it should do:
[Clear, specific description]

Or close Claude Code and reopen it. Fresh session, fresh context.

Failure Type 3: Build Breaks

Symptoms:

• The dev server crashes
• Browser shows error screen instead of app
• Terminal shows red error messages

Why it happens:

• Claude introduced a syntax error
• A file reference is broken
• Dependencies are missing

Check first:

Ask Claude:

The build is broken. Here's the error:
[paste error message]

What's wrong and how do we fix it?

Claude can often fix its own mistakes if you show it the error.

Failure Type 4: Git Conflicts

Symptoms:

• Can't push changes
• GitHub Desktop shows "merge conflict"
• Files have weird <<<<<< markers in them

Why it happens:

• Someone else changed the same file
• Your branch is out of date
• Two changes touched the same lines

You can try:

Simple case (just out of date):

1. Pull latest changes first
2. Try pushing again

Hand off to engineering:

If you see conflict markers or GitHub Desktop looks confusing, ask for help. Merge conflicts can corrupt files if resolved incorrectly.

---

Part 2: What You Can Fix (30 min)

Visual Problems → Describe What's Wrong

If something looks wrong in the browser, describe it:

"The button text is cut off"
"The shadow looks flat"
"There's too much space below the header"
"The hover state isn't working"
"The colors look washed out"

Claude will fix visual issues through your description. You don't need to know why it's happening technically.

Token Misuse → Check Documentation

If Claude is using wrong values:

"You used #F5F5F5 for the background, but our token is --bg-primary which is #FAF9F7"

Then check: is --bg-primary actually in your design-tokens.md? If not, add it.

Pattern Violations → Update Your Rules

If Claude keeps making the same mistake:

1. Fix it this time via prompt
2. Add a rule to CLAUDE.md or anti-slop directives
3. Now it won't happen again

Example:

• Claude keeps using single-layer shadows
• You fix it: "Use a compound shadow"
• You add to CLAUDE.md: "NEVER use single-layer shadows"

Simple Errors → Ask Claude to Fix

If the browser shows an error:

The browser shows this error:
[screenshot or paste error]

Fix it.

Most syntax errors and simple bugs, Claude can fix immediately.

---

Part 3: What Needs Engineering (20 min)

Build/Deployment Issues

Signs:

• npm install fails
• Deployment to production fails
• Environment variables are wrong

Why it's not your problem:

• These involve infrastructure, not UI
• Wrong fix can break things for everyone
• Requires access you probably don't have

What to do:

• Note what you were doing when it broke
• Share error messages
• Hand off to engineering

Database Problems

Signs:

• Data isn't saving
• Data loads incorrectly
• Errors mentioning database, KV, or storage

Why it's not your problem:

• Database issues can affect all users
• Wrong fix can lose data
• Requires backend knowledge

What to do:

• Don't try to fix database code
• Report what you observed
• Let engineering investigate

API Errors

Signs:

• Network errors in browser console
• "Failed to fetch" messages
• Features work in UI but data doesn't persist

Why it's not your problem:

• API issues are backend concerns
• Could be server, authentication, or networking
• Usually not caused by your UI changes

What to do:

• Verify your UI code is correct (is it calling the right endpoint?)
• Report the error
• Engineering will investigate the backend

Complex Logic Bugs

Signs:

• Feature works sometimes but not always
• Weird state issues (thing appears then disappears)
• Race conditions, timing problems

Why it might not be your problem:

• Logic bugs require reading code
• Could be in code you didn't touch
• Debugging requires developer tools

What to do:

• Document when it happens and when it doesn't
• Provide steps to reproduce
• Let engineering dig in

Architectural Changes

Signs:

• "We need to restructure how this works"
• Changes affect multiple files or systems
• Involves concepts like state management, routing, data flow

Why it's not your problem:

• Architecture affects the whole app
• Wrong decisions compound over time
• Requires full codebase understanding

What to do:

• Design what you need it to do
• Let engineering figure out how
• This is normal collaboration, not a limitation

---

Part 4: Recovery Strategies (30 min)

Strategy 1: Reset Claude's Context

When Claude is confused, start fresh.

Option A: New conversation

/clear

Then start over with a clean description.

Option B: Close and reopen Claude Code

Claude gets a fresh context. Previous confusion gone.

Strategy 2: Revert with Git

Made changes that broke things? Go back.

In GitHub Desktop:

1. Go to History tab
2. Find the last working commit
3. Right-click → "Revert changes in commit"

This creates a new commit that undoes the bad changes.

Or discard uncommitted changes:

1. Go to Changes tab
2. Right-click changed files
3. "Discard changes"

You're back to the last committed state.

Strategy 3: Start Fresh on a New Branch

Sometimes it's faster to start over.

1. Switch to main branch
2. Create new branch: feature/second-attempt
3. Start implementation fresh with lessons learned

Don't delete your old branch yet—you might want to reference what you tried.

Strategy 4: Hand Off Cleanly

When you need engineering help, make it easy for them.

Include:

• What you were trying to do
• What happened instead
• Steps to reproduce
• Error messages (screenshots or text)
• Your branch name

Example handoff:

I was adding a project overview card (branch: feature/project-card).

When I try to click the "New Surface" button, I get this error:
[screenshot]

Steps to reproduce:
1. Go to dashboard
2. Click "New Surface" on the project card
3. Error appears

The card renders correctly, just the button doesn't work.

Good handoffs get faster help.

---

Part 5: Confidence (10 min)

What You Can Ship Independently

You can handle:

• ✅ New UI components
• ✅ Styling changes
• ✅ Layout modifications
• ✅ Content updates
• ✅ Visual polish
• ✅ Simple interactions (hover, click, toggle)
• ✅ Using existing patterns and components

What Needs Support

Ask for help with:

• ❌ Build/deployment issues
• ❌ Database operations
• ❌ API changes
• ❌ Complex state management
• ❌ Authentication/security
• ❌ Performance optimization
• ❌ Architectural decisions

The Right Mindset

You're not a developer. You're not supposed to fix everything.

You're a designer who can ship UI to production. That's a massive expansion of what you could do before. The boundaries aren't limitations—they're clarity about where your new capabilities sit.

When you hit a boundary, hand off cleanly and move on. That's professional collaboration.

---

Session 10 Checklist

• [ ] Understand the 4 common failure types
• [ ] Know what problems you can fix yourself
• [ ] Know what problems need engineering
• [ ] Practiced resetting Claude's context
• [ ] Practiced reverting with Git
• [ ] Know how to hand off cleanly
• [ ] Have confidence in your new capabilities

---

Course Complete

You've finished the Shipping AI Designer course.

You started with: Figma expertise, zero Claude Code experience

You ended with:

• Environment fully configured
• Figma connected to Claude via MCP
• Design system documented for AI consumption
• Anti-slop rules preventing generic output
• Iteration skills for both paths
• Git workflow for shipping
• A real feature shipped to production
• Troubleshooting knowledge for when things break

Your new capability: Figma design → production PR in under an hour.

Welcome to the new era. Now go ship something.

---

Session 10 of 10 • The Shipping AI Designer Course

Course complete.