# Storefront Authentication Pages ## Overview This document details the implementation of customer authentication pages in the storefront frontend. All pages use Tailwind CSS, Alpine.js, and integrate with the multi-theme system for a branded, consistent experience across all stores. ## Implementation Date 2025-11-24 --- ## 📄 Available Pages ### 1. Login Page **Location:** `app/templates/storefront/account/login.html` **Route:** `/storefront/account/login` #### Features - Two-column layout with store branding on the left - Email and password fields with validation - Password visibility toggle - "Remember me" checkbox - Links to register and forgot password pages - Error and success message alerts - Loading states with animated spinner - Theme-aware colors using CSS variables - Full dark mode support - Mobile responsive design #### Alpine.js Component ```javascript function customerLogin() { return { credentials: { email: '', password: '' }, rememberMe: false, showPassword: false, loading: false, errors: {}, alert: { show: false, type: 'error', message: '' }, dark: false, async handleLogin() { // Validates input // Calls POST /api/v1/storefront/auth/login // Stores token in localStorage // Redirects to account page or return URL } } } ``` #### API Integration - **Endpoint:** `POST /api/v1/storefront/auth/login` - **Request:** `{ email_or_username: string, password: string }` - **Response:** `{ access_token: string, user: object }` --- ### 2. Register Page **Location:** `app/templates/storefront/account/register.html` **Route:** `/storefront/account/register` #### Features - Two-column layout with store branding - Form fields: - First name (required) - Last name (required) - Email (required, validated) - Phone (optional) - Password (required, min 8 chars, 1 letter, 1 number) - Confirm password (required, must match) - Marketing consent checkbox - Real-time client-side validation - Password visibility toggle - Password strength requirements displayed - Theme-aware styling - Loading states with spinner - Success/error message handling - Redirects to login page after successful registration #### Validation Rules - **First Name:** Required, non-empty - **Last Name:** Required, non-empty - **Email:** Required, valid email format - **Password:** Minimum 8 characters, at least one letter, at least one number - **Confirm Password:** Must match password field #### Alpine.js Component ```javascript function customerRegistration() { return { formData: { first_name: '', last_name: '', email: '', phone: '', password: '', marketing_consent: false }, confirmPassword: '', showPassword: false, loading: false, errors: {}, validateForm() { // Validates all fields // Sets this.errors for invalid fields // Returns true if all valid }, async handleRegister() { // Validates form // Calls POST /api/v1/storefront/auth/register // Shows success message // Redirects to login with ?registered=true } } } ``` #### API Integration - **Endpoint:** `POST /api/v1/storefront/auth/register` - **Request:** `{ first_name: string, last_name: string, email: string, phone?: string, password: string, marketing_consent: boolean }` - **Response:** `{ message: string }` --- ### 3. Forgot Password Page **Location:** `app/templates/storefront/account/forgot-password.html` **Route:** `/storefront/account/forgot-password` #### Features - Two-column layout with store branding - Email input field - Two-state interface: 1. **Form State:** Email input with submit button 2. **Success State:** Confirmation message with checkmark icon - Success state displays: - Checkmark icon - "Check Your Email" heading - Email sent confirmation - Instructions to check inbox - Option to retry if email not received - Theme-aware styling - Links back to login and storefront homepage - Dark mode support - Mobile responsive #### Alpine.js Component ```javascript function forgotPassword() { return { email: '', emailSent: false, loading: false, errors: {}, alert: { show: false, type: 'error', message: '' }, dark: false, async handleSubmit() { // Validates email // Calls POST /api/v1/storefront/auth/forgot-password // Sets emailSent = true on success // Shows confirmation message } } } ``` #### API Integration - **Endpoint:** `POST /api/v1/storefront/auth/forgot-password` - **Request:** `{ email: string }` - **Response:** `{ message: string }` --- ## 🎨 Theme Integration All authentication pages inject the store's theme CSS variables for consistent branding: ```html ``` ### Themed Elements | Element | CSS Variable | Usage | |---------|-------------|--------| | Left panel background | `var(--color-primary)` | Brand color fills entire left column | | Submit buttons | `var(--color-primary)` | Primary action buttons | | Links | `var(--color-primary)` | Forgot password, register, login links | | Checkboxes | `var(--color-primary)` | Remember me, marketing consent | | Focus states | `var(--color-primary)` | Input field focus rings | | Store logo | `theme.branding.logo` | Displayed in left column | ### Benefits - ✅ Each store's auth pages automatically match their brand - ✅ Consistent with main storefront design - ✅ Dark mode adapts to store colors - ✅ Professional, polished appearance - ✅ No custom CSS needed per store --- ## 📱 Responsive Design ### Mobile (<640px) - Vertical layout (branding on top, form below) - Smaller h-32 branding section - Full-width buttons - Reduced padding (p-6 instead of p-12) - Touch-friendly input fields - Stacked form elements ### Tablet (640px-1024px) - Side-by-side layout begins (md:flex-row) - Branding section grows (md:h-auto md:w-1/2) - Form section gets more space (md:w-1/2) - Comfortable padding (sm:p-12) ### Desktop (>1024px) - Full two-column layout - Max width container (max-w-4xl) - Centered on page with margins - Larger brand imagery - Optimal form spacing --- ## 🔒 Security Features ### Client-Side Security - Input validation before API submission - Password visibility toggle (not plain text by default) - HTTPS required (enforced by deployment) - No sensitive data in URLs or query params - Tokens stored in localStorage (not cookies) - Form autocomplete attributes for password managers ### Server-Side Security (API) - Password hashing with bcrypt - Email validation and sanitization - Rate limiting on auth endpoints - CSRF protection - SQL injection prevention via ORM - JWT token-based authentication - Secure password reset tokens --- ## 🎯 Design Principles ### Consistency - All three pages share the same layout structure - Identical styling patterns and spacing - Consistent error/success message handling - Same loading state indicators ### User Experience - Clear visual hierarchy - Immediate feedback on actions - Helpful error messages - Loading states prevent duplicate submissions - Success states confirm actions - Links to related pages (login ↔ register ↔ forgot password) ### Accessibility - Semantic HTML - Proper form labels - Focus states visible - Keyboard navigation support - Screen reader friendly - Sufficient color contrast ### Performance - Minimal JavaScript (Alpine.js only) - Tailwind CSS from CDN with local fallback - No external dependencies beyond Alpine.js - Fast page loads - Inline SVG icons (no image requests) --- ## 🔗 Navigation Flow ``` Storefront Homepage ↓ Login Page ←→ Register Page ↓ ↓ Forgot Password | ↓ ↓ Check Email Account/Cart ``` ### Link Structure - **Login Page:** - "Forgot password?" → `/storefront/account/forgot-password` - "Create an account" → `/storefront/account/register` - "← Continue shopping" → `/storefront/` - **Register Page:** - "Already have an account? Sign in instead" → `/storefront/account/login` - **Forgot Password Page:** - "Remember your password? Sign in" → `/storefront/account/login` - "← Continue shopping" → `/storefront/` All links use `{{ base_url }}` for multi-access routing support. --- ## 🛠️ Customization Guide ### For Developers #### Adding New Fields 1. Add field to HTML form 2. Add field to Alpine.js data 3. Update validation logic 4. Update API request body 5. Update backend endpoint #### Changing Validation Rules Edit the `validateForm()` method in Alpine.js component: ```javascript validateForm() { this.clearAllErrors(); let isValid = true; // Add/modify validation rules if (!this.formData.field_name.trim()) { this.errors.field_name = 'Field is required'; isValid = false; } return isValid; } ``` #### Customizing Theme Variables Stores can customize colors in their theme configuration: ```python theme = { "colors": { "primary": "#6366f1", # Changes all primary elements "secondary": "#8b5cf6", "accent": "#ec4899" } } ``` ### For Stores Stores can customize: - Primary brand color (buttons, links, left panel) - Logo (displayed in left column) - Custom CSS (additional styling) - Dark mode logo variant No code changes needed - all controlled via theme configuration. --- ## 📊 File Locations ``` app/ ├── templates/storefront/account/ │ ├── login.html ← Customer login page │ ├── register.html ← Customer registration page │ └── forgot-password.html ← Password reset page │ └── api/v1/storefront/ └── auth.py ← Authentication endpoints static/shared/css/ ├── base.css ← Base CSS (optional reference) └── auth.css ← Auth CSS (optional reference) Note: Templates use Tailwind CSS classes directly, not the CSS files above. ``` --- ## ✅ Testing Checklist ### Functionality - [ ] Login form submits correctly - [ ] Register form creates new account - [ ] Forgot password sends email - [ ] Validation errors display properly - [ ] Success messages show correctly - [ ] Loading states appear during API calls - [ ] Redirects work after success - [ ] Remember me checkbox persists - [ ] Password visibility toggle works ### Theme Integration - [ ] Store colors apply correctly - [ ] Store logo displays - [ ] Dark mode works with store colors - [ ] Custom fonts load - [ ] Left panel uses primary color - [ ] Buttons use primary color ### Responsive Design - [ ] Mobile layout works (<640px) - [ ] Tablet layout works (640-1024px) - [ ] Desktop layout works (>1024px) - [ ] Touch targets are adequate - [ ] Forms are usable on mobile ### Security - [ ] Passwords are masked by default - [ ] No sensitive data in URLs - [ ] API calls use HTTPS - [ ] Tokens stored securely - [ ] Input validation works ### Accessibility - [ ] Keyboard navigation works - [ ] Focus states visible - [ ] Form labels present - [ ] Error messages announced - [ ] Color contrast sufficient --- ## 🚀 Future Enhancements Possible additions: - Social login (Google, Facebook) - Two-factor authentication (2FA) - Password strength meter - Email verification flow - OAuth integration - Account recovery via phone - Security questions - Biometric authentication --- ## 📚 Related Documentation - [Storefront Frontend Architecture](./architecture.md) - [Page Template Guide](./page-templates.md) - [Theme System Overview](../../architecture/theme-system/overview.md) - [Theme Presets](../../architecture/theme-system/presets.md) - [API Authentication Documentation](../../api/authentication.md) --- **Last Updated:** 2025-11-24 **Status:** ✅ Production Ready **Maintainer:** Development Team