UI/UX - Design Principles & Implementation

Create beautiful, functional interfaces that delight users

When to Use This Skill

Use this skill when:

• Designing new components or interfaces

• Implementing UI elements (buttons, forms, cards, modals)

• Reviewing visual design and user experience

• Suggesting design improvements or alternatives

• Validating component states and interactions

• Creating responsive layouts

• Implementing dark mode or themes

• Building design systems or component libraries

Don't use this skill when:

• Only implementing backend logic (no UI)

• Working with pure data processing

• Technical accessibility fixes (use accessibility skill for WCAG)

• Performance optimization without visual impact

Critical Patterns

Pattern 1: Visual Hierarchy

When: Organizing information and guiding user attention

Good:

// Clear hierarchy with size, weight, color <div className="space-y-4"> {/* Primary: Large, bold, high contrast */} <h1 className="text-4xl font-bold text-gray-900"> Create Your Account </h1>

{/* Secondary: Medium, regular, medium contrast */} <p className="text-lg text-gray-600"> Get started with a free 14-day trial </p>

{/* Tertiary: Small, light, low contrast */} <span className="text-sm text-gray-400"> No credit card required </span> </div>

Bad:

// ❌ No hierarchy - everything same size/weight <div> <h1 className="text-base">Create Your Account</h1> <p className="text-base">Get started with a free 14-day trial</p> <span className="text-base">No credit card required</span> </div>

Why: Visual hierarchy guides user attention through size, weight, and contrast. Primary content should dominate, supporting content should recede.

Pattern 2: Comprehensive Component States

When: Implementing interactive components

Good:

const Button = ({ variant = 'primary', isLoading, disabled }) => { return ( <button disabled={disabled || isLoading} className={cn( // Base styles "px-4 py-2 rounded-lg font-medium transition-all",

    // Variant styles
    variant === 'primary' && "bg-blue-600 text-white",
    variant === 'secondary' && "bg-gray-200 text-gray-900",

    // Interactive states
    !disabled && !isLoading && "hover:opacity-90 active:scale-95",

    // Focus state (keyboard navigation)
    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2",

    // Disabled state
    disabled && "opacity-50 cursor-not-allowed",

    // Loading state
    isLoading && "cursor-wait"
  )}
>
  {isLoading && <Spinner className="mr-2" />}
  {children}
</button>

); };

Bad:

// ❌ Only handles default state const Button = ({ children }) => { return ( <button className="px-4 py-2 bg-blue-600 text-white rounded"> {children} </button> ); };

Why: Users need visual feedback for all interactions. Missing states create confusion and poor UX.

Required States:

• Default

• Hover (mouse users)

• Focus (keyboard users)

• Active/Pressed

• Disabled

• Loading

• Error (if applicable)

Pattern 3: Responsive Design with Mobile-First

When: Creating layouts that work across devices

Good:

// Mobile-first: start with mobile, enhance for desktop <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4"> {/* Cards stack on mobile, 2 cols on tablet, 3 on desktop */} {products.map(product => ( <Card key={product.id}> <img src={product.image} className="w-full h-48 object-cover" alt={product.name} /> <div className="p-4"> <h3 className="text-lg font-semibold">{product.name}</h3> <p className="text-sm text-gray-600 mt-2">{product.description}</p> </div> </Card> ))} </div>

Bad:

// ❌ Desktop-only, breaks on mobile <div className="grid grid-cols-3 gap-4"> {products.map(product => ( <Card>{/* Content */}</Card> ))} </div>

Why: Mobile-first ensures core experience works everywhere, then progressively enhances for larger screens.

Touch Targets: Minimum 44x44px for mobile (48x48px recommended)

// ✅ Good touch target <button className="min-h-[44px] min-w-[44px] p-3"> <Icon /> </button>

// ❌ Too small for touch <button className="p-1"> <Icon /> </button>

Pattern 4: Dark Mode Implementation

When: Supporting light and dark themes

Good:

// Using CSS variables for theme switching // globals.css :root { --background: 0 0% 100%; --foreground: 222.2 84% 4.9%; --card: 0 0% 100%; --card-foreground: 222.2 84% 4.9%; --primary: 221.2 83.2% 53.3%; --primary-foreground: 210 40% 98%; }

.dark { --background: 222.2 84% 4.9%; --foreground: 210 40% 98%; --card: 222.2 84% 4.9%; --card-foreground: 210 40% 98%; --primary: 217.2 91.2% 59.8%; --primary-foreground: 222.2 47.4% 11.2%; }

// Components use CSS variables <div className="bg-background text-foreground"> <div className="bg-card text-card-foreground p-6 rounded-lg"> <button className="bg-primary text-primary-foreground"> Click me </button> </div> </div>

Bad:

// ❌ Hardcoded colors, no dark mode support <div className="bg-white text-gray-900"> <div className="bg-white text-black p-6 rounded-lg"> <button className="bg-blue-600 text-white"> Click me </button> </div> </div>

Why: CSS variables allow instant theme switching. Hardcoded colors require conditional classes everywhere.

Dark Mode Considerations:

• Use semantic color names (background , foreground , not white , black )

• Reduce white (#FFF → #F9F9F9) to prevent eye strain

• Adjust shadows (use lighter shadows or borders in dark mode)

• Maintain contrast ratios (WCAG 4.5:1 minimum)

Pattern 5: Consistent Spacing System

When: Creating balanced, rhythmic layouts

Good:

// Use design tokens (spacing scale: 4px base) const spacing = { xs: '0.25rem', // 4px sm: '0.5rem', // 8px md: '1rem', // 16px lg: '1.5rem', // 24px xl: '2rem', // 32px '2xl': '3rem', // 48px };

<div className="space-y-8"> {/* Consistent 32px vertical rhythm /} <section className="p-8"> <h2 className="mb-4">Section Title</h2> <p className="mb-6">Description text</p> <div className="grid gap-4"> {/ Cards with consistent 16px gap */} </div> </section> </div>

Bad:

// ❌ Inconsistent, random spacing <div style={{ marginBottom: '13px' }}> <section style={{ padding: '17px' }}> <h2 style={{ marginBottom: '9px' }}>Title</h2> <p style={{ marginBottom: '21px' }}>Text</p> </section> </div>

Why: Consistent spacing creates visual rhythm and professional polish. Use multiples of 4px or 8px.

Pattern 6: Microinteractions for Feedback

When: Providing immediate user feedback

Good:

// Optimistic UI with animations const LikeButton = ({ postId }) => { const [isLiked, setIsLiked] = useState(false); const [count, setCount] = useState(0);

const handleLike = async () => { // Optimistic update setIsLiked(!isLiked); setCount(prev => isLiked ? prev - 1 : prev + 1);

try {
  await likePost(postId);
} catch (error) {
  // Rollback on error
  setIsLiked(!isLiked);
  setCount(prev => isLiked ? prev + 1 : prev - 1);
  toast.error('Failed to like post');
}

};

return ( <button onClick={handleLike} className="group flex items-center gap-2 transition-all" > <Heart className={cn( "w-5 h-5 transition-all", isLiked && "fill-red-500 text-red-500 scale-110", !isLiked && "text-gray-400 group-hover:text-red-400" )} /> <span className={cn( "transition-all", isLiked && "text-red-500 font-medium" )}> {count} </span> </button> ); };

Bad:

// ❌ No feedback, waits for server response const LikeButton = ({ postId }) => { const [count, setCount] = useState(0);

const handleLike = async () => { const result = await likePost(postId); setCount(result.count); };

return ( <button onClick={handleLike}> Like {count} </button> ); };

Why: Immediate feedback feels responsive. Optimistic updates provide instant gratification while server processes.

Anti-Patterns

❌ Anti-Pattern 1: Inconsistent Component Variants

Don't do this:

// ❌ Inconsistent button styles across app <button className="bg-blue-500 px-6 py-3 rounded">Save</button> <button className="bg-blue-600 px-4 py-2 rounded-lg">Submit</button> <button className="bg-indigo-500 px-5 py-2.5 rounded-md">Continue</button>

Why it's bad: Inconsistency looks unprofessional and confuses users.

Do this instead:

// ✅ Use a Button component with defined variants <Button variant="primary">Save</Button> <Button variant="primary">Submit</Button> <Button variant="primary">Continue</Button>

// Button component enforces consistency const Button = ({ variant = 'primary', size = 'md', children }) => { const styles = { primary: 'bg-blue-600 text-white hover:bg-blue-700', secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300', };

const sizes = { sm: 'px-3 py-1.5 text-sm', md: 'px-4 py-2 text-base', lg: 'px-6 py-3 text-lg', };

return ( <button className={cn(styles[variant], sizes[size], 'rounded-lg transition')}> {children} </button> ); };

❌ Anti-Pattern 2: Poor Empty States

Don't do this:

// ❌ Just shows nothing {products.length === 0 ? null : ( <ProductGrid products={products} /> )}

Why it's bad: Users don't know if it's loading, an error, or intentionally empty.

Do this instead:

// ✅ Helpful empty state with action {products.length === 0 ? ( <div className="flex flex-col items-center justify-center py-12 text-center"> <ShoppingBag className="w-16 h-16 text-gray-300 mb-4" /> <h3 className="text-lg font-medium text-gray-900 mb-2"> No products yet </h3> <p className="text-gray-500 mb-6"> Get started by adding your first product </p> <Button onClick={() => router.push('/products/new')}> Add Product </Button> </div> ) : ( <ProductGrid products={products} /> )}

❌ Anti-Pattern 3: Ignoring Loading States

Don't do this:

// ❌ No loading indicator const Dashboard = () => { const { data } = useQuery('stats');

return ( <div> <h1>Dashboard</h1> <Stats data={data} /> </div> ); };

Why it's bad: User sees broken/empty UI while loading, or worse, errors.

Do this instead:

// ✅ Proper loading and error states const Dashboard = () => { const { data, isLoading, error } = useQuery('stats');

if (isLoading) { return ( <div className="flex items-center justify-center min-h-[400px]"> <Spinner className="w-8 h-8" /> </div> ); }

if (error) { return ( <div className="p-4 bg-red-50 border border-red-200 rounded-lg"> <p className="text-red-800">Failed to load dashboard</p> <Button onClick={() => refetch()} className="mt-2"> Try Again </Button> </div> ); }

return ( <div> <h1>Dashboard</h1> <Stats data={data} /> </div> ); };

❌ Anti-Pattern 4: Tiny Touch Targets on Mobile

Don't do this:

// ❌ 24px icon button - too small for fingers <button className="p-1"> <X className="w-4 h-4" /> </button>

Why it's bad: Users will miss tap targets, causing frustration.

Do this instead:

// ✅ Minimum 44x44px touch target <button className="p-3 min-w-[44px] min-h-[44px] flex items-center justify-center"> <X className="w-5 h-5" /> </button>

Rule: 44x44px minimum (iOS), 48x48px recommended (Material Design)

❌ Anti-Pattern 5: Poor Form Error Handling

Don't do this:

// ❌ Generic error, no field-specific feedback <form onSubmit={handleSubmit}> <input name="email" /> <input name="password" /> {error && <p>Error: {error}</p>} <button type="submit">Submit</button> </form>

Why it's bad: User doesn't know which field has the problem.

Do this instead:

// ✅ Field-specific errors with helpful messages <form onSubmit={handleSubmit}> <div className="space-y-1"> <input name="email" className={cn( "border rounded-lg px-3 py-2", errors.email && "border-red-500" )} /> {errors.email && ( <p className="text-sm text-red-600 flex items-center gap-1"> <AlertCircle className="w-4 h-4" /> {errors.email.message} </p> )} </div>

<div className="space-y-1"> <input name="password" className={cn( "border rounded-lg px-3 py-2", errors.password && "border-red-500" )} /> {errors.password && ( <p className="text-sm text-red-600 flex items-center gap-1"> <AlertCircle className="w-4 h-4" /> {errors.password.message} </p> )} </div>

<button type="submit" disabled={isSubmitting}> {isSubmitting ? 'Submitting...' : 'Submit'} </button> </form>

❌ Anti-Pattern 6: Overwhelming Modals

Don't do this:

// ❌ Modal with 20 fields, long form <Dialog> <DialogContent className="max-w-4xl"> <form> {/* 20+ input fields /} <input name="field1" /> <input name="field2" /> {/ ... 18 more fields */} </form> </DialogContent> </Dialog>

Why it's bad: Cognitive overload, users abandon complex modals.

Do this instead:

// ✅ Multi-step wizard for complex forms <Dialog> <DialogContent> <div className="mb-4"> <div className="flex gap-2"> <div className={cn("h-1 flex-1 rounded", step >= 1 && "bg-blue-600")} /> <div className={cn("h-1 flex-1 rounded", step >= 2 && "bg-blue-600")} /> <div className={cn("h-1 flex-1 rounded", step >= 3 && "bg-blue-600")} /> </div> <p className="text-sm text-gray-500 mt-2">Step {step} of 3</p> </div>

{step === 1 && <BasicInfoFields />}
{step === 2 && <ContactFields />}
{step === 3 && <PreferencesFields />}

<div className="flex justify-between mt-6">
  {step > 1 && <Button onClick={prevStep}>Back</Button>}
  <Button onClick={nextStep}>
    {step === 3 ? 'Submit' : 'Continue'}
  </Button>
</div>

</DialogContent> </Dialog>

Code Examples

Example 1: Button Component with All States

export function Button({ variant = 'primary', isLoading, disabled, children }: ButtonProps) { return ( <button disabled={disabled || isLoading} className={cn( 'px-4 py-2 rounded-lg font-medium transition-all', variant === 'primary' && 'bg-blue-600 text-white', variant === 'secondary' && 'bg-gray-200 text-gray-900', !disabled && !isLoading && 'hover:opacity-90 active:scale-95', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500', disabled && 'opacity-50 cursor-not-allowed', isLoading && 'cursor-wait' )} > {isLoading && <Spinner className="mr-2 w-4 h-4 animate-spin" />} {children} </button> ); }

Example 2: Responsive Card Grid

export function ProductGrid({ products }: ProductGridProps) { return ( <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-6"> {products.map(product => ( <div key={product.id} className="bg-white rounded-lg shadow-md overflow-hidden"> <img src={product.image} alt={product.name} className="w-full h-48 object-cover" /> <div className="p-4 space-y-2"> <h3 className="text-lg font-semibold">{product.name}</h3> <p className="text-sm text-gray-600">{product.description}</p> <p className="text-xl font-bold text-blue-600">${product.price}</p> </div> </div> ))} </div> ); }

For comprehensive examples and detailed implementations, see the references/ folder.

Quick Reference

Visual Hierarchy Scale

Element Size Weight Color

Primary Heading text-4xl (36px) font-bold (700) text-gray-900

Secondary Heading text-2xl (24px) font-semibold (600) text-gray-800

Body Large text-lg (18px) font-normal (400) text-gray-700

Body text-base (16px) font-normal (400) text-gray-600

Small text-sm (14px) font-normal (400) text-gray-500

Caption text-xs (12px) font-normal (400) text-gray-400

Component States Checklist

• Default

• Hover (:hover )

• Focus (:focus-visible )

• Active (:active )

• Disabled (disabled , opacity-50 )

• Loading (cursor-wait , spinner)

• Error (border-red-500 , error message)

• Success (if applicable)

Spacing Scale (Tailwind)

// 4px base scale gap-1 = 4px gap-2 = 8px gap-4 = 16px gap-6 = 24px gap-8 = 32px gap-12 = 48px gap-16 = 64px

Responsive Breakpoints

sm: 640px // Small tablets md: 768px // Tablets lg: 1024px // Laptops xl: 1280px // Desktops 2xl: 1536px // Large desktops

Color Contrast Ratios (WCAG)

Level Normal Text Large Text

AA 4.5:1 3:1

AAA 7:1 4.5:1

Resources

Design Systems:

• Tailwind CSS - Utility-first CSS framework

• shadcn/ui - Re-usable components built with Radix UI and Tailwind

• Radix UI - Unstyled, accessible components

• Material Design - Google's design system

Component Libraries:

• Headless UI - Unstyled, accessible components

• Ark UI - Headless UI for React, Vue, Solid

Design Tools:

• Figma - Collaborative design tool

• Contrast Checker - WCAG contrast validation

Related Skills:

• accessibility: WCAG compliance, ARIA, keyboard navigation

• react: Component implementation patterns

• radix-ui: Headless component primitives

• patterns: Design patterns and principles

References (Progressive Disclosure):

• Design Systems - Tokens, theming, component libraries

• Component Patterns - Buttons, forms, cards, modals

• Interaction Patterns - Navigation, feedback, animations

• Trending Patterns - Glassmorphism, neumorphism, modern UI trends

Maintained by dsmj-ai-toolkit. Inspired by modern design systems and user-centered design principles.