Chapter 3: Polish & Design
Component Polish
Component Polish
Now we'll take the existing components and refine them. This is where your app starts to feel crafted rather than generated.
The polish prompt
"Polish the todo list components. For each todo item: add a subtle bottom border, gentle hover background (surface color at 50% opacity), rounded corners on the container, and increase padding to 12px 16px. The checkbox should use the primary color when checked. Add a smooth transition for the hover state. The overall list should have a card-like container with a light border and subtle shadow."
Notice how specific this prompt is. Instead of "make it look better," we're describing exact visual properties. This gives Claude Code clear direction while still allowing it to make good implementation decisions.
Key polish areas
Borders and shadows
Subtle borders and shadows create depth without being heavy:
"Use 1px borders in border color (from our color system) and box-shadow: 0 1px 3px rgba(0,0,0,0.08) for card elevation. No heavy drop shadows."
Spacing
Generous, consistent spacing makes everything feel calmer:
"Increase the gap between todo items to 2px. Add 24px padding inside the todo list card. Make sure there's at least 32px between the header and the list."
Hover and active states
Interactive feedback tells users "this is clickable":
"Add hover states to all interactive elements. Todo items should get a slight background change on hover. Buttons should darken slightly. The delete button should turn danger-red on hover."
- Container polish — Card wrapper with border, shadow, and rounded corners
- Item polish — Hover states, padding, borders between items
- Checkbox polish — Custom styled, uses primary color, smooth check animation
- Button polish — Consistent sizing, hover/active/focus states
- Empty state — A friendly message when there are no todos
Before and after
Ask Claude Code to make sure the empty state looks good too:
"When there are no todos, show a centered message with a subtle icon that says 'No tasks yet. Add one above to get started.' Make it feel inviting, not empty."
The empty state is often the first thing a new user sees. Making it look polished and helpful sets the tone for the entire app experience.
Reviewing the changes
After Claude Code makes the updates, check:
- Do items feel comfortable to read? (Spacing)
- Is it clear what's clickable? (Hover states)
- Does the hierarchy make sense? (Borders, shadows)
- Does it feel consistent? (Same border radius, same shadow everywhere)
If something feels off, describe what you see:
"The shadow on the card feels too strong. Make it more subtle — barely visible."
"The hover state is too abrupt. Slow it down to 150ms."
Small refinements compound into a polished experience. Each tweak might seem minor, but together they transform the app.
Managing context during polish work
Design polish generates many small back-and-forth messages that fill Claude Code's context window quickly. Use /compact between design areas to free up space:
Run /compact after finishing each design area (colors, typography, spacing). Claude Code summarizes the conversation, keeping your design decisions while freeing up context for the next area.