File	Status	When to Read
ux-psychology.md	🔴 REQUIRED	Always read first!
color-system.md	⚪ Optional	Color/palette decisions
typography-system.md	⚪ Optional	Font selection/pairing
visual-effects.md	⚪ Optional	Glassmorphism, shadows, gradients
animation-guide.md	⚪ Optional	Animation needed
motion-graphics.md	⚪ Optional	Lottie, GSAP, 3D
decision-trees.md	⚪ Optional	Context templates

🔴 ux-psychology.md = ALWAYS READ. Others = only if relevant.

🔧 Runtime Scripts

Execute these for audits (don't read, just run):

Script	Purpose	Usage
`scripts/ux_audit.py`	UX Psychology & Accessibility Audit	`python scripts/ux_audit.py <project_path>`

⚠️ CRITICAL: ASK BEFORE ASSUMING (MANDATORY)

STOP! If the user's request is open-ended, DO NOT default to your favorites.

When User Prompt is Vague, ASK:

Color not specified? Ask:

"What color palette do you prefer? (blue/green/orange/neutral/other?)"

Style not specified? Ask:

"What style are you going for? (minimal/bold/retro/futuristic/organic?)"

Layout not specified? Ask:

"Do you have a layout preference? (single column/grid/asymmetric/full-width?)"

⛔ DEFAULT TENDENCIES TO AVOID (ANTI-SAFE HARBOR):

AI Default Tendency	Why It's Bad	Think Instead
Bento Grids (Modern Cliché)	Used in every AI design	Why does this content NEED a grid?
Hero Split (Left/Right)	Predictable & Boring	How about Massive Typography or Vertical Narrative?
Mesh/Aurora Gradients	The "new" lazy background	What's a radical color pairing?
Glassmorphism	AI's idea of "premium"	How about solid, high-contrast flat?
Deep Cyan / Fintech Blue	Safe harbor from purple ban	Why not Red, Black, or Neon Green?
"Orchestrate / Empower"	AI-generated copywriting	How would a human say this?
Dark background + neon glow	Overused, "AI look"	What does the BRAND actually need?
Rounded everything	Generic/Safe	Where can I use sharp, brutalist edges?

🔴 "Every 'safe' structure you choose brings you one step closer to a generic template. TAKE RISKS."

1. Constraint Analysis (ALWAYS FIRST)

Before any design work, ANSWER THESE or ASK USER:

Constraint	Question	Why It Matters
Timeline	How much time?	Determines complexity
Content	Ready or placeholder?	Affects layout flexibility
Brand	Existing guidelines?	May dictate colors/fonts
Tech	What stack?	Affects capabilities
Audience	Who exactly?	Drives all visual decisions

Audience → Design Approach

Audience	Think About
Gen Z	Bold, fast, mobile-first, authentic
Millennials	Clean, minimal, value-driven
Gen X	Familiar, trustworthy, clear
Boomers	Readable, high contrast, simple
B2B	Professional, data-focused, trust
Luxury	Restrained elegance, whitespace

2. UX Psychology Principles

Core Laws (Internalize These)

Law	Principle	Application
Hick's Law	More choices = slower decisions	Limit options, use progressive disclosure
Fitts' Law	Bigger + closer = easier to click	Size CTAs appropriately
Miller's Law	~7 items in working memory	Chunk content into groups
Von Restorff	Different = memorable	Make CTAs visually distinct
Serial Position	First/last remembered most	Key info at start/end

Emotional Design Levels

VISCERAL (instant)  → First impression: colors, imagery, overall feel
BEHAVIORAL (use)    → Using it: speed, feedback, efficiency
REFLECTIVE (memory) → After: "I like what this says about me"

Trust Building

Security indicators on sensitive actions
Social proof where relevant
Clear contact/support access
Consistent, professional design
Transparent policies

3. Layout Principles

Golden Ratio (φ = 1.618)

Use for proportional harmony:
├── Content : Sidebar = roughly 62% : 38%
├── Each heading size = previous × 1.618 (for dramatic scale)
├── Spacing can follow: sm → md → lg (each × 1.618)

8-Point Grid Concept

All spacing and sizing in multiples of 8:
├── Tight: 4px (half-step for micro)
├── Small: 8px
├── Medium: 16px
├── Large: 24px, 32px
├── XL: 48px, 64px, 80px
└── Adjust based on content density

Key Sizing Principles

Element	Consideration
Touch targets	Minimum comfortable tap size
Buttons	Height based on importance hierarchy
Inputs	Match button height for alignment
Cards	Consistent padding, breathable
Reading width	45-75 characters optimal

4. Color Principles

60-30-10 Rule

60% → Primary/Background (calm, neutral base)
30% → Secondary (supporting areas)
10% → Accent (CTAs, highlights, attention)

Color Psychology (For Decision Making)

If You Need...	Consider Hues	Avoid
Trust, calm	Blue family	Aggressive reds
Growth, nature	Green family	Industrial grays
Energy, urgency	Orange, red	Passive blues
Luxury, creativity	Deep Teal, Gold, Emerald	Cheap-feeling brights
Clean, minimal	Neutrals	Overwhelming color

Selection Process

What's the industry? (narrows options)
What's the emotion? (picks primary)
Light or dark mode? (sets foundation)
ASK USER if not specified

For detailed color theory: color-system.md

5. Typography Principles

Scale Selection

Content Type	Scale Ratio	Feel
Dense UI	1.125-1.2	Compact, efficient
General web	1.25	Balanced (most common)
Editorial	1.333	Readable, spacious
Hero/display	1.5-1.618	Dramatic impact

Pairing Concept

Contrast + Harmony:
├── DIFFERENT enough for hierarchy
├── SIMILAR enough for cohesion
└── Usually: display + neutral, or serif + sans

Readability Rules

Line length: 45-75 characters optimal
Line height: 1.4-1.6 for body text
Contrast: Check WCAG requirements
Size: 16px+ for body on web

For detailed typography: typography-system.md

6. Visual Effects Principles

Glassmorphism (When Appropriate)

Key properties:
├── Semi-transparent background
├── Backdrop blur
├── Subtle border for definition
└── ⚠️ **WARNING:** Standard blue/white glassmorphism is a modern cliché. Use it radically or not at all.

Shadow Hierarchy

Elevation concept:
├── Higher elements = larger shadows
├── Y-offset > X-offset (light from above)
├── Multiple layers = more realistic
└── Dark mode: may need glow instead

Gradient Usage

Harmonious gradients:
├── Adjacent colors on wheel (analogous)
├── OR same hue, different lightness
├── Avoid harsh complementary pairs
├── 🚫 **NO Mesh/Aurora Gradients** (floating blobs)
└── VARY from project to project radically

For complete effects guide: visual-effects.md

7. Animation Principles

Timing Concept

Duration based on:
├── Distance (further = longer)
├── Size (larger = slower)
├── Importance (critical = clear)
└── Context (urgent = fast, luxury = slow)

Easing Selection

Action	Easing	Why
Entering	Ease-out	Decelerate, settle in
Leaving	Ease-in	Accelerate, exit
Emphasis	Ease-in-out	Smooth, deliberate
Playful	Bounce	Fun, energetic

Performance

Animate only transform and opacity
Respect reduced-motion preference
Test on low-end devices

For animation patterns: animation-guide.md, for advanced: motion-graphics.md

8. "Wow Factor" Checklist

Premium Indicators

Generous whitespace (luxury = breathing room)
Subtle depth and dimension
Smooth, purposeful animations
Attention to detail (alignment, consistency)
Cohesive visual rhythm
Custom elements (not all defaults)

Trust Builders

Emotional Triggers

Hero that evokes intended emotion
Human elements (faces, stories)
Progress/achievement indicators
Moments of delight

9. Anti-Patterns (What NOT to Do)

❌ Lazy Design Indicators

Default system fonts without consideration
Stock imagery that doesn't match
Inconsistent spacing
Too many competing colors
Walls of text without hierarchy
Inaccessible contrast

❌ AI Tendency Patterns (AVOID!)

Same colors every project
Dark + neon as default
Purple/violet everything (PURPLE BAN ✅)
Bento grids for simple landing pages
Mesh Gradients & Glow Effects
Same layout structure / Vercel clone
Not asking user preferences

❌ Dark Patterns (Unethical)

Hidden costs
Fake urgency
Forced actions
Deceptive UI
Confirmshaming

10. Decision Process Summary

For EVERY design task:

1. CONSTRAINTS
   └── What's the timeline, brand, tech, audience?
   └── If unclear → ASK

2. CONTENT
   └── What content exists?
   └── What's the hierarchy?

3. STYLE DIRECTION
   └── What's appropriate for context?
   └── If unclear → ASK (don't default!)

4. EXECUTION
   └── Apply principles above
   └── Check against anti-patterns

5. REVIEW
   └── "Does this serve the user?"
   └── "Is this different from my defaults?"
   └── "Would I be proud of this?"

Reference Files

For deeper guidance on specific areas:

color-system.md - Color theory and selection process
typography-system.md - Font pairing and scale decisions
visual-effects.md - Effects principles and techniques
animation-guide.md - Motion design principles
motion-graphics.md - Advanced: Lottie, GSAP, SVG, 3D, Particles
decision-trees.md - Context-specific templates
ux-psychology.md - User psychology deep dive

Remember: Design is THINKING, not copying. Every project deserves fresh consideration based on its unique context and users. Avoid the Modern SaaS Safe Harbor!

frontend-design

Frontend Design System

🎯 Selective Reading Rule (MANDATORY)