headquarter/openspec/changes/archive/2026-05-19-workspace-visual-overhaul/design.md

Workspace Visual Overhaul - Design

Layout Architecture

New Workspace Layout

┌──────────────────────────────────────────────────────────────────────┐
│  App Shell (Header + Nav)                                             │
├──────────────────────────────────────────────────────────────────────┤
│  Project Workspace Header                                             │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │  📁 My Project          [History] [⚙️ Settings]                │ │
│  │                         (secondary actions on right)           │ │
│  └─────────────────────────────────────────────────────────────────┘ │
├──────────────────────┬───────────────────────────────────────────────┤
│                      │                                               │
│  Sidebar (280px)     │  Main Content                                 │
│  ┌────────────────┐  │  ┌─────────────────────────────────────────┐  │
│  │ Branch ▼        │  │  │ Breadcrumbs: src > components           │  │
│  ├────────────────┤  │  ├─────────────────────────────────────────┤  │
│  │ 📁 src/         │  │  │ Toolbar: [Edit] [Raw] [Blame]           │  │
│  │ 📁 tests/       │  │  ├─────────────────────────────────────────┤  │
│  │ 📄 README.md    │  │  │                                         │  │
│  │ ...             │  │  │ function hello() {                      │  │
│  │                 │  │  │   return "world";                       │  │
│  └────────────────┘  │  │ }                                       │  │
│                      │  │                                         │  │
│                      │  └─────────────────────────────────────────┘  │
│                      │                                               │
└──────────────────────┴───────────────────────────────────────────────┘

Project Settings Page

┌──────────────────────────────────────────────────────────────────────┐
│  App Shell (Header + Nav)                                             │
├──────────────────────────────────────────────────────────────────────┤
│  Settings Header                                                      │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │  ← Back to Project    My Project / Settings                    │ │
│  └─────────────────────────────────────────────────────────────────┘ │
├──────────────────┬───────────────────────────────────────────────────┤
│                  │                                                   │
│  Settings Tabs   │  Tab Content                                      │
│  ┌──────────────┐│  ┌─────────────────────────────────────────────┐  │
│  │ General      ││  │ General Settings                              │  │
│  ├──────────────┤│  │                                               │  │
│  │ Repositories ││  │ Project Name: [My Project        ]            │  │
│  ├──────────────┤│  │ Description:  [A test project... ]            │  │
│  │ Members      ││  │                                               │  │
│  ├──────────────┤│  │ [Save Changes]                                │  │
│  │ Danger Zone  ││  │                                               │  │
│  └──────────────┘│  └─────────────────────────────────────────────┘  │
│                  │                                                   │
└──────────────────┴───────────────────────────────────────────────────┘

Component Changes

1. WorkspaceHeader (New Component)

Location: apps/web/src/components/workspace-header.tsx

Props:

interface WorkspaceHeaderProps {
  project: Project;
  onNavigateToHistory: () => void;
  onNavigateToSettings: () => void;
}

Layout:

• Left: Project icon + Project name (bold)
• Right: Action buttons group
  • "History" button (clock icon)
  • "Settings" button (gear icon)
• Subtitle (optional): Project description or current repo name

2. ProjectSettingsPage (New Page)

Location: apps/web/src/pages/project-settings.tsx

Route: /projects/:projectId/settings

Tabs:

1. General

   • Project name input
   • Description textarea
   • Created date (read-only)
   • Save button

2. Repositories (moved from separate page)

   • List of project repositories
   • Add repository button
   • Repository cards with actions (delete)
   • Same functionality as current repo management

3. Members (placeholder for future)

   • "Coming soon" message

4. Danger Zone

   • Delete project button (with confirmation)

3. Sidebar Simplification

Remove from sidebar:

• "Manage Repositories" link (moved to settings)
• "History" link (moved to header)

Keep in sidebar:

• Branch selector
• File tree

4. Navigation Updates

Current routes:

• /projects → Project list (unchanged)
• /projects/:id → Workspace (new header)
• /projects/:id/repositories → Repository list (REMOVE)
• /projects/:id/repositories/:repoId/history → History (keep)
• /projects/:id/settings → NEW

New navigation flow:

Projects List
  ↓ click
Workspace (with header actions)
  ↓ click Settings
Project Settings
  ↓ click Repositories tab
Repository Management (in settings)
  ↓ click Back
Workspace

CSS Changes

Workspace Header

.workspace-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 1rem 1.5rem;
  border-bottom: 1px solid var(--border-color);
  background: var(--surface-color);
}

.workspace-header-left {
  display: flex;
  align-items: center;
  gap: 0.75rem;
}

.workspace-header-title {
  font-size: 1.25rem;
  font-weight: 600;
  color: var(--text-primary);
}

.workspace-header-actions {
  display: flex;
  gap: 0.5rem;
}

.workspace-header-action-btn {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.5rem 1rem;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--surface-color);
  color: var(--text-secondary);
  font-size: 0.875rem;
  cursor: pointer;
  transition: all 0.2s;
}

.workspace-header-action-btn:hover {
  background: var(--hover-color);
  border-color: var(--primary-color);
}

Settings Layout

.settings-container {
  display: flex;
  min-height: calc(100vh - var(--header-height));
}

.settings-sidebar {
  width: 240px;
  border-right: 1px solid var(--border-color);
  padding: 1.5rem 0;
}

.settings-tab {
  display: block;
  padding: 0.75rem 1.5rem;
  color: var(--text-secondary);
  text-decoration: none;
  font-size: 0.875rem;
  border-left: 3px solid transparent;
}

.settings-tab:hover {
  background: var(--hover-color);
}

.settings-tab.active {
  color: var(--primary-color);
  border-left-color: var(--primary-color);
  background: var(--primary-light);
}

.settings-content {
  flex: 1;
  padding: 2rem;
  max-width: 800px;
}

API Changes

No new API endpoints needed. The settings page will use existing APIs:

• GET /projects/:id - project details
• PUT /projects/:id - update project (already exists? if not, add)
• DELETE /projects/:id - delete project (already exists)

Implementation Order

1. Create WorkspaceHeader component

   • Extract from current workspace page
   • Add action buttons
   • Style appropriately

2. Create ProjectSettingsPage

   • Settings layout with tabs
   • General tab with project info
   • Danger zone with delete button

3. Move repository management

   • Move repo list from separate page to settings tab
   • Update routes

4. Update workspace page

   • Remove sidebar links
   • Add WorkspaceHeader
   • Keep file tree and viewer

5. Update router

   • Remove /projects/:id/repositories route
   • Add /projects/:id/settings route
   • Add tab routes: /projects/:id/settings/general, etc.

6. Polish

   • Ensure responsive design
   • Test navigation flow
   • Update breadcrumbs if needed

Migration Notes

• Users currently accessing /projects/:id/repositories will need to navigate to Settings > Repositories
• Can add a redirect or show a message on the old route temporarily
• Update any hardcoded links in the codebase