UX/UI Design Guide

Your agent for applying user experience and interface design principles to software development — covering wireframing, design system integration, accessibility, and translating designs into implementation.

When to Use This Agent

Choose UX/UI Design Guide when:

• Translating design mockups into implementation specifications
• Reviewing frontend implementations for UX/UI consistency
• Implementing responsive layouts, animations, and interactive patterns
• Applying accessibility standards (WCAG 2.1) to UI components
• Building or extending a design system (components, tokens, patterns)

Consider alternatives when:

• You need visual design (Figma, Sketch) — use a design tool
• You need backend development — use a backend agent
• You need pure CSS/HTML coding — use a frontend developer agent

Quick Start

Copy
# .claude/agents/ux-ui-guide.yml
name: UX/UI Design Guide
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: UX/UI implementation agent for design system integration, accessibility, responsive layouts, and design-to-code translation

Example invocation:

claude "Review our checkout flow implementation against the Figma designs — check spacing, typography scale, color usage, and interactive states match the design system"

Core Concepts

Design-to-Code Translation

Design Element	Code Implementation	Verification
Spacing	CSS custom properties, spacing scale	Visual diff against mockup
Typography	Font scale tokens (--text-sm, --text-lg)	Type specimen comparison
Color	Color tokens (--color-primary-500)	Color contrast checker
Layout	CSS Grid / Flexbox with breakpoints	Responsive testing at breakpoints
Animation	CSS transitions, Framer Motion	Reduced motion media query
States	:hover, :focus, :active, :disabled	Keyboard navigation testing

Accessibility Checklist

WCAG 2.1 Level AA Requirements:
  ├── Color contrast ≥ 4.5:1 (text), ≥ 3:1 (large text)
  ├── All functionality available via keyboard
  ├── Focus indicators visible and clear
  ├── Form inputs have associated labels
  ├── Images have meaningful alt text
  ├── Page structure uses semantic HTML
  ├── Dynamic content announced to screen readers
  └── No content flashes more than 3 times/second

Configuration

Parameter	Description	Default
design_system	Design system in use (custom, material, ant, chakra)	auto-detect
framework	Frontend framework (react, vue, svelte, angular)	auto-detect
accessibility_level	WCAG target (a, aa, aaa)	aa
responsive_breakpoints	Breakpoint strategy (mobile-first, desktop-first)	mobile-first
animation_library	Animation approach (css, framer-motion, gsap)	css

Best Practices

1. Use design tokens for every visual property. Never hardcode colors, spacing, or typography values in components. Use semantic tokens (--color-text-primary, --spacing-md) that can be themed, adjusted for accessibility, and maintained from a single source.

2. Test with keyboard navigation before shipping. Tab through every interactive element, verify focus order makes sense, confirm all actions work without a mouse, and check that focus indicators are visible against all backgrounds.

3. Design mobile-first, then enhance for larger screens. Start with the mobile layout in CSS, then use min-width media queries to add complexity for tablets and desktops. This produces simpler code and ensures mobile works well.

4. Include loading, empty, and error states in every component. Designs often show the "happy path" with data. Implement skeleton loaders for loading states, helpful empty state messages, and clear error states with recovery actions.

5. Respect prefers-reduced-motion for all animations. Wrap motion in @media (prefers-reduced-motion: no-preference) so users who experience motion sensitivity aren't affected. Provide functional alternatives (opacity transitions) for reduced-motion mode.

Common Issues

Implementation doesn't match the design at specific screen sizes. Designs are typically created at fixed widths (375px, 768px, 1440px), but real devices span a continuous range. Test at breakpoint boundaries and between breakpoints to catch layout issues that appear at non-standard sizes.

Color contrast fails accessibility requirements. Light gray text on white backgrounds is a common offender. Use a contrast checker tool during development and add automated contrast testing to your CI pipeline. Fix contrast issues by darkening the text color, not by changing the design intent.

Focus indicators are invisible or hidden by outline: none. CSS resets often remove default focus indicators. Always provide custom focus styles that are visible against all backgrounds. :focus-visible shows focus only for keyboard users, not mouse clicks.