tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
auth-yes/docs/superpowers/specs/2026-08-24-mobile-first-ui-revamp-design.md

7.7 KiB
Raw Blame History

Technical Design Spec: Auth-Yes Mobile-First & Modern Minimalist UI Revamp

Date: 2026-08-24
Author: Tyler Gillispie & Antigravity
Status: Approved by User
Scope: Frontend UI & SSR Layouts (ui/)

1. Executive Summary & Objectives

Auth-Yes provides an ultra-low-friction IAM and WebAuthn Passkey authority. The goal of this technical revamp is to modernize the user interface with a mobile-first, modern minimalist design that feels native and thumb-friendly on smartphones while remaining clean, responsive, and spacious on desktop browsers.

Key Objectives:

  1. Ergonomic Mobile Navigation: Implement a fixed, thumb-accessible bottom navigation bar on mobile (< 768px) with env(safe-area-inset-bottom) support.
  2. Instant Biometric Login: Transform the login experience to prioritize one-tap passkey biometric authentication with WebAuthn conditional UI autofill, moving USB/username clutter behind progressive disclosure.
  3. Adaptive Card Decks: Eliminate rigid desktop-style tables on mobile devices for Sessions, Passkeys, and Admin screens in favor of responsive, touch-friendly card lists.
  4. Zero-Dependency Purity: Maintain 100% pure Hono SSR JSX and vanilla CSS with zero client-side framework runtime bloat.

2. Visual Design System & Theme Foundation

2.1 CSS Custom Properties (Design Tokens)

The stylesheet will be embedded globally via the root layouts using standard CSS custom properties:

:root {
  /* Brand & Accents */
  --primary: #0066cc;
  --primary-hover: #0052a3;
  --primary-light: #e6f0fa;
  --primary-ring: rgba(0, 102, 204, 0.25);

  /* Neutrals & Surfaces */
  --surface-canvas: #f8fafc;
  --surface-card: #ffffff;
  --surface-muted: #f1f5f9;
  --border-subtle: #e2e8f0;
  --border-strong: #cbd5e1;

  /* Typography */
  --text-primary: #0f172a;
  --text-secondary: #475569;
  --text-muted: #94a3b8;

  /* Semantic Feedback */
  --success: #10b981;
  --success-bg: #ecfdf5;
  --success-border: #a7f3d0;
  --warning: #f59e0b;
  --warning-bg: #fffbeb;
  --warning-border: #fde68a;
  --danger: #ef4444;
  --danger-bg: #fef2f2;
  --danger-border: #fecaca;

  /* Spacing & Geometry */
  --radius-sm: 6px;
  --radius-md: 10px;
  --radius-lg: 16px;
  --radius-full: 9999px;
  --touch-target-min: 48px;
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
}

@media (prefers-color-scheme: dark) {
  :root {
    --surface-canvas: #0b0f19;
    --surface-card: #111827;
    --surface-muted: #1e293b;
    --border-subtle: #1f2937;
    --border-strong: #374151;

    --text-primary: #f8fafc;
    --text-secondary: #cbd5e1;
    --text-muted: #64748b;

    --primary-light: #172554;
    --success-bg: #064e3b;
    --success-border: #065f46;
    --warning-bg: #451a03;
    --warning-border: #78350f;
    --danger-bg: #450a0a;
    --danger-border: #7f1d1d;
  }
}

3. Shell Architecture & Navigation

3.1 Adaptive Layout Structure

+-------------------------------------------------------------+
| MOBILE VIEW (< 768px)                                       |
+-------------------------------------------------------------+
| [⚡ Auth-Yes]      Launchpad               [tylerg] [🚪Logout] |  <-- Compact Top Bar
+-------------------------------------------------------------+
|                                                             |
|   (Main Content Area - Adaptive Cards & Tiles)              |
|                                                             |
+-------------------------------------------------------------+
| [ 🚀 Launchpad ] [ 📱 Sessions ] [ 🔑 Passkeys ] [ 🛡️ Admin ] |  <-- Fixed Bottom Nav
+-------------------------------------------------------------+

+-------------------------------------------------------------+
| DESKTOP VIEW (≥ 768px)                                      |
+-------------------------------------------------------------+
| [⚡ Auth-Yes]  Launchpad  Sessions  Passkeys    [Admin] [Logout] |  <-- Sticky Top Bar
+-------------------------------------------------------------+
|                                                             |
|   (Main Content Area - Wide Container & Tables)             |
|                                                             |
+-------------------------------------------------------------+

3.2 Navigation Components

  1. ui/components/AuthenticatedLayout.tsx:

    • On screens < 768px: Renders a fixed bottom navigation bar with 4 primary targets:
      • Launchpad: /dashboard
      • Sessions: /dashboard/sessions
      • Passkeys: /dashboard/passkeys
      • Admin Console: /admin/users (visible when isAdmin === true)
    • Bottom padding on <main> container dynamically set to calc(4rem + env(safe-area-inset-bottom)) to prevent content overlap.
    • On screens ≥ 768px: Hides the bottom navigation bar and renders the top horizontal navigation pill strip.

  2. ui/components/AdminLayout.tsx:

    • Sub-navigation across Admin modules (Users, Invites, Apps, Roles, Audit Logs, AAGUIDs) rendered as a horizontal scrollable pill bar on mobile and clean tab bar on desktop.

4. Authentication Flow & Ergonomics

4.1 Login Screen (ui/components/LoginPage.tsx)

  • Primary Hero: Large 52px button: "Sign In with Passkey" with biometric fingerprint glyph.
  • Conditional UI / Autofill: Script initializes SimpleWebAuthnBrowser.startAuthentication({ ... }, true) with mediation: 'conditional' if supported by browser.
  • Progressive Disclosure: USB instructions and optional username input collapsed behind an expandable trigger: "Need to specify a username or use account recovery?".
  • Live State: Smooth spinner and subtle pulsing aura while authenticator prompt is active.

4.2 Registration Screen (ui/components/RegisterPage.tsx)

  • Clean 2-step onboarding card for invite-code validation + 1-tap passkey enrollment.
  • 12-word recovery phrase presented with single-tap "Copy Seed Phrase" button.

4.3 Recovery Screen (ui/components/RecoveryPage.tsx)

  • Mobile-friendly 12-box input matrix supporting paste-all and auto-focus advance.

5. Adaptive Data Views

5.1 Application Launchpad (ui/components/AppLaunchpadPage.tsx)

  • Responsive grid (1 column on mobile, minmax(320px, 1fr) on desktop).
  • Card elements: App Name, Domain link, Role Badge (Admin / Member / Viewer), description, and prominent 48px "Launch App ↗" button.

5.2 Sessions Management (ui/components/SessionsPage.tsx)

  • Mobile Cards: Replaces rigid table with session cards showing:
    • Device type icon (📱 Phone / 💻 Laptop).
    • Emerald "Current Device" pill.
    • IP Address and formatted date.
    • Dedicated "Revoke Session" button.
  • Top Action: "Revoke All Other Sessions" danger button.

5.3 Passkeys Management (ui/components/PasskeysPage.tsx)

  • Mobile Cards: Replaces rigid table with passkey cards showing:
    • Authenticator vendor brand chip (Google Password Manager, Apple Keychain, YubiKey).
    • Nickname and Credential ID preview.
    • Creation and last-used dates.
    • 1-tap "Add New Passkey" hero action button.
    • Revoke / Delete action.

5.4 Admin Screens (ui/components/Admin*.tsx)

  • Responsive cards for Users, Apps, Invites, and Audit Logs on mobile with search filters and expandable details.

6. Implementation & Quality Gates

  1. Pure SSR JSX: All changes strictly implemented in Hono SSR JSX without React runtime.
  2. Quality Gates:
    • deno fmt
    • deno task lint
    • deno task check
    • deno task test