SurfSense/_bmad-output/ux-design/extension-ux-design.md
API Test Bot e4d020799b feat(crypto): add SurfSense 2.0 Crypto Co-Pilot UI components
Frontend - Web Dashboard:
- Add crypto dashboard page with Watchlist, Alerts, Market, Profile tabs
- Add 11 tool-ui components for inline chat display
- Add crypto components (ChainIcon, SafetyBadge, PriceDisplay, etc.)
- Add modals (AddTokenModal, CreateAlertModal)
- Add mock data for development

Frontend - Browser Extension:
- Add shared components (ChainIcon, RiskBadge, PriceDisplay, SuggestionCard)
- Add crypto components (SafetyScoreDisplay, WatchlistPanel, AlertConfigModal)
- Add chat enhancements (WelcomeScreen, ThinkingStepsDisplay)
- Add widget components for inline display
- Enhance TokenInfoCard, ChatHeader, ChatInput, ChatInterface

Documentation:
- Add conversational UX specification
- Add UX analysis report
- Update extension UX design

This implements the Conversational UX paradigm where crypto features
are AI-callable tools that render inline in the chat interface.
2026-02-04 02:19:57 +07:00

1239 lines
48 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# SurfSense 2.0 Chrome Extension - UX Design Document
**Version:** 3.0 (Conversational UX Update)
**Date:** 2026-02-02
**Status:** ✅ COMPLETE
**Owner:** UX Designer (Sally)
---
## ⚠️ IMPORTANT: Conversational UX Paradigm Shift
> **This document has been updated to reflect the new Conversational AI approach.**
>
> **Key Change:** SurfSense is now a **conversational AI crypto advisor** where chat is the PRIMARY interface. All crypto features (watchlist, alerts, portfolio, analysis) are accessible through natural language commands and embedded as widgets within the chat experience.
>
> **See:** `_bmad-output/ux-design/conversational-ux-specification.md` for the complete Conversational UX Specification.
---
## Document Purpose
This UX Design Document provides comprehensive design guidance for the SurfSense 2.0 Chrome Extension - AI Co-Pilot for Crypto. It covers:
- **Conversational Interface** - Chat as the primary interaction method
- **Embedded Widgets** - Token analysis, watchlist, alerts displayed inline in chat
- **AI Tool Calling** - Natural language commands that trigger backend tools
- **Proactive Monitoring** - AI-initiated alerts and recommendations
- **Design system** (colors, typography, spacing, components)
- **Interaction patterns** and micro-animations
**Target Audience:** Developers, Product Managers, QA Engineers
> 📌 **Related Documents:**
> - `_bmad-output/ux-design/conversational-ux-specification.md` - Complete Conversational UX Spec
> - `_bmad-output/planning-artifacts/prd.md` - Product Requirements
---
## Table of Contents
1. [Design Principles](#design-principles)
2. [Conversational UX Architecture](#conversational-ux-architecture) ⭐ NEW
3. [Information Architecture](#information-architecture)
4. [User Flows](#user-flows)
5. [Wireframes](#wireframes)
6. [Embedded Widget Components](#embedded-widget-components) ⭐ NEW
7. [Design System](#design-system)
8. [Component Library](#component-library)
9. [Interaction Patterns](#interaction-patterns)
10. [Accessibility](#accessibility)
11. [Implementation Notes](#implementation-notes)
---
## Design Principles
### 1. **Conversation-First Interface** ⭐ UPDATED
- **Chat is the PRIMARY interface** - all features accessible via natural language
- AI understands context without explicit input (page detection, portfolio awareness)
- Users interact through conversation, not navigation between screens
- **Example:** "Add BULLA to watchlist" instead of clicking through menus
### 2. **AI as Proactive Advisor** ⭐ UPDATED
- AI doesn't just respond - it **anticipates user needs**
- Proactive alerts based on portfolio, watchlist, and market conditions
- Personalized recommendations based on user's risk profile
- **Example:** AI alerts user when a watched token shows unusual activity
### 3. **Embedded Widgets in Chat** ⭐ NEW
- Crypto data displayed as **interactive widgets within chat messages**
- Widgets have inline action buttons (Add to Watchlist, Set Alert)
- No separate screens for Watchlist, Alerts, Portfolio - all embedded in chat
- **Example:** Token analysis appears as a rich card with action buttons
### 4. **Context-Aware Intelligence**
- AI understands 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
- **Auto-detect tokens** on supported sites and pre-populate context
### 5. **Speed & Efficiency**
- Quick access to AI insights (natural language commands)
- Keyboard shortcuts for power users
- Instant feedback for all interactions
- **Target: <1s token detection, <2s AI response start**
### 6. **Trust & Transparency**
- Clear indication of AI reasoning (thinking steps)
- Explicit data sources and confidence levels
- Easy to verify AI suggestions
- **Safety scores with detailed breakdown**
---
## Conversational UX Architecture ⭐ NEW
> **Core Principle:** Chat is the primary interface. All crypto features are accessible through natural language and displayed as embedded widgets within the conversation.
### Interaction Model
```
┌─────────────────────────────────────────────────────────────────┐
│ CONVERSATIONAL INTERFACE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ USER INPUT (Natural Language) │
│ ├── "Research BULLA token" │
│ ├── "Add to my watchlist" │
│ ├── "Set alert if price drops 20%" │
│ └── "Show my portfolio" │
│ │
│ ↓ │
│ │
│ AI PROCESSING │
│ ├── Intent Recognition │
│ ├── Context Injection (portfolio, watchlist, risk profile) │
│ ├── Tool Calling (DexScreener, Safety Check, etc.) │
│ └── Response Generation │
│ │
│ ↓ │
│ │
│ EMBEDDED WIDGET RESPONSE │
│ ├── TokenAnalysisCard (price, safety, metrics) │
│ ├── WatchlistWidget (inline list with actions) │
│ ├── AlertWidget (confirmation with edit options) │
│ └── ActionConfirmation (success/failure feedback) │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Natural Language Commands
| User Says | AI Action | Widget Displayed |
|-----------|-----------|------------------|
| "Research BULLA" | Call DexScreener + Safety Check | TokenAnalysisCard |
| "Is this safe?" | Call Safety Analysis | SafetyScoreWidget |
| "Add to watchlist" | Execute add_to_watchlist tool | ActionConfirmation |
| "Set price alert at $0.001" | Execute set_alert tool | AlertWidget |
| "Show my watchlist" | Fetch user's watchlist | WatchlistWidget |
| "What's trending on Solana?" | Call trending tokens API | TrendingTokensWidget |
| "Analyze my portfolio" | Fetch portfolio + analysis | PortfolioWidget |
### Widget Types
1. **TokenAnalysisCard** - Full token analysis with price, safety, metrics
2. **SafetyScoreWidget** - Detailed safety breakdown with risk factors
3. **WatchlistWidget** - Inline watchlist with quick actions
4. **AlertWidget** - Alert configuration/confirmation
5. **ActionConfirmation** - Success/failure feedback for actions
6. **TrendingTokensWidget** - List of trending tokens
7. **PortfolioWidget** - Portfolio summary with P&L
8. **ProactiveAlertCard** - AI-initiated alerts (price changes, whale activity)
### Action Types
| Type | Description | Example | Requires Confirmation |
|------|-------------|---------|----------------------|
| **Immediate** | Safe actions, auto-execute | Add to watchlist | No |
| **Confirmation** | Potentially destructive | Clear all alerts | Yes |
| **Advisory** | AI suggests, never executes | "Consider selling" | N/A (info only) |
---
## Information Architecture ⭐ UPDATED
```
Side Panel (400px width) - CONVERSATIONAL INTERFACE
├── Header (56px)
│ ├── Logo + Brand
│ ├── Search Space Selector
│ └── Settings Menu
├── Page Context Bar (conditional, 48px) ⭐ SIMPLIFIED
│ ├── Detected Token: "BULLA/SOL on DexScreener"
│ └── Quick Actions: [Analyze] [Watchlist] [Alert]
├── Chat Area (flex-grow) ⭐ PRIMARY INTERFACE
│ ├── Welcome State (suggestions)
│ ├── Messages List
│ │ ├── User Messages
│ │ ├── AI Messages with Embedded Widgets
│ │ │ ├── TokenAnalysisCard
│ │ │ ├── SafetyScoreWidget
│ │ │ ├── WatchlistWidget
│ │ │ ├── AlertWidget
│ │ │ └── ActionConfirmation
│ │ └── Proactive Alert Cards
│ └── Thinking Steps (collapsible)
├── Suggestion Chips (40px)
│ └── Context-aware quick actions
├── Input Area (80px)
│ ├── Text Input
│ └── Send Button
└── Quick Capture (48px sticky)
```
**Key Changes from v2.0:**
- Removed: Separate Watchlist Panel, Alert Configuration Modal, Portfolio Page
- Added: Embedded widgets in chat, Proactive Alert Cards, Suggestion Chips
- Simplified: Page Context Bar (just shows detected token + quick actions)
---
## User Flows ⭐ UPDATED FOR CONVERSATIONAL UX
### Flow 1: First-Time User Onboarding
```mermaid
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 - Chat Interface]
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: Token Research via Conversation ⭐ UPDATED
```mermaid
flowchart TD
A[User visits DexScreener] --> B{Extension detects token}
B -->|Yes| C[Show Page Context Bar]
B -->|No| D[Show default chat]
C --> E{User interaction}
E -->|Click 'Analyze'| F[AI: "Analyzing BULLA..."]
E -->|Type "Is this safe?"| F
E -->|Type "Research this token"| F
F --> G[Show thinking steps in chat]
G --> H[Display TokenAnalysisCard widget]
H --> I{User says/clicks}
I -->|"Add to watchlist"| J[AI executes action]
I -->|"Set alert at +50%"| K[AI executes action]
I -->|"Tell me more about holders"| L[AI continues analysis]
J --> M[ActionConfirmation widget]
K --> N[AlertWidget in chat]
L --> O[HolderAnalysisWidget]
```
**Key Difference from v2.0:**
- Old: Click button Open modal Fill form Save
- New: Say "add to watchlist" AI executes Confirmation in chat
**Success Criteria:**
- Token detection happens in <1 second
- User can complete any action via natural language
- All results displayed as embedded widgets in chat
---
### Flow 3: Proactive Alert Flow ⭐ NEW
```mermaid
flowchart TD
A[Background Monitor] --> B{Trigger detected}
B -->|Price change| C[Evaluate against user alerts]
B -->|Whale activity| D[Check if user watches token]
B -->|Safety change| E[Check user's watchlist]
C --> F{User has alert?}
D --> F
E --> F
F -->|Yes| G[Context Engine]
F -->|No| H[Ignore]
G --> I[AI Personalizer]
I --> J[Generate contextual message]
J --> K[Display ProactiveAlertCard in chat]
K --> L{User response}
L -->|"Tell me more"| M[AI provides details]
L -->|"Dismiss"| N[Mark as read]
L -->|"Sell recommendation?"| O[AI gives advisory]
```
**Example Proactive Alert:**
```
🔔 AI: "Heads up! BULLA just pumped +45% in the last hour.
You have 500K tokens worth ~$6,200 now.
Based on your moderate risk profile, you might want to
consider taking some profits.
[View Details] [Set New Alert] [Dismiss]"
```
---
### Flow 4: Quick Capture Page
```mermaid
flowchart TD
A[User clicks Save Page] --> B{Logged in?}
B -->|No| C[Show login prompt]
B -->|Yes| D[Show Search Space selector]
C --> E[OAuth login]
E --> D
D --> F[User selects space]
F --> G[Capture page content]
G --> H[Extract metadata]
H --> I[Upload to backend]
I --> J{Success?}
J -->|Yes| K[Show success toast]
J -->|No| L[Show error + retry]
K --> M[Page saved to knowledge base]
```
**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 ⭐ UPDATED FOR CONVERSATIONAL UX
> **Key Change:** All wireframes now show embedded widgets within the chat interface, not separate screens.
### 1. Main Chat Interface with Page Context Bar
```
┌─────────────────────────────────────────┐
│ 🌊 SurfSense [Crypto ▼] [⚙️] [👤]│
├─────────────────────────────────────────┤
│ 📍 BULLA/SOL on DexScreener │
│ $0.00001234 (+156%) [Analyze][Watch]│
├─────────────────────────────────────────┤
│ │
│ Good morning, Alex! 🌊 │
│ │
│ I see you're looking at BULLA. │
│ Want me to analyze it for you? │
│ │
│ 💡 Quick actions: │
│ ┌─────────────────────────────────┐ │
│ │ "Is this token safe?" │ │
│ └─────────────────────────────────┘ │
│ ┌─────────────────────────────────┐ │
│ │ "Add to my watchlist" │ │
│ └─────────────────────────────────┘ │
│ ┌─────────────────────────────────┐ │
│ │ "Show trending on Solana" │ │
│ └─────────────────────────────────┘ │
│ │
├─────────────────────────────────────────┤
│ [What's trending?][My watchlist][Alerts]│
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │ Ask anything about crypto... [→] │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│ 📸 Save this page to knowledge base │
└─────────────────────────────────────────┘
```
**Components:**
- **Page Context Bar**: Shows detected token with quick actions
- **AI Greeting**: Context-aware welcome message
- **Suggestion Chips**: Clickable quick actions
- **Chat Input**: Natural language input
---
### 2. Token Analysis as Embedded Widget
```
┌─────────────────────────────────────────┐
│ 🌊 SurfSense [Crypto ▼] [⚙️] [👤]│
├─────────────────────────────────────────┤
│ 📍 BULLA/SOL on DexScreener │
├─────────────────────────────────────────┤
│ │
│ 👤 You: Is this token safe? │
│ │
│ 🧠 AI: Analyzing BULLA on Solana... │
│ ┌─────────────────────────────────┐ │
│ │ 🔍 Fetching price data... │ │
│ │ 🛡️ Running safety analysis... │ │
│ │ 👥 Checking holder distribution │ │
│ └─────────────────────────────────┘ │
│ │
│ 🧠 AI: Here's my analysis of BULLA: │
│ ┌─────────────────────────────────────┐│
│ │ 📊 TokenAnalysisCard ││
│ │ ───────────────────────────────── ││
│ │ 🪙 BULLA/SOL ││
│ │ $0.00001234 ▲ +156.7% (24h) ││
│ │ ││
│ │ Vol: $1.2M | Liq: $450K | MC: $2.1M││
│ │ ││
│ │ 🛡️ Safety: 🟡 65/100 (Medium Risk) ││
│ │ ████████░░ ││
│ │ ││
│ │ ✅ LP locked 6 months ││
│ │ ✅ No mint authority ││
│ │ ⚠️ Top 10 hold 45% ││
│ │ 🔴 Similar to known rugs ││
│ │ ││
│ │ [ Watchlist] [🔔 Alert] [📊 More]││
│ └─────────────────────────────────────┘│
│ │
│ Based on your moderate risk profile, │
│ I'd suggest a small position (2-5%). │
│ Want me to add it to your watchlist? │
│ │
├─────────────────────────────────────────┤
│ [Add to watchlist][Set alert][More info]│
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │ Ask follow-up question... [→] │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘
```
**Key Features:**
- **Thinking Steps**: Collapsible, shows AI's process
- **TokenAnalysisCard Widget**: Embedded in chat message
- **Inline Action Buttons**: Add to watchlist, Set alert directly from widget
- **Personalized Recommendation**: Based on user's risk profile
- **Suggestion Chips**: Context-aware follow-up actions
---
### 3. Safety Analysis Response
```
┌─────────────────────────────────────────┐
│ [AI] 🛡️ Safety Analysis: BULLA/SOL │
│ │
│ ┌─────────────────────────────────────┐│
│ │ Overall Risk Score: 🟡 MEDIUM ││
│ │ ████████░░ 65/100 ││
│ └─────────────────────────────────────┘│
│ │
│ ✅ Positive Signals: │
│ • Contract verified on Solscan │
│ • No mint authority (can't create more)│
│ • LP locked for 6 months │
│ │
│ ⚠️ Warning Signs: │
│ • Top 10 holders own 45% of supply │
│ • Token is only 3 days old │
│ • Low social media presence │
│ │
│ 🔴 Red Flags: │
│ • Similar contract to known rug pulls │
│ │
│ 📊 Holder Distribution: │
│ ┌─────────────────────────────────────┐│
│ │ Top 10: ████████░░ 45% ││
│ │ Top 50: ██████████████░░ 72% ││
│ │ Others: ██████░░░░░░░░░░ 28% ││
│ └─────────────────────────────────────┘│
│ │
│ 💡 Recommendation: │
│ Proceed with caution. Consider small │
│ position size due to concentration │
│ risk and young token age. │
│ │
│ Sources: Solscan, DexScreener, RugCheck│
│ │
│ [📋 Add to Watchlist] [🔔 Set Alert] │
└─────────────────────────────────────────┘
```
**Risk Score Colors:**
- 0-30: 🔴 High Risk (red)
- 31-60: <EFBFBD> Medium Risk (yellow)
- 61-80: 🟢 Low Risk (green)
- 81-100: Very Safe (bright green)
---
### 4. Watchlist Panel
```
┌─────────────────────────────────────────┐
│ 🌊 SurfSense [📋 Watchlist] [⚙️] [👤] │
├─────────────────────────────────────────┤
│ My Watchlist [+ Add] │
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │ 🪙 BULLA/SOL ▲ +156.7% │ │
│ │ $0.00001234 Vol: $1.2M │ │
│ │ 🔔 Alert: Price > $0.00002 │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ 🪙 PEPE/ETH ▼ -12.3% │ │
│ │ $0.00000891 Vol: $45M │ │
│ │ 🔔 Alert: Volume spike detected │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ 🪙 WIF/SOL ▲ +8.2% │ │
│ │ $2.34 Vol: $89M │ │
│ │ ✓ No active alerts │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│ Recent Alerts │
├─────────────────────────────────────────┤
│ 🔴 2m ago: BULLA whale sold 5% supply │
│ 🟡 15m ago: PEPE unusual volume spike │
│ 🟢 1h ago: WIF hit price target $2.30 │
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │ Ask about your watchlist... [📎][→]│ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘
```
---
### 5. Alert Configuration Modal
```
┌─────────────────────────────────────────┐
│ 🔔 Configure Alert for BULLA/SOL [×]│
├─────────────────────────────────────────┤
│ │
│ Alert Type: │
│ ┌─────────────────────────────────────┐ │
│ │ ○ Price reaches │ │
│ │ ○ Price change % (24h) │ │
│ │ ● Volume spike │ │
│ │ ○ Whale movement │ │
│ │ ○ Liquidity change │ │
│ │ ○ New holder concentration │ │
│ └─────────────────────────────────────┘ │
│ │
│ Condition: │
│ ┌─────────────────────────────────────┐ │
│ │ Volume increases by [ 200 ] % │ │
│ │ within [ 1 hour ▼ ] │ │
│ └─────────────────────────────────────┘ │
│ │
│ Notification: │
│ ☑ Browser notification │
│ ☑ Email alert │
│ ☐ Telegram (connect in settings) │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ 💾 Save Alert │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────┘
```
**Alert Types:**
- Price reaches target
- Price change % (24h)
- Volume spike
- Whale movement (large transactions)
- Liquidity change
- Holder concentration change
---
### 6. 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)
---
### 7. 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
│ 📋 Manage Watchlist │ ← Link to web
│ 🔔 Alert History │ ← 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:**
```css
--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:**
```css
--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:**
```css
--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:**
```css
--bg-primary: #121212;
--bg-secondary: #1E1E1E;
--bg-tertiary: #2C2C2C;
--text-primary: #FFFFFF;
--text-secondary: #B0B0B0;
--text-tertiary: #808080;
```
---
### Typography
**Font Family:**
```css
--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', monospace;
```
**Font Sizes:**
```css
--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:**
```css
--font-normal: 400;
--font-medium: 500;
--font-semibold: 600;
--font-bold: 700;
```
**Line Heights:**
```css
--leading-tight: 1.25;
--leading-normal: 1.5;
--leading-relaxed: 1.75;
```
---
### Spacing
**Spacing Scale (8px base):**
```css
--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
```css
--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
```css
--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:**
```tsx
<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:**
```tsx
<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:**
```tsx
<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:**
```tsx
<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:**
- [x] UX Designer: Augment Agent (Date: 2026-02-02)
- [ ] Product Manager: _______________ (Date: _______)
- [ ] Tech Lead: _______________ (Date: _______)
**Status:** ✅ COMPLETE - Ready for developer handoff
---
**Document Version History:**
- v3.0 (2026-02-02): **Conversational UX Update** - Major paradigm shift to chat-first interface with embedded widgets
- v2.0 (2026-02-02): Complete UX design with wireframes, user flows, and crypto features
- v1.0 (2026-02-02): Initial outline created
---
## Appendix: Conversational UX Wireframes (v3.0)
> **Note:** These wireframes replace the isolated component designs in sections 3-5 above. The new approach embeds all crypto features as widgets within the chat interface.
### A1. Action Confirmation Widget
```
┌─────────────────────────────────────────┐
│ │
│ 👤 You: Add it to my watchlist │
│ │
│ 🧠 AI: Done! │
│ ┌─────────────────────────────────────┐│
│ │ ActionConfirmation ││
│ │ ───────────────────────────────── ││
│ │ BULLA added to your watchlist ││
│ │ ││
│ │ I've also set up default alerts: ││
│ │ - Price change +/-20% ││
│ │ - Liquidity drop >10% ││
│ │ - Whale movement >$50K ││
│ │ ││
│ │ [View Watchlist] [Edit Alerts] ││
│ └─────────────────────────────────────┘│
│ │
│ Anything else you'd like to know │
│ about BULLA or other tokens? │
│ │
├─────────────────────────────────────────┤
│ [Show watchlist][Research another token]│
└─────────────────────────────────────────┘
```
---
### A2. Watchlist Widget (Embedded in Chat)
```
┌─────────────────────────────────────────┐
│ │
│ 👤 You: Show my watchlist │
│ │
│ 🧠 AI: Here's your watchlist: │
│ ┌─────────────────────────────────────┐│
│ │ WatchlistWidget ││
│ │ ───────────────────────────────── ││
│ │ BULLA/SOL +156.7% ││
│ │ $0.00001234 3 alerts ││
│ │ [Analyze] [Remove] ││
│ │ ───────────────────────────────── ││
│ │ PEPE/ETH -12.3% ││
│ │ $0.00000891 1 alert ││
│ │ [Analyze] [Remove] ││
│ │ ───────────────────────────────── ││
│ │ WIF/SOL +8.2% ││
│ │ $2.34 No alerts ││
│ │ [Analyze] [Remove] ││
│ │ ───────────────────────────────── ││
│ │ Total: 3 tokens | [+ Add Token] ││
│ └─────────────────────────────────────┘│
│ │
│ BULLA is up 156% - your best performer!│
│ Want me to analyze if it's time to │
│ take profits? │
│ │
├─────────────────────────────────────────┤
│ [Analyze BULLA][Add token][Clear all] │
└─────────────────────────────────────────┘
```
**Key Difference from v2.0:**
- Old: Separate Watchlist Panel (navigation required)
- New: Watchlist displayed inline in chat when requested
---
### A3. Proactive Alert Card
```
┌─────────────────────────────────────────┐
│ │
│ AI Alert (just now) │
│ ┌─────────────────────────────────────┐│
│ │ ProactiveAlertCard ││
│ │ ───────────────────────────────── ││
│ │ BULLA just pumped +45% in 1 hour! ││
│ │ ││
│ │ Current: $0.00001789 ││
│ │ Your entry: $0.00000500 ││
│ │ Your P&L: +257% (~$3,200) ││
│ │ ││
│ │ Warning: Volume spike (5x avg) ││
│ │ Warning: Whale sold 2% of supply ││
│ │ ││
│ │ [View Details] [Set New Alert] ││
│ └─────────────────────────────────────┘│
│ │
│ Based on your moderate risk profile, │
│ you might want to consider taking │
│ some profits. This is just a │
│ suggestion - I won't execute trades. │
│ │
├─────────────────────────────────────────┤
│ [Tell me more][Dismiss][Set sell alert] │
└─────────────────────────────────────────┘
```
**Key Features:**
- **Proactive**: AI initiates the alert, not user
- **Contextual**: Shows user's position and P&L
- **Advisory**: Suggests action but doesn't execute
- **Actionable**: Quick follow-up options
---
### A4. Alert Configuration via Conversation
```
┌─────────────────────────────────────────┐
│ │
│ 👤 You: Set alert if BULLA drops 20% │
│ │
│ 🧠 AI: I'll set that up for you: │
│ ┌─────────────────────────────────────┐│
│ │ AlertWidget ││
│ │ ───────────────────────────────── ││
│ │ Alert Created ││
│ │ ││
│ │ Token: BULLA/SOL ││
│ │ Condition: Price drops 20% ││
│ │ Current: $0.00001234 ││
│ │ Trigger at: $0.00000987 ││
│ │ ││
│ │ Notify via: ││
│ │ [x] Browser notification ││
│ │ [x] In-app alert ││
│ │ [ ] Email (not configured) ││
│ │ ││
│ │ [Edit] [Delete] [Add Another] ││
│ └─────────────────────────────────────┘│
│ │
│ Done! I'll notify you if BULLA drops │
│ 20% from current price. Want to set │
│ any other alerts? │
│ │
├─────────────────────────────────────────┤
│ [View all alerts][Set another][Done] │
└─────────────────────────────────────────┘
```
**Key Difference from v2.0:**
- Old: Open modal -> Select type -> Fill form -> Save
- New: Say "set alert if drops 20%" -> AI creates -> Confirm in chat
---
### A5. Summary: v2.0 vs v3.0 Comparison
| Feature | v2.0 (Isolated Components) | v3.0 (Conversational) |
|---------|---------------------------|----------------------|
| **Watchlist** | Separate panel with navigation | Embedded widget in chat |
| **Alerts** | Modal form with dropdowns | Natural language command |
| **Token Analysis** | Context card + separate response | Embedded TokenAnalysisCard |
| **Portfolio** | Separate page | Inline PortfolioWidget |
| **User Interaction** | Click through menus | Type natural language |
| **AI Role** | Responds to queries | Proactively advises |
| **Actions** | Manual form submission | AI executes on command |