summary

BKB Mockup Summary

Feature: Brain Knowledge Base (BKB) Created: 2025-11-29 Reference: GitBook documentation UI

Mockup Files

File	Description	Variations
main-layout.txt	Three-column page layout	4 options + responsive
tree-sidebar.txt	Left navigation tree	5 options
feedback-widget.txt	”Was this helpful?” rating	6 options

Recommendations

Main Layout: Option A (GitBook-Style)

┌─────────────────────────────────────────────────────────────────────────────┐
│ TC Portal    [🔍 Search Brain...  ⌘K]                              User ▼   │
├──────────────────┬──────────────────────────────────────┬───────────────────┤
│ Tree Sidebar     │ Content Panel                        │ TOC + Feedback    │
│ (~250px)         │ (flexible, max 896px)                │ (~200px)          │
└──────────────────┴──────────────────────────────────────┴───────────────────┘

Why: Matches GitBook exactly - users expect this pattern for documentation.

GETTING STARTED       ← Section header (bold, uppercase)
📖 Documentation      ← Flat doc with icon
▼ GitHub Sync         ← Expanded folder
  ● Enabling Sync     ← Selected doc
    GitLab Sync

Why: Clear visual hierarchy, icons aid recognition, matches reference.

Was this helpful?
  😊  😐  😞

Why: Low friction, matches GitBook, optional comment expansion available.

Key Design Decisions

Phase 1 (MVP)

Single “Brain” content collection
Three-column layout
Section headers + expandable folders
TOC with scroll spy
Emoji feedback widget

Phase 2 (Future)

Top tabs for multiple content collections (Brain, API Docs, Guides, etc.)
Cross-tab search
Same layout per tab with different rootPath

Responsive Strategy

Desktop (1024px+): Full three-column
Tablet (768-1023px): Two-column, TOC as collapsible header
Mobile (<768px): Single column, tree as slide-in drawer

Open Questions

Section header detection: Use folder naming convention (e.g., “1. OVERVIEW” becomes header)?
- Recommendation: Yes - simple, no config needed
Icons in tree: Emoji vs SVG icons?
- Recommendation: SVG icons (more professional, customizable)
Feedback timing: Show after scroll threshold or always visible?
- Recommendation: Always visible in TOC panel (desktop), bottom of content (mobile)

Next Steps

Review mockups with stakeholders
Finalize any preference variations
Proceed to /speckit.plan for implementation planning
Consider /trilogy.mockup for interactive HTML mockups if needed