orion/docs/frontend/storefront/authentication-pages.md

Shop Authentication Pages

Overview

This document details the implementation of customer authentication pages in the shop frontend. All pages use Tailwind CSS, Alpine.js, and integrate with the multi-theme system for a branded, consistent experience across all vendors.

Implementation Date

2025-11-24

---

📄 Available Pages

1. Login Page

Location: app/templates/shop/account/login.html Route: /shop/account/login

Features

• Two-column layout with vendor 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

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/shop/auth/login
            // Stores token in localStorage
            // Redirects to account page or return URL
        }
    }
}

API Integration

• Endpoint: POST /api/v1/shop/auth/login
• Request: { email_or_username: string, password: string }
• Response: { access_token: string, user: object }

---

2. Register Page

Location: app/templates/shop/account/register.html Route: /shop/account/register

Features

• Two-column layout with vendor 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

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/shop/auth/register
            // Shows success message
            // Redirects to login with ?registered=true
        }
    }
}

API Integration

• Endpoint: POST /api/v1/shop/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/shop/account/forgot-password.html Route: /shop/account/forgot-password

Features

• Two-column layout with vendor 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 shop homepage
• Dark mode support
• Mobile responsive

Alpine.js Component

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/shop/auth/forgot-password
            // Sets emailSent = true on success
            // Shows confirmation message
        }
    }
}

API Integration

• Endpoint: POST /api/v1/shop/auth/forgot-password
• Request: { email: string }
• Response: { message: string }

---

🎨 Theme Integration

All authentication pages inject the vendor's theme CSS variables for consistent branding:

<style id="vendor-theme-variables">
    :root {
        {% for key, value in theme.css_variables.items() %}
        {{ key }}: {{ value }};
        {% endfor %}
    }

    /* Theme-aware button and focus colors */
    .btn-primary-theme {
        background-color: var(--color-primary);
    }
    .btn-primary-theme:hover:not(:disabled) {
        background-color: var(--color-primary-dark, var(--color-primary));
        filter: brightness(0.9);
    }
    .focus-primary:focus {
        border-color: var(--color-primary);
        box-shadow: 0 0 0 3px rgba(var(--color-primary-rgb, 124, 58, 237), 0.1);
    }
</style>

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
Vendor logo	theme.branding.logo	Displayed in left column

Benefits

• ✅ Each vendor's auth pages automatically match their brand
• ✅ Consistent with main shop design
• ✅ Dark mode adapts to vendor colors
• ✅ Professional, polished appearance
• ✅ No custom CSS needed per vendor

---

📱 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

Shop Homepage
    ↓
Login Page ←→ Register Page
    ↓              ↓
Forgot Password    |
    ↓              ↓
Check Email   Account/Cart

Link Structure

• Login Page:

  • "Forgot password?" → /shop/account/forgot-password
  • "Create an account" → /shop/account/register
  • "← Continue shopping" → /shop/

• Register Page:

  • "Already have an account? Sign in instead" → /shop/account/login

• Forgot Password Page:

  • "Remember your password? Sign in" → /shop/account/login
  • "← Continue shopping" → /shop/

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:

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

Vendors can customize colors in their theme configuration:

theme = {
    "colors": {
        "primary": "#6366f1",  # Changes all primary elements
        "secondary": "#8b5cf6",
        "accent": "#ec4899"
    }
}

For Vendors

Vendors 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/shop/account/
│   ├── login.html              ← Customer login page
│   ├── register.html           ← Customer registration page
│   └── forgot-password.html    ← Password reset page
│
└── api/v1/shop/
    └── 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

• Vendor colors apply correctly
• Vendor logo displays
• Dark mode works with vendor 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

• Shop Frontend Architecture
• Page Template Guide
• Theme System Overview
• Theme Presets
• API Authentication Documentation

---

Last Updated: 2025-11-24 Status: ✅ Production Ready Maintainer: Development Team