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

<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

<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