design spec

Design Specification: Brain Knowledge Base

Feature: BKB - Brain Knowledge Base Initiative: TP-2141-Work-Management Created: 2025-11-29 Status: Draft Stakeholder Type: Internal Staff (power users) Design Approach: Balanced density - efficient for frequent documentation browsing with clear information hierarchy

Design Philosophy

This is an internal staff documentation tool following the established GitBook/Docus pattern. The design prioritizes:

Information efficiency: Staff browse docs frequently, so optimize for quick scanning and navigation
Familiar patterns: Follow established documentation UI conventions (no need to reinvent)
Power-user optimization: Keyboard shortcuts, persistent state, fast interactions
Accessibility: WCAG AA from the start
Component reuse: Leverage existing Storybook components and MDE editor

Not consumer-facing: This is not a marketing site. No emotional design, spacious layouts, or hand-holding needed. Staff expect professional, efficient tooling.

Layout Architecture

Desktop Layout (Primary)

┌──────────────────────────────────────────────────────────────────────────┐
│ Top Navigation Bar (existing portal nav)                                 │
├──────────┬────────────────────────────────────────────────┬──────────────┤
│          │                                                 │              │
│  Tree    │            Content Panel                        │  TOC Panel   │
│ Sidebar  │                                                 │              │
│          │  ┌──────────────────────────────────────────┐  │  On this page│
│  SEARCH  │  │                                           │  │  • Overview  │
│  ┌────┐  │  │  # Document Title                         │  │  • Setup     │
│  │🔍  │  │  │                                           │  │  • Config    │
│  └────┘  │  │  Rendered markdown content with           │  │    - Step 1  │
│          │  │  formatting, code blocks, lists,          │  │    - Step 2  │
│  BRAIN   │  │  images, etc.                             │  │  • Advanced  │
│  └─○ Welcome                                            │  │              │
│  ▼ 1. OVERVIEW                                           │  │  ─────────   │
│    ○ About                                               │  │  Helpful?    │
│    ○ Getting Started                                     │  │  😊 😐 😞    │
│  ▼ 2. PROCESSES                                          │  │              │
│    ▼ Workflows                                           │  │              │
│      ● Current Doc                                       │  │              │
│      ○ Step by Step                                      │  │              │
│          │  │                                           │  │              │
│          │  └──────────────────────────────────────────┘  │              │
│          │                                                 │              │
│  (~250px)│               (flexible)                        │   (~200px)   │
│          │                                                 │              │
└──────────┴────────────────────────────────────────────────┴──────────────┘

Panel Widths

Tree Sidebar: 250px fixed (resizable future enhancement)
TOC Panel: 200px fixed
Content Panel: Flexible (fills remaining space)
Min Content Width: 600px before horizontal scroll

Responsive Behavior

Tablet (768px - 1024px):

Hide TOC panel
Show TOC as collapsible section above content
Tree sidebar reduces to 200px or collapses to hamburger menu

Mobile (< 768px):

Full-width content
Tree sidebar as overlay (slide-in menu)
TOC as collapsible accordion above content
Search moves to top bar

Note: Desktop is primary target for internal staff. Mobile/tablet are secondary.

Visual Design System

Color Palette (from Trilogy Brand)

Interface Colors:

Background: bg-white dark:bg-slate-900
Panels: bg-slate-50 dark:bg-slate-800
Borders: border-slate-200 dark:border-slate-700
Text Primary: text-slate-900 dark:text-slate-100
Text Secondary: text-slate-600 dark:text-slate-400

Interactive Colors:

Links/Active: text-blue-600 dark:text-blue-400 (Trilogy Blue #4B7BBE)
Hover: bg-slate-100 dark:bg-slate-700
Selected: bg-blue-50 dark:bg-blue-900/20 border-l-4 border-blue-600

Accent Colors:

Teal: #43C0BE - secondary actions, icons
Navy: #2C4C79 - headers, emphasis
Red: #E04B51 - errors, delete actions only

Typography

From Trilogy Brand:

Headings: font-serif (Roboto Serif)
- H1: text-3xl font-bold (30px)
- H2: text-2xl font-semibold (24px)
- H3: text-xl font-semibold (20px)
- H4-H6: text-lg font-medium (18px, 16px, 14px)
Body: font-sans (Roboto Flex)
- Default: text-base (16px)
- Small: text-sm (14px)
- Tiny: text-xs (12px)

Code/Monospace:

Font: font-mono (system monospace)
Inline: bg-slate-100 dark:bg-slate-800 px-1.5 py-0.5 rounded text-sm
Blocks: Use MDE renderer styling

Spacing Scale (4px grid)

Tight: gap-1 (4px) - list items within tree
Default: gap-2 (8px) - form fields, button groups
Comfortable: gap-4 (16px) - section spacing
Spacious: gap-6 (24px) - panel padding
Generous: gap-8 (32px) - major section breaks

Component Inventory

Purpose: Hierarchical navigation of Brain folders and documents

Anatomy:

┌────────────────────┐
│ ┌──────────────┐   │ <- Search Input (sticky)
│ │🔍 Search...  │   │
│ └──────────────┘   │
│                    │
│ BRAIN              │ <- Root label (non-interactive)
│ └─○ Welcome        │ <- Document node (○ = unselected)
│ ▼ 1. OVERVIEW      │ <- Section header (expanded)
│   ○ About          │ <- Document node
│   ○ Getting Started│
│ ▼ 2. PROCESSES     │ <- Section header
│   ▼ Workflows      │ <- Folder (expanded)
│     ● Current Doc  │ <- Document node (● = selected)
│     ○ Another Doc  │
│   ▶ Templates      │ <- Folder (collapsed)
│ ▶ 3. REFERENCE     │ <- Section header (collapsed)
│                    │
│ + New Document     │ <- Action button (bottom sticky)
│ + New Folder       │
└────────────────────┘

Node Types:

Section Header (e.g., “1. OVERVIEW”)
- Non-navigable grouping label
- Bold uppercase text: text-xs font-bold uppercase text-slate-500 tracking-wide
- No hover state
- Collapsible arrow (▼/▶)
- Padding: py-2 px-3
Folder Node
- Expandable/collapsible
- Icon: 📁 or folder SVG icon
- Arrow indicator: ▶ collapsed, ▼ expanded
- Hover: bg-slate-100 dark:bg-slate-700 rounded
- Click: toggle expansion
- Indentation: pl-[depth * 16px] (16px per level)
Document Node
- Selectable
- Icon: ○ unselected, ● selected (or document SVG)
- Selected state: bg-blue-50 dark:bg-blue-900/20 border-l-4 border-blue-600 font-medium
- Hover: bg-slate-100 dark:bg-slate-700 rounded
- Click: navigate to document
- Indentation: pl-[depth * 16px + 16px] (offset from parent)

Interactions:

Click folder/section header: toggle expansion
Click document: navigate and highlight
Keyboard:
- Arrow keys: navigate up/down
- Enter: select document
- Right/Left: expand/collapse folders
- / or Ctrl+K: focus search

States:

Default: folders collapsed except path to current doc
Expanded: folder shows children
Loading: skeleton for tree structure
Empty: “No documents yet” message with “Create Document” button
Search active: filter tree, highlight matches

Technical Notes:

Use Reka UI Collapsible for expand/collapse
Persist expansion state in session storage
Lazy render children (virtualize if >100 items per level)

2. Search Input Component

Purpose: Full-text search across all Brain documents

Anatomy:

┌──────────────────────┐
│ 🔍 Search Brain...   │ <- Placeholder text
└──────────────────────┘
         ↓ (on input)
┌──────────────────────┐
│ 🔍 workflow          │ <- User typing
├──────────────────────┤
│ Search Results (3)   │ <- Dropdown
│ ────────────────────│
│ 📄 Approval Workflow │
│    2. PROCESSES      │ <- Breadcrumb
│ ────────────────────│
│ 📄 Workflow Guide    │
│    2. PROCESSES > Templates
│ ────────────────────│
│ 📄 Emergency Workflow│
│    3. REFERENCE      │
└──────────────────────┘

Placement: Sticky at top of tree sidebar

Styling:

Input: border border-slate-300 dark:border-slate-600 rounded-md px-3 py-2 text-sm
Icon: text-slate-400 positioned left inside input
Focus: ring-2 ring-blue-500

Dropdown Results:

Max height: max-h-96 overflow-y-auto
Result item: px-3 py-2 hover:bg-slate-100 dark:hover:bg-slate-700 cursor-pointer
Match highlighting: <mark> tag with bg-yellow-200 dark:bg-yellow-800
Empty state: “No documents found” with text-slate-500 text-center py-8

Interactions:

Type: debounced search (300ms)
Click result: navigate to document, expand tree to show location
Escape: close dropdown
Down/Up arrows: navigate results
Enter: select highlighted result

Technical Notes:

Use simple client-side filtering for MVP (backend search future enhancement)
Search document titles and content
Rank: title matches > content matches

3. Content Panel Component

Purpose: Display rendered markdown document content

Anatomy:

┌─────────────────────────────────────────────┐
│ [Edit] [•••]                    <- Actions │
│                                             │
│ # Document Title (H1)                       │
│                                             │
│ Introductory paragraph with **bold** and   │
│ *italic* formatting. Links look like this. │
│                                             │
│ ## Section 1 (H2)                           │
│                                             │
│ Content with lists:                         │
│ - Item one                                  │
│ - Item two                                  │
│                                             │
│ ```javascript                               │
│ // Code block                               │
│ const example = true;                       │
│ ```                                         │
│                                             │
│ ## Section 2 (H2)                           │
│                                             │
│ More content...                             │
└─────────────────────────────────────────────┘

Max Width: max-w-4xl mx-auto (centered, ~896px for optimal reading)

Padding: px-8 py-6 (comfortable margins)

Content Styling (matches GitBook pattern):

Paragraphs: mb-4 leading-7 (28px line height for readability)
Headings:
- H1: text-3xl font-bold mb-4 mt-8 pb-2 border-b border-slate-200
- H2: text-2xl font-semibold mb-3 mt-6
- H3: text-xl font-semibold mb-2 mt-4
Links: text-blue-600 dark:text-blue-400 underline hover:text-blue-800
Lists: ml-6 mb-4 list-disc (ul), list-decimal (ol)
Blockquotes: border-l-4 border-slate-300 pl-4 italic text-slate-600 my-4
Code blocks: Use MDE renderer with syntax highlighting
Tables: border border-slate-300 w-full with striped rows
Images: max-w-full rounded shadow-md my-4

Actions Bar (top right):

Edit button: Primary button (blue)
Menu (•••): Dropdown with “Delete Document”, “Move to…”, “History”

States:

Loading: Skeleton with pulsing lines (animate-pulse)
Empty: “Select a document to view” with tree illustration
Error: “Document not found” with “Return to welcome” link
Editing: Replace content with MDE editor component

Technical Notes:

Use markdown-it or similar renderer
Sanitize HTML output (XSS prevention)
Auto-generate heading IDs for anchor links
Smooth scroll to anchors: scroll-behavior: smooth

4. TOC Panel Component

Purpose: In-page navigation for document sections

Anatomy:

┌──────────────────┐
│ On this page     │ <- Header
│ ────────────     │
│ • Overview       │ <- H2
│ • Setup          │ <- H2
│   - Step 1       │ <- H3 (indented)
│   - Step 2       │ <- H3
│ • Configuration  │ <- H2 (active)
│ • Advanced       │ <- H2
│                  │
│ ────────────     │
│ Was this helpful?│ <- Feedback widget
│ 😊 😐 😞         │
└──────────────────┘

Placement: Fixed position in right sidebar, sticky top

Styling:

Header: text-sm font-semibold text-slate-900 dark:text-slate-100 mb-2
List: space-y-1 text-sm
H2 items: pl-2 py-1
H3 items: pl-6 py-1 (indented)
H4+ items: pl-10 py-1 (further indented)
Active item: text-blue-600 dark:text-blue-400 font-medium border-l-2 border-blue-600 pl-1.5
Inactive: text-slate-600 dark:text-slate-400 hover:text-slate-900 dark:hover:text-slate-100

Heading Extraction:

Include H2, H3, H4 only (skip H1 as it’s the title)
Max depth: 3 levels of nesting
Generate anchors: slugify heading text

Interactions:

Click heading: smooth scroll to section
Scroll spy: highlight active section based on viewport position
Keyboard: Tab through links

States:

Default: List of headings
No headings: Hide TOC panel or show “No sections”
Active: Highlight current section
Hover: Underline link

Technical Notes:

Use IntersectionObserver for scroll spy
Smooth scroll with scrollIntoView({ behavior: 'smooth' })
Throttle scroll events (100ms)

Purpose: Quick document helpfulness rating

Anatomy:

┌──────────────────────┐
│ Was this helpful?    │
│ ─────────────────    │
│  😊    😐    😞      │ <- Emoji buttons (large, clickable)
│                      │
└──────────────────────┘
      ↓ (after click)
┌──────────────────────┐
│ Thanks for feedback! │
│ ─────────────────    │
│ Want to add more?    │
│ ┌──────────────────┐│
│ │ Optional comment ││ <- Textarea
│ └──────────────────┘│
│ [Skip] [Submit]      │
└──────────────────────┘
      ↓ (after submit)
┌──────────────────────┐
│ ✓ Feedback received  │
│ Thank you!           │
└──────────────────────┘

Placement: Below TOC in right sidebar, sticky at top when scrolling

Emoji Rating:

Positive: 😊 (happy face)
Neutral: 😐 (neutral face)
Negative: 😞 (sad face)

Styling:

Container: border-t border-slate-200 dark:border-slate-700 pt-4 mt-4
Header: text-sm font-medium text-slate-700 dark:text-slate-300 mb-2
Emoji buttons: text-3xl p-2 hover:scale-110 transition-transform cursor-pointer opacity-70 hover:opacity-100
Selected emoji: opacity-100 scale-110
Textarea: border border-slate-300 rounded p-2 text-sm w-full mt-2 h-20
Buttons: Secondary (Skip), Primary (Submit)

Interactions:

Click emoji: Show comment textarea
Skip: Submit rating only, show thank you
Submit: Save rating + comment, show thank you
Edit: If user clicks emoji again, allow updating feedback

States:

Default: Show emoji buttons
Rating selected: Show comment field + buttons
Submitted: Show thank you message (5 seconds, then reset to default)
Previously rated: Show “You rated this 😊” with “Change rating” link
Loading: Disabled state on submit
Error: “Failed to save feedback. Try again?”

Data Storage:

Table: document_feedback
Columns: id, document_path, user_id, rating (enum: positive/neutral/negative), comment (nullable), created_at, updated_at
Unique constraint: user_id + document_path (users can update their feedback)

Technical Notes:

Auto-save on emoji click (rating only)
Optional comment submission
Show aggregate rating counts (future enhancement)

6. Edit Button Component

Purpose: Trigger document editing mode

Placement: Top right of content panel

Styling:

Primary button: bg-blue-600 hover:bg-blue-700 text-white px-4 py-2 rounded-md text-sm font-medium
Icon: Pencil SVG prepended
Tooltip on hover: “Edit this document (Ctrl+E)”

Interactions:

Click: Replace content panel with MDE editor
Keyboard: Ctrl+E or Cmd+E to edit
Permission check: Show only if user has edit rights (assume all staff do for MVP)

States:

Default: Visible
Hover: Darker background
Editing: Hide button, show “Save” and “Cancel” in editor toolbar
Loading: Disabled with spinner

7. MDE Editor Component (Reused)

Purpose: Edit markdown content with live preview

Note: This component is reused from the MDE feature. See MDE design spec for full details.

Key Features Used:

Split-pane editor (markdown | preview)
Auto-save (debounced 500ms)
Validation (markdown syntax check)
Toolbar: formatting buttons
Concurrent edit detection: “User X is editing” warning

Integration Points:

Load document content into editor
Save updates document file
Cancel: discard changes, return to view mode

BKB-Specific Additions:

Path display: Show “Editing: Brain > Folder > Document” breadcrumb
Cancel confirmation: “Discard changes?” if content modified
Save location: Always saves to original document path (no “Save As”)

Purpose: Create new markdown document in selected folder

Anatomy:

┌─────────────────────────────────┐
│ Create New Document        [×]  │
│ ─────────────────────────────  │
│                                 │
│ Folder: 2. PROCESSES > Workflows│ <- Read-only, shows location
│                                 │
│ Document Title *                │
│ ┌─────────────────────────────┐│
│ │ Enter document title        ││ <- Text input
│ └─────────────────────────────┘│
│ ℹ️ Filename: enter-document-title.md │ <- Auto-generated preview
│                                 │
│          [Cancel]  [Create]     │
└─────────────────────────────────┘

Trigger: Click ”+ New Document” in tree sidebar or folder context menu

Fields:

Folder (read-only): Display selected folder path
Document Title (required): Text input
- Validation: Not empty, max 100 chars
- Help text: “Filename will be auto-generated”
Filename Preview: Show slugified filename (e.g., “my-doc-title.md”)

Interactions:

Type title: Live update filename preview
Create: Open MDE editor with empty document
Cancel: Close modal
Enter key: Submit form

States:

Default: Empty form
Validation error: “Title is required” in red below input
Duplicate name: Auto-append number (e.g., “document-2.md”)
Creating: Show spinner, disable buttons

Technical Notes:

Slugify title per MDE conventions: lowercase, hyphens, no special chars
Create file on “Create” click, then open editor
Use Reka UI Dialog component

Purpose: Create new folder in Brain hierarchy

Anatomy:

┌─────────────────────────────────┐
│ Create New Folder          [×]  │
│ ─────────────────────────────  │
│                                 │
│ Parent: BRAIN (root)            │ <- Dropdown (select location)
│                                 │
│ Folder Name *                   │
│ ┌─────────────────────────────┐│
│ │ Enter folder name           ││
│ └─────────────────────────────┘│
│                                 │
│ ☐ Create as section header      │ <- Checkbox (e.g., "3. NEW SECTION")
│                                 │
│          [Cancel]  [Create]     │
└─────────────────────────────────┘

Trigger: Click ”+ New Folder” in tree sidebar or context menu

Fields:

Parent Folder (dropdown): Select where to create folder
- Options: BRAIN (root), any existing folder
Folder Name (required): Text input
- Validation: Not empty, max 50 chars, filesystem safe
Section Header (checkbox): If checked, format as “X. UPPERCASE”

Interactions:

Select parent: Update location
Type name: Validate
Section header: Show example format (“3. PROCESSES”)
Create: Add folder to tree
Cancel: Close modal

States:

Default: Empty form
Validation error: “Invalid folder name” in red
Duplicate: “Folder already exists” error
Creating: Spinner, disabled buttons

Technical Notes:

Section headers numbered automatically (next available number)
Folder creation updates tree immediately
Use Reka UI Dialog + Select components

Purpose: Right-click actions on tree nodes

Anatomy:

┌────────────────┐
│ 📄 Open        │ <- For documents
│ ✏️  Edit        │
│ ───────────    │
│ 🗑️  Delete     │
└────────────────┘

┌────────────────┐
│ 📂 Expand All  │ <- For folders
│ 📁 Collapse All│
│ ───────────    │
│ ➕ New Document│
│ ➕ New Folder  │
│ ───────────    │
│ ✏️  Rename      │
│ 🗑️  Delete     │
└────────────────┘

Trigger: Right-click tree node or click ”•••” icon

Document Actions:

Open: Navigate to document (same as click)
Edit: Open editor
Delete: Show confirmation modal

Folder Actions:

Expand/Collapse All: Recursive expand/collapse
New Document: Open new document modal with folder pre-selected
New Folder: Open new folder modal with parent pre-selected
Rename: Inline edit (text input replaces folder name)
Delete: Confirmation modal (warn if non-empty)

Styling:

Dropdown: bg-white dark:bg-slate-800 shadow-lg rounded-md border border-slate-200
Items: px-3 py-2 hover:bg-slate-100 dark:hover:bg-slate-700 text-sm cursor-pointer
Dividers: border-t border-slate-200
Icons: text-slate-500 next to labels

Technical Notes:

Use Reka UI DropdownMenu component
Close on outside click or Escape
Position near cursor (avoid viewport overflow)

Purpose: Confirm destructive actions

Anatomy:

┌─────────────────────────────────┐
│ Delete Document?           [×]  │
│ ─────────────────────────────  │
│                                 │
│ Are you sure you want to delete:│
│                                 │
│ "Approval Workflow.md"          │ <- Document name in quotes
│                                 │
│ ⚠️ This action cannot be undone.│
│                                 │
│          [Cancel]  [Delete]     │ <- Delete button is red
└─────────────────────────────────┘

Variants:

Empty Folder: Simple confirmation

Non-empty Folder: Warning + count

This folder contains 5 documents.
All contents will be deleted permanently.

Styling:

Modal: Standard dialog with red accent
Delete button: bg-red-600 hover:bg-red-700 text-white
Warning icon: Red exclamation triangle

Interactions:

Delete: Execute deletion, close modal, show toast notification
Cancel: Close modal
Escape key: Cancel

States:

Default: Show warning
Deleting: Spinner on button, disabled
Error: Show error message below buttons

Technical Notes:

Use Reka UI AlertDialog component
Return focus to tree after deletion
Navigate to welcome doc if deleting current document

Interaction Patterns

User lands on /brain
    ↓
Display tree with welcome doc (index.md or first doc)
    ↓
User clicks document in tree
    ↓
Content loads, TOC updates, tree highlights selection
    ↓
User clicks TOC item
    ↓
Smooth scroll to section, update active TOC item

Editing Flow

User viewing document
    ↓
Click Edit button (or Ctrl+E)
    ↓
Content panel replaced with MDE editor
    ↓
User makes changes (auto-saved)
    ↓
Click Save → Return to view mode with updated content
Click Cancel → Discard changes, return to view mode

Search Flow

User types in search input
    ↓
Debounced search (300ms)
    ↓
Results dropdown appears
    ↓
User clicks result
    ↓
Navigate to document, expand tree to show location, close dropdown

Keyboard Shortcuts

Shortcut	Action
`/` or `Ctrl+K`	Focus search
`Ctrl+E` / `Cmd+E`	Edit current document
Arrow keys	Navigate tree (when focused)
Enter	Select tree item
Right/Left	Expand/collapse folder
Escape	Close modal/dropdown
`Ctrl+S`	Save document (in editor)

Implementation: Use keyboard event listeners on document level, check for modifiers

Component States

Loading States

Initial Page Load:
- Skeleton tree structure (3-5 rows of pulsing lines)
- Skeleton content panel (pulsing heading + paragraphs)
- No TOC panel
Document Load (navigation):
- Content area: Pulsing skeleton matching previous document structure
- Tree: No loading state (instant)
- TOC: Fade out old, fade in new
Search Loading:
- Show spinner icon in search input
- Disable input until results load

Visual: Use Tailwind animate-pulse on skeleton elements

Skeleton: bg-slate-200 dark:bg-slate-700 rounded h-4 w-full mb-2

Empty States

No Documents:

┌─────────────────────────┐
│                         │
│    📚                   │
│                         │
│  No documents yet       │
│                         │
│  [+ Create Document]    │
│                         │
└─────────────────────────┘

No Search Results:

┌─────────────────────────┐
│   🔍                    │
│   No documents found    │
│   Try different terms   │
└─────────────────────────┘

No TOC (document without headings):
- Option A: Hide TOC panel completely
- Option B: Show “No sections in this document”
- Recommendation: Option A (cleaner)
No Folder Contents:
- Show “(empty)” next to folder name in tree
- Context menu shows only “New Document” and “Delete”

Error States

Document Not Found:

┌─────────────────────────┐
│   ⚠️                     │
│   Document not found    │
│                         │
│   The document may have │
│   been moved or deleted │
│                         │
│   [Return to Welcome]   │
└─────────────────────────┘

Load Error:

┌─────────────────────────┐
│   ❌                     │
│   Failed to load        │
│                         │
│   [Try Again] [Report]  │
└─────────────────────────┘

Save Error (in editor):
- Toast notification: “Failed to save changes”
- Keep editor open with changes
- Show retry button

Concurrent Editing

Pattern: Reuse MDE concurrent edit detection

Another User Editing:
- Show banner above content: “⚠️ User X is currently editing this document”
- Edit button disabled with tooltip: “Document locked by User X”
Your Edit Session Expires:
- Warning after 30 minutes: “Your edit session is still active. Continue editing?”
- Auto-cancel edit if user navigates away

Responsive Breakpoints

Desktop (1280px+)

Full three-column layout
Tree: 250px, Content: flexible, TOC: 200px
All features visible

Laptop (1024px - 1279px)

Three columns maintained
Tree: 200px, TOC: 180px
Slightly tighter spacing

Tablet (768px - 1023px)

Two columns: Tree + Content
TOC collapses to accordion above content
Tree: 200px or hamburger menu option

Mobile (<768px)

Single column: Content only
Tree as slide-in overlay (hamburger icon in top nav)
TOC as collapsible section above content
Search in top navigation bar
Simplified action buttons

Implementation Strategy: Mobile is secondary priority. Focus on desktop first, then adapt.

Accessibility Requirements (WCAG AA)

Semantic HTML

Use <nav> for tree sidebar
Use <main> for content panel
Use <aside> for TOC panel
Headings follow logical hierarchy (no skipped levels)

All interactive elements are focusable
Logical tab order: Search → Tree → Content → TOC → Feedback
Focus visible: ring-2 ring-blue-500 ring-offset-2
Skip links: “Skip to content” link at top

Screen Readers

Tree: Use ARIA tree widget pattern (role="tree", role="treeitem")
Expandable items: aria-expanded="true/false"
Current document: aria-current="page"
TOC: aria-label="Table of contents"
Search: aria-label="Search documentation"
Live regions: aria-live="polite" for search results count

Color Contrast

Text: 4.5:1 contrast ratio minimum
Interactive elements: 3:1 contrast
Test both light and dark modes

Focus Management

Modal opens: Focus first interactive element
Modal closes: Return focus to trigger element
Document navigation: Focus content heading (H1)

Alternatives

Icon-only buttons: Include aria-label or visible text
Emoji ratings: Include text labels for screen readers

Testing: Use axe DevTools, NVDA/JAWS screen readers

Dark Mode Support

Strategy: Full dark mode support using Tailwind dark: variant

Color Adjustments

Element	Light Mode	Dark Mode
Background	`bg-white`	`bg-slate-900`
Panel	`bg-slate-50`	`bg-slate-800`
Border	`border-slate-200`	`border-slate-700`
Text Primary	`text-slate-900`	`text-slate-100`
Text Secondary	`text-slate-600`	`text-slate-400`
Interactive	`text-blue-600`	`text-blue-400`
Hover	`bg-slate-100`	`bg-slate-700`
Selected	`bg-blue-50`	`bg-blue-900/20`
Code block	`bg-slate-100`	`bg-slate-800`

Implementation

Respect system preference: prefers-color-scheme: dark
Allow manual toggle (if portal has theme switcher)
Persist preference in localStorage

Testing

Test all components in both modes
Verify contrast ratios
Check syntax highlighting in code blocks

Animation & Transitions

Philosophy: Subtle, purposeful animations that enhance usability without distraction

Transition Timing

Fast: 150ms - hovers, focus states
Default: 200ms - dropdowns, tooltips
Smooth: 300ms - panel slides, page transitions
Slow: 500ms - skeleton loading fade

Specific Animations

Tree Expand/Collapse:
- transition-all duration-200 ease-in-out
- Rotate arrow icon: transform rotate-90
Document Navigation:
- Fade out old content: 150ms
- Fade in new content: 200ms (stagger 50ms)
TOC Scroll:
- Smooth scroll: scroll-behavior: smooth
- Active item transition: 200ms
Search Dropdown:
- Slide down: transition-transform duration-200 ease-out
- Fade in: transition-opacity duration-150
Modal:
- Backdrop fade: 200ms
- Content scale: scale-95 to scale-100, 200ms
Hover States:
- Background change: 150ms
- Scale (emoji buttons): transition-transform duration-150
Loading Skeletons:
- Pulse: animate-pulse (default Tailwind)

Reduced Motion: Respect prefers-reduced-motion media query - disable animations

Performance Considerations

Tree Rendering

Virtualize if >100 items per level (use vue-virtual-scroller)
Lazy load deeply nested folders
Debounce search: 300ms

Content Panel

Lazy load images: loading="lazy"
Defer syntax highlighting for large code blocks
Limit initial render to viewport content

Caching

Cache rendered markdown (localStorage or memory)
Cache tree structure (session storage)
Invalidate on document update

Bundle Size

Code-split MDE editor (only load when editing)
Lazy load markdown renderer
Tree-shake unused Tailwind classes

Target Performance:

Initial load: <2s (tree + welcome doc)
Document navigation: <200ms
Search results: <500ms
Smooth scrolling: 60fps

Edge Cases & Handling

Very Deep Nesting (>5 levels)

Allow horizontal scroll in tree sidebar if needed
Consider “breadcrumb collapse” for mobile (e.g., ”… > Parent > Current”)
Limit visual indentation to 5 levels (further nesting at same indent)

Very Long Document Titles

Truncate with ellipsis: truncate utility
Show full title on hover (tooltip)
Max display: ~30 characters in tree

Special Characters in Names

Slugify for filenames: lowercase, hyphens, remove special chars
Display original title in UI
Handle Unicode properly (e.g., “Café” → cafe.md)

Duplicate Names

Auto-append number: document-2.md, document-3.md
Show warning: “A document with this name exists. Created as [name]“

Large Files (>1MB)

Show warning before opening: “This is a large document. Load anyway?”
Consider pagination or “Read more” sections

Concurrent Editing

Detect via polling (check modified timestamp every 30s)
Show “User X is editing” banner
Lock edit button
Allow viewing but not editing

Broken Links

Highlight broken internal links in red
Show tooltip: “Document not found”
Future: Validation report

No Documents in Brain

Show welcome message: “Start building your knowledge base”
Prominent “Create First Document” button
Optional: Sample documents or templates

Search with Many Results (>50)

Show first 10 in dropdown
“Show all results” link at bottom
Future: Full search results page

Technical Implementation Notes

Vue Component Structure

/resources/js/Pages/Brain/
├── Index.vue              # Main layout (3-column)
├── Components/
│   ├── TreeSidebar.vue    # Tree navigation
│   ├── TreeNode.vue       # Individual tree item
│   ├── SearchInput.vue    # Search component
│   ├── ContentPanel.vue   # Document viewer
│   ├── TocPanel.vue       # Table of contents
│   ├── FeedbackWidget.vue # Helpfulness rating
│   ├── NewDocModal.vue    # Create document
│   ├── NewFolderModal.vue # Create folder
│   ├── ContextMenu.vue    # Right-click menu
│   └── DeleteModal.vue    # Confirmation dialog

Composables (Vue 3 Composition API)

// useTreeState.js - Tree expansion/selection state
export function useTreeState() {
  const expandedNodes = ref(new Set())
  const selectedDoc = ref(null)
  // ...
}

// useDocumentContent.js - Document loading/rendering
export function useDocumentContent(path) {
  const content = ref('')
  const headings = ref([])
  // ...
}

// useTocScroll.js - TOC scroll spy
export function useTocScroll(headings) {
  const activeId = ref(null)
  // IntersectionObserver logic
}

// useSearch.js - Search functionality
export function useSearch(documents) {
  const query = ref('')
  const results = computed(() => /* filter logic */)
  // ...
}

Storybook Components to Reuse

From https://design.trilogycare.dev:

Button (Primary, Secondary)
Dialog / Modal
Dropdown Menu
Input / Text Field
Tooltip
Alert / Banner
Skeleton Loader

New Custom Components:

Tree widget (if not in Storybook)
TOC scroll spy
Feedback emoji selector

API Endpoints

GET  /api/brain/tree              # Get folder/document tree
GET  /api/brain/document/{path}   # Get document content
POST /api/brain/document          # Create document
PUT  /api/brain/document/{path}   # Update document
DELETE /api/brain/document/{path} # Delete document

POST /api/brain/folder            # Create folder
PUT  /api/brain/folder/{path}     # Rename folder
DELETE /api/brain/folder/{path}   # Delete folder

GET  /api/brain/search?q=term     # Search documents

POST /api/brain/feedback          # Submit feedback
GET  /api/brain/feedback/{path}   # Get user's feedback

Database Schema

-- Document Feedback
CREATE TABLE document_feedback (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    document_path VARCHAR(255) NOT NULL,
    user_id BIGINT UNSIGNED NOT NULL,
    rating ENUM('positive', 'neutral', 'negative') NOT NULL,
    comment TEXT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY unique_user_document (user_id, document_path),
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    INDEX idx_document_path (document_path)
);

Testing Strategy

Visual Testing

Storybook stories for all components
Test light and dark modes
Test all component states (loading, error, empty)

Interaction Testing

Playwright tests for user flows:
- Navigate tree → view document → edit → save
- Search → click result → verify navigation
- Create document → verify in tree
- Submit feedback → verify stored

Accessibility Testing

Automated: axe-core in Playwright
Manual: Keyboard navigation, screen reader
Color contrast checks

Responsive Testing

Test at 320px, 768px, 1024px, 1440px
Verify layouts adapt correctly

Performance Testing

Lighthouse audit (target >90 score)
Test with 100+ documents
Measure search performance

Design Rationale

Why Three-Column Layout?

Standard pattern: Users familiar with GitBook, Confluence, etc.
Information density: All navigation context visible without scrolling
No surprises: Predictable, learnable interface

Consistency: Prevents layout shift on navigation
Optimal reading: ~250px is sweet spot for nested tree
Future enhancement: Can add resize handles later

Why Sticky TOC?

Constant reference: Users don’t lose context while reading
Quick navigation: Always accessible without scrolling up

Why Emoji Feedback?

Low friction: One-click feedback (vs form)
Universal: Emojis transcend language
Optional depth: Can add comment if needed

Why Desktop-First?

Primary use case: Staff at workstations browsing docs
Internal tool: No SEO or mobile traffic concerns
Complexity: Tree navigation difficult on small screens

Why Reuse MDE Editor?

Consistency: Same editing experience across portal
DRY principle: Don’t duplicate editor logic
Proven: MDE already handles edge cases

Open Questions for Engineering

Tree Data Structure: Fetch entire tree on load or lazy load per folder?
- Recommendation: Fetch all (likely <100 docs), lazy load if >500 docs
Search Implementation: Client-side filter or backend API?
- Recommendation: Client-side for MVP, backend for >1000 docs
Concurrent Edit Locking: Soft lock (warning) or hard lock (prevent editing)?
- Recommendation: Soft lock per MDE pattern (show warning, allow override)
Folder Persistence: Session storage or localStorage?
- Recommendation: Session storage (fresh state per session)
Feedback Aggregation: Show aggregate stats or just individual feedback?
- Recommendation: Individual only for MVP, aggregate in future

Phase 2: Tab-Based Architecture (Future Enhancement)

Pattern Reference: GitBook-style top tabs for multiple content collections

Concept

Phase 1 delivers the Brain knowledge base as a single section. Phase 2 extends this to support multiple “books” or content collections, each with their own navigation tree.

┌─────────────────────────────────────────────────────────────────────────────┐
│ TC Portal    [🔍 Search...  ⌘K]                                    User ▼   │
├─────────────────────────────────────────────────────────────────────────────┤
│ [Brain] [API Docs] [Guides] [Changelog]                    ← TOP TABS      │
├──────────────────┬──────────────────────────────────────┬───────────────────┤
│ OVERVIEW         │ Content for selected tab...          │ On this page      │
│ ─────────────────│                                      │ ─────────────────│
│ (Tab-specific    │                                      │ (Tab-specific     │
│  navigation)     │                                      │  TOC)             │
└──────────────────┴──────────────────────────────────────┴───────────────────┘

Tab Configuration

Each tab would map to a content source:

Tab	Source	Description
Brain	`.claude/BRAIN/`	Internal knowledge base (Phase 1)
API Docs	`.claude/API/` or generated	API reference documentation
Guides	`.claude/GUIDES/`	How-to guides and tutorials
Changelog	`.claude/CHANGELOG/` or DB	Release notes and updates

Implementation Approach

Phase 1 Foundation: Build Brain with extensible component architecture
- Tree sidebar accepts rootPath prop
- Content panel is source-agnostic
- URL structure: /brain/{path} supports future /docs/{path}, /guides/{path}
Phase 2 Extension: Add tab bar component
- Tab configuration stored in config file or database
- Each tab renders same three-column layout with different rootPath
- Shared search across all tabs (with tab filter)

Design Considerations for Phase 1

To ensure Phase 2 compatibility, Phase 1 should:

Use generic component names (not “Brain”-specific)
Pass content source as prop, not hardcoded
URL routing supports nested paths: /brain/overview/getting-started
Search component accepts scope parameter
Breadcrumb component is reusable

Future Enhancements (Out of Scope)

Version history and diffs
Advanced search (filters, operators, fuzzy matching)
Document templates
Export to PDF
Comments/annotations on documents
Related documents suggestions
Analytics (most viewed, least helpful)
Drag-and-drop reordering
Keyboard shortcuts overlay (? key)

Deliverables Checklist

Sign-Off

Designer: Bruce (UI Designer) Created: 2025-11-29 Status: Ready for Engineering Review

Next Steps:

Engineering review of technical feasibility
Identify Storybook components to use/create
Create tickets for component implementation
Set up Playwright test scenarios
Begin implementation with tree sidebar (foundational)

This design spec follows Trilogy brand guidelines and internal staff stakeholder density. All decisions optimize for rapid 6-day sprint implementability.

design spec

Design Specification: Brain Knowledge Base

Design Philosophy

Layout Architecture

Desktop Layout (Primary)

Panel Widths

Responsive Behavior

Visual Design System

Color Palette (from Trilogy Brand)

Typography

Spacing Scale (4px grid)

Component Inventory

1. Tree Sidebar Component

2. Search Input Component

3. Content Panel Component

4. TOC Panel Component

5. Feedback Widget Component

6. Edit Button Component

7. MDE Editor Component (Reused)

8. New Document Modal

9. New Folder Modal

10. Context Menu Component

11. Delete Confirmation Modal

Interaction Patterns

Navigation Flow

Editing Flow

Search Flow

Keyboard Shortcuts

Component States

Loading States

Empty States

Error States

Concurrent Editing

Responsive Breakpoints

Desktop (1280px+)

Laptop (1024px - 1279px)

Tablet (768px - 1023px)

Mobile (<768px)

Accessibility Requirements (WCAG AA)

Semantic HTML

Keyboard Navigation

Screen Readers

Color Contrast

Focus Management

Alternatives

Dark Mode Support

Color Adjustments

Implementation

Testing

Animation & Transitions

Transition Timing

Specific Animations

Performance Considerations

Tree Rendering

Content Panel

TOC

Caching

Bundle Size

Edge Cases & Handling

Very Deep Nesting (>5 levels)

Very Long Document Titles

Special Characters in Names

Duplicate Names

Large Files (>1MB)

Concurrent Editing

Broken Links

No Documents in Brain

Search with Many Results (>50)

Technical Implementation Notes

Vue Component Structure

Composables (Vue 3 Composition API)

Storybook Components to Reuse

API Endpoints

Database Schema

Testing Strategy

Visual Testing

Interaction Testing

Accessibility Testing

Responsive Testing

Performance Testing