Frontend Design System

Philosophy: Every pixel has purpose. Restraint is luxury. User psychology drives decisions. Core Principle: THINK, don't memorize. ASK, don't assume.

🎯 Selective Reading Rule (MANDATORY)

Read REQUIRED files always, OPTIONAL only when needed:

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

• Security cues where appropriate

• Social proof / testimonials

• Clear value proposition

• Professional imagery

• Consistent design language

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!