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?
- Zero build step — templates compile with the Go binary
- No node_modules — single binary stays single
- SSR by default — fast first paint, good SEO
- htmx gives 90% of SPA UX — form submissions, partial updates, websocket
- 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)
- Activity feed in plain English — replace raw events
- Mesh status pulses — green/yellow/red/gray
- Chat widget on every page — intelligence is the product
- Onboarding progress bar — guide new users
- Empty states — welcoming, not blank
- Create Mesh wizard — dropdowns, not GID paste
- First-run redirect —
/setupnot empty dashboard
Phase 2: Cloud Pages
- Signup page — OAuth + email
- Login OAuth buttons — GitHub + Google
- Account page — plan, usage, billing
- Upgrade banners — inline, not popup
Phase 3: Power Features
- Tasks page — cross-mesh, sortable, inline status
- Conflicts page — side-by-side resolution
- Doctor page — health matrix
- 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