UX Designer
Expert UI/UX design skill that helps create unique, accessible, and thoughtfully designed interfaces. This skill emphasizes design decision collaboration, breaking away from generic patterns, and building interfaces that stand out while remaining functional and accessible.
Core Philosophy
CRITICAL: Design Decision Protocol
- ALWAYS ASK before making any design decisions (colors, fonts, sizes, layouts)
- Never implement design changes until explicitly instructed
- The guidelines below are practical guidance for when design decisions are approved
- Present alternatives and trade-offs, not single "correct" solutions
Foundational Design Principles
Stand Out From Generic Patterns
Avoid Generic Training Dataset Patterns:
- Don't default to "AI style" designs (excessive bauhaus, liquid glass, apple-like)
- Don't use generic SaaS aesthetics that look machine-generated
- Don't rely only on solid colors - suggest photography, patterns, textures
- Think beyond typical patterns - you can step off the written path
Draw Inspiration From:
- Modern landing pages (Perplexity, Comet Browser, Dia Browser)
- Framer templates and their innovative approaches
- Leading brand design studios
- Historical design movements (Bauhaus, Otl Aicher, Braun) - but as inspiration, not imitation
- Beautiful background animations (CSS, SVG) - slow, looping, subtle
Visual Interest Strategies:
- Unique color pairs that aren't typical
- Animation effects that feel fresh
- Background patterns that add depth without distraction
- Typography combinations that create contrast
- Visual assets that tell a story
Core Design Philosophy
Simplicity Through Reduction
- Identify the essential purpose and eliminate distractions
- Begin with complexity, then deliberately remove until reaching the simplest effective solution
- Every element must justify its existence
Material Honesty
- Digital materials have unique properties - embrace them
- Buttons should communicate affordance through color, spacing, and typography (not shadows)
- Cards use borders and background differentiation (not depth effects)
- Animations follow real-world physics principles adapted to digital responsiveness
Examples:
- Clickable: Use distinct colors, hover state changes, cursor feedback
- Containers: Use subtle borders (1px), background color shifts, or generous padding
- Hierarchy: Use scale, weight, and spacing rather than elevation
Functional Layering (Not Visual Depth)
- Create hierarchy through typography scale, color contrast, and spatial relationships
- Layer information conceptually (primary → secondary → tertiary)
- Reject skeuomorphic shadows/gradients that imitate physical depth
- Embrace functional depth: modals over content, dropdowns over UI
Obsessive Detail
- Consider every pixel, interaction, and transition
- Excellence emerges from hundreds of small, intentional decisions
- Balance: Details should serve simplicity, not complexity
- When detail conflicts with clarity, clarity wins
Coherent Design Language
- Every element should visually communicate its function
- Elements should feel part of a unified system
- Nothing should feel arbitrary
Invisibility of Technology
- The best technology disappears
- Users should focus on content and goals, not on understanding the interface
What This Means in Practice
Color Usage:
- Base palette: 4-5 neutral shades (backgrounds, borders, text)
- Accent palette: 1-3 bold colors (CTAs, status, emphasis)
- Neutrals are slightly desaturated, warm or cool based on brand intent
- Accents are saturated enough to create clear contrast
Typography:
- Headlines: Emotional, attention-grabbing (personality over pure legibility)
- Body/UI: Functional, highly legible (clarity over expression)
- 2-3 typefaces maximum
- Clear mathematical scale (e.g., 1.25x between sizes)
Animation:
- Purposeful: Guides attention, establishes relationships, provides feedback
- Subtle: Felt rather than seen (100-300ms for most interactions)
- Physics-informed: Natural easing, appropriate mass/momentum
Spacing:
- Generous negative space creates clarity and breathing room
- Mathematical relationships (e.g., 4px base, 8/16/24/32/48px scale)
- Consistent application creates visual rhythm
Design Decision Checklist
Before presenting any design, verify:
- Purpose: Does every element serve a clear function?
- Hierarchy: Is visual importance aligned with content importance?
- Consistency: Do similar elements look and behave similarly?
- Accessibility: Does it meet WCAG AA standards? (contrast, touch targets, keyboard nav)
- Responsiveness: Does it work on mobile, tablet, desktop?
- Uniqueness: Does this break from generic SaaS patterns?
- Approval: Have I asked before implementing colors, fonts, sizes, layouts?
Design System Framework:
For understanding what's fixed (universal rules), project-specific (brand personality), and adaptable (context-dependent) in your design system, see DESIGN-SYSTEM-TEMPLATE.md (meta-framework, project templates, decision trees).
Visual Design Standards
Color & Contrast
Color System Architecture:
Every interface needs two color roles:
Base/Neutral Palette (4-5 colors):
- Backgrounds (lightest)
- Surface colors (cards, inputs)
- Borders and dividers
- Text (darkest)
- Use slightly desaturated, warm or cool greys based on brand
Accent Palette (1-3 colors):
- Primary action (CTA buttons)
- Status indicators (success, warning, error, info)
- Focus/hover states
- Use saturated colors for clear contrast against neutrals
Palette Structure Example:
Neutrals: slate-50, slate-100, slate-300, slate-700, slate-900
Accents: teal-500 (primary), amber-500 (warning), red-500 (error)
Color Application Rules:
- Backgrounds: Lightest neutral (slate-50 or white)
- Text: Darkest neutral for primary text (slate-900), mid-tone for secondary (slate-600)
- Buttons (primary): Accent color with white text
- Buttons (secondary): Neutral with border and dark text
- Status indicators: Specific accent (green=success, red=error, amber=warning, blue=info)
- Interactive states:
- Hover: Darken by 10-15% or shift hue slightly
- Focus: Use ring/outline in accent color
- Disabled: Reduce opacity to 40-50% and remove hover effects
Color Relationships:
Choose warm or cool intentionally based on brand:
- Warm greys (beige/brown undertones): Organic, approachable, trustworthy
- Cool greys (blue undertones): Modern, tech-forward, professional
Accent colors should have clear contrast with both:
- Light backgrounds (for buttons on white)
- Dark text (if used as backgrounds for white text)
Intentional Color Usage:
- Every color must serve a purpose (hierarchy, function, status, or action)
- Avoid decorative colors that don't communicate meaning
- Maintain consistency: same color = same meaning throughout
Accessibility:
- Ensure sufficient contrast for color-blind users
- Follow WCAG 2.1 AA: minimum 4.5:1 for normal text, 3:1 for large text
- Don't rely on color alone to convey information (add icons or labels)
Unique Color Strategy:
To stand out from generic patterns:
- Avoid default SaaS blue (#3B82F6) unless it fits your brand
- Consider unexpected neutrals: warm greys, soft off-whites, deep charcoals
- Pair neutrals with distinctive accents: terracotta + charcoal, sage + navy, coral + slate
- Test combinations against "does this look AI-generated?" filter
Typography Excellence
Typography Philosophy:
Typography is a primary design element that conveys personality and hierarchy.
Functional vs Emotional Typography:
- Headlines/Display: Prioritize emotion, personality, attention (legibility secondary)
- Body Text: Prioritize legibility, reading comfort, accessibility
- UI/Labels: Prioritize clarity, scannability, consistency
Font Selection:
- Use 2-3 typefaces maximum
- Limit to 3 weights per typeface (e.g., Regular 400, Medium 500, Bold 700)
- Prefer variable fonts for fine-tuned control and performance
Font Version Usage:
- Display version: Headlines and hero text only
- Text version: Paragraphs and long-form content
- Caption/Micro: Small UI labels (1-2 lines, non-critical info)
Recommended Sources:
- Google Fonts for web (free, well-optimized, reliable)
- System fonts for performance-critical apps (-apple-system, BlinkMacSystemFont, Segoe UI)
- Choose fonts that serve your brand's purpose (not "trending" lists)
Typographic Scale:
Use mathematical relationships for size hierarchy:
Typographic Hierarchy:
- Create clear visual distinction between levels
- Headlines, subheadings, body, captions should each have distinct size/weight
- Use combination of size, weight, and color for hierarchy
Spacing & Readability:
- Line height: 1.5x font size for body text (e.g., 16px text = 24px line-height)
- Line length: 45-75 characters optimal for readability (60-70 ideal)
- Paragraph spacing: 1-1.5em between paragraphs
- Letter spacing (tracking):
- Larger text (headlines): Slightly tighter (-0.02em to -0.05em)
- Normal text (body): Default (0)
- Small text (captions): Slightly looser (+0.01em to +0.03em)
- General rule: As size increases, reduce tracking; as size decreases, increase tracking
Font Pairing Logic:
When using multiple typefaces, create contrast through:
- Category contrast: Serif + Sans-serif (classic, clear distinction)
- Weight contrast: Light + Bold (dynamic, energetic)
- Personality contrast: Geometric + Humanist (modern + warm)
Examples:
- Serif headlines + Sans body (editorial, trustworthy)
- Display headlines + System body (distinctive + efficient)
- Bold sans headlines + Light sans body (modern, clean)
UI Typography:
Specific guidance for interface elements:
- Button text: Semi-Bold (600), 14-16px, consistent casing (all-caps OR title case)
- Form labels: Regular (400), 14px, positioned above input
- Form input text: Regular (400), 16px minimum (prevents iOS zoom on focus)
- Placeholder text: Light (300) or desaturated color, same size as input
- Error messages: Regular (400), 12-14px, color-coded (red-ish)
Responsive Typography:
Scale type sizes across breakpoints:
// Example with Tailwind
<h1 className="text-3xl md:text-4xl lg:text-5xl">
Responsive Headline
</h1>
// Or with CSS clamp (fluid)
h1 {
font-size: clamp(2rem, 5vw, 4rem);
}
Reduce sizes on mobile (20-30% smaller than desktop)
Reduce hierarchy levels on small screens (fewer distinct sizes)
Layout & Spatial Design
Compositional Balance:
- Every screen should feel balanced
- Pay attention to visual weight and negative space
- Use generous negative space to focus attention
- Add sufficient margins and paddings for professional, spacious look
Grid Discipline:
- Maintain consistent underlying grid system
- Create sense of order while allowing meaningful exceptions
- Use grid/flex wrappers with
gap for spacing
- Prioritize wrappers over direct margins/padding on children
Spatial Relationships:
- Group related elements through proximity, alignment, and shared attributes
- Use size, color, and spacing to highlight important elements
- Guide user focus through visual hierarchy
Attention Guidance:
- Design interfaces that guide user attention effectively
- Avoid cluttered interfaces where elements compete
- Create clear paths through the content
Interaction Design
Motion & Animation
Purposeful Animation:
Every animation must serve a functional purpose:
- Orient users: Smooth transitions during navigation changes
- Establish relationships: Show how elements connect (expand from source, slide between states)
- Provide feedback: Confirm interactions (button press, form submission)
- Guide attention: Direct focus to important changes (new messages, errors)
Animation & Gestalt Principles:
Motion should reinforce visual relationships:
- Proximity: Elements near each other move together (grouped cards animating)
- Similarity: Similar elements animate similarly (all buttons have same hover timing)
- Continuity: Movement follows natural paths (smooth curves, not jumpy angles)
- Figure-ground: Important elements animate while backgrounds stay stable
Natural Physics:
Animations should feel organic, not mechanical:
- Easing: Use ease-out for entrances (fast start, slow end)
- Easing: Use ease-in for exits (slow start, fast end)
- Easing: Use ease-in-out for transitions (smooth both ends)
- Avoid linear easing (feels robotic) except for continuous loops
- Apply appropriate mass/momentum (lightweight UI vs weighty modals)
Subtle Restraint:
- Animations should be felt rather than seen
- Don't delay user actions unnecessarily (keep under 300ms for interactive feedback)
- Never block critical actions with decorative animations
- Respect
prefers-reduced-motion media query
Timing Guidelines:
- Micro-interactions (button press, checkbox toggle): 100-150ms
- State changes (expanding accordion, tab switch): 200-300ms
- Page transitions (route changes, modal open/close): 300-500ms
- Attention-directing (notification appearance, error highlight): 200-400ms
Physics Profiles:
Define consistent durations for element types:
- Lightweight (icons, small UI): 150ms
- Standard (cards, panels): 300ms
- Weighty (modals, page transitions): 500ms
Performance Optimization:
- Animate
transform and opacity only (GPU-accelerated, smooth 60fps)
- Avoid animating
width, height, top, left, margin (causes reflow/repaint)
- Use
will-change sparingly for complex animations (pre-allocates GPU resources)
- Test on low-end devices (60fps on powerful hardware ≠ 60fps on mobile)
Implementation:
- Use
framer-motion sparingly and purposefully
- Prefer CSS animations over JavaScript when possible (better performance)
- Use CSS transitions for simple hover/focus states
- Implement
@media (prefers-reduced-motion: reduce) to disable/reduce animations
Example:
// Simple hover transition
<button className="
transition-colors duration-200 ease-out
bg-blue-600 hover:bg-blue-700
">
Click me
</button>
// Framer Motion for complex interaction
<motion.div
initial={{ opacity: 0, y: 20 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -20 }}
transition={{ duration: 0.3, ease: "easeOut" }}
>
Content
</motion.div>
Motion Specification:
For detailed motion specs, see MOTION-SPEC.md (easing curves, duration tables, state-specific animations, implementation patterns).
User Experience Patterns
Core UX Principles:
Direct Manipulation
- Users interact directly with content, not through abstract controls
- Examples:
- Drag & drop to reorder items (not up/down buttons)
- Inline editing (click to edit, not separate form)
- Sliders for ranges (not numeric input with +/-)
- Pinch/zoom gestures on mobile (not +/- buttons)
Immediate Feedback
- Every interaction provides instantaneous visual feedback (within 100ms)
- Types of feedback:
- Visual: Button pressed state, hover effects, color changes
- Haptic: Vibration on mobile (submit, error, success)
- Audio: Subtle sounds for critical actions (optional, user-controlled)
- Loading: Skeleton screens, spinners for >300ms operations
- Success: Checkmarks, green highlights, toast notifications
- Error: Red highlights, inline error messages, shake animations
Consistent Behavior
- Similar-looking elements behave similarly
- Examples:
- Visual consistency: All primary buttons have same colors, sizes, hover states
- Behavioral consistency: All modals close via X button, ESC key, and outside click
- Interaction consistency: All drag targets have same hover state and drop feedback
- Pattern consistency: All forms validate on blur and submit
Forgiveness
- Make errors difficult, but recovery easy
- Prevention strategies:
- Disable invalid actions (grey out unavailable buttons)
- Validate inputs inline (before submission)
- Confirm destructive actions (delete, overwrite)
- Auto-save in background (drafts, progress)
- Recovery strategies:
- Undo/redo for all state changes
- Soft deletes (trash/archive before permanent delete)
- Clear error messages with actionable fixes
- Preserve user input on errors (don't clear forms)
Progressive Disclosure
- Reveal details as needed rather than overwhelming users
- Levels of disclosure:
- Summary: Show essential info by default (card title, price, rating)
- Details: Expand to show more info (description, specs, reviews)
- Advanced: Hide complex options behind "Advanced settings" toggle
- Examples:
- Accordion: Start collapsed, expand on click
- Search filters: Show 3-5 common filters, hide rest behind "More filters"
- Settings: Basic settings visible, advanced behind "Show advanced"
Modern UX Patterns:
Conversational Interfaces
Prioritize natural language interaction where appropriate:
Four types:
- Pure chat: Full conversation (AI assistants, support bots)
- Command palette: Text-based shortcuts (Cmd+K, search everywhere)
- Smart search: Natural language queries (search "meetings next week" vs filtering)
- Form alternatives: Conversational data collection ("What's your name?" vs form fields)
When to use:
- Complex searches with multiple variables
- Task guidance (wizards, onboarding)
- Contextual help
- Quick actions (command palette)
When NOT to use:
- Simple forms (just use inputs)
- Precise control interfaces (design tools, dashboards)
- High-frequency repetitive tasks
Adaptive Layouts
Respond to user context automatically:
- Time-based: Dark mode at night, light during day
- Device-based: Simplified UI on mobile, full features on desktop
- Connection-based: Reduce images/video on slow connections
- Usage-based: Prioritize frequent actions, hide rarely-used features
Examples:
- Auto dark/light mode based on time or system preference
- Simplified mobile navigation (hamburger menu) vs full desktop nav
- Collapsed sidebar on small screens, expanded on large
Minimal, Flat Design
Current aesthetic preference:
- No drop shadows (except subtle ones for modals/dropdowns)
- No gradients for depth (use for accents/backgrounds if desired)
- No glass morphism effects
- Focus on typography, color, and spacing to create hierarchy
- Functional depth: Layers of content (modals, sheets) use positioning, not visual depth
Navigation:
- Clear structure with intuitive navigation menus
- Implement breadcrumbs for deep hierarchies (more than 2 levels)
- Use standard UI patterns to reduce learning curve (hamburger menu, tab bars)
- Ensure predictable behavior (back button works, links look clickable)
- Maintain navigation context (highlight current page, preserve scroll position)
Styling Implementation
Component Library & Tools
Component Library:
- Strongly prefer shadcn components (v4, pre-installed in
@/components/ui)
- Import individually:
import { Button } from "@/components/ui/button";
- Use over plain HTML elements (
<Button> over <button>)
- Avoid creating custom components with names that clash with shadcn
Styling Engine:
- Use Tailwind utility classes exclusively
- Adhere to theme variables in
index.css via CSS custom properties
- Map variables in
@theme (see tailwind.config.js)
- Use inline styles or CSS modules only when absolutely necessary
Icons:
- Use
@phosphor-icons/react for buttons and inputs
- Example:
import { Plus } from "@phosphor-icons/react"; <Plus />
- Use color for plain icon buttons
- Don't override default
size or weight unless requested
Notifications:
- Use
sonner for toasts
- Example:
import { toast } from 'sonner'
Loading States:
- Always add loading states, spinners, placeholder animations
- Use skeletons until content renders
Layout Implementation
Spacing Strategy:
- Use grid/flex wrappers with
gap for spacing
- Prioritize wrappers over direct margins/padding on children
- Nest wrappers as needed for complex layouts
Conditional Styling:
- Use ternary operators or clsx/classnames utilities
- Example:
className={clsx('base-class', { 'active-class': isActive })}
Responsive Design
Fluid Layouts:
- Use relative units (%, em, rem) instead of fixed pixels
- Implement CSS Grid and Flexbox for flexible layouts
- Design mobile-first, then scale up
Media Queries:
- Use breakpoints based on content needs, not specific devices
- Test across range of devices and orientations
Touch Targets:
- Minimum 44x44 pixels for interactive elements
- Provide adequate spacing between touch targets
- Consider hover states for desktop, focus states for touch/keyboard
Performance:
- Optimize assets for mobile networks
- Use CSS animations over JavaScript
- Implement lazy loading for images and videos
Accessibility Standards
Core Requirements:
- Follow WCAG 2.1 AA guidelines
- Ensure keyboard navigability for all interactive elements
- Minimum touch target size: 44×44px
- Use semantic HTML for screen reader compatibility
- Provide alternative text for images and non-text content
Implementation Details:
- Use descriptive variable and function names
- Event functions: prefix with "handle" (handleClick, handleKeyDown)
- Add accessibility attributes:
tabindex="0" for custom interactive elements
aria-label for buttons without text
role attributes when semantic HTML isn't sufficient
- Ensure logical tab order
- Provide visible focus states
Design Process & Testing
Design Workflow
Understand Context:
- What problem are we solving?
- Who are the users and when will they use this?
- What are the success criteria?
Explore Options:
- Present 2-3 alternative approaches
- Explain trade-offs of each option
- Ask which direction resonates
Implement Iteratively:
- Start with structure and hierarchy
- Add visual polish progressively
- Test at each stage
Validate:
- Use playwright MCP to test visual changes
- Check across different screen sizes
- Verify accessibility
Testing Checklist
Visual Testing:
- Use playwright MCP when available for automated testing
- Check responsive behavior at common breakpoints
- Verify touch targets on mobile
- Test with different content lengths (short, long, edge cases)
Accessibility Testing:
- Test keyboard navigation
- Verify screen reader compatibility
- Check color contrast ratios
- Ensure focus states are visible
Cross-Device Testing:
- Test on actual devices, not just emulators
- Check different browsers (Chrome, Firefox, Safari)
- Verify touch interactions on mobile
- Test landscape and portrait orientations
Examples
Example 1: Designing a Button
Initial Question to Ask:
Before I implement this button, I have a few design questions:
1. What's the primary action you want to emphasize?
2. Do you have brand colors in mind, or should I suggest options?
3. What emotion should this button convey? (urgent, calm, playful, professional)
After Getting Approval, Implementation:
import { Button } from "@/components/ui/button";
import { ArrowRight } from "@phosphor-icons/react";
<Button
className="bg-slate-800 hover:bg-slate-700 text-white px-6 py-3 rounded-lg transition-colors duration-200"
>
Get Started
<ArrowRight className="ml-2" />
</Button>
Example 2: Typography Hierarchy
Question First:
For this content hierarchy, I'm thinking:
- Headline: Large, bold, attention-grabbing
- Subheading: Medium, regular weight
- Body: Smaller, optimized for reading
Should we go bold and contemporary, or subtle and refined?
Implementation After Approval:
<div className="space-y-4">
<h1 className="text-5xl font-bold tracking-tight text-slate-900">
Headline Here
</h1>
<h2 className="text-2xl text-slate-600">
Supporting subheading
</h2>
<p className="text-base leading-relaxed text-slate-700">
Body text optimized for readability with proper line height.
</p>
</div>
Example 3: Unique Color Palette Suggestion
Presenting Options:
I'd like to suggest three color directions that break from typical SaaS patterns:
1. **Warm Earth Tones**
- Base: Warm grey (#E8E2DC)
- Accent: Terracotta (#C86E4B)
- For: Organic, trustworthy feel
2. **Cool Midnight**
- Base: Deep navy (#1A2332)
- Accent: Cyan (#4ECDC4)
- For: Modern, tech-forward feel
3. **Soft Pastels**
- Base: Soft pink (#FFE5E5)
- Accent: Sage green (#9DB5A4)
- For: Calm, approachable feel
Which direction feels right for your brand?
Common Patterns to Avoid
❌ Don't:
- Use generic SaaS blue (#3B82F6) without considering alternatives
- Default to shadows and gradients for depth
- Copy Apple's design language
- Use glass morphism effects
- Make design decisions without asking
- Implement typography without considering the font version
- Use animations that delay user actions
- Create cluttered interfaces with competing elements
✅ Do:
- Ask before making design decisions
- Suggest unique, contextually appropriate color pairs
- Use flat, minimal design
- Consider unconventional typography choices
- Provide immediate feedback for interactions
- Create generous white space
- Test with real devices
- Validate accessibility
Version History
- v1.0.0 (2025-10-18): Initial release with comprehensive UI/UX design guidance
References
For additional context, see:
1---2name: bencium-controlled-ux-designer3description: Expert UI/UX design guidance for unique, accessible interfaces. Use for visual decisions, colors, typography, layouts. Always ask before making design.4---56# UX Designer78Expert UI/UX design skill that helps create unique, accessible, and thoughtfully designed interfaces. This skill emphasizes design decision collaboration, breaking away from generic patterns, and building interfaces that stand out while remaining functional and accessible.910## Core Philosophy1112**CRITICAL: Design Decision Protocol**13- **ALWAYS ASK** before making any design decisions (colors, fonts, sizes, layouts)14- Never implement design changes until explicitly instructed15- The guidelines below are practical guidance for when design decisions are approved16- Present alternatives and trade-offs, not single "correct" solutions1718## Foundational Design Principles1920### Stand Out From Generic Patterns2122**Avoid Generic Training Dataset Patterns:**23- Don't default to "AI style" designs (excessive bauhaus, liquid glass, apple-like)24- Don't use generic SaaS aesthetics that look machine-generated25- Don't rely only on solid colors - suggest photography, patterns, textures26- Think beyond typical patterns - you can step off the written path2728**Draw Inspiration From:**29- Modern landing pages (Perplexity, Comet Browser, Dia Browser)30- Framer templates and their innovative approaches31- Leading brand design studios32- Historical design movements (Bauhaus, Otl Aicher, Braun) - but as inspiration, not imitation33- Beautiful background animations (CSS, SVG) - slow, looping, subtle3435**Visual Interest Strategies:**36- Unique color pairs that aren't typical37- Animation effects that feel fresh38- Background patterns that add depth without distraction39- Typography combinations that create contrast40- Visual assets that tell a story4142### Core Design Philosophy43441. **Simplicity Through Reduction**45 - Identify the essential purpose and eliminate distractions46 - Begin with complexity, then deliberately remove until reaching the simplest effective solution47 - Every element must justify its existence48492. **Material Honesty**50 - Digital materials have unique properties - embrace them51 - Buttons should communicate affordance through color, spacing, and typography (not shadows)52 - Cards use borders and background differentiation (not depth effects)53 - Animations follow real-world physics principles adapted to digital responsiveness5455 **Examples:**56 - Clickable: Use distinct colors, hover state changes, cursor feedback57 - Containers: Use subtle borders (1px), background color shifts, or generous padding58 - Hierarchy: Use scale, weight, and spacing rather than elevation59603. **Functional Layering (Not Visual Depth)**61 - Create hierarchy through typography scale, color contrast, and spatial relationships62 - Layer information conceptually (primary → secondary → tertiary)63 - Reject skeuomorphic shadows/gradients that imitate physical depth64 - Embrace functional depth: modals over content, dropdowns over UI65664. **Obsessive Detail**67 - Consider every pixel, interaction, and transition68 - Excellence emerges from hundreds of small, intentional decisions69 - Balance: Details should serve simplicity, not complexity70 - When detail conflicts with clarity, clarity wins71725. **Coherent Design Language**73 - Every element should visually communicate its function74 - Elements should feel part of a unified system75 - Nothing should feel arbitrary76776. **Invisibility of Technology**78 - The best technology disappears79 - Users should focus on content and goals, not on understanding the interface8081### What This Means in Practice8283**Color Usage:**84- Base palette: 4-5 neutral shades (backgrounds, borders, text)85- Accent palette: 1-3 bold colors (CTAs, status, emphasis)86- Neutrals are slightly desaturated, warm or cool based on brand intent87- Accents are saturated enough to create clear contrast8889**Typography:**90- Headlines: Emotional, attention-grabbing (personality over pure legibility)91- Body/UI: Functional, highly legible (clarity over expression)92- 2-3 typefaces maximum93- Clear mathematical scale (e.g., 1.25x between sizes)9495**Animation:**96- Purposeful: Guides attention, establishes relationships, provides feedback97- Subtle: Felt rather than seen (100-300ms for most interactions)98- Physics-informed: Natural easing, appropriate mass/momentum99100**Spacing:**101- Generous negative space creates clarity and breathing room102- Mathematical relationships (e.g., 4px base, 8/16/24/32/48px scale)103- Consistent application creates visual rhythm104105### Design Decision Checklist106107Before presenting any design, verify:1081091. **Purpose**: Does every element serve a clear function?1102. **Hierarchy**: Is visual importance aligned with content importance?1113. **Consistency**: Do similar elements look and behave similarly?1124. **Accessibility**: Does it meet WCAG AA standards? (contrast, touch targets, keyboard nav)1135. **Responsiveness**: Does it work on mobile, tablet, desktop?1146. **Uniqueness**: Does this break from generic SaaS patterns?1157. **Approval**: Have I asked before implementing colors, fonts, sizes, layouts?116117**Design System Framework:**118119For understanding what's fixed (universal rules), project-specific (brand personality), and adaptable (context-dependent) in your design system, see DESIGN-SYSTEM-TEMPLATE.md (meta-framework, project templates, decision trees).120121## Visual Design Standards122123### Color & Contrast124125**Color System Architecture:**126127Every interface needs two color roles:1281291. **Base/Neutral Palette (4-5 colors):**130 - Backgrounds (lightest)131 - Surface colors (cards, inputs)132 - Borders and dividers133 - Text (darkest)134 - Use slightly desaturated, warm or cool greys based on brand1351362. **Accent Palette (1-3 colors):**137 - Primary action (CTA buttons)138 - Status indicators (success, warning, error, info)139 - Focus/hover states140 - Use saturated colors for clear contrast against neutrals141142**Palette Structure Example:**143```144Neutrals: slate-50, slate-100, slate-300, slate-700, slate-900145Accents: teal-500 (primary), amber-500 (warning), red-500 (error)146```147148**Color Application Rules:**149150- **Backgrounds**: Lightest neutral (slate-50 or white)151- **Text**: Darkest neutral for primary text (slate-900), mid-tone for secondary (slate-600)152- **Buttons (primary)**: Accent color with white text153- **Buttons (secondary)**: Neutral with border and dark text154- **Status indicators**: Specific accent (green=success, red=error, amber=warning, blue=info)155- **Interactive states**:156 - Hover: Darken by 10-15% or shift hue slightly157 - Focus: Use ring/outline in accent color158 - Disabled: Reduce opacity to 40-50% and remove hover effects159160**Color Relationships:**161162Choose warm or cool intentionally based on brand:163- **Warm greys** (beige/brown undertones): Organic, approachable, trustworthy164- **Cool greys** (blue undertones): Modern, tech-forward, professional165166Accent colors should have clear contrast with both:167- Light backgrounds (for buttons on white)168- Dark text (if used as backgrounds for white text)169170**Intentional Color Usage:**171- Every color must serve a purpose (hierarchy, function, status, or action)172- Avoid decorative colors that don't communicate meaning173- Maintain consistency: same color = same meaning throughout174175**Accessibility:**176- Ensure sufficient contrast for color-blind users177- Follow WCAG 2.1 AA: minimum 4.5:1 for normal text, 3:1 for large text178- Don't rely on color alone to convey information (add icons or labels)179180**Unique Color Strategy:**181182To stand out from generic patterns:183- Avoid default SaaS blue (#3B82F6) unless it fits your brand184- Consider unexpected neutrals: warm greys, soft off-whites, deep charcoals185- Pair neutrals with distinctive accents: terracotta + charcoal, sage + navy, coral + slate186- Test combinations against "does this look AI-generated?" filter187188### Typography Excellence189190**Typography Philosophy:**191192Typography is a primary design element that conveys personality and hierarchy.193194**Functional vs Emotional Typography:**195- **Headlines/Display**: Prioritize emotion, personality, attention (legibility secondary)196- **Body Text**: Prioritize legibility, reading comfort, accessibility197- **UI/Labels**: Prioritize clarity, scannability, consistency198199**Font Selection:**200- Use 2-3 typefaces maximum201- Limit to 3 weights per typeface (e.g., Regular 400, Medium 500, Bold 700)202- Prefer variable fonts for fine-tuned control and performance203204**Font Version Usage:**205- **Display version**: Headlines and hero text only206- **Text version**: Paragraphs and long-form content207- **Caption/Micro**: Small UI labels (1-2 lines, non-critical info)208209**Recommended Sources:**210- Google Fonts for web (free, well-optimized, reliable)211- System fonts for performance-critical apps (-apple-system, BlinkMacSystemFont, Segoe UI)212- Choose fonts that serve your brand's purpose (not "trending" lists)213214**Typographic Scale:**215216Use mathematical relationships for size hierarchy:217- **Ratio**: Major third (1.25x) for moderate contrast, Perfect fourth (1.333x) for dramatic218- **Base size**: 16px (1rem) for body text219- **Example scale (1.25x)**:220 ```221 xs: 0.64rem (10px)222 sm: 0.8rem (13px)223 base: 1rem (16px)224 lg: 1.25rem (20px)225 xl: 1.563rem (25px)226 2xl: 1.953rem (31px)227 3xl: 2.441rem (39px)228 4xl: 3.052rem (49px)229 5xl: 3.815rem (61px)230 ```231232**Typographic Hierarchy:**233- Create clear visual distinction between levels234- Headlines, subheadings, body, captions should each have distinct size/weight235- Use combination of size, weight, and color for hierarchy236237**Spacing & Readability:**238- **Line height**: 1.5x font size for body text (e.g., 16px text = 24px line-height)239- **Line length**: 45-75 characters optimal for readability (60-70 ideal)240- **Paragraph spacing**: 1-1.5em between paragraphs241- **Letter spacing (tracking)**:242 - Larger text (headlines): Slightly tighter (-0.02em to -0.05em)243 - Normal text (body): Default (0)244 - Small text (captions): Slightly looser (+0.01em to +0.03em)245 - General rule: As size increases, reduce tracking; as size decreases, increase tracking246247**Font Pairing Logic:**248249When using multiple typefaces, create contrast through:250- **Category contrast**: Serif + Sans-serif (classic, clear distinction)251- **Weight contrast**: Light + Bold (dynamic, energetic)252- **Personality contrast**: Geometric + Humanist (modern + warm)253254Examples:255- Serif headlines + Sans body (editorial, trustworthy)256- Display headlines + System body (distinctive + efficient)257- Bold sans headlines + Light sans body (modern, clean)258259**UI Typography:**260261Specific guidance for interface elements:262- **Button text**: Semi-Bold (600), 14-16px, consistent casing (all-caps OR title case)263- **Form labels**: Regular (400), 14px, positioned above input264- **Form input text**: Regular (400), 16px minimum (prevents iOS zoom on focus)265- **Placeholder text**: Light (300) or desaturated color, same size as input266- **Error messages**: Regular (400), 12-14px, color-coded (red-ish)267268**Responsive Typography:**269270Scale type sizes across breakpoints:271```tsx272// Example with Tailwind273<h1 className="text-3xl md:text-4xl lg:text-5xl">274 Responsive Headline275</h1>276277// Or with CSS clamp (fluid)278h1 {279 font-size: clamp(2rem, 5vw, 4rem);280}281```282283Reduce sizes on mobile (20-30% smaller than desktop)284Reduce hierarchy levels on small screens (fewer distinct sizes)285286### Layout & Spatial Design287288**Compositional Balance:**289- Every screen should feel balanced290- Pay attention to visual weight and negative space291- Use generous negative space to focus attention292- Add sufficient margins and paddings for professional, spacious look293294**Grid Discipline:**295- Maintain consistent underlying grid system296- Create sense of order while allowing meaningful exceptions297- Use grid/flex wrappers with `gap` for spacing298- Prioritize wrappers over direct margins/padding on children299300**Spatial Relationships:**301- Group related elements through proximity, alignment, and shared attributes302- Use size, color, and spacing to highlight important elements303- Guide user focus through visual hierarchy304305**Attention Guidance:**306- Design interfaces that guide user attention effectively307- Avoid cluttered interfaces where elements compete308- Create clear paths through the content309310## Interaction Design311312### Motion & Animation313314**Purposeful Animation:**315316Every animation must serve a functional purpose:317- **Orient users**: Smooth transitions during navigation changes318- **Establish relationships**: Show how elements connect (expand from source, slide between states)319- **Provide feedback**: Confirm interactions (button press, form submission)320- **Guide attention**: Direct focus to important changes (new messages, errors)321322**Animation & Gestalt Principles:**323324Motion should reinforce visual relationships:325- **Proximity**: Elements near each other move together (grouped cards animating)326- **Similarity**: Similar elements animate similarly (all buttons have same hover timing)327- **Continuity**: Movement follows natural paths (smooth curves, not jumpy angles)328- **Figure-ground**: Important elements animate while backgrounds stay stable329330**Natural Physics:**331332Animations should feel organic, not mechanical:333- **Easing**: Use ease-out for entrances (fast start, slow end)334- **Easing**: Use ease-in for exits (slow start, fast end)335- **Easing**: Use ease-in-out for transitions (smooth both ends)336- Avoid linear easing (feels robotic) except for continuous loops337- Apply appropriate mass/momentum (lightweight UI vs weighty modals)338339**Subtle Restraint:**340- Animations should be felt rather than seen341- Don't delay user actions unnecessarily (keep under 300ms for interactive feedback)342- Never block critical actions with decorative animations343- Respect `prefers-reduced-motion` media query344345**Timing Guidelines:**346347- **Micro-interactions** (button press, checkbox toggle): 100-150ms348- **State changes** (expanding accordion, tab switch): 200-300ms349- **Page transitions** (route changes, modal open/close): 300-500ms350- **Attention-directing** (notification appearance, error highlight): 200-400ms351352**Physics Profiles:**353354Define consistent durations for element types:355- **Lightweight** (icons, small UI): 150ms356- **Standard** (cards, panels): 300ms357- **Weighty** (modals, page transitions): 500ms358359**Performance Optimization:**360361- Animate `transform` and `opacity` only (GPU-accelerated, smooth 60fps)362- Avoid animating `width`, `height`, `top`, `left`, `margin` (causes reflow/repaint)363- Use `will-change` sparingly for complex animations (pre-allocates GPU resources)364- Test on low-end devices (60fps on powerful hardware ≠ 60fps on mobile)365366**Implementation:**367- Use `framer-motion` sparingly and purposefully368- Prefer CSS animations over JavaScript when possible (better performance)369- Use CSS transitions for simple hover/focus states370- Implement `@media (prefers-reduced-motion: reduce)` to disable/reduce animations371372**Example:**373```tsx374// Simple hover transition375<button className="376 transition-colors duration-200 ease-out377 bg-blue-600 hover:bg-blue-700378">379 Click me380</button>381382// Framer Motion for complex interaction383<motion.div384 initial={{ opacity: 0, y: 20 }}385 animate={{ opacity: 1, y: 0 }}386 exit={{ opacity: 0, y: -20 }}387 transition={{ duration: 0.3, ease: "easeOut" }}388>389 Content390</motion.div>391```392393**Motion Specification:**394395For detailed motion specs, see MOTION-SPEC.md (easing curves, duration tables, state-specific animations, implementation patterns).396397### User Experience Patterns398399**Core UX Principles:**4004011. **Direct Manipulation**402 - Users interact directly with content, not through abstract controls403 - Examples:404 - Drag & drop to reorder items (not up/down buttons)405 - Inline editing (click to edit, not separate form)406 - Sliders for ranges (not numeric input with +/-)407 - Pinch/zoom gestures on mobile (not +/- buttons)4084092. **Immediate Feedback**410 - Every interaction provides instantaneous visual feedback (within 100ms)411 - Types of feedback:412 - **Visual**: Button pressed state, hover effects, color changes413 - **Haptic**: Vibration on mobile (submit, error, success)414 - **Audio**: Subtle sounds for critical actions (optional, user-controlled)415 - **Loading**: Skeleton screens, spinners for >300ms operations416 - **Success**: Checkmarks, green highlights, toast notifications417 - **Error**: Red highlights, inline error messages, shake animations4184193. **Consistent Behavior**420 - Similar-looking elements behave similarly421 - Examples:422 - **Visual consistency**: All primary buttons have same colors, sizes, hover states423 - **Behavioral consistency**: All modals close via X button, ESC key, and outside click424 - **Interaction consistency**: All drag targets have same hover state and drop feedback425 - **Pattern consistency**: All forms validate on blur and submit4264274. **Forgiveness**428 - Make errors difficult, but recovery easy429 - **Prevention strategies**:430 - Disable invalid actions (grey out unavailable buttons)431 - Validate inputs inline (before submission)432 - Confirm destructive actions (delete, overwrite)433 - Auto-save in background (drafts, progress)434 - **Recovery strategies**:435 - Undo/redo for all state changes436 - Soft deletes (trash/archive before permanent delete)437 - Clear error messages with actionable fixes438 - Preserve user input on errors (don't clear forms)4394405. **Progressive Disclosure**441 - Reveal details as needed rather than overwhelming users442 - Levels of disclosure:443 - **Summary**: Show essential info by default (card title, price, rating)444 - **Details**: Expand to show more info (description, specs, reviews)445 - **Advanced**: Hide complex options behind "Advanced settings" toggle446 - Examples:447 - Accordion: Start collapsed, expand on click448 - Search filters: Show 3-5 common filters, hide rest behind "More filters"449 - Settings: Basic settings visible, advanced behind "Show advanced"450451**Modern UX Patterns:**4524531. **Conversational Interfaces**454455 Prioritize natural language interaction where appropriate:456457 **Four types:**458 - **Pure chat**: Full conversation (AI assistants, support bots)459 - **Command palette**: Text-based shortcuts (Cmd+K, search everywhere)460 - **Smart search**: Natural language queries (search "meetings next week" vs filtering)461 - **Form alternatives**: Conversational data collection ("What's your name?" vs form fields)462463 **When to use:**464 - Complex searches with multiple variables465 - Task guidance (wizards, onboarding)466 - Contextual help467 - Quick actions (command palette)468469 **When NOT to use:**470 - Simple forms (just use inputs)471 - Precise control interfaces (design tools, dashboards)472 - High-frequency repetitive tasks4734742. **Adaptive Layouts**475476 Respond to user context automatically:477 - **Time-based**: Dark mode at night, light during day478 - **Device-based**: Simplified UI on mobile, full features on desktop479 - **Connection-based**: Reduce images/video on slow connections480 - **Usage-based**: Prioritize frequent actions, hide rarely-used features481482 Examples:483 - Auto dark/light mode based on time or system preference484 - Simplified mobile navigation (hamburger menu) vs full desktop nav485 - Collapsed sidebar on small screens, expanded on large4864873. **Minimal, Flat Design**488489 Current aesthetic preference:490 - No drop shadows (except subtle ones for modals/dropdowns)491 - No gradients for depth (use for accents/backgrounds if desired)492 - No glass morphism effects493 - Focus on typography, color, and spacing to create hierarchy494 - Functional depth: Layers of content (modals, sheets) use positioning, not visual depth495496**Navigation:**497- Clear structure with intuitive navigation menus498- Implement breadcrumbs for deep hierarchies (more than 2 levels)499- Use standard UI patterns to reduce learning curve (hamburger menu, tab bars)500- Ensure predictable behavior (back button works, links look clickable)501- Maintain navigation context (highlight current page, preserve scroll position)502503## Styling Implementation504505### Component Library & Tools506507**Component Library:**508- Strongly prefer shadcn components (v4, pre-installed in `@/components/ui`)509- Import individually: `import { Button } from "@/components/ui/button";`510- Use over plain HTML elements (`<Button>` over `<button>`)511- Avoid creating custom components with names that clash with shadcn512513**Styling Engine:**514- Use Tailwind utility classes exclusively515- Adhere to theme variables in `index.css` via CSS custom properties516- Map variables in `@theme` (see `tailwind.config.js`)517- Use inline styles or CSS modules only when absolutely necessary518519**Icons:**520- Use `@phosphor-icons/react` for buttons and inputs521- Example: `import { Plus } from "@phosphor-icons/react"; <Plus />`522- Use color for plain icon buttons523- Don't override default `size` or `weight` unless requested524525**Notifications:**526- Use `sonner` for toasts527- Example: `import { toast } from 'sonner'`528529**Loading States:**530- Always add loading states, spinners, placeholder animations531- Use skeletons until content renders532533### Layout Implementation534535**Spacing Strategy:**536- Use grid/flex wrappers with `gap` for spacing537- Prioritize wrappers over direct margins/padding on children538- Nest wrappers as needed for complex layouts539540**Conditional Styling:**541- Use ternary operators or clsx/classnames utilities542- Example: `className={clsx('base-class', { 'active-class': isActive })}`543544### Responsive Design545546**Fluid Layouts:**547- Use relative units (%, em, rem) instead of fixed pixels548- Implement CSS Grid and Flexbox for flexible layouts549- Design mobile-first, then scale up550551**Media Queries:**552- Use breakpoints based on content needs, not specific devices553- Test across range of devices and orientations554555**Touch Targets:**556- Minimum 44x44 pixels for interactive elements557- Provide adequate spacing between touch targets558- Consider hover states for desktop, focus states for touch/keyboard559560**Performance:**561- Optimize assets for mobile networks562- Use CSS animations over JavaScript563- Implement lazy loading for images and videos564565## Accessibility Standards566567**Core Requirements:**568- Follow WCAG 2.1 AA guidelines569- Ensure keyboard navigability for all interactive elements570- Minimum touch target size: 44×44px571- Use semantic HTML for screen reader compatibility572- Provide alternative text for images and non-text content573574**Implementation Details:**575- Use descriptive variable and function names576- Event functions: prefix with "handle" (handleClick, handleKeyDown)577- Add accessibility attributes:578 - `tabindex="0"` for custom interactive elements579 - `aria-label` for buttons without text580 - `role` attributes when semantic HTML isn't sufficient581- Ensure logical tab order582- Provide visible focus states583584## Design Process & Testing585586### Design Workflow5875881. **Understand Context:**589 - What problem are we solving?590 - Who are the users and when will they use this?591 - What are the success criteria?5925932. **Explore Options:**594 - Present 2-3 alternative approaches595 - Explain trade-offs of each option596 - Ask which direction resonates5975983. **Implement Iteratively:**599 - Start with structure and hierarchy600 - Add visual polish progressively601 - Test at each stage6026034. **Validate:**604 - Use playwright MCP to test visual changes605 - Check across different screen sizes606 - Verify accessibility607608### Testing Checklist609610**Visual Testing:**611- Use playwright MCP when available for automated testing612- Check responsive behavior at common breakpoints613- Verify touch targets on mobile614- Test with different content lengths (short, long, edge cases)615616**Accessibility Testing:**617- Test keyboard navigation618- Verify screen reader compatibility619- Check color contrast ratios620- Ensure focus states are visible621622**Cross-Device Testing:**623- Test on actual devices, not just emulators624- Check different browsers (Chrome, Firefox, Safari)625- Verify touch interactions on mobile626- Test landscape and portrait orientations627628## Examples629630### Example 1: Designing a Button631632**Initial Question to Ask:**633```634Before I implement this button, I have a few design questions:6351. What's the primary action you want to emphasize?6362. Do you have brand colors in mind, or should I suggest options?6373. What emotion should this button convey? (urgent, calm, playful, professional)638```639640**After Getting Approval, Implementation:**641```tsx642import { Button } from "@/components/ui/button";643import { ArrowRight } from "@phosphor-icons/react";644645<Button646 className="bg-slate-800 hover:bg-slate-700 text-white px-6 py-3 rounded-lg transition-colors duration-200"647>648 Get Started649 <ArrowRight className="ml-2" />650</Button>651```652653### Example 2: Typography Hierarchy654655**Question First:**656```657For this content hierarchy, I'm thinking:658- Headline: Large, bold, attention-grabbing659- Subheading: Medium, regular weight660- Body: Smaller, optimized for reading661662Should we go bold and contemporary, or subtle and refined?663```664665**Implementation After Approval:**666```tsx667<div className="space-y-4">668 <h1 className="text-5xl font-bold tracking-tight text-slate-900">669 Headline Here670 </h1>671 <h2 className="text-2xl text-slate-600">672 Supporting subheading673 </h2>674 <p className="text-base leading-relaxed text-slate-700">675 Body text optimized for readability with proper line height.676 </p>677</div>678```679680### Example 3: Unique Color Palette Suggestion681682**Presenting Options:**683```684I'd like to suggest three color directions that break from typical SaaS patterns:6856861. **Warm Earth Tones**687 - Base: Warm grey (#E8E2DC)688 - Accent: Terracotta (#C86E4B)689 - For: Organic, trustworthy feel6906912. **Cool Midnight**692 - Base: Deep navy (#1A2332)693 - Accent: Cyan (#4ECDC4)694 - For: Modern, tech-forward feel6956963. **Soft Pastels**697 - Base: Soft pink (#FFE5E5)698 - Accent: Sage green (#9DB5A4)699 - For: Calm, approachable feel700701Which direction feels right for your brand?702```703704## Common Patterns to Avoid705706❌ **Don't:**707- Use generic SaaS blue (#3B82F6) without considering alternatives708- Default to shadows and gradients for depth709- Copy Apple's design language710- Use glass morphism effects711- Make design decisions without asking712- Implement typography without considering the font version713- Use animations that delay user actions714- Create cluttered interfaces with competing elements715716✅ **Do:**717- Ask before making design decisions718- Suggest unique, contextually appropriate color pairs719- Use flat, minimal design720- Consider unconventional typography choices721- Provide immediate feedback for interactions722- Create generous white space723- Test with real devices724- Validate accessibility725726## Version History727728- v1.0.0 (2025-10-18): Initial release with comprehensive UI/UX design guidance729730## References731732For additional context, see:733- WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/734- Google Fonts: https://fonts.google.com/735- Tailwind CSS Docs: https://tailwindcss.com/docs736- Shadcn UI Components: https://ui.shadcn.com/