UX Vision
Document-First Interface, Not Chat-First
Core Insight
"We want to feel as less as possible as a chat interface. Instead we speak through text rewriting and generation in MD files."
Spec Doc is NOT ChatGPT for specs. Spec Doc IS Cursor for specs — you work in the document, AI assists.
What We're NOT Building
❌ Chat-First (Like ChatGPT)
┌─────────────────────────────────────┐
│ 💬 Chat History (80% of screen) │
│ You: Create epic... │
│ AI: [3000 words] │
│ You: Add rate limiting │
│ AI: [2000 words] │
│ [Endless scrolling, lost context] │
├─────────────────────────────────────┤
│ Type message... [→] │
└─────────────────────────────────────┘
Problems: Chat dominates, document buried, verbose, loses context.
What WE ARE Building
✅ Document-First (Like Cursor + Notion AI)
┌────────────────────────────────────────────┐
│ 📁 Projects / My Spec / Epic [v12] │
├────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────┐ │
│ │ # Epic: User Authentication │ │
│ │ │ │
│ │ ## Overview │ │
│ │ JWT-based auth with refresh tokens │ │
│ │ │ │
│ │ ## Requirements │ │
│ │ - Email/password registration │ │
│ │ - Login with JWT (15min/7day) │ │
│ │ │ │
│ │ [Beautiful Markdown rendering] │ │
│ └──────────────────────────────────────┘ │
│ │
├────────────────────────────────────────────┤
│ 💬 Add rate limiting section [→] │
└────────────────────────────────────────────┘
↑ Small input (5% of screen)
Features:
- Document: 95% of screen
- AI input: 5%
- Direct editing is primary
- AI updates document silently
- Feels like Cursor, not ChatGPT
Interface Comparison
| Aspect | ChatGPT | Spec Doc |
|---|---|---|
| Primary UI | Chat | Document |
| Screen Space | Chat 80%, Doc 20% | Doc 95%, Input 5% |
| Interaction | Type messages | Edit + commands |
| AI Response | Verbose | Silent edits |
| Context | Lost after 50 msgs | Always visible |
| Feel | Consumer chatbot | Professional tool |
Two Interaction Modes
Mode 1: Direct Editing (Primary)
User clicks, types, edits. AI: passive (inline suggestions, autocomplete).
User types: "## Rate Limiting"
AI suggests: "### Rules"
User accepts → AI generates section
Mode 2: AI Commands (Secondary)
User types command in small input. AI: active (executes, updates silently).
User: "Add security considerations section"
[Document updates]
[Toast]: "✓ Added security section"
No chat response. Just document update.
Workflow Comparison
Chat-First (Old):
Type → Wait → Read → Copy → Paste → Repeat
Document-First (New):
Edit → Command → Document updates → Continue
10x faster iteration.
Design Principles
- Document First, Chat Second - 95% doc, 5% input
- Silent Execution - AI updates document, no verbose responses
- Direct Manipulation - Click to edit (primary), command to generate (secondary)
- Professional Aesthetics - Typography like Docusaurus, minimal like Linear
- Fast Iteration - No copy/paste, no scroll fatigue
Success Criteria
User should say:
- ✅ "This feels like Cursor, but for specs"
- ✅ "I'm editing the document, not chatting"
- ✅ "AI helps me write, doesn't write for me"
User should NOT say:
- ❌ "This is just ChatGPT with better export"
- ❌ "Why is there so much chat scrolling?"
The Fundamental Shift
| Old | New |
|---|---|
| "I'm chatting with AI to create specs" | "I'm writing specs, AI is my copilot" |
| Type → Wait → Read → Copy → Paste | Edit → Command → Continue |
| ChatGPT (consumer) | Cursor (professional) |
This is the UX that will win. 🚀