Design Better UI with Claude Code: A Practical Guide

Design better UI with Claude Code by front-loading design specs in the terminal: paste a DESIGN.md at session start, scope each request to explicit file paths, build landing pages section-by-section, and feed browser screenshots back into chat. Claude Code excels at multi-file React UI when constraints are agent-readable — not when you ask for "something modern."

Claude Code is Anthropic's terminal-native coding agent. If you live in the shell, SSH into servers, or prefer conversational CLI over IDE chat, this is your primary UI surface.

What Claude Code is good at for UI

Claude Code operates on your full repository from the terminal. For interface work, that translates to concrete strengths:

Strength	UI impact
Multi-file reasoning	Layout, components, and styles stay consistent across edits
Long context	Paste full DESIGN.md + component inventory once per session
CLAUDE.md persistence	Project-level design rules survive across sessions
Explicit file paths	You direct exactly which routes and components change
Repo-wide refactors	Rename tokens, restructure folders, update imports in one pass

Claude Code does not give you a WYSIWYG canvas. You review in the browser, Storybook, or screenshots. That tradeoff suits developers who already treat UI as code.

What Claude Code does not solve

Without design input, Claude Code produces the same slop as every other agent:

Gradient heroes and generic SaaS card grids
Inconsistent spacing between files edited in different sessions
New font imports on every page
Over-animated hover states

The terminal interface does not cause slop. Missing specs cause slop. Claude Code is particularly good at executing a detailed brief — and particularly bad at inventing taste from "build me a landing page."

The Claude Code UI workflow (start to ship)

1. Prepare the repo

Before opening Claude Code, set up the same foundation you would for Cursor:

your-app/
├── CLAUDE.md              ← standing agent instructions
├── DESIGN.md              ← tokens, layout, anti-patterns
├── app/ or src/
└── components/

CLAUDE.md should include stack facts (Next.js App Router, Tailwind v4, HeroUI) and standing UI rules: use DESIGN.md for all styling, no new colors outside defined tokens, one section per task unless asked otherwise.

Copy DESIGN.md from the Agent's Design gallery or follow the agent-ready DESIGN.md guide.

2. Open a session with the full design brief

Start every UI session by loading context — do not assume Claude remembers yesterday's aesthetic decisions.

Paste at session open:

The gallery agent prompt for your chosen layout
Full DESIGN.md content (or path instruction: "read DESIGN.md first")
Anti-slop footer from design prompt patterns
Scope statement — which route, which sections, which files may change

Example opener:

Read DESIGN.md and CLAUDE.md before writing code.

Task: Implement only the hero section for app/(marketing)/page.tsx. Create components/landing/hero.tsx. Use existing components/ui/button.tsx. Do not edit nav, footer, or global CSS. No gradients. No font imports beyond DESIGN.md.

3. Build landing pages section by section

Claude Code handles narrative long-scroll marketing pages well when you give it a section map upfront.

Order	Section	Typical files
1	Shell	`layout.tsx`, `nav.tsx`, `footer.tsx`
2	Hero	`hero.tsx`, page entry
3	Proof	`logo-strip.tsx` or `testimonial.tsx`
4	Features	`features.tsx` — prefer bento over 3-column cards
5	Pricing	`pricing.tsx` — one highlighted tier
6	FAQ	`faq.tsx` — typography-led accordion
7	Final CTA	`cta.tsx` or inline section

After each section: bun run dev, review at mobile and desktop widths, screenshot issues, paste back into Claude Code with file paths and specific fixes.

4. Multi-file app UI (dashboards, settings, product)

Landing pages are the entry point. Claude Code's deeper value shows in multi-route product UI:

Shared layout with sidebar + header
Settings pages with form density rules from DESIGN.md
Empty, loading, and error states as explicit follow-up tasks
Data tables with consistent cell padding and header typography

Scope these as features, not screens:

Implement the settings profile form: app/settings/profile/page.tsx, components/settings/profile-form.tsx. Match form field spacing to DESIGN.md dashboard density. Use existing Input and Label from components/ui/.

Claude Code's multi-file strength means you can ask for token renames across the repo once your DESIGN.md evolves — something painful in copy-paste generator workflows.

Design specs as context (the non-negotiable layer)

Think of design specs as three layers Claude Code reads:

Layer	Contents	Delivery
DESIGN.md	Tokens, type scale, layout, motion, anti-patterns	File in repo; tell agent to read first
Template prompt	Section order, copy structure, hero layout	Paste at session start
CLAUDE.md	Stack, libraries, persistent never-do rules	Committed; auto-loaded

Claude Code performs best when these layers agree. If DESIGN.md says "no drop shadows" but your prompt says "make cards pop," you get conflict and drift.

When adapting a landing page template for Cursor and Claude Code, the same prompt works in Claude Code — delivery is paste instead of @ reference.

Terminal workflow tips

Name files before Claude Code invents structure

Agents guess folder layouts. Pre-decide:

components/landing/ for marketing
components/dashboard/ for app chrome
components/ui/ for primitives

Tell Claude Code explicitly. Fewer moves later.

Use screenshots as the review surface

No built-in preview. Your loop is: change → dev server → screenshot → annotate → paste. "In hero.tsx, reduce py-24 to py-16 on mobile" beats "hero feels too tall."

Commit after each section

Git checkpoints let you roll back a bad multi-file diff without losing the whole session. Claude Code can move fast; commits keep you safe.

Run the anti-slop checklist before merge

Typography hierarchy, color role consistency, motion restraint, real copy placeholders — see the anti-slop design checklist.

Claude Code vs Cursor for UI

Both agents read the same repo. Choose by surface preference, not model mythology.

Dimension	Claude Code	Cursor
Interface	Terminal / CLI	VS Code fork
Context delivery	Paste paths, read files	`@` file attachments
Diff review	Terminal output	Inline IDE diffs
Best for	SSH, large refactors, CLI-first devs	IDE-native iteration

Many teams use Claude Code for refactors and page builds, Cursor for inline polish. Share one DESIGN.md and one gallery template across both.

For a three-way comparison including v0, see Cursor vs Claude Code vs v0.

When to pull templates from Agent's Design

Use a gallery template when:

You are starting a new landing page and want section names and layout ratios predefined
You are recovering from slop and need a clean spec-backed restart
You ship repeat client work and want industry-specific starting compositions
You are teaching a team a spec-first agent workflow

The Agent's Design gallery provides agent prompts and DESIGN.md exports — the same brief works in Claude Code, Cursor, v0, and other tools. Pro templates (~$89) add niche layouts; the workflow is identical.

You are not outsourcing judgment. You are outsourcing initial layout decisions so Claude Code executes craft-aware structure instead of default patterns.

Landing page patterns that work in Claude Code

These patterns consistently outperform open-ended requests:

Split hero with proof strip

55/45 desktop split, stacked mobile, logo strip below — not a full-bleed gradient. Claude Code maps this cleanly to flex/grid utilities when the ratio is explicit.

Bento feature grid

Asymmetric cells break the three-identical-cards habit. Specify cell sizes in the prompt; reference bento rules in DESIGN.md.

Editorial long-scroll

Single-column prose width, whitespace section breaks. Claude Code handles narrative flow when you forbid colored bands between sections.

Dark developer landing

Monospace accents, syntax-block placeholders, defined dark tokens. Steers away from consumer SaaS clichés.

Full copy-paste prompts for each pattern live in design prompts for better UI.

Common Claude Code UI mistakes

Mistake	Fix
Vague "make it modern"	Paste DESIGN.md + template prompt
Entire app in one message	One section or feature per task
No CLAUDE.md	Persist stack and anti-slop rules
Skipping mobile review	Screenshot 390px width every section
Mixing two component libraries	Pick shadcn or HeroUI; state in CLAUDE.md

FAQ

Can Claude Code build production UI?

Yes — with the same caveats as any agent: you own accessibility, performance, content accuracy, and brand decisions. Claude Code accelerates implementation when specs are clear.

How do I give Claude Code my design system?

Commit DESIGN.md, reference your components/ui/ primitives in prompts, and list allowed imports in CLAUDE.md. For larger systems, add a short component inventory section to DESIGN.md.

Should I use v0 first, then Claude Code?

Often, yes. Generate exploratory blocks in v0, then integrate and normalize tokens in Claude Code. See how to ship tasteful UI with v0.

Does Claude Code work with Next.js App Router?

Yes. State routing conventions in CLAUDE.md (app/ structure, server vs client components) to reduce wrong defaults.

What about design review without Figma?

Browser review + checklist + screenshots is enough for many indie and dev-tool products. Figma remains useful for brand exploration and stakeholder sign-off — not as a substitute for agent-readable specs.

Design better UI by briefing better

Claude Code does not need a different design philosophy than Cursor. It needs the same agent-readable constraints: DESIGN.md in the repo, template prompts at session start, scoped file paths, screenshot feedback loops, and persistent anti-slop rules in CLAUDE.md.

Paste a brief from the Agent's Design gallery, build one section at a time, and let Claude Code's multi-file strength work on structure — not on guessing your taste.