ui-ux-design-patterns

Original source / Raw SKILL.md

---
name: ui-ux-design-patterns
description: Expert guidance for creating distinctive, beautiful UI designs and psychologically-informed UX patterns. Use this skill when designing interfaces, improving user experience, optimizing conversion flows, or enhancing visual aesthetics. Applies to landing pages, dashboards, onboarding flows, and any user-facing interface design work.
---

# UI/UX Design Patterns

## Overview

This skill provides expert guidance for creating distinctive, beautiful frontend interfaces combined with psychologically-informed user experience patterns. It helps avoid generic "AI slop" aesthetics while applying proven UX psychology principles to improve engagement, conversion, and user satisfaction.

**Core capabilities:**

- **UI Aesthetics**: Typography, color systems, motion design, backgrounds, and visual distinctiveness
- **UX Psychology**: Cognitive load management, decision-making psychology, behavioral design, and trust-building
- **Pattern Application**: Practical implementation strategies for common interface challenges

## When to Use This Skill

Invoke this skill when working on:

**Visual Design Tasks:**

- "Make this landing page more visually distinctive"
- "Design a unique color theme for this dashboard"
- "Choose typography that stands out from generic interfaces"
- "Add delightful animations to this page load"
- "Create an atmospheric background instead of solid colors"

**User Experience Optimization:**

- "Improve the conversion rate of this registration flow"
- "Reduce cognitive load in this complex dashboard"
- "Design an onboarding experience that keeps users engaged"
- "Apply psychological principles to encourage user actions"
- "Optimize this checkout flow to reduce abandonment"

**Design System Development:**

- "Establish a cohesive visual identity"
- "Create reusable UI patterns with personality"
- "Design component libraries that avoid generic aesthetics"

**Problem-Solving:**

- "Users find this interface overwhelming"
- "This page feels generic and forgettable"
- "We need to increase user engagement without dark patterns"
- "The design lacks visual hierarchy"

## UI Aesthetic Guidelines

### Core Principle: Distinctive Over Generic

The fundamental challenge is avoiding convergence toward predictable, machine-generated aesthetics. Create frontends that surprise and delight through creative, distinctive choices.

**Key focus areas:**

#### 1. Typography

Choose fonts that are beautiful, unique, and interesting. Avoid generic choices like Arial, Inter, or Roboto.

**Strong alternatives by category:**

- **Serif**: Playfair Display, Lora, Crimson Text, Spectral, Merriweather
- **Sans-Serif**: Poppins, DM Sans, Outfit, Syne, Epilogue, Manrope
- **Display**: Bebas Neue, Righteous, Abril Fatface, Fredoka
- **Monospace**: JetBrains Mono, Fira Code, IBM Plex Mono

**Typography combinations:**

- Playfair Display (headlines) + Lora (body) = Editorial elegance
- Bebas Neue (headlines) + Poppins (body) = Modern impact
- Spectral (serif body) + Outfit (sans UI) = Inverted tradition

For detailed typography guidance, font pairings, and implementation best practices, see `references/ui-aesthetics.md`.

#### 2. Color & Theme

Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.

**Theme inspiration sources:**

- **IDE themes**: Dracula, Nord, Tokyo Night, Catppuccin
- **Cultural aesthetics**: Japanese minimalism, Scandinavian cool, Brutalist high-contrast
- **Contextual**: Match product domain while subverting expectations

**Implementation:**

```css
:root {
  --color-background: #0a0e27;
  --color-surface: #1a1f3a;
  --color-primary: #00ff9f;
  --color-accent: #ff0080;
  --color-text-primary: #e0e0e0;
}
```

**Avoid:**

- Clichéd purple gradients on white backgrounds
- Generic blue-gray neutrals
- Evenly-distributed, timid palettes

For complete color system architecture, theme examples, and gradient techniques, see `references/ui-aesthetics.md`.

#### 3. Motion & Animation

Use animations for effects and micro-interactions. Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions.

**Strategic approach:**

- Prioritize CSS-only solutions for HTML
- Use Motion library (Framer Motion) for complex React animations
- Orchestrate page loads with staggered animation delays
- Add purposeful micro-interactions on key elements

**Example - Staggered page load:**

```css
.hero-title {
  animation: fadeInUp 0.8s ease-out;
}
.hero-subtitle {
  animation: fadeInUp 0.8s ease-out 0.2s both;
}
.hero-cta {
  animation: fadeInUp 0.8s ease-out 0.4s both;
}
```

For comprehensive animation patterns, timing guidelines, and performance optimization, see `references/ui-aesthetics.md`.

#### 4. Backgrounds

Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects.

**Effective techniques:**

- Layered gradients for atmospheric depth
- Geometric patterns (dots, grids, stripes)
- Subtle noise textures
- Contextual effects (spotlight, vignette)

**Example - Atmospheric gradient:**

```css
background:
  radial-gradient(ellipse at top, rgba(102, 126, 234, 0.15), transparent),
  radial-gradient(ellipse at bottom, rgba(118, 75, 162, 0.15), transparent), #0a0e27;
```

For background pattern libraries, image overlay techniques, and advanced effects, see `references/ui-aesthetics.md`.

## UX Psychology Principles

### Core Principles

#### 1. Cognitive Load Management

Minimize mental effort required to process information.

**Progressive Disclosure**: Reveal information gradually.

- Use accordion menus, step wizards, expandable sections
- Apply to: Complex forms, feature-rich interfaces, data dashboards

**Visual Hierarchy**: Establish clear priority through size, color, contrast, spacing.

- Primary: Main action (largest, highest contrast)
- Secondary: Supporting actions (medium size/contrast)
- Tertiary: Optional details (smallest, lowest contrast)

#### 2. Decision-Making Psychology

**Anchoring Effect**: First information encountered influences subsequent judgments.

- Show original price before discounted price
- Display completion time estimates upfront
- Set defaults that guide optimal choices

**Framing Effect**: How information is presented affects decisions.

- Emphasize gains over losses ("95% success" vs "5% failure")
- Use action-oriented language
- Focus on benefits, not just features

**Loss Aversion**: People feel losses roughly twice as strongly as gains.

- "You'll lose your progress if you leave now"
- "Your discount expires in 24 hours"
- Balance with positive framing (avoid pure fear tactics)

#### 3. Attention and Memory

**Peak-End Rule**: Users judge experiences by peak moment and ending, not average.

- Optimize highest-impact moment in journey
- Ensure final interaction leaves positive impression
- Apply: Onboarding "aha moments", celebration on task completion

**Zeigarnik Effect**: Uncompleted tasks are remembered better.

- Progress bars showing partial completion
- "Continue where you left off" features
- Profile completion indicators

#### 4. Behavioral Design

**Nudge Theory**: Subtle cues guide beneficial actions without restricting choice.

- Pre-select recommended options (allow changing)
- Highlight suggested paths visually
- Default to privacy-protecting settings

**Gamification**: Game mechanics increase engagement.

- Points/scores, levels/tiers, badges/achievements
- Use when: Learning platforms, productivity tools, community engagement
- Ensure mechanics serve user goals, not just metrics

**Social Proof**: People look to others' behavior.

- User counts, testimonials, ratings/reviews
- Activity indicators, expert endorsements
- Use genuine, verifiable proof only

For comprehensive UX psychology principles, implementation patterns, and ethical guidelines, see `references/ux-psychology.md`.

## Applying UI/UX Patterns

### Integration Strategy

Effective design combines aesthetic distinctiveness with psychological insight:

1. **Start with UX foundation**: Understand user goals, pain points, and decision points
2. **Apply psychology patterns**: Choose relevant UX principles for the context
3. **Layer distinctive aesthetics**: Add visual personality that enhances (not distracts from) UX
4. **Orchestrate key moments**: Focus design and animation effort on peak experiences
5. **Test and refine**: Validate that beauty and usability reinforce each other

### Common Design Scenarios

#### Landing Page

**UX considerations:**

- Anchoring effect: Lead with compelling value proposition
- Visual hierarchy: Clear primary CTA
- Social proof: Testimonials and user counts

**UI execution:**

- Distinctive typography for hero headline
- Orchestrated page load animation (staggered reveals)
- Atmospheric background (not solid color)
- Sharp color accent on primary CTA

#### Registration Flow

**UX considerations:**

- Progressive disclosure: Multi-step form, not overwhelming single page
- Foot-in-the-door: Start with minimal ask (email), build trust
- Zeigarnik effect: Progress bar to encourage completion

**UI execution:**

- Clear step indicators with visual feedback
- Smooth transitions between steps
- Success micro-animations on field completion
- Cohesive color system reinforcing brand

#### Dashboard

**UX considerations:**

- Cognitive load: Progressive disclosure of advanced features
- Visual hierarchy: Primary metrics prominent
- Decision fatigue: Smart defaults, reduce choices

**UI execution:**

- Strong typographic scale for metric hierarchy
- Unique color palette (avoid generic blue-gray)
- Subtle background patterns for depth
- Purposeful animations on data updates

#### Onboarding

**UX considerations:**

- Peak-end rule: Deliver "aha moment" early, end with success celebration
- Gamification: Progress tracking, achievement on completion
- Sunk cost: Show investment to encourage completion

**UI execution:**

- Delightful animations on milestone completion
- Distinctive illustration style (not generic undraw.co)
- Celebration moment with confetti or unique visual
- Consistent motion language throughout flow

### Balancing Beauty and Usability

**The aesthetic-usability effect**: Beautiful designs are perceived as more usable, but actual usability must match aesthetic promise.

**Guidelines:**

- Don't use aesthetics to mask poor usability
- Ensure clarity isn't sacrificed for style
- Test with real users, not just designers
- Maintain accessibility standards (contrast, reduced motion)

**Accessibility checklist:**

- Text contrast: 4.5:1 minimum (normal), 3:1 (large)
- Respect `prefers-reduced-motion` for animations
- Ensure keyboard navigation works
- Test with screen readers for complex interactions

### Avoiding Generic Aesthetics

**Common pitfalls:**

- Purple gradient hero sections
- Rounded cards with drop shadows everywhere
- Generic illustrations and stock photos
- Cookie-cutter layouts
- Overused fonts (Inter, Roboto)

**Creating distinctiveness:**

1. Reference unexpected sources (architecture, fashion, art movements)
2. Combine contrasting aesthetics intentionally
3. Commit to strong direction (don't hedge with "safe" choices)
4. Add contextual details that relate to content
5. Break conventions intentionally
6. Develop a signature (recurring motifs, unique spacing)

**Validation questions:**

- Does this feel thoughtfully designed or machine-generated?
- Have I seen this exact combination before?
- Does this design have personality and point of view?
- Would a user remember this interface?
- Does the aesthetic match the product's unique context?

## Resources

This skill includes comprehensive reference documentation:

### references/ui-aesthetics.md

Complete guide to creating distinctive, beautiful frontend interfaces.

**Contents:**

- Typography: Font selection philosophy, categories, pairings, scales, loading strategies
- Color & Theme: System architecture, theme inspirations (dark/light), gradients, accessibility
- Motion & Animation: CSS patterns, React libraries, timing, performance optimization
- Backgrounds: Gradients, geometric patterns, noise textures, contextual effects
- Layout & Spatial Design: Container widths, spacing scales, depth/elevation
- Avoiding Generic AI Aesthetics: Common pitfalls and strategies for originality

**Use when:**

- Implementing specific UI patterns
- Choosing fonts, colors, or animations
- Need detailed code examples
- Seeking inspiration for distinctive aesthetics

### references/ux-psychology.md

Comprehensive UX psychology principles and behavioral design patterns.

**Contents:**

- Cognitive Load Management: Progressive disclosure, visual hierarchy
- Decision-Making Psychology: Anchoring, framing, decoy effects, loss aversion, sunk cost
- Attention and Memory: Peak-end rule, serial position effect, Zeigarnik effect
- Behavioral Design: Nudge theory, gamification, foot-in-the-door, variable rewards, scarcity
- Performance and Quality: Doherty threshold, decision fatigue
- Trust and Credibility: Social proof, halo effect, aesthetic-usability effect
- Implementation Priorities: When to apply each principle
- Ethical Considerations: User autonomy, transparency, long-term well-being

**Use when:**

- Optimizing conversion flows
- Improving user engagement
- Designing onboarding experiences
- Solving specific UX problems
- Need evidence-based design patterns

## Workflow

When applying this skill to a design task:

1. **Understand the goal**: What user problem are we solving? What action do we want to encourage?

2. **Identify relevant UX patterns**: Consult `ux-psychology.md` for principles that apply to this scenario.

3. **Choose distinctive aesthetics**: Consult `ui-aesthetics.md` for typography, color, motion, and background approaches that create uniqueness.

4. **Design the experience**: Combine UX patterns with aesthetic choices to create cohesive design.

5. **Implement with attention to detail**: Use code examples from references, maintain consistency, ensure accessibility.

6. **Validate distinctiveness**: Ask validation questions to ensure design isn't generic or predictable.

## Ethical Design Principles

Always prioritize:

- **User autonomy**: Preserve choice, don't manipulate
- **Transparency**: Be honest about recommendations and limitations
- **Genuine value**: Don't use psychology to mask poor products
- **Long-term well-being**: Optimize for user benefit, not just engagement metrics
- **Accessibility**: Ensure designs work for all users
- **Privacy and security**: Default to protective settings

Avoid dark patterns:

- Artificial scarcity or false urgency
- Manipulative loss framing
- Addictive variable reward schemes
- Deceptive design that tricks users
- Exploiting psychological vulnerabilities


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/ui-aesthetics.md

```markdown
# UI Aesthetic Guidelines

This reference provides guidelines for creating distinctive, beautiful frontend interfaces that avoid generic "AI slop" aesthetics.

## Core Principle: Distinctive Over Generic

The fundamental challenge in UI design is avoiding convergence toward "on distribution" outputs—the generic, predictable aesthetic that makes interfaces feel uninspired and machine-generated.

**The goal**: Create frontends that surprise and delight through creative, distinctive choices that feel genuinely designed for their specific context.

---

## Typography

Typography is the primary voice of your interface. Choose fonts that elevate the aesthetic and create personality.

### Font Selection Philosophy

**Avoid the generic:**

- ❌ Inter, Roboto, Arial, system fonts
- ❌ Default font stacks that everyone uses
- ❌ "Safe" choices that blend into the background

**Embrace the distinctive:**

- ✅ Beautiful, unique typefaces with character
- ✅ Fonts that match the project's personality
- ✅ Unexpected combinations that work surprisingly well
- ✅ Cultural or contextual references in typography

### Font Categories & When to Use

#### Serif Fonts

**Character**: Classical, elegant, authoritative, editorial

**Strong choices:**

- **Playfair Display**: Elegant, high-contrast serif for luxury or editorial
- **Lora**: Warm, readable serif with calligraphic details
- **Crimson Text**: Book-like quality for content-heavy interfaces
- **Spectral**: Contemporary serif designed for screens
- **Merriweather**: Sturdy serif with personality

**Use when:**

- Editorial or content-focused interfaces
- Luxury or premium positioning
- Classical or traditional contexts
- Long-form reading experiences

#### Sans-Serif Fonts (Non-Generic)

**Character**: Modern, clean, but with personality

**Strong choices:**

- **Poppins**: Geometric with warmth and friendliness
- **DM Sans**: Contemporary with optical adjustments for screens
- **Outfit**: Display sans with distinctive geometric forms
- **Syne**: Ultra-modern with condensed, striking appearance
- **Epilogue**: Refined sans with slightly condensed proportions
- **Manrope**: Semi-rounded with excellent readability

**Use when:**

- Modern, tech-forward interfaces
- Clean, minimal aesthetics
- Professional but approachable tone

#### Display & Decorative

**Character**: Bold, attention-grabbing, distinctive

**Strong choices:**

- **Bebas Neue**: Condensed, all-caps impact
- **Righteous**: Retro-futuristic display face
- **Abril Fatface**: Ultra-high contrast for dramatic headlines
- **Fredoka**: Rounded, playful display font
- **Nixie One**: Vintage typewriter aesthetic

**Use when:**

- Headlines and hero sections
- Landing pages needing strong visual impact
- Branding-heavy interfaces
- Playful or retro contexts

#### Monospace (Beyond Standard)

**Character**: Technical, precise, developer-focused

**Strong choices:**

- **JetBrains Mono**: Modern code font with ligatures
- **Fira Code**: Elegant monospace with programming ligatures
- **IBM Plex Mono**: Corporate monospace with personality
- **Source Code Pro**: Adobe's refined code font

**Use when:**

- Developer tools or technical interfaces
- Code display or editing
- Data-heavy dashboards
- Retro computer aesthetics

### Typography Combinations

Successful interfaces often pair two fonts with contrasting characteristics.

#### Classic Pairings

- **Playfair Display** (headlines) + **Lora** (body): Editorial elegance
- **Bebas Neue** (headlines) + **Poppins** (body): Modern impact
- **Abril Fatface** (display) + **Lato** (UI): Dramatic contrast
- **Syne** (headings) + **DM Sans** (body): Contemporary edge

#### Unexpected Pairings

- **Spectral** (serif body) + **Outfit** (sans UI elements): Inverted tradition
- **Nixie One** (retro headings) + **IBM Plex Mono** (technical body): Vintage-tech fusion
- **Righteous** (futuristic display) + **Epilogue** (refined body): Sci-fi sophistication

### Typographic Scale

Establish clear hierarchy through intentional size relationships.

**Large-scale approach (bold hierarchy):**

```css
--text-xs: 0.75rem; /* 12px - metadata */
--text-sm: 0.875rem; /* 14px - secondary */
--text-base: 1rem; /* 16px - body */
--text-lg: 1.25rem; /* 20px - emphasis */
--text-xl: 1.5rem; /* 24px - subheadings */
--text-2xl: 2rem; /* 32px - headings */
--text-3xl: 3rem; /* 48px - page titles */
--text-4xl: 4.5rem; /* 72px - hero display */
```

**Modular scale approach (mathematical harmony):**
Use a ratio (e.g., 1.25, 1.333, 1.5, 1.618) to create proportional sizes.

```css
/* Example with 1.333 (perfect fourth) ratio */
--text-base: 1rem;
--text-lg: 1.333rem;
--text-xl: 1.776rem;
--text-2xl: 2.369rem;
--text-3xl: 3.157rem;
```

### Font Weight & Style

**Weight hierarchy:**

- **Light (300)**: Subtle, elegant, use sparingly
- **Regular (400)**: Body text default
- **Medium (500)**: UI elements, subtle emphasis
- **Semi-bold (600)**: Subheadings, moderate emphasis
- **Bold (700)**: Headlines, strong emphasis
- **Extra-bold (800+)**: Display text, maximum impact

**Variable fonts**: Modern approach allowing fine-grained weight control.

### Implementation Best Practices

**Loading strategy:**

```css
/* Preload critical fonts */
<link rel="preload" href="/fonts/Poppins-Regular.woff2" as="font" type="font/woff2" crossorigin>

/* Use font-display for performance */
@font-face {
  font-family: 'Poppins';
  src: url('/fonts/Poppins-Regular.woff2') format('woff2');
  font-display: swap; /* or optional */
  font-weight: 400;
}
```

**Fallback stacks:**

```css
font-family:
  'Poppins',
  -apple-system,
  BlinkMacSystemFont,
  'Segoe UI',
  sans-serif;
```

---

## Color & Theme

Color defines emotional tone and creates cohesive aesthetic identity. Commit to a distinctive palette rather than playing it safe.

### Color Philosophy

**Avoid:**

- ❌ Clichéd purple gradients on white backgrounds
- ❌ Generic blue-gray neutrals
- ❌ Evenly-distributed, timid palettes
- ❌ "Safe" color choices that lack personality

**Embrace:**

- ✅ Dominant colors with sharp accents
- ✅ Cultural or contextual color references
- ✅ Unexpected but harmonious combinations
- ✅ Strong commitment to aesthetic direction

### Color System Architecture

Build color systems using CSS variables for consistency and theme switching.

**Base structure:**

```css
:root {
  /* Semantic color roles */
  --color-background: ...;
  --color-surface: ...;
  --color-primary: ...;
  --color-secondary: ...;
  --color-accent: ...;
  --color-text-primary: ...;
  --color-text-secondary: ...;
  --color-border: ...;

  /* State colors */
  --color-success: ...;
  --color-warning: ...;
  --color-error: ...;
  --color-info: ...;
}
```

### Theme Inspirations

#### Dark Themes with Character

**Cyberpunk Noir:**

```css
--color-background: #0a0e27;
--color-surface: #1a1f3a;
--color-primary: #00ff9f;
--color-accent: #ff0080;
--color-text-primary: #e0e0e0;
--color-text-secondary: #00ff9f;
```

**Midnight Developer:**

```css
--color-background: #0d1117;
--color-surface: #161b22;
--color-primary: #58a6ff;
--color-accent: #f78166;
--color-text-primary: #c9d1d9;
--color-text-secondary: #8b949e;
```

**Obsidian Purple:**

```css
--color-background: #1e1e2e;
--color-surface: #2a2a3e;
--color-primary: #bb9af7;
--color-accent: #f7768e;
--color-text-primary: #cdd6f4;
--color-text-secondary: #9399b2;
```

#### Light Themes with Personality

**Warm Minimal:**

```css
--color-background: #fefcf8;
--color-surface: #ffffff;
--color-primary: #d4734c;
--color-accent: #a85c3f;
--color-text-primary: #2a2520;
--color-text-secondary: #6b5f54;
```

**Botanical:**

```css
--color-background: #f5f8f3;
--color-surface: #ffffff;
--color-primary: #3a6b35;
--color-accent: #c77966;
--color-text-primary: #1f2d1c;
--color-text-secondary: #5a6c57;
```

**High-Contrast Editorial:**

```css
--color-background: #ffffff;
--color-surface: #fafafa;
--color-primary: #000000;
--color-accent: #ff3366;
--color-text-primary: #000000;
--color-text-secondary: #666666;
```

#### Thematic Approaches

**IDE-Inspired:**

- Dracula, Nord, Solarized, Tokyo Night, Catppuccin
- Strong developer appeal
- Proven readability
- Built-in community recognition

**Cultural Aesthetics:**

- Japanese minimalism: Neutral tones, subtle accents
- Scandinavian: Cool grays, natural blues, warm wood tones
- Brutalist: High contrast, pure black/white, bold accents
- Vaporwave: Pastels, gradients, retro-futuristic

**Contextual:**

- Match product domain (finance → trust blues, creative → vibrant)
- Align with brand personality
- Consider user expectations while subverting them creatively

### Color Contrast & Accessibility

While creating distinctive aesthetics, maintain WCAG contrast standards:

- **Normal text**: 4.5:1 minimum
- **Large text**: 3:1 minimum
- **UI components**: 3:1 minimum

**Tools:**

- Use contrast checkers during palette creation
- Test with actual content, not just swatches
- Ensure both light and dark themes meet standards

### Gradients

Gradients add depth and atmosphere but must be used intentionally.

**Effective gradient patterns:**

**Subtle backgrounds:**

```css
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
```

**Mesh gradients (modern):**

```css
background:
  radial-gradient(at 40% 20%, #667eea 0px, transparent 50%),
  radial-gradient(at 80% 0%, #764ba2 0px, transparent 50%),
  radial-gradient(at 0% 50%, #f093fb 0px, transparent 50%);
```

**Text gradients:**

```css
background: linear-gradient(90deg, #667eea, #764ba2);
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
```

**Avoid:**

- Overused purple-pink gradients
- Gradients everywhere (use sparingly for impact)
- Poor contrast with text overlays

---

## Motion & Animation

Motion creates delight, provides feedback, and guides attention. Prioritize high-impact moments over scattered micro-interactions.

### Animation Philosophy

**Strategic approach:**

- One well-orchestrated page load creates more delight than scattered animations
- Focus on moments that matter: initial load, completion, key interactions
- Use animation to communicate state changes and relationships
- Prefer CSS-only solutions for HTML; use animation libraries for complex React

### CSS Animation Patterns

#### Page Load Orchestration

**Staggered reveal (high impact):**

```css
.hero-title {
  animation: fadeInUp 0.8s ease-out;
}

.hero-subtitle {
  animation: fadeInUp 0.8s ease-out 0.2s both;
}

.hero-cta {
  animation: fadeInUp 0.8s ease-out 0.4s both;
}

@keyframes fadeInUp {
  from {
    opacity: 0;
    transform: translateY(30px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}
```

**Cascade effect:**

```css
.card {
  animation: scaleIn 0.5s cubic-bezier(0.34, 1.56, 0.64, 1);
}

.card:nth-child(1) {
  animation-delay: 0s;
}
.card:nth-child(2) {
  animation-delay: 0.1s;
}
.card:nth-child(3) {
  animation-delay: 0.2s;
}

@keyframes scaleIn {
  from {
    opacity: 0;
    transform: scale(0.8);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}
```

#### Micro-Interactions

**Button hover:**

```css
.button {
  transition:
    transform 0.2s ease,
    box-shadow 0.2s ease;
}

.button:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

.button:active {
  transform: translateY(0);
}
```

**Input focus:**

```css
.input {
  border: 2px solid transparent;
  transition:
    border-color 0.2s ease,
    box-shadow 0.2s ease;
}

.input:focus {
  border-color: var(--color-primary);
  box-shadow: 0 0 0 3px rgba(var(--color-primary-rgb), 0.1);
}
```

#### Loading States

**Skeleton screens:**

```css
.skeleton {
  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
  background-size: 200% 100%;
  animation: loading 1.5s infinite;
}

@keyframes loading {
  0% {
    background-position: 200% 0;
  }
  100% {
    background-position: -200% 0;
  }
}
```

**Spinner (custom):**

```css
.spinner {
  border: 3px solid rgba(0, 0, 0, 0.1);
  border-top-color: var(--color-primary);
  border-radius: 50%;
  width: 40px;
  height: 40px;
  animation: spin 0.8s linear infinite;
}

@keyframes spin {
  to {
    transform: rotate(360deg);
  }
}
```

### React Animation Libraries

For complex React animations, use established libraries:

**Framer Motion** (recommended):

```jsx
import { motion } from 'framer-motion';

<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.5 }}
>
  Content
</motion.div>;
```

**Staggered children:**

```jsx
const container = {
  hidden: { opacity: 0 },
  show: {
    opacity: 1,
    transition: {
      staggerChildren: 0.1,
    },
  },
};

const item = {
  hidden: { opacity: 0, y: 20 },
  show: { opacity: 1, y: 0 },
};

<motion.div variants={container} initial="hidden" animate="show">
  <motion.div variants={item}>Item 1</motion.div>
  <motion.div variants={item}>Item 2</motion.div>
  <motion.div variants={item}>Item 3</motion.div>
</motion.div>;
```

### Animation Timing

**Easing functions:**

- **ease-out**: Best for enter animations (starts fast, ends slow)
- **ease-in**: Best for exit animations (starts slow, ends fast)
- **ease-in-out**: Best for state changes
- **cubic-bezier**: Custom curves for unique feel

**Duration guidelines:**

- **Micro-interactions**: 150-300ms
- **Component transitions**: 300-500ms
- **Page transitions**: 500-800ms
- **Dramatic moments**: 800ms-1.2s

### Performance Considerations

**Optimize for performance:**

- Animate `transform` and `opacity` (GPU-accelerated)
- Avoid animating `width`, `height`, `top`, `left` (causes layout recalculation)
- Use `will-change` sparingly for heavy animations
- Respect `prefers-reduced-motion`

```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}
```

---

## Backgrounds

Backgrounds create atmosphere and depth. Move beyond solid colors to establish visual richness.

### Background Strategies

#### Layered Gradients

**Atmospheric depth:**

```css
background:
  radial-gradient(ellipse at top, rgba(102, 126, 234, 0.15), transparent),
  radial-gradient(ellipse at bottom, rgba(118, 75, 162, 0.15), transparent), #0a0e27;
```

**Mesh gradient (modern):**

```css
background:
  radial-gradient(at 0% 0%, #667eea 0px, transparent 50%),
  radial-gradient(at 50% 0%, #764ba2 0px, transparent 50%),
  radial-gradient(at 100% 0%, #f093fb 0px, transparent 50%), #1a1a2e;
```

#### Geometric Patterns

**Dots:**

```css
background-image: radial-gradient(circle, #333 1px, transparent 1px);
background-size: 20px 20px;
```

**Grid:**

```css
background-image:
  linear-gradient(rgba(255, 255, 255, 0.05) 1px, transparent 1px),
  linear-gradient(90deg, rgba(255, 255, 255, 0.05) 1px, transparent 1px);
background-size: 50px 50px;
```

**Diagonal stripes:**

```css
background-image: repeating-linear-gradient(
  45deg,
  transparent,
  transparent 10px,
  rgba(255, 255, 255, 0.03) 10px,
  rgba(255, 255, 255, 0.03) 20px
);
```

#### Noise Texture

Add subtle texture for depth:

```css
background: #1a1a2e;
position: relative;

/* Use ::before for noise overlay */
&::before {
  content: '';
  position: absolute;
  inset: 0;
  background-image: url('data:image/svg+xml,...'); /* noise pattern */
  opacity: 0.05;
  pointer-events: none;
}
```

#### Contextual Effects

**Spotlight effect:**

```css
background:
  radial-gradient(
    circle at var(--mouse-x, 50%) var(--mouse-y, 50%),
    rgba(255, 255, 255, 0.1) 0%,
    transparent 50%
  ),
  #0a0e27;
```

**Vignette:**

```css
background: radial-gradient(ellipse at center, transparent 0%, rgba(0, 0, 0, 0.4) 100%), #1a1a2e;
```

### Image Backgrounds

When using images:

- Apply overlays for text legibility
- Use high-quality, contextually relevant images
- Consider dark/light theme variations
- Optimize for performance (WebP, lazy loading)

```css
.hero {
  background-image: linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0.5)), url('/hero-image.jpg');
  background-size: cover;
  background-position: center;
}
```

---

## Layout & Spatial Design

### Container Widths

**Intentional constraints create focus:**

```css
--container-sm: 640px; /* Narrow content (articles) */
--container-md: 768px; /* Standard content */
--container-lg: 1024px; /* Wide content */
--container-xl: 1280px; /* App layouts */
--container-2xl: 1536px; /* Maximum width */
```

### Spacing Scale

**Consistent spacing creates rhythm:**

```css
--space-1: 0.25rem; /* 4px */
--space-2: 0.5rem; /* 8px */
--space-3: 0.75rem; /* 12px */
--space-4: 1rem; /* 16px */
--space-6: 1.5rem; /* 24px */
--space-8: 2rem; /* 32px */
--space-12: 3rem; /* 48px */
--space-16: 4rem; /* 64px */
--space-24: 6rem; /* 96px */
```

### Depth & Elevation

**Shadow system for hierarchy:**

```css
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
--shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.15);
```

---

## Avoiding Generic AI Aesthetics

### Common Pitfalls

**Visual clichés to avoid:**

- Purple gradient hero sections
- Rounded cards with drop shadows everywhere
- Generic illustrations (undraw.co style)
- Cookie-cutter layouts (header, hero, three features, footer)
- Predictable color schemes
- Overused fonts (Inter, Roboto)

### Creating Distinctive Designs

**Strategies for originality:**

1. **Reference unexpected sources**: Architecture, fashion, print design, art movements
2. **Combine contrasting aesthetics**: Brutalism + soft colors, minimalism + bold typography
3. **Commit to a strong direction**: Don't hedge with "safe" choices
4. **Add contextual details**: Design elements that relate to content, not just decoration
5. **Break conventions intentionally**: Unusual layouts, unexpected interactions
6. **Develop a signature**: Recurring motifs, unique spacing, distinctive component styles

**Questions to ask:**

- Does this feel machine-generated or thoughtfully designed?
- Have I seen this exact combination before?
- Does this design have personality and point of view?
- Would a user remember this interface?
- Does the aesthetic match the product's unique context?

---

## Implementation Checklist

When designing a new interface:

- [ ] Choose distinctive typography (avoid Inter, Roboto, Arial)
- [ ] Develop cohesive color system with CSS variables
- [ ] Create dominant palette with sharp accents (not evenly distributed)
- [ ] Design one well-orchestrated page load animation
- [ ] Add atmospheric backgrounds (not just solid colors)
- [ ] Establish clear visual hierarchy
- [ ] Implement smooth micro-interactions on key elements
- [ ] Ensure accessibility (contrast, reduced motion)
- [ ] Test that design feels distinctive and contextually appropriate
- [ ] Verify it doesn't look like generic AI output

---

## Cross-Reference with UX Psychology

Combine UI aesthetics with UX psychology for maximum impact:

- **Visual hierarchy** supports **cognitive load management**
- **Motion design** reinforces **peak moments** in user journey
- **Color psychology** enhances **framing effects** and **emotional response**
- **Typography** affects **perceived credibility** (halo effect)
- **Aesthetic quality** leverages **aesthetic-usability effect**

For detailed UX psychology principles, see `ux-psychology.md`.

```

### references/ux-psychology.md

```markdown
# UX Psychology Principles

This reference provides detailed UX psychology principles and patterns to inform design decisions that improve user engagement, conversion, and satisfaction.

## Core Principles

### Cognitive Load Management

**Cognitive Load** refers to the mental effort required to process information. Minimize cognitive load to improve user experience.

#### Progressive Disclosure

Reveal information gradually rather than all at once.

**When to use:**

- Complex multi-step processes (registration, checkout, configuration)
- Feature-rich interfaces with advanced options
- Data-heavy dashboards

**Implementation patterns:**

- Accordion menus for nested information
- Step-by-step wizards with progress indicators
- "Advanced options" expandable sections
- Contextual help that appears on demand

**Example applications:**

- Registration forms: Start with email/password, then collect profile details
- Dashboard filters: Show basic filters first, hide advanced filters behind a toggle
- Product configuration: Break complex customization into sequential steps

#### Visual Hierarchy

Establish clear priority through size, color, contrast, and spacing.

**Hierarchy levels:**

1. **Primary**: Main action or critical information (largest, highest contrast)
2. **Secondary**: Supporting actions or context (medium size, moderate contrast)
3. **Tertiary**: Optional details or metadata (smallest, lowest contrast)

**Implementation:**

- Use size and weight to indicate importance
- Apply color to direct attention (sparingly)
- Create whitespace around high-priority elements
- Group related items to reduce mental parsing

---

## Decision-Making Psychology

### Value Perception Effects

#### Anchoring Effect

The first piece of information encountered heavily influences subsequent judgments.

**When to use:**

- Pricing displays
- Setting expectations for form completion time
- Establishing baseline metrics in dashboards

**Implementation patterns:**

- Show original price before discounted price
- Display estimated completion time at the start of a process
- Present context ("Most users complete this in 5 minutes") before task
- Set default values that guide user toward optimal choice

**Anti-patterns to avoid:**

- Manipulative anchoring that misleads users
- Constantly changing anchors that erode trust

#### Framing Effect

How information is presented affects decision-making, even when content is identical.

**Positive framing examples:**

- "95% success rate" vs "5% failure rate"
- "Join 10,000 users" vs "Don't miss out"
- "Save $50" vs "Only $50 more"

**When to use:**

- Call-to-action buttons
- Feature descriptions
- Error messages (reframe as solutions)
- Progress indicators (show completion, not remaining work)

**Implementation:**

- Emphasize gains over losses
- Use action-oriented language
- Focus on benefits, not just features
- Present choices in a context that highlights value

#### Decoy Effect (Asymmetric Dominance)

Adding a third option makes one of the original two options more attractive.

**Classic pattern:**

- **Basic**: $10/month
- **Premium**: $30/month (seems expensive)
- **Pro** (decoy): $28/month with fewer features than Premium

Result: Premium now appears as better value.

**When to use:**

- Pricing tiers
- Feature comparison tables
- Subscription plans

**Guidelines:**

- The decoy should be clearly inferior to the target option
- The decoy should be similar in price to the target
- Use sparingly and ethically

### Loss and Gain Psychology

#### Loss Aversion

People feel losses roughly twice as strongly as equivalent gains.

**When to use:**

- Preventing user churn
- Encouraging feature adoption
- Motivating action completion

**Implementation patterns:**

- "You'll lose your progress if you leave now"
- "Your discount expires in 24 hours"
- "Don't miss out on..." (sparingly, to avoid manipulation)
- Show what users will miss, not just what they'll gain

**Ethical considerations:**

- Avoid creating artificial scarcity or false urgency
- Provide genuine value, not just fear-based motivation
- Balance loss messaging with positive framing

#### Sunk Cost Effect

Users continue investing in something because they've already invested resources.

**When to use:**

- Onboarding flows
- Multi-step processes
- Gamification systems

**Implementation patterns:**

- Progress bars showing completion percentage
- "You're 80% done!" messaging
- Profile completion indicators
- Level/achievement systems that track accumulated effort

**Design considerations:**

- Make progress visible and meaningful
- Provide value at each step, not just at completion
- Allow users to save progress and return later

---

## Attention and Memory

### Peak-End Rule

Users judge experiences based on the peak (most intense moment) and the end, not the average.

**Application in design:**

- Optimize the highest-impact moment in user journey
- Ensure final interaction leaves positive impression
- Don't assume users evaluate the entire experience equally

**Implementation:**

- **Onboarding peak**: Deliver "aha moment" quickly (not after completing entire setup)
- **Purchase end**: Confirmation page with celebration, not just receipt
- **Task completion**: Satisfying animation or acknowledgment
- **Error recovery**: Turn frustrating moment into delightful support experience

**Example patterns:**

- Confetti animation on successful subscription
- Personalized "Welcome aboard!" message with user's name
- Gamified achievements for milestone completion
- Graceful error messages with helpful next steps and personality

### Serial Position Effect

Items at the beginning and end of a list are remembered better than middle items.

**When to use:**

- Navigation menus
- Feature lists
- Pricing comparison tables
- Form field ordering

**Implementation:**

- Place most important items first or last
- Put critical CTAs at the end of content flow
- Position destructive actions (delete, cancel) away from primacy/recency positions
- Use middle positions for less critical items

### Zeigarnik Effect

People remember uncompleted or interrupted tasks better than completed ones.

**When to use:**

- Multi-step processes
- Content consumption experiences
- Task management interfaces
- Gamification

**Implementation patterns:**

- Progress bars that show partial completion
- Checklists with some items checked
- "Continue where you left off" features
- Incomplete profile indicators
- Unfinished lesson/module trackers

**Best practices:**

- Make it easy to resume interrupted tasks
- Don't frustrate users by creating artificial incompleteness
- Provide value even if user doesn't complete everything

---

## Behavioral Design Techniques

### Nudge Theory

Subtle design cues guide users toward beneficial actions without restricting choice.

**When to use:**

- Encouraging best practices
- Improving security behavior
- Promoting healthy usage patterns

**Implementation patterns:**

- Pre-select recommended options (but allow changing)
- Use visual cues to highlight suggested path
- Provide contextual tips at decision points
- Default to privacy-protecting settings

**Examples:**

- Pre-check "Enable two-factor authentication (recommended)"
- Highlight "Most popular" pricing tier
- Show "Other users also..." suggestions
- Default to "Save password securely"

**Ethical guidelines:**

- Nudge toward user's benefit, not just business goals
- Always preserve user autonomy
- Make it easy to choose different option
- Be transparent about recommendations

### Gamification

Apply game mechanics to increase engagement and motivation.

**Core mechanics:**

- **Points/scores**: Quantify progress and achievement
- **Levels/tiers**: Provide progression framework
- **Badges/achievements**: Recognize accomplishments
- **Leaderboards**: Enable social comparison (use carefully)
- **Challenges/quests**: Create structured goals

**When to use:**

- Learning platforms
- Productivity tools
- Community engagement
- Health and fitness applications

**Implementation considerations:**

- Ensure mechanics serve user goals, not just engagement metrics
- Avoid addictive dark patterns
- Provide intrinsic value beyond game elements
- Consider users who don't respond to gamification

### Foot-in-the-Door Technique

Start with small request, then progress to larger commitment.

**When to use:**

- User onboarding
- Permission requests
- Account creation
- Newsletter signup

**Implementation pattern:**

1. Small ask: "Just enter your email"
2. Medium ask: "Tell us your interests"
3. Larger ask: "Create full profile"

**Best practices:**

- Provide value at each step
- Make each step genuinely optional
- Don't hide the full scope of eventual request
- Build trust progressively

### Variable Rewards

Unpredictable rewards create stronger engagement than predictable ones.

**Types:**

- **Rewards of the tribe**: Social validation (likes, follows)
- **Rewards of the hunt**: Material resources (discounts, prizes)
- **Rewards of the self**: Personal achievement (mastery, completion)

**When to use:**

- Social features
- Achievement systems
- Content discovery
- Engagement loops

**Ethical considerations:**

- Avoid creating addictive patterns
- Ensure core value exists beyond reward mechanism
- Don't exploit psychological vulnerabilities
- Consider time-well-spent principles

### Scarcity Effect

Limited availability increases perceived value.

**Types:**

- **Time-limited**: "Offer ends in 24 hours"
- **Quantity-limited**: "Only 3 left in stock"
- **Access-limited**: "Exclusive to members"

**When to use:**

- Special promotions
- Limited releases
- Exclusive features

**Ethical implementation:**

- Use only when scarcity is genuine
- Avoid creating false urgency
- Don't pressure users into hasty decisions
- Provide clear, honest information

**Anti-patterns:**

- Fake countdown timers that reset
- Artificial stock limitations
- Manufactured exclusivity

---

## Performance and Quality

### Doherty Threshold

Response times under 400ms maintain user engagement; beyond this, interest deteriorates.

**Critical thresholds:**

- **<100ms**: Feels instantaneous
- **100-400ms**: Slight delay, but flow maintained
- **400ms-1s**: User notices delay
- **>1s**: User's attention begins to wander

**Implementation strategies:**

- Optimize critical path rendering
- Use optimistic UI updates
- Show loading indicators for >400ms operations
- Implement progressive loading
- Use skeleton screens for perceived performance
- Cache aggressively
- Defer non-critical operations

**Perceived performance techniques:**

- Animate elements while loading (gives sense of progress)
- Load above-the-fold content first
- Show partial results immediately
- Provide feedback within 100ms of user action

### Decision Fatigue

The quality of decisions deteriorates after making many decisions.

**When to consider:**

- Long forms
- Complex configuration flows
- Multi-step checkout processes

**Mitigation strategies:**

- Reduce number of choices at each step
- Provide smart defaults
- Save decisions for later
- Order decisions strategically (most important first)
- Group related decisions together
- Use progressive disclosure

**Implementation:**

- Break long forms into multiple pages
- Offer "Recommended settings" option
- Allow saving and resuming
- Minimize optional fields
- Use intelligent defaults based on user context

---

## Trust and Credibility

### Social Proof

People look to others' behavior to guide their own actions.

**Types:**

- **User numbers**: "Join 50,000+ users"
- **Testimonials**: Real user quotes
- **Ratings/reviews**: Star ratings and detailed feedback
- **Activity indicators**: "23 people viewing this now"
- **Expert endorsements**: Industry authority recommendations
- **Certifications**: Trust badges and security indicators

**When to use:**

- Landing pages
- Product pages
- Checkout flows
- Sign-up flows

**Best practices:**

- Use genuine, verifiable social proof
- Show recent activity (timestamps)
- Include specific details (not just numbers)
- Match social proof to user context

### Halo Effect

Positive impression in one area influences perception of other areas.

**Application in design:**

- Beautiful UI suggests reliable functionality
- Strong brand presence implies trustworthiness
- Attention to detail signals quality throughout

**Implementation:**

- Invest in visual polish
- Maintain consistency across touchpoints
- Highlight quality indicators
- Associate with trusted brands/certifications

### Aesthetic-Usability Effect

Users perceive attractive designs as more usable, even if they're not.

**Implications:**

- Visual design directly impacts perceived functionality
- Users are more tolerant of minor usability issues in beautiful interfaces
- First impressions heavily weight aesthetic quality

**Balance considerations:**

- Don't use aesthetics to mask poor usability
- Ensure actual usability matches aesthetic promise
- Invest in both beauty and function
- Test with real users, not just designers

---

## Implementation Priorities

When applying UX psychology principles, prioritize based on impact and context:

### High-Priority Universals

Apply to almost all interfaces:

1. **Progressive disclosure**: Prevent information overload
2. **Visual hierarchy**: Guide attention effectively
3. **Doherty threshold**: Optimize performance
4. **Peak-end rule**: Optimize critical moments
5. **Clear framing**: Use positive, action-oriented language

### Context-Dependent

Apply when relevant:

- **Gamification**: Learning, productivity, community platforms
- **Social proof**: E-commerce, SaaS landing pages, communities
- **Scarcity**: Promotions, limited releases (use ethically)
- **Variable rewards**: Social features, content discovery

### Use Sparingly

Powerful but easy to misuse:

- **Loss aversion**: Can feel manipulative if overused
- **Decoy effect**: Should feel natural, not forced
- **Scarcity effect**: Only when genuinely limited

### Ethical Considerations

Always prioritize:

- User autonomy and informed choice
- Transparent communication
- Genuine value delivery
- Long-term user well-being over short-term metrics
- Privacy and security

---

## Cross-Reference with UI Aesthetics

Combine UX psychology with UI aesthetics for maximum impact:

- **Cognitive load** + **Visual hierarchy**: Use typography scale and color to guide attention
- **Peak-end rule** + **Motion design**: Create memorable moments with well-crafted animations
- **Progressive disclosure** + **Spatial design**: Use depth and layering to reveal information
- **Social proof** + **Typography**: Make testimonials visually compelling
- **Aesthetic-usability effect** + **Color & theme**: Beautiful palettes improve perceived functionality

For detailed UI aesthetic guidelines, see `ui-aesthetics.md`.

```