230 lines
7.7 KiB
Markdown
230 lines
7.7 KiB
Markdown
# 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`
|