flynn/docs/plans/2026-02-18-gateway-ui-redesign-design.md

# Gateway UI Responsive Redesign

**Date:** 2026-02-18
**Status:** Approved

## Goal

Redesign the Flynn gateway web frontend for a modern, responsive, mobile-friendly experience with monitoring dashboard as the primary mobile use case.

## Decisions

- **Visual style:** Modern minimal (Linear/Vercel aesthetic), dark theme
- **CSS framework:** Tailwind CSS via CDN (Play CDN for zero build step)
- **Mobile navigation:** Swipeable pages via CSS scroll-snap with pill indicator
- **Dependencies:** Tailwind CDN only; no JS frameworks or gesture libraries
- **Approach:** Full rewrite of style.css → Tailwind utility classes in JS page renderers

## Visual Language

### Typography
- **Body/UI:** Inter (sans-serif) via Google Fonts CDN
- **Code/technical values:** JetBrains Mono (monospace) — session IDs, code blocks, config values only

### Color Palette (Tailwind zinc scale)
| Role | Token | Value |
|------|-------|-------|
| Background deepest | zinc-950 | #09090b |
| Background card | zinc-900 | #18181b |
| Background elevated | zinc-800 | #27272a |
| Accent | blue-500 | #3b82f6 |
| Success | green-500 | #22c55e |
| Warning | amber-500 | #f59e0b |
| Error | red-500 | #ef4444 |
| Text primary | zinc-50 | #fafafa |
| Text secondary | zinc-400 | #a1a1aa |
| Text muted | zinc-600 | #52525b |

### Spacing
- Tailwind 4px scale
- Cards: `p-4` (16px) mobile, `p-6` (24px) desktop
- Grid gaps: `gap-4` consistent
- Touch targets: minimum 44px

### Borders & Depth
- `border-zinc-800` subtle borders
- `ring-1 ring-zinc-800` for cards
- No drop shadows — layered backgrounds create depth

## Layout & Navigation

### Desktop (≥1024px)
- Fixed left sidebar: 64px collapsed (icons only), 240px expanded on hover or pin
- Logo at top, 5 nav items with icons + labels, connection status at bottom
- Main content with max-width constraint for readability

### Tablet (768px–1023px)
- Sidebar: 64px icon-only strip (always collapsed)
- Content fills remaining width
- Grids: 3 → 2 columns

### Mobile (<768px)
- **No sidebar.** Replaced with:
  - Top bar: logo + connection indicator + current page title
  - Swipeable horizontal page container (`scroll-snap-type: x mandatory`)
  - Pill indicator bar showing page position (tappable to jump)
- Page order: Dashboard → Chat → Sessions → Usage → Settings
- Each page is `100vw` wide, `scroll-snap-align: start`
- JS manages page lifecycle (teardown old page, render new page on snap)

## Page Designs

### Dashboard (Primary Mobile Target)
- **Stat cards:** Horizontally scrollable strip on mobile, grid on desktop. Compact: large value, small label, optional trend.
- **Service status:** Colored pill badges in a compact row. Green/amber/red dots + name.
- **Session analytics:** CSS-only bar chart for daily trend. Badge list for top tools/topics.
- **Model performance:** Horizontal-scroll table, sticky first column.
- **Event stream:** Collapsible, 5 most recent visible by default.
- **Active requests:** Only shown when in-flight, with animated indicator.
- **Mobile pattern:** All sections are collapsible accordion-style. Headers + summary visible, tap to expand.

### Chat
- Full-height message area, bottom-anchored input
- Full-width messages on mobile (no side margins)
- Assistant messages: lighter card background. User messages: accent-tinted.
- Tool events: compact inline chips (expandable on tap)
- Slash command popup: bottom-sheet on mobile, floating on desktop
- File attachment: bottom sheet (mobile), drag-drop zone (desktop)
- Auto-growing textarea with always-visible send button on mobile

### Sessions
- **Mobile:** Card list (not table). Each card: session ID, channel badge, message count, last activity. Tap to expand history.
- **Desktop:** Table with inline history viewer.

### Usage
- Summary stat cards in scrollable strip (mobile) or grid (desktop)
- Per-session: stacked cards (mobile), table (desktop)
- Auto-refresh every 30s

### Settings
- Sectioned form: each group in its own card
- Toggle switches for booleans, full-width inputs for text
- 44px minimum touch targets
- Sections: PA Mode, Push Notifications, Hook Patterns, Tools, Services, Config

## Technical Approach

### Tailwind Setup
```html
<script src="https://cdn.tailwindcss.com"></script>
<script>
tailwind.config = {
  darkMode: 'class',
  theme: {
    extend: {
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        mono: ['JetBrains Mono', 'Fira Code', 'monospace'],
      }
    }
  }
}
</script>
```

### Font Loading
```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
```

### Swipe Navigation (Mobile)
CSS scroll-snap container wrapping all page divs. JS `IntersectionObserver` or `scrollend` event detects which page is visible and updates the pill indicator + triggers page lifecycle.

### Migration Strategy
1. Replace `style.css` with a minimal base (resets, custom utilities not in Tailwind)
2. Rewrite `index.html` shell with Tailwind classes
3. Rewrite each page renderer (JS) to emit Tailwind-classed HTML
4. Update `app.js` router for scroll-snap container on mobile
5. Test each page at all breakpoints

### Files Modified
- `src/gateway/ui/index.html` — new shell, Tailwind CDN, fonts
- `src/gateway/ui/style.css` — reduced to minimal base (~100 lines)
- `src/gateway/ui/app.js` — responsive router, swipe container, pill indicator
- `src/gateway/ui/pages/dashboard.js` — Tailwind classes, accordion, scrollable stats
- `src/gateway/ui/pages/chat.js` — Tailwind classes, bottom-sheet slash popup
- `src/gateway/ui/pages/sessions.js` — card list on mobile
- `src/gateway/ui/pages/usage.js` — card layout on mobile
- `src/gateway/ui/pages/settings.js` — form card layout
- `src/gateway/ui/sw.js` — update cache version
- `src/gateway/ui/manifest.webmanifest` — update theme color to zinc-950