SurfSense/_bmad-output/planning-artifacts/ux-design-specification.md

stepsCompleted	inputDocuments
1 2 3 4 5 6 7 8	_bmad-output/planning-artifacts/prd.md _bmad-epics/epic-1-ai-powered-crypto-assistant.md _bmad-epics/epic-2-smart-monitoring-alerts.md _bmad-epics/epic-3-trading-intelligence.md _bmad-epics/epic-4-content-creation-productivity.md

UX Design Specification SurfSense

Author: Luis Date: 2026-02-02

---

Executive Summary

Project Vision

SurfSense 2.0 transforms from a general-purpose tool into a specialized AI Co-pilot for Crypto Traders. The core value proposition shifts from passive data aggregation to proactive intelligence—providing "Smart Monitoring," "Trading Intelligence," and "Content Creation" tools that work seamlessly alongside the trader's workflow.

Target Users

• Momentum Traders: Need real-time, "hot" information (Whale alerts, Volume spikes) to catch rapid price movements. They prioritize speed and accessibility (Extension).
• Cautious Investors: Prioritize safety and due diligence. They need tools to verify contracts, detect rug pulls, and analyze long-term metrics.
• Content Creators: Use the platform to generate insights and share them (charts, threads) to build their audience.

Key Design Challenges (Web-First)

• Data Density vs. Clarity: The new features (Portfolio, Market Intelligence) introduce complex data (charts, tables, metrics) that must be displayed without overwhelming the user, distinguishing this from the chat-heavy v1.
• Navigation Scalability: The current chat-centric sidebar is insufficient for a multi-module application. We must integrate new functional areas (Market, Portfolio, Alerts) without burying them or cluttering the interface.
• Hybrid Workflow: Users will constantly switch between "Deep Dive" analysis on the Web Dashboard and "Quick Checks" via the Extension. The experience must be consistent and synchronized.

Design Opportunities

• Hybrid Interface Structure: Transitioning the Web Dashboard from a purely "Chat UI" to a "Hybrid Interface" that balances App Modules (for data/tools) with the AI Assistant (for query/support). This allows distinct spaces for "doing" (Trading/Monitoring) and "asking" (Chat).
• Unified Design System: Leveraging the existing Web Design System (Tailwind/Shadcn) to rapidly build the Extension UI, ensuring a consistent look and feel while reducing development effort ($18K constraint).

Core User Experience

Defining Experience: "The Intel Layer"

SurfSense is not where users go to see price (they use DexScreener for that), but where they go to see The Truth. The defining interaction is an "Instant Reality Check": while the chart shows hype (FOMO), SurfSense overlays the cold, hard data (Risk/Whale movement), allowing users to verify a trade in seconds. It acts as the "Verify" step in the "Detect → Verify → Act" loop.

User Mental Model

• The Old Way: See price spike → Check Twitter (hype) → Search Contract (manual) → Check Holders → Panic/FOMO → Buy blindly.
• The SurfSense Way: See price spike → Glance at Extension (Traffic Light):
  • 🔴 Red: Ignore immediately (Rug/Honeypot). Time saved: 10 mins.
  • 🟢 Green: Trade with confidence.
  • 🟡 Yellow: "Investigate" → One click to open Web Dashboard for deep reasoning (Whale behavior, Fresh wallet movement).

Platform Strategy

• Web Dashboard (Master): The "Command Center" for Portfolio, Alert Management, and Deep Intelligence Analysis. Focuses on textual/numerical insights over graphical charts.
• Extension (Satellite): The "Tactical" tool for instant context. Smartly advises the user based on their current active tab using the "Symbiotic Side-Panel" pattern (lives alongside the chart, doesn't block it).

Experience Mechanics

1. Initiation: User navigates to a token on DexScreener/Twitter.
2. Interaction: Extension Badge updates color (Red/Green). User clicks for Summary Overlay.
3. Cross-Over: User clicks "Open Dashboard" for deep dive (if needed). Web App opens to the exact token context.
4. Completion: User executes trade on DexScreener (or bot) with full confidence.

Success Criteria

• Time-to-Truth < 5s: User determines safety (SCAM vs LEGIT) within 5 seconds of landing on a chart.
• "Savior" Frequency: User experiences a "saved me from a rug" moment at least once per week.
• Zero-Context Switching: User never manually copies a contract address; the system auto-detects context.

Novel UX Patterns

• "Evidence-First" AI: Insights are always coupled with proof (e.g., "Bullish because 3 whales bought" with links to txns), avoiding "Black Box" trust issues.
• Traffic Light Risk Coding: Universal color cues (Green=Safe, Yellow=Caution, Red=Danger) for Risk Scores allow scanning in < 1 second.

Desired Emotional Response

Primary Emotional Goals

• Confidence (Tự tin): Users feel they possess "Insider Intelligence" that others missing by relying solely on charts. The AI provides the "Why" behind the price action.
• Calm (Bình tĩnh): In a chaotic market (FOMO, rapid candles), SurfSense acts as a stabilizing anchor, providing "Cold Hard Data" (Risk Scores, On-chain metrics) to rationalize decision-making.
• Clarity (Sự rõ ràng): Cutting through the noise of social media and complex charts to show the simple truth about a token's safety and potential.

Emotional Journey Mapping

• Trigger (Alert): Urgency & Curiosity. "Whale Accumulating" alert sparks immediate interest but balanced with a need to know why.
• Action (Verify): Reassurance. Opening the dashboard confirms safety (Verified Contract) and validates the trend (AI Sentiment). Confusion turns into clarity.
• Result (Decision): Superiority & Relief. User feels smarter than the herd ("I avoided a rug pull" or "I caught a trend early").

UX Pattern Analysis & Inspiration

Inspiring Products Analysis

• DexScreener (Crypto): Excellent Data Density. They maximize screen real estate to show price, txns, and liquidity simultaneously without clutter. Inspiration: High-density layouts using color coding (Green/Red) to direct attention.
• GMGN.ai (Crypto): Strong Risk Visualization. They surface hidden risks (dev dumping, high holder concentration) prominently. Inspiration: "Warning Badges" and "Risk Clusters" that are impossible to ignore.
• Perplexity AI (Non-Crypto): Mastering Trust & Citations. Every AI claim is backed by a source link. Inspiration: SurfSense AI insights should link back to source data (e.g., "Whale bought" -> Link to Txn).
• Linear (Productivity): Keyboard-First Navigation and speed. Inspiration: Power user shortcuts (Cmd+K) for quick search and navigation between modules.

Key Takeaways

• Terminal-Style Efficiency: Use a dense, tabular view for the "Market Intelligence" module (Web Dashboard) to allow sorting/filtering of 50+ tokens instantly.
• No Chart, Just Intel: Don't replicate DexScreener. Provide the "Why" (Insights) behind the "What" (Price).

Design System Foundation

1.1 Design System Choice

Shadcn/UI + Tailwind CSS (Confirmed Existing Stack).

Rationale for Selection

• Consistency: The existing surfsense_web frontend already utilizes Tailwind CSS (v4) and Shadcn/UI components (Radix primitives). Maintaining this stack ensures zero friction between the current codebase and new v2 features.
• Inheritance: The Extension (Slave) will directly inherit color tokens and typography from the Web Dashboard's tailwind.config.js, ensuring a unified brand experience with minimal effort.

Implementation Approach

• Web-First Truth: The Web Dashboard remains the "Master" for design tokens and component definitions.
• Dark Mode Native: The system is already optimized for Dark Mode, which aligns perfectly with the crypto trading persona.
• Customization: Extend default Shadcn theme with "Signal Colors" (Neon Green, Alert Red) for financial data visualization.

Visual Design Foundation

Color System

• Core Palette (Inherited): Maintain established globals.css structure (OKLCH variables) for 100% implementation speed.
  • Background: oklch(0.145 0 0) (Dark Gray) for enterprise-grade stability.
  • Foreground: oklch(0.985 0 0) (White).
• Signal Colors (New): High-saturation "Neon" variants for "Traffic Light" indicators in Dark Mode.
  • 🟢 Success: oklch(0.6 0.18 145) (Neon Green) - Use for "Safe", "Verified", "Buy Signal".
  • 🔴 Danger: oklch(0.6 0.2 25) (Neon Red) - Use for "Scam", "Rug Risk", "Sell Signal".
  • 🟡 Warning: oklch(0.8 0.15 85) (Amber) - Use for "Caution", "Low Liquidity".

Typography System

• Primary Font: Geist Sans (Inherited).
  • Rationale: Optimized for Vercel/Next.js stack, zero layout shift, and includes excellent tabular figures for price data.
  • Usage: All UI text, headers, and especially data tables.
• Tone: Professional, direct, data-first. No decorative serifs.

Spacing & Layout Foundation

• Base Unit: 0.25rem (4px). Standard Tailwind grid.
• Radius: 0.625rem (Default) for cards/inputs to match existing Web UI.
• Density Strategy:
  • Extension: "Standard" density for touch/click friendliness.
  • Market Intelligence (Web): "Compact" density to maximize rows per screen (Terminal feel).

Accessibility Considerations

• High Contrast Signals: Prioritize distinctive colors for status indicators (Red/Green) but ensure they are accompanied by text/icon labels (not color-only) to support color-blind users.
• Dark Mode Optimization: Ensure text contrast remains high (AA standard) against the dark gray background.