git:20251217.3f83b43 to git:20251217.f66687a
122 added, 88 removed. Audit A to A.
---
name: generic-fullstack-ux-designer
description: Professional UI/UX design expertise for full-stack applications. Covers design thinking, user psychology (Hick's/Fitts's/Jakob's Law), visual hierarchy, interaction patterns, accessibility, performance-driven design, and design critique. Use when designing features, improving UX, solving user problems, or conducting design reviews.
---
# Fullstack UX Designer
Professional UX expertise for Next.js/NestJS full-stack applications.
- **Foundational Reference:** See [UX Principles](./../_shared/UX_PRINCIPLES.md) for core concepts.
+ **Extends:** [Generic UX Designer](../generic-ux-designer/SKILL.md) - Read base skill for design thinking process, research methods, interaction patterns, and critique framework.
- ## Design Philosophy
+ ## Full-Stack UX Considerations
- **Your Role:**
- 1. **Critique** - Evaluate designs against professional standards
- 2. **Improve** - Suggest specific, actionable improvements
- 3. **Innovate** - Propose solutions based on UX best practices
- 4. **Educate** - Explain the "why" behind decisions
+ ### Server-Side Rendering UX
- **Project Constraints (Define in CLAUDE.md):**
- - Brand colors and design tokens
- - Performance budgets
- - Accessibility level (AA minimum)
- - Tech stack (Next.js, shadcn/ui, Tailwind)
+ | Scenario | UX Pattern |
+ |----------|------------|
+ | Initial page load | Hydration-safe skeleton screens |
+ | Data fetching | Server components for static, client for dynamic |
+ | Authentication | Protected routes with redirect UX |
+ | Form submission | Progressive enhancement |
- ## Jobs-to-be-Done Framework
+ ### Hydration-Safe Patterns
- Every feature has a "job":
- ```
- When I [situation]
- I want to [motivation]
- So I can [expected outcome]
+ ```tsx
+ // ✓ Avoid hydration mismatch
+ function Timestamp({ date }: { date: Date }) {
+ const [formatted, setFormatted] = useState('');
+
+ useEffect(() => {
+ setFormatted(date.toLocaleString()); // Client-side only
+ }, [date]);
+
+ return <span>{formatted || 'Loading...'}</span>;
+ }
```
- Design Implications: Minimize steps, optimize for common paths.
+ ## API Loading & Error States
- ## Progressive Disclosure
+ ### Loading State Hierarchy
- | Level | Visibility | Examples |
- |-------|------------|----------|
- | Primary | Always visible | Core functionality |
- | Secondary | On hover/focus | Supporting actions |
- | Tertiary | In menus/modals | Advanced features |
+ | Duration | Pattern | Example |
+ |----------|---------|---------|
+ | < 100ms | No indicator | Button click |
+ | 100ms - 1s | Subtle spinner | Form submit |
+ | 1s - 5s | Skeleton screen | Page fetch |
+ | > 5s | Progress bar | File upload |
- ## Visual Design Principles
+ ### Error State Design
- ### Visual Hierarchy
```
- H1: 36-48px - Page titles
- H2: 24-30px - Section titles
- Body: 16px - Default
- Small: 14px - Metadata
+ API Error → Parse Error → User-Friendly Message → Recovery Action
```
- ### Gestalt Principles
- - **Proximity** - Related items close together
- - **Similarity** - Same styling for related elements
- - **Figure-Ground** - Separate foreground from background
-
- ## Interaction Design
+ | Error Type | User Message | Recovery |
+ |------------|--------------|----------|
+ | 400 Validation | Show field errors | Fix and retry |
+ | 401 Unauthorized | "Please log in" | Redirect to login |
+ | 404 Not Found | "Item not found" | Navigate back |
+ | 500 Server Error | "Something went wrong" | Retry button |
- ### Feedback Timing
- | Type | Timing | Example |
- |------|--------|---------|
- | Instant | < 100ms | Button press |
- | Expected | 1-3s | Loading spinner |
- | Long | > 3s | Progress bar |
+ ## Optimistic UI Pattern
- ### GPU-Accelerated Animations
- ```css
- /* DO animate */
- transform: translateY(-4px);
- opacity: 0.5;
+ ```typescript
+ // Show immediate feedback, rollback on error
+ async function toggleLike(postId: string) {
+ // 1. Update UI immediately
+ setLiked(true);
+ setLikeCount(c => c + 1);
- /* NEVER animate */
- margin, width, height, top, left
+ try {
+ // 2. Call API
+ await api.like(postId);
+ } catch {
+ // 3. Rollback on failure
+ setLiked(false);
+ setLikeCount(c => c - 1);
+ showToast('Failed to like');
+ }
+ }
```
- ## Accessibility (WCAG AA)
+ ### When to Use Optimistic UI
- ### Keyboard Navigation
+ | Action | Optimistic? | Why |
+ |--------|-------------|-----|
+ | Like/favorite | Yes | Low risk, common action |
+ | Add comment | Yes | Can show pending state |
+ | Delete item | No | Destructive, needs confirm |
+ | Payment | No | Critical, must verify |
+ | Form submit | Maybe | Depends on complexity |
+
+ ## Form Submission UX
+
+ ### Client → Server Flow
+
```
- Tab - Move forward
- Enter/Space - Activate
- Escape - Close modals
- Arrow keys - Navigate lists
+ User Input → Client Validation → Submit → Server Validation → Response
+ ↓ ↓ ↓ ↓ ↓
+ Feedback Inline errors Loading... Field errors Success/Error
```
- ### Requirements
- - Focus indicators on all interactive elements
- - Color contrast >= 4.5:1
- - ARIA labels on icon-only buttons
- - Focus trapped in modals
+ ### Multi-Step Forms
- ## Performance-Driven Design
+ ```tsx
+ // Show progress and allow back navigation
+ <FormStepper
+ steps={['Details', 'Payment', 'Confirm']}
+ currentStep={step}
+ onBack={() => setStep(s => s - 1)}
+ />
+ ```
- - Optimistic UI updates (immediate feedback)
- - Skeleton screens over spinners
- - Lazy load non-essential components
- - GPU-accelerated animations only
+ ## Authentication UX
- ## Design Critique Framework
+ ### Login Flow Patterns
- ### Nielsen's Heuristics (Quick Check)
- 1. System status visible
- 2. Familiar language
- 3. Easy undo
- 4. Consistent patterns
- 5. Error prevention
- 6. Options visible
- 7. Power user shortcuts
- 8. Minimal elements
- 9. Helpful errors
- 10. Contextual help
+ | State | UX |
+ |-------|-----|
+ | Loading auth | Full-page skeleton |
+ | Not logged in | Show login form |
+ | Logging in | Disable form, show spinner |
+ | Success | Redirect with toast |
+ | Error | Inline error, keep form data |
- ### Quick Decision Matrix
+ ### Protected Route Pattern
- | Situation | Decision | Why |
- |-----------|----------|-----|
- | Primary CTA | Large, prominent | Fitts's Law |
- | Destructive action | Confirm dialog | Error prevention |
- | 10+ form fields | Multi-step wizard | Cognitive load |
- | Loading < 1s | Skeleton | Perception |
+ ```tsx
+ // Redirect unauthenticated users
+ if (!user && !loading) {
+ return <Navigate to="/login" state={{ from: location }} />;
+ }
+ ```
+ ## Real-Time Updates
+
+ | Pattern | Use Case |
+ |---------|----------|
+ | Polling | Low-frequency updates (notifications) |
+ | WebSocket | Chat, live collaboration |
+ | SSE | One-way server updates |
+
+ ### Presence Indicators
+
+ - Online status dots
+ - "User is typing..." indicators
+ - Collaborative cursors
+
+ ## Full-Stack Design Critique
+
+ | Aspect | Questions |
+ |--------|-----------|
+ | Loading states | What shows during API calls? |
+ | Error recovery | Can users recover from errors? |
+ | Offline behavior | What happens without network? |
+ | Auth transitions | Smooth login/logout experience? |
+ | Data freshness | Is stale data clearly indicated? |
+
## See Also
- - [UX Principles](./../_shared/UX_PRINCIPLES.md) - Core psychology
- - [Design Patterns](./../_shared/DESIGN_PATTERNS.md) - Visual design
- - [Code Review Standards](./../_shared/CODE_REVIEW_STANDARDS.md) - Accessibility
+ - [Generic UX Designer](../generic-ux-designer/SKILL.md) - Base methodology
+ - [UX Principles](../_shared/UX_PRINCIPLES.md) - Research methods, heuristics
+ - [Design Patterns](../_shared/DESIGN_PATTERNS.md) - Visual patterns