UI/UX Best Practices for AI-Assisted Development¶
Practical guidelines for building professional user interfaces with Claude Code. Covers design system setup, component patterns, accessibility, and recommended tools.
1. Design System First¶
Before writing UI code, establish a design system. This prevents inconsistency and reduces back-and-forth with Claude.
What to Define¶
| Element | What to Specify | Example |
|---|---|---|
| Colors | Primary, secondary, neutral, semantic (error, success, warning) | primary: #4F46E5, error: #DC2626 |
| Typography | Font family, scale (h1–body–caption), line heights, weights | Inter for body, heading scale 1.25 ratio |
| Spacing | Base unit and scale | 4px base: 4, 8, 12, 16, 24, 32, 48, 64 |
| Breakpoints | Mobile, tablet, desktop widths | 640px, 768px, 1024px, 1280px |
| Border radius | Small, medium, large, full | 4px, 8px, 12px, 9999px |
| Shadows | Elevation levels (1–5) | sm, md, lg, xl |
Tell Claude Your Design System¶
Add a design system section to your CLAUDE.md:
## Design System
- **Colors**: Primary=#4F46E5 Secondary=#7C3AED Neutral=Slate Error=#DC2626 Success=#16A34A
- **Font**: Inter (body), font-size base 16px, scale 1.25
- **Spacing**: 4px base unit. Use multiples: 4, 8, 12, 16, 24, 32, 48, 64
- **Radius**: sm=4px md=8px lg=12px full=9999px
- **Breakpoints**: sm=640px md=768px lg=1024px xl=1280px
Or use a dedicated design system file and reference it:
## Design System
See `design-system/MASTER.md` for colors, typography, spacing, and component specs.
2. Component Design Principles¶
Hierarchy and Layout¶
| Principle | Rule | Why |
|---|---|---|
| Visual hierarchy | Size, weight, and color should signal importance | Users scan, they don't read |
| Consistent spacing | Use your spacing scale — never arbitrary values | Inconsistent spacing looks amateur |
| Alignment | Left-align text, align elements to a grid | Creates visual order |
| Proximity | Group related items, separate unrelated ones | Reduces cognitive load |
| White space | More space = more breathing room = more professional | Crowded UIs feel overwhelming |
Component Patterns¶
When asking Claude to build UI components, specify:
Build a [component] that:
- Layout: [how elements are arranged]
- States: [default, hover, active, disabled, loading, error, empty]
- Responsive: [how it adapts at each breakpoint]
- Accessibility: [keyboard nav, screen reader, ARIA]
- Animation: [transitions, micro-interactions]
Example:
Build a card component:
- Layout: image top, title + description below, action button bottom-right
- States: default, hover (slight lift shadow), loading (skeleton), empty (placeholder)
- Responsive: 3-column grid on desktop, 2 on tablet, 1 on mobile
- Accessibility: focusable, descriptive alt text on image
- Animation: 150ms ease-out on hover shadow transition
3. Color and Typography¶
Color Usage Rules¶
| Color Role | Usage | Anti-pattern |
|---|---|---|
| Primary | Main CTA buttons, active states, key links | Using primary for everything |
| Secondary | Supporting actions, tags, badges | Making secondary too similar to primary |
| Neutral | Text, backgrounds, borders, dividers | Pure black (#000) on white — use dark gray |
| Error | Validation errors, destructive actions | Red for non-error states |
| Success | Confirmations, positive states | Only green with no accompanying text |
| Warning | Caution states, pending actions | Ignoring colorblind users (use icons too) |
Typography Rules¶
- Maximum 2 font families — one for headings, one for body (or the same for both)
- Limit font weights — regular (400), medium (500), semibold (600), bold (700)
- Line height — 1.5 for body text, 1.2–1.3 for headings
- Max line width — 65–75 characters for readable body text
- Contrast ratio — minimum 4.5:1 for normal text, 3:1 for large text (WCAG AA)
4. Responsive Design¶
Mobile-First Approach¶
Always design for mobile first, then enhance for larger screens.
/* Mobile first */
.container { padding: 16px; }
/* Tablet */
@media (min-width: 768px) { .container { padding: 24px; } }
/* Desktop */
@media (min-width: 1024px) { .container { padding: 32px; max-width: 1200px; } }
Common Responsive Patterns¶
| Pattern | Mobile | Tablet | Desktop |
|---|---|---|---|
| Navigation | Hamburger menu | Hamburger or tab bar | Full horizontal nav |
| Grid | 1 column | 2 columns | 3–4 columns |
| Sidebar | Hidden (drawer) | Collapsible | Always visible |
| Table | Card layout or scroll | Scroll with sticky column | Full table |
| Modal | Full screen | Centered overlay | Centered overlay |
| Font size | 14–16px base | 16px base | 16px base |
5. Accessibility (a11y)¶
The Non-Negotiables¶
| Requirement | How | Check |
|---|---|---|
| Keyboard navigation | All interactive elements focusable and operable with keyboard | Tab through the entire page |
| Color contrast | 4.5:1 minimum for text | Use a contrast checker tool |
| Alt text | Every image has descriptive alt text (or alt="" for decorative) |
Inspect images |
| Focus indicators | Visible focus ring on all interactive elements | Tab and look |
| Semantic HTML | Use <button>, <nav>, <main>, <article> — not divs for everything |
Check element tags |
| Form labels | Every input has an associated <label> |
Click the label — does it focus the input? |
| Error messages | Descriptive, associated with the field, announced to screen readers | Use aria-describedby |
Tell Claude About Accessibility¶
Add to your CLAUDE.md:
## Accessibility
- All interactive elements must be keyboard accessible
- Color contrast minimum 4.5:1 (WCAG AA)
- Every image needs alt text
- Use semantic HTML elements
- Form inputs must have associated labels
- Focus indicators must be visible
- Don't rely on color alone to convey meaning
6. Performance¶
Image Guidelines¶
| Format | Use For | Notes |
|---|---|---|
| WebP | Photos, complex images | 25–35% smaller than JPEG |
| SVG | Icons, logos, illustrations | Scales infinitely, tiny file size |
| PNG | Screenshots, images with transparency | Use only when WebP won't work |
| AVIF | Modern browsers, best compression | Check browser support |
Loading Patterns¶
| Pattern | When | Implementation |
|---|---|---|
| Skeleton screens | Content loading | Gray placeholder shapes matching content layout |
| Progressive loading | Images | Low-quality placeholder → full image |
| Infinite scroll | Long lists | Load more as user scrolls near bottom |
| Pagination | Data tables | Page controls with clear current page indicator |
| Optimistic updates | User actions | Show success immediately, rollback on error |
7. Common UI Anti-Patterns¶
| Anti-Pattern | Problem | Better Approach |
|---|---|---|
| Mystery icons | Users don't know what unlabeled icons mean | Add text labels, or use tooltips |
| Wall of text | Nobody reads long paragraphs in UIs | Break into bullet points, headings, progressive disclosure |
| Tiny touch targets | Mobile users can't tap small buttons | Minimum 44x44px touch targets |
| Unclear CTAs | "Submit" or "Click here" say nothing | Use action verbs: "Create Account", "Save Changes" |
| No loading state | Users think the app is broken | Show spinners, skeletons, or progress bars |
| No empty state | Blank screens confuse users | Design helpful empty states with guidance |
| Disabled without reason | Users don't know why a button is disabled | Show tooltip or inline message explaining why |
| Too many choices | Decision paralysis (Hick's Law) | Limit visible options, use progressive disclosure |
8. Instructing Claude for UI Work¶
Effective Prompts¶
Good:
Build a pricing page with 3 tiers (Free, Pro, Enterprise).
- Use the design system in design-system/MASTER.md
- Card layout: highlighted "Pro" tier in the center
- Each card: tier name, price, feature list (checkmarks), CTA button
- Pro card has primary color border and "Most Popular" badge
- Mobile: stack vertically, Pro card first
- Accessible: semantic HTML, keyboard navigable, 4.5:1 contrast
Bad:
Review Checklist¶
After Claude builds UI, verify:
- Looks correct at mobile, tablet, and desktop widths
- All states handled (loading, empty, error, hover, focus, disabled)
- Keyboard navigation works (Tab, Enter, Escape)
- Color contrast passes (use browser DevTools)
- No horizontal scroll on mobile
- Touch targets are at least 44x44px
- Images have alt text
- Animations respect
prefers-reduced-motion - Text is readable (not too small, not too long per line)
- Consistent spacing using the spacing scale
9. Recommended Tools¶
External tools and AI skills that enhance UI/UX development with Claude Code.
AI Design Skills¶
| Tool | What It Does | Install | Source |
|---|---|---|---|
| UI/UX Pro Max | Design intelligence skill — 67 styles, 96 palettes, 57 font pairings, 100 reasoning rules. Generates complete design systems. | npm install -g uipro-cli && uipro init --ai claude |
nextlevelbuilder/ui-ux-pro-max-skill |
Design Validation¶
| Tool | What It Does | Usage |
|---|---|---|
| Lighthouse | Audits performance, accessibility, SEO, best practices | Chrome DevTools → Lighthouse tab |
| axe DevTools | Accessibility testing in browser | Browser extension |
| Contrast Checker | Verify WCAG color contrast ratios | WebAIM Contrast Checker |
Component Libraries¶
| Library | Framework | Highlights |
|---|---|---|
| shadcn/ui | React + Tailwind | Copy-paste components, fully customizable |
| Radix UI | React | Unstyled, accessible primitives |
| Headless UI | React / Vue | Unstyled, accessible components by Tailwind Labs |
| DaisyUI | Tailwind CSS | Pre-styled Tailwind components |
Design System References¶
| Resource | What It Offers |
|---|---|
| Material Design 3 | Google's design system — comprehensive guidelines |
| Apple HIG | Human Interface Guidelines for Apple platforms |
| Tailwind UI | Premium component examples (paid) |
| Refactoring UI | Design tips for developers (book) |
10. Design System File Structure¶
For projects that need a persistent design system, use this structure:
design-system/
├── MASTER.md # Global design rules (colors, typography, spacing, components)
└── pages/
├── dashboard.md # Page-specific overrides for dashboard
├── landing.md # Landing page variations
└── settings.md # Settings page rules
MASTER.md Template¶
# Design System
## Colors
| Role | Light Mode | Dark Mode |
|------|-----------|-----------|
| Primary | #4F46E5 | #818CF8 |
| Background | #FFFFFF | #0F172A |
| Surface | #F8FAFC | #1E293B |
| Text | #0F172A | #F8FAFC |
| Border | #E2E8F0 | #334155 |
| Error | #DC2626 | #F87171 |
| Success | #16A34A | #4ADE80 |
## Typography
- Heading: Inter, weights 600/700
- Body: Inter, weight 400/500
- Mono: JetBrains Mono
- Scale: 12, 14, 16, 18, 20, 24, 30, 36, 48
## Spacing
Base: 4px
Scale: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96
## Border Radius
sm: 4px | md: 8px | lg: 12px | xl: 16px | full: 9999px
## Shadows
sm: 0 1px 2px rgba(0,0,0,0.05)
md: 0 4px 6px rgba(0,0,0,0.07)
lg: 0 10px 15px rgba(0,0,0,0.1)
xl: 0 20px 25px rgba(0,0,0,0.15)
Claude Code reads this file automatically and applies the system consistently across all pages.