From c5f8f6fcbc4f1c482f86e8b640b050d9f35d8a51 Mon Sep 17 00:00:00 2001 From: Tyler Gillispie Date: Mon, 24 Aug 2026 22:10:09 -0700 Subject: [PATCH] docs: add technical design spec for mobile-first UI revamp --- ...026-08-24-mobile-first-ui-revamp-design.md | 229 ++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-24-mobile-first-ui-revamp-design.md diff --git a/docs/superpowers/specs/2026-08-24-mobile-first-ui-revamp-design.md b/docs/superpowers/specs/2026-08-24-mobile-first-ui-revamp-design.md new file mode 100644 index 0000000..98dc95c --- /dev/null +++ b/docs/superpowers/specs/2026-08-24-mobile-first-ui-revamp-design.md @@ -0,0 +1,229 @@ +# 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: + +```css +: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 `
` 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`