Frontend Design System Skill

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!

Agent Skills: Frontend Design System

Skill Files