User Experience¶
User experience considerations for the authentication system.
Registration Flow¶
Door A: Create New Team¶
┌─────────────────────────────────────────────────────────────┐
│ 1. Sign Up Form │
│ - Email │
│ - Password (min 8 chars) │
│ - Name │
│ - Team Name │
│ - Team Slug (auto-generated from name, editable) │
│ - "Create Account" button │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Email Verification │
│ - "Check your email to verify your account" │
│ - Email contains: "Verify Email" button │
│ - 24-hour expiration │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Welcome to Your Team! │
│ - "Your team has been created" │
│ - "Get started by deploying your first site" │
│ - CTA: "Go to Dashboard" │
└─────────────────────────────────────────────────────────────┘
UX Considerations: - Team slug auto-generated from team name - Email verification prevents spam accounts - Clear next steps after verification - Progress indicator for multi-step flow
Door B: Join Existing Team¶
┌─────────────────────────────────────────────────────────────┐
│ 1. Invite Email │
│ From: "Your Name @ Company Name" │
│ Subject: "You're invited to join [Team Name]" │
│ Body: │
│ "You've been invited to join [Team Name] as a [Role]. │
│ Click below to create your account and accept." │
│ │
│ [Accept Invitation] │
│ (Link contains invite token) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Create Account │
│ - Email pre-filled from invite │
│ - Password (min 8 chars) │
│ - Name │
│ - "Join Team" button │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Welcome to the Team! │
│ - "You've joined [Team Name] as a [Role]" │
│ - "Your team has [X] members and [Y] sites" │
│ - CTA: "Go to Dashboard" │
└─────────────────────────────────────────────────────────────┘
UX Considerations: - Invite link single-use and time-limited - Email context (inviter name, team info) - Clear role communication - Immediate access after acceptance
Login Flow¶
Two-Step Login Experience¶
┌─────────────────────────────────────────────────────────────┐
│ Step 1: Enter Credentials │
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ Email: [user@example.com ] │ │
│ │ Password: [••••••••• ] │ │
│ │ │ │
│ │ [Remember me on this device] │ │
│ │ │ │
│ │ [Log In →] │ │
│ └─────────────────────────────────────────┘ │
│ │
│ Forgot password? │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Step 2: Select Team (if multi-team) │
│ │
│ Select the team you want to access: │
│ ┌─────────────────────────────────────────┐ │
│ │ ○ Acme Corporation (Owner) │ │
│ │ ○ ABC Consulting (Developer) │ │
│ │ ○ Personal Projects (Owner) │ │
│ └─────────────────────────────────────────┘ │
│ │
│ [Continue →] │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Step 3: Security Check (if needed) │
│ │
│ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
│ ┃ New Device Detected ┃ │
│ ┃ ┃ │
│ ┃ We detected a login from a new device. ┃ │
│ ┃ For your security, please enter the 6-digit ┃ │
│ ┃ code sent to: ┃ │
│ ┃ ┃ │
│ ┃ u***@example.com ┃ │
│ ┃ ┃ │
│ ┃ Enter code: [ _____ ] ┃ │
│ ┃ ┃ │
│ ┃ [Verify] [Resend Code] ┃ │
│ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │
│ │
│ A new code was sent at 10:30 AM │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Step 4: Suspicious Login (if applicable) │
│ │
│ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
│ ┃ Suspicious Login Detected ┃ │
│ ┃ ┃ │
│ ┃ We detected a login from: ┃ │
│ ┃ • New location: New York, US (usual: SF, US) ┃ │
│ ┃ • New device: Chrome on Windows ┃ │
│ ┃ ┃ │
│ ┃ Was this you? ┃ │
│ ┃ ┃ │
│ ┃ [Yes, Approve This Login] [No, Deny This Login] ┃ │
│ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │
└─────────────────────────────────────────────────────────────┘
UX Considerations: - Step 2 hidden if only one team - Device approval only for new devices - Suspicious login only if anomaly detected - Clear CTAs for approve/deny decisions
Password Management¶
Password Reset Flow¶
┌─────────────────────────────────────────────────────────────┐
│ 1. Request Reset │
│ ┌─────────────────────────────────────────┐ │
│ │ Email: [user@example.com ] │ │
│ │ [Send Reset Link →] │ │
│ └─────────────────────────────────────────┘ │
│ │
│ Check your email for a password reset link │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Email Sent │
│ │
│ If an account exists for user@example.com, you will │
│ receive an email with instructions to reset your │
│ password. This link will expire in 1 hour. │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Set New Password │
│ ┌─────────────────────────────────────────┐ │
│ │ New Password: [••••••••• ] │ │
│ │ Confirm: [••••••••• ] │ │
│ │ [Reset Password →] │ │
│ └─────────────────────────────────────────┘ │
│ │
│ Password must: │
│ • Be at least 8 characters │
│ • Contain letters and numbers │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Success │
│ │
│ Your password has been reset. Please log in with your │
│ new password. │
│ │
│ [Go to Login →] │
└─────────────────────────────────────────────────────────────┘
UX Considerations: - Email enumeration prevented (always returns success) - Clear expiration time (1 hour) - Password requirements visible - Confirmation that all sessions are revoked
Device Management¶
Trusted Devices¶
┌─────────────────────────────────────────────────────────────┐
│ Your Devices │
│ │
│ Trusted devices can skip the verification step when │
│ you log in. │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Chrome on macOS Trusted │ │
│ │ First seen: Jan 1, 2025 Last seen: Jan 22, 2025 │ │
│ │ Location: San Francisco, US │ │
│ │ [Revoke Device] │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Safari on iPhone Not Trusted │ │
│ │ First seen: Jan 15, 2025 Last seen: Jan 20, 2025 │ │
│ │ Location: New York, US │ │
│ │ [Revoke Device] │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
UX Considerations: - Clear device identification (browser + OS) - First seen / last seen dates - Location information - Easy revoke action
Recent Activity¶
┌─────────────────────────────────────────────────────────────┐
│ Recent Login Activity │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Today, 10:30 AM │ │
│ │ Chrome on macOS - San Francisco, US │ │
│ │ ✓ Successful login │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Yesterday, 3:45 PM │ │
│ │ Firefox on Windows - New York, US │ │
│ │ ⚠ Suspicious login - Denied by you │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Jan 20, 9:00 AM │ │
│ │ Safari on iPhone - London, UK │ │
│ │ ✓ Successful login │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Error States¶
Clear Error Messages¶
| Error | Message | Action |
|---|---|---|
| Invalid credentials | "Email or password is incorrect" | Try again or reset password |
| Email not verified | "Please verify your email before logging in" | Resend verification email |
| Session expired | "Your session has expired. Please log in again" | Re-login |
| Permission denied | "You don't have permission to access this resource" | Contact admin |
| Rate limited | "Too many login attempts. Please try again in 5 minutes" | Wait or contact support |
Recovery Actions¶
Each error includes a clear next step: - Button to resend verification email - Link to password reset - Contact support link - Retry action (with countdown)
Mobile Considerations¶
Responsive Design¶
| Element | Desktop | Mobile |
|---|---|---|
| Login Form | Centered card | Full-width form |
| Team Selection | Radio buttons | Dropdown/cards |
| OTP Input | Numbered boxes | Numeric keyboard |
| Activity List | Table | Cards |
Mobile-Specific UX¶
- Auto-capitalize disabled on email input
- Numeric keyboard for OTP
- Biometric authentication (planned)
- Touch-friendly buttons (44px min height)
Accessibility¶
Keyboard Navigation¶
- All forms accessible via keyboard
- Tab order logical
- Enter key submits forms
- Escape key cancels actions
Screen Reader Support¶
- Proper ARIA labels
- Error announcements
- Live regions for dynamic updates
- Semantic HTML
Contrast Requirements¶
- WCAG AA compliant (4.5:1 contrast)
- Focus indicators visible
- Error text in red + bold
- Success text in green + bold
Performance¶
Load Times¶
| Page | Target | Current |
|---|---|---|
| Login | < 1s | ~400ms |
| Session Exchange | < 500ms | ~300ms |
| Token Refresh | < 200ms | ~150ms |
Optimizations¶
- Server-side rendering for initial load
- Lazy loading for team selector
- Debounced search inputs
- Optimized images
Related Documentation¶
- Features - Feature capabilities
- Cost Considerations - Cost analysis
- Security Posture - Security UX