# 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`