Flow Mesh — UI Design System

The UI IS the product. Every feature must have a UI manifestation. CLI is for agents. Web is for humans. Both are first-class. Related: CLOUD.md, COMMERCIAL.md, VIBE-CODER-GTM.md


1. Principle: UI-First, CLI-Second

Every feature in Flow Mesh must be fully usable from the web UI without touching a terminal. The CLI exists for agents and power users. The web UI exists for everyone else.

Feature Web UI CLI Equivalent
Create mesh Visual wizard with dropdowns mesh ps create
Create task Inline form or chat bubble mesh task create
View tasks Sortable table with filters mesh task list
Connect Asana OAuth button or paste field mesh config set / mesh connect
Connect Discord OAuth button or paste field mesh config set / mesh connect
Resolve conflict Side-by-side diff + buttons mesh resolve
View events Filterable feed in plain English mesh events
Intelligence chat Floating widget on every page mesh ask / mesh chat
Configure sync Visual policy cards with toggles mesh config set
Manage users Account settings page mesh auth
View spending Charts + limits bar mesh intel spending
Export data Download buttons mesh export
Backup One-click download DB sqlite3 .backup
Upgrade plan Inline banner → Stripe N/A

Rule: If it can only be done via CLI, it's incomplete.


2. Current Pages (v0.3.x)

Existing

Page Route Purpose Status
Login /login Username/password auth ✅ Working
Dashboard / Stats, mesh list, recent activity ✅ Working
Setup /setup Asana, Discord, scanner, intelligence config ✅ Working
Discovery /discovery Scan results (server, Asana, Discord tabs) ✅ Working
Meshes /project-spaces List all meshes ✅ Working
Mesh Detail /project-spaces/:id Mappings, policy, sync settings, events ✅ Working
Approvals /approvals Pending approval queue ✅ Working
Events /events Event ledger with filters ✅ Working
Intelligence /intelligence AI config, spending, delegations, chat ✅ Working

Missing (Required for Launch)

Page Route Purpose Priority
Signup /signup OAuth + email registration (cloud) P1
Account /account Profile, plan, usage, billing, export P1
Create Mesh /project-spaces/new Visual wizard — dropdowns, policy cards P1
Tasks /tasks Cross-mesh task list with inline actions P1
Task Detail /tasks/:id Full task view with comments, links, history P2
Conflicts /conflicts Side-by-side diff with resolution buttons P1
Doctor /doctor Health matrix — green/red per service P2
Connect /connect Connection broker landing (self-hosted) P2

3. Design System

Stack

  • Go html/template — server-rendered, zero JS build step
  • htmx — dynamic interactions without SPA complexity
  • CSS custom properties — dark theme with tokens
  • SVG icons — inline, no icon fonts, no emoji
  • Mobile-first — 375px minimum, scroll-snap navigation

Why NOT React/Next/Vue?

  1. Zero build step — templates compile with the Go binary
  2. No node_modules — single binary stays single
  3. SSR by default — fast first paint, good SEO
  4. htmx gives 90% of SPA UX — form submissions, partial updates, websocket
  5. Matches self-hosted ethos — no separate frontend deploy

Color Tokens

:root {
  --bg: #0d1117;
  --bg-card: #161b22;
  --bg-input: #0d1117;
  --border: #30363d;
  --text: #c9d1d9;
  --dim: #8b949e;
  --accent: #58a6ff;       /* Primary blue */
  --green: #3fb950;        /* Success / active */
  --yellow: #d2992a;       /* Warning / pending */
  --red: #f85149;          /* Error / failed */
  --purple: #bc8cff;       /* Intelligence / AI */
  --indigo: #6366f1;       /* Brand primary */
}

Typography

font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
font-size: 14px (base), 12px (small), 16px (headers), 24px (page titles);

Component Patterns

Component Implementation Used On
Card .card with --bg-card background Dashboard, meshes, settings
Badge .badge-{green,yellow,red,blue} Status indicators everywhere
Button .btn-primary, .btn-danger, .btn-ghost Forms, actions
Input <input> with --bg-input Setup, create forms
Dropdown <select> styled Policy, filters
Tab bar .tab-bar with htmx hx-get Events, discovery
Pulse dot .pulse-{green,yellow,red} Mesh status
Progress bar .progress-bar with percentage Usage, onboarding
Modal .modal with backdrop Confirmations, create task
Toast .toast auto-dismiss Success/error feedback
Chat bubble .chat-widget fixed bottom-right Intelligence on every page

4. Page-by-Page UX Specification

4.1 Login (/login)

Current: Username + password form, animated logo.

Cloud addition:

┌─────────────────────────────────┐
│          Flow Mesh              │
│    Human · Agent Task Fabric    │
│                                 │
│  [  Sign in with GitHub    ]    │  ← Primary CTA
│  [  Sign in with Google    ]    │
│                                 │
│  ─────── or ────────            │
│                                 │
│  Email:    [_____________]      │
│  Password: [_____________]      │
│  ☑ Remember me                  │
│                                 │
│  [        Sign In        ]      │
│                                 │
│  New? Create account →          │
└─────────────────────────────────┘

4.2 Dashboard (/)

Current: Stats (meshes, items, pending, approvals), mesh list, recent activity.

Improvements:

┌─────────────────────────────────────────┐
│ Dashboard                               │
│                                         │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐      │
│  │  3  │ │ 47  │ │  0  │ │  1  │      │
│  │Mesh │ │Tasks│ │Pend │ │Conf │      │
│  └─────┘ └─────┘ └─────┘ └─────┘      │
│                                         │
│  ┌─ Onboarding ──────────────────────┐  │  ← Only shows until complete
│  │ ●━━━●━━━●━━━○━━━○  3/5 complete  │  │
│  │ Next: Connect Discord →           │  │
│  └───────────────────────────────────┘  │
│                                         │
│  My Meshes                              │
│  ┌─────────────────────────────────┐    │
│  │ 🟢 Auth System     active       │    │  ← Green pulse = syncing
│  │    47 tasks · synced 2m ago     │    │
│  ├─────────────────────────────────┤    │
│  │ 🟡 Landing Page    behind       │    │  ← Yellow = events pending
│  │    12 tasks · 3 pending         │    │
│  ├─────────────────────────────────┤    │
│  │ ⚪ Archive         paused       │    │  ← Gray = paused
│  │    89 tasks                     │    │
│  └─────────────────────────────────┘    │
│                                         │
│  [+ Create Mesh]                        │
│                                         │
│  Recent Activity                        │
│  ┌─────────────────────────────────┐    │
│  │ ✓ "Fix login" synced to Discord │    │  ← Plain English
│  │   2 minutes ago                 │    │
│  │ + "Add payments" created        │    │
│  │   5 minutes ago                 │    │
│  │ ⚡ Conflict: title changed on   │    │
│  │   2 surfaces → Resolve →        │    │
│  └─────────────────────────────────┘    │
│                                         │
│  💬 ──────────────────────── [Send]     │  ← Chat widget
└─────────────────────────────────────────┘

4.3 Create Mesh Wizard (/project-spaces/new)

Current: No dedicated page — meshes created via CLI or discovery.

New: Step-by-step visual wizard.

Step 1: Name Your Mesh
┌─────────────────────────────────┐
│  Mesh Name: [My Project      ]  │
│                                 │
│  [Next →]                       │
└─────────────────────────────────┘

Step 2: Connect Asana (optional)
┌─────────────────────────────────┐
│  ○ Skip Asana                   │
│  ◉ Link existing project        │
│    ┌──────────────────────────┐ │
│    │ ▾ Marketing Campaign     │ │  ← Dropdown, fetched from API
│    │   Website Redesign       │ │
│    │   Q1 Engineering         │ │
│    └──────────────────────────┘ │
│  ○ Create new Asana project     │
│    Name: [________________]     │
│                                 │
│  [← Back]  [Next →]            │
└─────────────────────────────────┘

Step 3: Connect Discord (optional)
┌─────────────────────────────────┐
│  ○ Skip Discord                 │
│  ◉ Link existing channel        │
│    ┌──────────────────────────┐ │
│    │ ▾ #project-updates       │ │  ← Dropdown, forums only
│    │   #dev-chat              │ │
│    └──────────────────────────┘ │
│  ○ Create new forum channel     │
│    Name: [my-project         ]  │
│                                 │
│  [← Back]  [Next →]            │
└─────────────────────────────────┘

Step 4: Sync Settings
┌─────────────────────────────────┐
│  How should this mesh sync?     │
│                                 │
│  ┌──────────┐  ┌──────────┐    │
│  │ ↔ Full   │  │ → One-Way│    │
│  │ Two-Way  │  │ Asana is │    │
│  │ Changes  │  │ source   │    │  ← Visual cards, not A/B/C
│  │ flow     │  │ of truth │    │
│  │ both     │  │          │    │
│  │ ways     │  │          │    │
│  │ (Rec.)   │  │          │    │
│  └──────────┘  └──────────┘    │
│                                 │
│  [← Back]  [Create Mesh →]     │
└─────────────────────────────────┘

Step 5: Done!
┌─────────────────────────────────┐
│  🎉 My Project is live!        │
│                                 │
│  ● Syncing 23 tasks             │
│  Asana ↔ Discord                │
│                                 │
│  Import existing Asana tasks?   │
│  [Import Tasks]  [Skip]         │
│                                 │
│  [Go to Dashboard →]            │
└─────────────────────────────────┘

4.4 Tasks Page (/tasks)

Current: Tasks only visible inside mesh detail page.

New: Dedicated cross-mesh task list.

┌─────────────────────────────────────────┐
│ Tasks                    [+ New Task]   │
│                                         │
│ Filter: [All Meshes ▾] [All Status ▾]  │
│         [All Priority ▾] [Search...  ]  │
│                                         │
│ ┌───┬─────────────┬────────┬────┬─────┐ │
│ │ P │ Title       │ Status │Mesh│ Due  │ │
│ ├───┼─────────────┼────────┼────┼─────┤ │
│ │🔴│ Fix login   │▾ Done  │Auth│ Mar 1│ │  ← Inline status toggle
│ │🟡│ Add Stripe  │▾ Open  │Auth│ Mar 5│ │
│ │🟡│ Mobile nav  │▾ WIP   │Web │ —    │ │
│ │🟢│ Update docs │▾ Open  │Web │ Mar 8│ │
│ └───┴─────────────┴────────┴────┴─────┘ │
│                                         │
│ Showing 47 of 128 tasks                 │
└─────────────────────────────────────────┘

4.5 Conflict Resolution (/conflicts)

Current: Conflicts only visible in events feed as event type.

New: Dedicated page with side-by-side diff.

┌─────────────────────────────────────────┐
│ ⚡ 1 Active Conflict                    │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ Title conflict on "Fix login page"  │ │
│ │ Auth System · detected 3 min ago    │ │
│ │                                     │ │
│ │ ┌──────────┐   ┌──────────┐        │ │
│ │ │  Asana    │   │ Discord  │        │ │
│ │ │           │   │          │        │ │
│ │ │ "Fix the  │   │ "Fix     │        │ │
│ │ │  login    │   │  auth    │        │ │
│ │ │  page"    │   │  page"   │        │ │
│ │ │           │   │          │        │ │
│ │ │ [Keep ✓]  │   │ [Keep ✓] │        │ │
│ │ └──────────┘   └──────────┘        │ │
│ │                                     │ │
│ │ Or: [Dismiss — keep both]           │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘

4.6 Intelligence Chat Widget

Appears on EVERY page as a floating bubble in the bottom-right corner.

                                    ┌──┐
                                    │💬│  ← Collapsed: bubble
                                    └──┘

Click to expand:
                          ┌─────────────────┐
                          │ Flow Mesh AI     │
                          │                  │
                          │ You: list tasks  │
                          │                  │
                          │ FM: You have 12  │
                          │ open tasks:      │
                          │ 🔴 Fix login (P1)│
                          │ 🟡 Add Stripe    │
                          │ ...              │
                          │                  │
                          │ [___________] ↵  │
                          └─────────────────┘

4.7 Setup Page — Cloud vs Self-Hosted

Self-hosted (current + improvements):

Setup
├── Asana: [Connect Asana →] button OR paste PAT field
├── Discord: [Connect Discord →] button OR paste token field
├── Scanner: paths + excludes
├── Intelligence: provider/model/key config
├── Server: external_url, log level
└── Sync: poll intervals, conflict window

Cloud (simplified):

Setup
├── Asana: [Connect Asana →] OAuth button (done in onboarding)
├── Discord: [Add to Discord →] OAuth button (done in onboarding)
├── Intelligence: provider/model selection (simpler — no base_url)
└── Preferences: notifications, default sync mode

Cloud users don't see: scanner, external_url, log level, poll intervals.

4.8 Account Page (/account) — Cloud Only

┌─────────────────────────────────┐
│ Account                         │
│                                 │
│ Profile                         │
│ Name: [Verious Smith       ]    │
│ Email: [email protected]      │
│ Connected: GitHub ✓ · Google ✓  │
│                                 │
│ Plan: Pro ($29/mo)              │
│ Meshes: 5 / unlimited          │
│ Events today: 847 / 10,000     │
│ ████████░░░░ 85%                │
│                                 │
│ [Manage Billing →]              │  ← Opens Stripe Portal
│ [Upgrade to Team →]             │
│                                 │
│ Data                            │
│ [Download Database]             │  ← Self-host migration
│ [Export All Events (JSON)]      │
│ [Delete Account]                │  ← GDPR
└─────────────────────────────────┘

5. UI States

Every page must handle 4 states:

State What Shows Example
Empty Helpful CTA, not blank space "No meshes yet. [Create your first mesh →]"
Loading Spinner or skeleton htmx hx-indicator
Error Plain English + action "Asana disconnected. [Reconnect →]"
Success Green toast or checkmark "Task created ✓"

Empty States (Critical for First Impressions)

Dashboard (no meshes):
┌─────────────────────────────────┐
│  Welcome to Flow Mesh! 🎉      │
│                                 │
│  Let's connect your tools and   │
│  create your first mesh.        │
│                                 │
│  [Create Your First Mesh →]     │
│                                 │
│  Or follow the setup guide →    │
└─────────────────────────────────┘

Tasks (no tasks):
┌─────────────────────────────────┐
│  No tasks yet.                  │
│                                 │
│  Create a task here or in       │
│  Asana/Discord — it'll sync     │
│  automatically.                 │
│                                 │
│  [+ Create Task]                │
│  Or ask: "@Flow Mesh create     │
│  task 'Fix login'" in Discord   │
└─────────────────────────────────┘

6. Responsive Breakpoints

Breakpoint Layout Navigation
< 768px (mobile) Single column, scroll-snap carousel Bottom tab bar (6 items)
768-1024px (tablet) Two columns where applicable Top nav bar
> 1024px (desktop) Full width with sidebars Top nav bar + side panel

Mobile Navigation (Bottom Bar)

┌─────────────────────────────────┐
│ [Dashboard][Setup][Discover]    │
│ [Meshes 3][Approvals][Events]   │
└─────────────────────────────────┘

Desktop Navigation (Top Bar)

Flow Mesh ●●●  Dashboard  Setup  Discover  Meshes⁵  Approvals  Events  Intelligence

7. htmx Patterns

Partial Updates

<!-- Dashboard mesh list refreshes every 30s -->
<div hx-get="/api/dashboard/meshes" hx-trigger="every 30s" hx-swap="innerHTML">
  ...mesh cards...
</div>

<!-- Create task inline -->
<form hx-post="/api/work-items" hx-target="#task-list" hx-swap="afterbegin">
  <input name="title" placeholder="Task title...">
  <button type="submit">Create</button>
</form>

Websocket Chat

<!-- Intelligence chat widget -->
<div hx-ws="connect:/ws/chat">
  <div id="chat-messages">...</div>
  <form hx-ws="send">
    <input name="text" placeholder="Ask Flow Mesh...">
  </form>
</div>

Optimistic Updates

<!-- Toggle task status immediately, sync in background -->
<select hx-post="/api/work-items/{{.ID}}/status" hx-swap="none"
        hx-on::after-request="this.closest('tr').querySelector('.status-badge').className = 'badge-' + this.value">
  <option value="open">Open</option>
  <option value="in_progress">In Progress</option>
  <option value="done">Done</option>
</select>

8. UI in Every Model

Commercial Model (COMMERCIAL.md)

Feature gating must be VISIBLE in the UI:

Free sees Pro sees Team sees
3 mesh cards Unlimited Unlimited
No chat widget Chat widget on all pages Chat + delegation
No intelligence page Full intelligence page + Scheduled jobs config
Basic events Full events + export + Analytics dashboard
"Upgrade to Pro" banners "Upgrade to Team" banners Full access

Upgrade prompts appear as inline banners, not popups:

┌──────────────────────────────────────────────┐
│ ⭐ You've used 3/3 meshes. Upgrade to Pro    │
│    for unlimited meshes + AI assistant.       │
│    [$29/mo — Start Free Trial →]              │
└──────────────────────────────────────────────┘

Cloud Model (CLOUD.md)

The cloud onboarding IS the UI. Every cloud step = a UI page:

1. /signup          → OAuth buttons + form
2. /onboarding/1    → Connect Asana (OAuth button)
3. /onboarding/2    → Connect Discord (OAuth button)
4. /onboarding/3    → Create mesh (dropdown wizard)
5. /                → Dashboard with first mesh syncing

Vibe Coder Model (VIBE-CODER-GTM.md)

The chat widget IS the killer feature for vibe coders. They don't navigate pages — they talk to the bot:

"create task fix login P1"
"what's in progress?"
"plan add payments"

The chat widget must be prominent, not hidden. Consider:

  • Auto-expand on first visit
  • Suggested prompts: "Try: 'list my tasks'"
  • Voice input button (mobile)

Agent Model (SKILL.md, AGENTS.md)

Agents don't use the UI — but they need to know:

  • Web UI exists at {base_url}/ for human users
  • API endpoints mirror every UI action
  • Screenshots/links in docs so agents can reference for users

Self-Hosted Model

The setup wizard must handle BOTH paths:

Has external_url? → OAuth buttons enabled
No external_url?  → Paste fields shown (with guided help)

Auto-detect and show the right UX.


9. Implementation Priority

Phase 1: Core UX Fixes (Pre-Launch)

  1. Activity feed in plain English — replace raw events
  2. Mesh status pulses — green/yellow/red/gray
  3. Chat widget on every page — intelligence is the product
  4. Onboarding progress bar — guide new users
  5. Empty states — welcoming, not blank
  6. Create Mesh wizard — dropdowns, not GID paste
  7. First-run redirect — /setup not empty dashboard

Phase 2: Cloud Pages

  1. Signup page — OAuth + email
  2. Login OAuth buttons — GitHub + Google
  3. Account page — plan, usage, billing
  4. Upgrade banners — inline, not popup

Phase 3: Power Features

  1. Tasks page — cross-mesh, sortable, inline status
  2. Conflicts page — side-by-side resolution
  3. Doctor page — health matrix
  4. Task detail — full view with comments

10. Testing the UI

Visual Regression

# Screenshot every page via vision skill
for page in "/" "/setup" "/project-spaces" "/events" "/intelligence"; do
  curl "localhost:7456/api/screenshot?url=https://mesh.philoveracity.com${page}&width=390&height=844" > "ui-${page//\//-}.png"
done

Mobile Testing

Test every page at: 375px, 390px, 414px, 768px, 1024px, 1440px.

Accessibility

  • All interactive elements keyboard-navigable
  • Color contrast meets WCAG AA
  • Screen reader labels on icons
  • Focus indicators visible

Created: 2026-02-24 | Source of truth for all UI decisions

Generated from the Flow Mesh repository by scripts/build-docs-site.sh. If a page is wrong here, the file it was rendered from is wrong.