SurfSense/_bmad-output/ux-design/extension-ux-design.md

SurfSense 2.0 Chrome Extension - UX Design Document

Version: 1.0
Date: 2026-02-02
Status: 🚧 DRAFT - Needs Wireframes & Design System
Owner: UX Designer / PM

---

Document Purpose

This UX Design Document provides comprehensive design guidance for the SurfSense 2.0 Chrome Extension. It covers:

• Wireframes for all key screens
• User flows for critical journeys
• Design system (colors, typography, spacing, components)
• Interaction patterns and micro-animations
• Responsive behavior and accessibility

Target Audience: Developers, Product Managers, QA Engineers

---

Table of Contents

1. Design Principles
2. User Flows
3. Wireframes
4. Design System
5. Component Library
6. Interaction Patterns
7. Accessibility
8. Implementation Notes

---

Design Principles

1. Context-Aware Intelligence

• AI should understand what the user is viewing without explicit input
• Proactive suggestions based on page context (DexScreener, Twitter, etc.)
• Minimize cognitive load - users shouldn't need to explain context

2. Seamless Integration

• Extension feels like a natural part of the browsing experience
• Consistent with SurfSense web dashboard design language
• Non-intrusive - doesn't block content or disrupt workflow

3. Speed & Efficiency

• Quick access to AI insights (1-click actions)
• Keyboard shortcuts for power users
• Instant feedback for all interactions

4. Trust & Transparency

• Clear indication of AI reasoning (thinking steps)
• Explicit data sources and confidence levels
• Easy to verify AI suggestions

---

User Flows

Flow 1: First-Time User Onboarding

graph TD
    A[Install Extension] --> B[Click Extension Icon]
    B --> C[Side Panel Opens]
    C --> D[Welcome Screen]
    D --> E{User Action}
    E -->|Login| F[OAuth Popup]
    E -->|Skip| G[Guest Mode]
    F --> H[Logged In State]
    G --> I[Limited Features]
    H --> J[Sync Settings from Web]
    J --> K[Ready to Use]
    I --> K

Key Screens:

1. Welcome Screen (first launch)
2. Login Screen (OAuth options)
3. Settings Sync Screen (loading state)
4. Main Chat Interface (ready state)

Success Criteria:

• User completes login in <30 seconds
• Settings sync automatically from web dashboard
• User understands core value proposition (AI co-pilot for crypto)

---

Flow 2: Chat with AI about Token

graph TD
    A[User on DexScreener] --> B[Extension Detects Token]
    B --> C[Token Info Card Appears]
    C --> D{User Action}
    D -->|Click 'Is this safe?'| E[Pre-filled Safety Query]
    D -->|Type Custom Question| F[Custom Query]
    D -->|Click 'Top Holders'| G[Pre-filled Holders Query]
    E --> H[AI Processes with Context]
    F --> H
    G --> H
    H --> I[Streaming Response]
    I --> J[Thinking Steps Visible]
    J --> K[Final Answer with Sources]

Key Screens:

1. Token Info Card (context display)
2. Chat Input (with suggestions)
3. Streaming Response (thinking steps)
4. Final Answer (with tool UIs)

Success Criteria:

• Token detection happens in <1 second
• User can ask question in <5 seconds
• AI response starts streaming in <2 seconds

---

Flow 3: Quick Capture Page

graph TD
    A[User Finds Interesting Page] --> B[Click 'Save Page' Button]
    B --> C{Logged In?}
    C -->|Yes| D[Select Search Space]
    C -->|No| E[Login Prompt]
    E --> F[OAuth Login]
    F --> D
    D --> G[Capture Page Content]
    G --> H[Upload to Backend]
    H --> I[Success Toast]
    I --> J[Page Saved]

Key Screens:

1. Quick Capture Button (sticky footer)
2. Search Space Selector (modal)
3. Capturing State (loading)
4. Success Confirmation (toast)

Success Criteria:

• User can save page in <3 clicks
• Capture completes in <5 seconds
• Clear confirmation of success

---

Wireframes

⚠️ TODO: Add wireframes for all screens below. Use Figma, Excalidraw, or hand-drawn sketches.

1. Side Panel - Main Chat Interface

Layout:

┌─────────────────────────────────────┐
│ [Logo] SurfSense    [⚙️] [👤]      │ ← Header (60px)
├─────────────────────────────────────┤
│ 🪙 BULLA/SOL                        │ ← Token Info Card
│ $0.0001  📈 +15%                    │   (Conditional, 120px)
│ Vol: $10K | Liq: $5K                │
│ [Is this safe?] [Top Holders]       │
├─────────────────────────────────────┤
│                                     │
│ Chat Messages Area                  │ ← Scrollable Chat
│ (Scrollable)                        │   (Flex-grow)
│                                     │
│ [AI]: Analyzing token...            │
│ [Thinking steps visible]            │
│                                     │
│ [User]: Is this token safe?         │
│                                     │
├─────────────────────────────────────┤
│ [Type your message...]       [📎]  │ ← Chat Input (80px)
│                              [🎤]  │
├─────────────────────────────────────┤
│        📸 Save Current Page         │ ← Quick Capture
└─────────────────────────────────────┘   (Sticky, 50px)

Total Height: Viewport height
Width: 400px (default), resizable 300-600px

Components:

• Header: Logo, Settings dropdown, User profile
• Token Info Card: Conditional (only on DexScreener)
• Chat Messages: Scrollable, auto-scroll to bottom
• Chat Input: Text area with attachment button
• Quick Capture: Sticky footer button

States:

• Loading: Skeleton screens for chat messages
• Empty: Welcome message with suggestions
• Error: Inline error messages with retry button

---

2. Welcome Screen (First Launch)

┌─────────────────────────────────────┐
│                                     │
│         🌊 SurfSense                │
│    AI Co-Pilot for Crypto           │
│                                     │
│  Chat with AI about any token       │
│  Get instant safety checks          │
│  Save insights to your knowledge    │
│                                     │
│  ┌─────────────────────────────┐   │
│  │   🔐 Login with Google      │   │
│  └─────────────────────────────┘   │
│                                     │
│  ┌─────────────────────────────┐   │
│  │   📧 Login with Email       │   │
│  └─────────────────────────────┘   │
│                                     │
│       Skip for now (Guest)          │
│                                     │
└─────────────────────────────────────┘

Copy:

• Headline: "AI Co-Pilot for Crypto"
• Subheadline: "Chat with AI about any token, get instant safety checks, save insights"
• CTA: "Login with Google" (primary), "Login with Email" (secondary)
• Skip: "Skip for now (Guest)" (text link)

---

3. Token Info Card (DexScreener Context)

┌─────────────────────────────────────┐
│ 🪙 BULLA/SOL                        │
│ $0.0001234  📈 +15.3%               │
│ Vol: $10.2K | Liq: $5.1K            │
│                                     │
│ ┌──────────────┐ ┌────────────────┐│
│ │ Is this safe?│ │ Top Holders    ││
│ └──────────────┘ └────────────────┘│
│                                     │
│ ┌──────────────┐ ┌────────────────┐│
│ │ Price Predict│ │ Rug Pull Risk  ││
│ └──────────────┘ └────────────────┘│
└─────────────────────────────────────┘

Data Displayed:

• Token Symbol/Name (e.g., "BULLA/SOL")
• Current Price (e.g., "$0.0001234")
• 24h Change (e.g., "+15.3%" with color: green if positive, red if negative)
• 24h Volume (e.g., "$10.2K")
• Liquidity (e.g., "$5.1K")

Quick Actions:

• "Is this safe?" → Trigger safety check query
• "Top Holders" → Query blockchain for holder distribution
• "Price Predict" → AI price prediction
• "Rug Pull Risk" → Rug pull detection analysis

---

4. Settings Dropdown

┌─────────────────────────────────────┐
│ ⚙️ Settings                         │
├─────────────────────────────────────┤
│ Model: GPT-4 Turbo                  │ ← Read-only
│ Search Space: Crypto Research       │ ← Read-only
│                                     │
│ ─────────────────────────────────   │
│                                     │
│ 🔗 Manage Connectors                │ ← Link to web
│ 💬 View All Chats                   │ ← Link to web
│ ⚙️ Full Settings                    │ ← Link to web
│                                     │
│ ─────────────────────────────────   │
│                                     │
│ 🚪 Logout                           │
└─────────────────────────────────────┘

Behavior:

• Dropdown triggered by ⚙️ icon in header
• Model and Search Space are read-only (managed on web)
• Links open web dashboard in new tab
• Logout clears JWT and redirects to welcome screen

---

Design System

⚠️ TODO: Define complete design system with color palette, typography, spacing, and elevation.

Colors

Primary Palette:

--primary-50:  #E3F2FD;  /* Lightest blue */
--primary-100: #BBDEFB;
--primary-200: #90CAF9;
--primary-300: #64B5F6;
--primary-400: #42A5F5;
--primary-500: #2196F3;  /* Primary brand color */
--primary-600: #1E88E5;
--primary-700: #1976D2;
--primary-800: #1565C0;
--primary-900: #0D47A1;  /* Darkest blue */

Semantic Colors:

--success: #4CAF50;   /* Green for positive changes */
--warning: #FF9800;   /* Orange for warnings */
--error: #F44336;     /* Red for errors/negative changes */
--info: #2196F3;      /* Blue for informational */

Neutral Palette:

--gray-50:  #FAFAFA;
--gray-100: #F5F5F5;
--gray-200: #EEEEEE;
--gray-300: #E0E0E0;
--gray-400: #BDBDBD;
--gray-500: #9E9E9E;
--gray-600: #757575;
--gray-700: #616161;
--gray-800: #424242;
--gray-900: #212121;

Dark Mode:

--bg-primary: #121212;
--bg-secondary: #1E1E1E;
--bg-tertiary: #2C2C2C;
--text-primary: #FFFFFF;
--text-secondary: #B0B0B0;
--text-tertiary: #808080;

---

Typography

Font Family:

--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', monospace;

Font Sizes:

--text-xs:   12px;  /* Small labels */
--text-sm:   14px;  /* Body text, buttons */
--text-base: 16px;  /* Default body */
--text-lg:   18px;  /* Subheadings */
--text-xl:   20px;  /* Headings */
--text-2xl:  24px;  /* Large headings */
--text-3xl:  30px;  /* Hero text */

Font Weights:

--font-normal: 400;
--font-medium: 500;
--font-semibold: 600;
--font-bold: 700;

Line Heights:

--leading-tight: 1.25;
--leading-normal: 1.5;
--leading-relaxed: 1.75;

---

Spacing

Spacing Scale (8px base):

--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 20px;
--space-6: 24px;
--space-8: 32px;
--space-10: 40px;
--space-12: 48px;
--space-16: 64px;

Component Spacing:

• Header padding: --space-4 (16px)
• Card padding: --space-4 (16px)
• Button padding: --space-3 horizontal, --space-2 vertical
• Input padding: --space-3 (12px)
• Gap between elements: --space-3 (12px)

---

Border Radius

--radius-sm: 4px;   /* Small elements (badges) */
--radius-md: 8px;   /* Buttons, inputs */
--radius-lg: 12px;  /* Cards */
--radius-xl: 16px;  /* Modals */
--radius-full: 9999px; /* Pills, avatars */

---

Shadows

--shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
--shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1);

---

Component Library

⚠️ TODO: Create reusable component specs for all UI elements.

Button

Variants:

• Primary: Filled with primary color
• Secondary: Outlined with primary color
• Ghost: Text-only, no background
• Danger: Filled with error color

Sizes:

• Small: 32px height, 12px padding
• Medium: 40px height, 16px padding
• Large: 48px height, 20px padding

States:

• Default: Normal state
• Hover: Darken background by 10%
• Active: Darken background by 20%
• Disabled: 50% opacity, no pointer events
• Loading: Show spinner, disable interaction

Example:

<Button variant="primary" size="medium" loading={false}>
  Is this safe?
</Button>

---

Input Field

Variants:

• Text: Single-line text input
• Textarea: Multi-line text input
• Search: Text input with search icon

States:

• Default: Border gray-300
• Focus: Border primary-500, shadow
• Error: Border error, show error message
• Disabled: Background gray-100, no interaction

Example:

<Input
  placeholder="Type your message..."
  error="Please enter a message"
  disabled={false}
/>

---

Card

Variants:

• Default: White background, shadow-md
• Outlined: Border gray-300, no shadow
• Elevated: shadow-lg

Padding:

• Default: 16px (--space-4)
• Compact: 12px (--space-3)
• Spacious: 24px (--space-6)

Example:

<Card variant="elevated" padding="default">
  <CardHeader>Token Info</CardHeader>
  <CardBody>...</CardBody>
</Card>

---

Toast Notification

Variants:

• Success: Green background, checkmark icon
• Error: Red background, error icon
• Info: Blue background, info icon
• Warning: Orange background, warning icon

Position:

• Top-right (default)
• Bottom-right
• Top-center

Duration:

• Default: 3 seconds
• Persistent: Manual dismiss

Example:

<Toast variant="success" duration={3000}>
  Page saved successfully!
</Toast>

---

Interaction Patterns

Loading States

Skeleton Screens:

• Use for initial page load
• Animate shimmer effect (left to right)
• Match layout of actual content

Spinners:

• Use for button actions (e.g., "Saving...")
• Use for inline loading (e.g., "Loading chat history...")

Progress Bars:

• Use for file uploads
• Use for multi-step processes

---

Micro-Animations

Hover Effects:

• Buttons: Scale 1.02, darken background
• Cards: Lift with shadow-lg
• Links: Underline on hover

Click Effects:

• Ripple effect on buttons
• Scale down to 0.98 on active

Transitions:

• Duration: 200ms (default)
• Easing: ease-in-out

---

Keyboard Shortcuts

Global:

• Cmd/Ctrl + K: Focus chat input
• Cmd/Ctrl + S: Save current page
• Esc: Close modals, clear input

Chat:

• Enter: Send message
• Shift + Enter: New line
• ↑: Edit last message
• ↓: Navigate message history

---

Accessibility

WCAG 2.1 AA Compliance

Color Contrast:

• Text on background: Minimum 4.5:1 ratio
• Large text (18px+): Minimum 3:1 ratio
• Interactive elements: Minimum 3:1 ratio

Keyboard Navigation:

• All interactive elements focusable
• Visible focus indicators (2px outline)
• Logical tab order

Screen Readers:

• Semantic HTML (header, nav, main, footer)
• ARIA labels for icons and buttons
• ARIA live regions for dynamic content

Motion:

• Respect prefers-reduced-motion
• Disable animations if user prefers

---

Implementation Notes

Responsive Behavior

Side Panel Width:

• Default: 400px
• Minimum: 300px
• Maximum: 600px
• User can resize by dragging edge

Breakpoints:

• Small screens (<1280px): Default 300px width
• Medium screens (1280-1920px): Default 400px width
• Large screens (>1920px): Default 500px width

---

Performance Considerations

Loading States:

• Show skeleton screens within 100ms
• Stream chat responses (don't wait for full response)
• Lazy load images in chat history

Caching:

• Cache token data for 5 minutes
• Cache chat history locally (Plasmo Storage)
• Prefetch user settings on login

Debouncing:

• Settings sync: Debounce 2 seconds after user action
• Search input: Debounce 300ms

---

Error Handling

Network Errors:

• Show "Offline" indicator in header
• Queue actions for retry when online
• Clear error message with retry button

API Errors:

• Show inline error message
• Provide actionable guidance (e.g., "Try again" button)
• Log errors to backend for monitoring

Validation Errors:

• Show inline error message below input
• Highlight invalid fields with red border
• Prevent form submission until valid

---

Next Steps

Immediate Actions (Week 1)

1. Create Wireframes (3 days)

   • Main Chat Interface
   • Welcome Screen
   • Token Info Card
   • Settings Dropdown
   • Quick Capture Modal

2. Define Design System (2 days)

   • Finalize color palette
   • Choose typography (confirm Inter font)
   • Define spacing scale
   • Create shadow/elevation system

3. Build Component Library (2 days)

   • Button component
   • Input component
   • Card component
   • Toast component
   • Modal component

Follow-up Actions (Week 2)

4. Create User Flows (2 days)

   • Onboarding flow (detailed)
   • Chat flow (detailed)
   • Quick Capture flow (detailed)

5. Prototype in Figma (3 days)

   • High-fidelity mockups
   • Interactive prototype
   • Handoff to developers

6. Accessibility Audit (1 day)

   • Color contrast check
   • Keyboard navigation test
   • Screen reader test

---

Approval & Sign-off

Stakeholders:

• UX Designer: _______________ (Date: _______)
• Product Manager: _______________ (Date: _______)
• Tech Lead: _______________ (Date: _______)

Status: 🚧 DRAFT - Awaiting wireframes and design system completion

---

Document Version History:

• v1.0 (2026-02-02): Initial outline created