docs: add technical design spec for mobile-first UI revamp
This commit is contained in:
parent
b9f4ccd71d
commit
c5f8f6fcbc
@ -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 `<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`
|
||||
Loading…
x
Reference in New Issue
Block a user