Skip to content
Trilogy Care Logo TC Docs

initiatives ui plan

Initiatives UI Enhancement Plan

Goal

Bring Brain’s GitBook-style UI patterns to the Initiatives section while respecting its unique data structure (Initiatives → Epics → Documents/Stories/Tasks).

Current Analysis

Brain Features to Port

  1. Reading Progress Bar - Top progress indicator
  2. Table of Contents (TOC) Panel - Sticky sidebar with scroll spy
  3. Back to Top Button - Appears when scrolled
  4. Keyboard Navigation - j/k for prev/next
  5. Enhanced Breadcrumbs - With folder icons, title case
  6. Code Copy Buttons - For code blocks
  7. Smooth Transitions - Content fade-in animations
  8. Print Optimization - Full document print support

Initiatives-Specific Needs

  • Tab-based document switching (Overview, Idea Brief, PRD, etc.)
  • Phase stepper visualization
  • Story/Task list views
  • Initiative → Epic hierarchy

Implementation Plan

Phase 1: Shared Components (Foundation)

Create reusable components in /resources/js/Components/Documentation/:

  1. DocumentTocPanel.vue - Generic TOC sidebar

    • Scroll spy for active heading
    • Click to scroll
    • Collapsible on mobile

  2. DocumentContentPanel.vue - Generic markdown viewer

    • Code copy buttons
    • Smooth animations
    • Print optimizations

  3. DocumentBreadcrumb.vue - Enhanced breadcrumb

    • Folder icons for non-clickable segments
    • Title case formatting
    • Consistent styling

  4. DocumentProgress.vue - Reading progress bar

    • Horizontal progress indicator
    • Smooth animation

  5. BackToTopButton.vue - Floating back to top

    • Appears on scroll
    • Smooth scroll to top

Phase 2: Epic Show Enhancement

Apply components to Epic Show page:

  1. Layout Update

    • Add reading progress bar at top
    • Restructure document tabs to include TOC sidebar
    • Add back-to-top button

  2. Document Tabs (Idea Brief, PRD, RACI)

    • Replace inline TOC with TocPanel component
    • Add code copy functionality
    • Improve print styles

  3. Breadcrumb Enhancement

    • Use DocumentBreadcrumb component
    • Add folder icon for Initiative segment

  4. Keyboard Navigation

    • Add j/k for prev/next epic
    • Add ? for keyboard shortcuts help

Phase 3: Initiatives Index Enhancement

Improve the master-detail view:

  1. Sidebar Refinement

    • Add expand/collapse all button
    • Improve hover/active states
    • Add keyboard navigation (arrows)

  2. Detail Panel

    • Add loading skeleton
    • Smooth transitions between initiatives

  3. Search Enhancement

    • Keyboard shortcut (Cmd+K)
    • Search result highlighting

Phase 4: Polish & Consistency

Final touches:

  1. Dark Mode - Ensure all new components support dark mode
  2. Mobile Responsiveness - Test and fix mobile layouts
  3. Print Styles - Ensure documents print correctly
  4. Accessibility - ARIA labels, keyboard nav, focus states

Component Architecture

/resources/js/Components/Documentation/
├── DocumentBreadcrumb.vue      # Enhanced breadcrumb
├── DocumentContentPanel.vue    # Markdown viewer with code copy
├── DocumentProgress.vue        # Reading progress bar
├── DocumentTocPanel.vue        # TOC sidebar with scroll spy
├── BackToTopButton.vue         # Floating back to top
└── KeyboardShortcutsHelp.vue   # ? modal showing shortcuts

Files to Modify

New Files

  • Components/Documentation/DocumentTocPanel.vue
  • Components/Documentation/DocumentContentPanel.vue
  • Components/Documentation/DocumentBreadcrumb.vue
  • Components/Documentation/DocumentProgress.vue
  • Components/Documentation/BackToTopButton.vue

Modified Files

  • Pages/Documentation/Initiatives/Epics/Show.vue - Major refactor
  • Pages/Documentation/Initiatives/Index.vue - Minor enhancements
  • icons.ts - Add any new icons

Implementation Order

  1. Create DocumentTocPanel.vue (can reuse Brain’s TocPanel logic)
  2. Create BackToTopButton.vue (extract from BrainLayout)
  3. Create DocumentBreadcrumb.vue (extract from ContentHeader)
  4. Update Epic Show with new components
  5. Add keyboard navigation to Epic Show
  6. Enhance Index page sidebar
  7. Final polish and testing

Estimated Effort

  • Phase 1: 4-6 components
  • Phase 2: Major page refactor
  • Phase 3: Minor enhancements
  • Phase 4: Testing and polish

Success Criteria

  • Epic documents have TOC sidebar with scroll spy
  • Reading progress bar shows on Epic Show
  • Back to top button appears on scroll
  • j/k navigates between epics
  • Breadcrumbs have folder icons
  • Code blocks have copy buttons
  • Print produces full document
  • Dark mode works correctly