Skip to content

UI_UX_GUIDE.md

Latest commit

 

History

History
315 lines (247 loc) · 11.1 KB

UI_UX_GUIDE.md

File metadata and controls

315 lines (247 loc) · 11.1 KB
Raw

日本語版

CommandMate UI/UX Guide

This document describes CommandMate's current UI/UX implementation.

Table of Contents

  1. Overview
  2. Responsive Design
  3. Desktop UI
  4. Mobile UI
  5. Common Features
  6. Component Structure

Overview

CommandMate provides a responsive UI optimized for both desktop and mobile.

Screen Layout Features
Desktop 3-column (ActivityBar / ActivityPane / Right (History inside TerminalContainer)) VS Code-style full-height Activity Bar, instant Tooltip, History embedded in the Terminal area, resizable panes
Mobile Tab-based Bottom navigation

Responsive Design

Auto Detection

The useIsMobile hook automatically switches layouts based on screen size.

  • Desktop: 768px and above
  • Mobile: Below 768px
┌─────────────────────────────────────────┐
│  768px+ → Desktop Layout               │
│  <768px → Mobile Layout                │
└─────────────────────────────────────────┘

Desktop UI

Layout Structure (Issue #727 / #730)

Adopts a VS Code-style full-height Activity Bar. History is embedded in the Terminal area and runs down to the bottom of the screen.

┌───┬─────────────────────────────────────────────────┐
│   │  [←Back]  worktree-name                  [Info] │ ← Header
│ A │ ├─────────────────────────────────────────────┤  │
│ c │ │ BranchMismatchAlert (conditional)             │
│ t │ ├──────────┬─────────────────┬──────────────────┤
│ B │ │          │                 │                  │
│ a │ │ Activity │ History         │ Terminal         │
│ r │ │ Pane     │ (inside TerminalContainer, left sub-panel) │ + FilePanel │
│ ┃ │ │  - Files │ │  - Git        │                 │                  │
│ ┃ │ │  - Notes │ │  - Schedules  │                 │                  │
│ ┃ │ │  - Agent │ │  - Timer      │                 │                  │
│ ┃ │ ├──────────┴─────────────────┴──────────────────┤
│ ┃ │ │  NavigationButtons (conditional, OpenCode TUI) │
│ ┃ │ ├─────────────────────────────────────────────┤  │
│ ┃ │ │  [Message Input]                       [Send] │
└───┴─────────────────────────────────────────────────┘
   ↑          ↑               ↑              ↑
ActivityBar full-height  ActivityPane  History (collapsible)  FilePanel
(48px, runs from below Header to bottom)

Feature Details

1. Header

  • Back button: Return to the top page (Worktree list)
  • Worktree name: Displays the current branch/worktree name
  • Info button: Opens the Worktree info modal

2. ActivityBar (48px, full-height)

  • VS Code-style vertical Activity Bar
  • 6 Activities: Files / Git / Notes / Schedules / Agent / Timer
  • Runs from below the Header to the bottom of the screen (Issue #730)
  • Instant Tooltip on each icon (100ms, dark theme, right placement) (Issue #730)
  • Keyboard navigation: ArrowUp/Down/Home/End/Enter/Space

3. ActivityPane (renders the selected Activity)

  • Displays the content of the currently selected Activity
  • Drag-resizable width via ResizableColumn

4. TerminalContainer (Right Pane, Issue #730)

  • Embeds History (left sub-panel) + Terminal + FilePanel (right)
  • History is collapsible (< / > buttons)
  • History width is drag-resizable (10-60%, DEFAULT 40% relative to the TerminalContainer)
  • History / Terminal are each wrapped in an ErrorBoundary
  • The internal id worktree-history-pane is applied to the HistoryPane outer wrapper div

5. Resize Feature

  • Drag the boundary between ActivityPane and TerminalContainer to adjust width
  • Inside the TerminalContainer, drag the boundary between History and Terminal
  • Visual feedback during drag

5. Info Modal

  • Displays Worktree details:
    • Path
    • Branch name
    • CLI tool
    • Creation date
  • Memo editing: Save memos per branch

6. Prompt Panel

  • Displays CLI tool confirmation prompts as an overlay
  • Supports Yes/No selection or multiple choice
  • Animated show/hide transitions

Mobile UI

Layout Structure

┌─────────────────────────────┐
│ [←] worktree-name    [state]│  ← Header
├─────────────────────────────┤
│                             │
│                             │
│     Content Area            │
│     (Based on selected tab) │
│                             │
│                             │
├─────────────────────────────┤
│ Terminal│History│Logs│Info   │  ← Tab Bar
└─────────────────────────────┘

Tab Structure

Tab Icon Content
Terminal 💻 Real-time terminal output + input field
History 🕐 Message history
Logs 📄 Markdown log file list
Info ℹ️ Worktree info + memo editing

Feature Details

1. Header

  • Back button: Return to top page
  • Worktree name: Current branch name (truncated)
  • Status indicator:
    • 🟢 Running
    • 🟡 Waiting (prompt pending)
    • ⚪ Idle
    • 🔴 Error

2. Tab Bar

  • Fixed at the bottom of the screen
  • Safe Area support (iPhone notch/home bar)
  • Notification badges:
    • 🟢 New output available
    • 🟡 Prompt pending

3. Prompt Sheet

  • Displayed as a bottom sheet when CLI prompt is detected
  • Swipe down to dismiss
  • Tap overlay to dismiss
  • Supports Yes/No or multiple choice

4. Virtual Keyboard Support

  • Layout auto-adjusts when keyboard is displayed
  • Input field remains visible at all times

Common Features

1. Real-Time Polling

Active:   Poll every 2 seconds
Idle:     Poll every 5 seconds
  • Periodically fetches CLI tool output
  • Prompt detection (Yes/No, multiple choice)
  • Thinking state detection

2. Prompt Detection & Response

When a CLI tool asks for confirmation:

┌─────────────────────────────────┐
│  Confirmation from Claude       │
│                                 │
│  Do you want to proceed?        │
│                                 │
│  [Yes]  [No]                    │
└─────────────────────────────────┘
  • Automatically displayed in the UI
  • Selected answer is sent to the CLI

3. Memo Feature

Save memos for each Worktree:

  • Desktop: Inside the Info modal
  • Mobile: Inside the Info tab

4. Error Boundary

Each component is wrapped with ErrorBoundary:

  • Partial errors don't affect the whole app
  • Fallback UI is displayed on error

Component Structure

Directory Structure

src/components/
├── mobile/
│   ├── MobileHeader.tsx      # Mobile header
│   ├── MobileTabBar.tsx      # Bottom tab bar
│   └── MobilePromptSheet.tsx # Bottom sheet for prompts
├── common/
│   └── Tooltip.tsx              # 100ms-delay custom Tooltip (Issue #730)
├── worktree/
│   ├── WorktreeDetailRefactored.tsx  # Main component (ActivityBar full-height: Issue #730)
│   ├── WorktreeDesktopLayout.tsx     # Desktop 2-column (ActivityPane + Right) — simplified in Issue #730
│   ├── ActivityBar.tsx               # VS Code-style Activity Bar (Issue #727), Tooltip wrap (Issue #730)
│   ├── ActivityPane.tsx              # Renders the selected Activity (Issue #727)
│   ├── TerminalContainer.tsx         # History + Terminal container (Issue #730)
│   ├── TerminalDisplay.tsx           # Terminal display
│   ├── HistoryPane.tsx               # History pane (delegated inside TerminalContainer, collapsible)
│   ├── PromptPanel.tsx               # Desktop prompt
│   ├── PaneResizer.tsx               # Pane resizer
│   └── MessageInput.tsx              # Message input
├── error/
│   └── ErrorBoundary.tsx     # Error boundary
└── ui/
    └── Modal.tsx             # Modal component

Custom Hooks

src/hooks/
├── useIsMobile.ts          # Mobile detection
├── useWorktreeUIState.ts   # UI state management (useReducer)
├── usePromptAnimation.ts   # Prompt animation
├── useSwipeGesture.ts      # Swipe gesture
├── useTerminalScroll.ts    # Terminal auto-scroll
└── useVirtualKeyboard.ts   # Virtual keyboard handling

Screen Navigation Flow

┌─────────────────┐
│  Top Page        │
│  (Worktree List) │
└────────┬────────┘
         │ Tap
         ▼
┌─────────────────┐
│  Worktree Detail │◄──────────────┐
│  (Chat Screen)   │               │
└────────┬────────┘               │
         │                        │
    ┌────┴────┐                   │
    ▼         ▼                   │
┌───────┐ ┌───────┐               │
│ Logs  │ │ Info  │               │
│ View  │ │ Modal │               │
└───────┘ └───────┘               │
                                  │
         [Back]───────────────────┘

Technical Highlights

Performance Optimization

  • Component memoization with memo
  • Recomputation prevention with useMemo / useCallback
  • Conditional rendering to avoid unnecessary DOM generation

Accessibility

  • Proper ARIA attribute usage
  • Keyboard navigation support
  • Screen reader-compatible labels

Error Handling

  • ErrorBoundary for each pane/component
  • Fallback UI provision
  • Error log output

Related Documents