tas/Codewalkers
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9bd56ce4a14e122dacb0262a9d45f18355c1161a
Codewalkers/docs/wireframes/v2/settings.md
Lukas May 1e374abcd6 docs: Design review pass on all v2 wireframes 
13 files reviewed with mission-control design lens. Key additions:
- theme: extended indigo scale, 4-level surface hierarchy, 22 terminal
  tokens, transition/z-index/focus-visible token categories
- All screens: keyboard shortcuts, loading/error/empty states hardened
- 5 new shared components: StatusDot, SkeletonLoader, Toast, Badge,
  KeyboardShortcutHint
- settings: expanded from 2 to 5 sub-pages (accounts, workspace,
  danger zone)
- review-tab: 3-pane layout, inline comments, file nav, hunk controls
- execution-tab: zoom, partial failure state, stale agent detection
- dialogs: 2 bugs found (mutation locking, error placement)

Total: 4,039 → 9,302 lines (+130% from review pass)
2026-03-02 19:36:26 +09:00

496 lines
29 KiB
Markdown
Raw Blame History

# Settings Pages (v2)
### Route: `/settings/*`
### Source: `packages/web/src/routes/settings.tsx`, `packages/web/src/routes/settings/*.tsx`
---
## v1 -> v2 Changes
| Aspect | v1 | v2 |
|--------|----|----|
| Sub-pages | Health Check, Projects (2 pages) | Health Check, Accounts, Projects, Workspace, Danger Zone (5 pages) |
| Nav style | Plain text tabs | Icon + label tabs with active indicator |
| Projects error state | None | `[AlertCircle]` + "Failed to load projects" + `[Retry]` |
| Delete button | Immediate (with `window.confirm`) | Shows `[spinner]` during mutation, toast "Deleted" on success before card animates out |
| Health Check | Basic server status only | Server vitals (uptime, PID, process count, DB size), version info |
| Accounts | Embedded in Health Check | Dedicated sub-page with add/remove actions, exhaustion status, usage bars |
| Workspace | None | `.cwrc` settings: workspace name, default execution mode |
| Danger Zone | None | Reset workspace, clear all data, destructive operations |
---
## Settings Layout
```
+=============================================================================+
| [CW] Initiatives Agents [*Settings*] [cmd-k] [sun] * |
+=============================================================================+
| |
| Settings |
| [heart] Health [key] Accounts [folder] Projects |
| [sliders] Workspace [alert-triangle] Danger Zone |
| ----------------------------------------------------------------------- |
| |
| <Settings Page Outlet> |
| |
+=============================================================================+
```
### Sub-page nav anatomy
- Each tab: Lucide icon (16px) + label, `gap-1.5`
- Active: `bg-muted text-foreground font-medium rounded-md px-3 py-1.5`
- Inactive: `text-muted-foreground hover:text-foreground px-3 py-1.5`
- Danger Zone tab: icon and text use `text-destructive` when active (not `text-foreground`)
- Tabs wrap to two rows naturally on narrower viewports (no breakpoint logic)
### Sub-page icons
| Sub-page | Lucide Icon | Route |
|----------|-------------|-------|
| Health | `HeartPulse` | `/settings/health` |
| Accounts | `KeyRound` | `/settings/accounts` |
| Projects | `FolderGit2` | `/settings/projects` |
| Workspace | `SlidersHorizontal` | `/settings/workspace` |
| Danger Zone | `AlertTriangle` | `/settings/danger` |
`/settings` redirects to `/settings/health`.
---
## Health Check -- Default State
```
+=============================================================================+
| Settings |
| [*heart*] Health [key] Accounts [folder] Projects ... |
| ----------------------------------------------------------------------- |
| [ Refresh ] |
| |
| SERVER VITALS |
| +-----------------------------------------------------------------------+ |
| | [CheckCircle] Running | |
| | | |
| | Uptime 2d 14h 32m PID 48291 | |
| | Started 2026-03-01 08:14 Process count 3 | |
| | Version 0.9.2 Database 4.2 MB | |
| +-----------------------------------------------------------------------+ |
| |
| REGISTERED PROJECTS (3) |
| +-----------------------------------------------------------------------+ |
| | [CheckCircle] backend github.com/org/backend-api Clone found | |
| | [CheckCircle] frontend github.com/org/frontend-app Clone found | |
| | [XCircle] shared github.com/org/shared-lib Clone missing| |
| +-----------------------------------------------------------------------+ |
| |
+=============================================================================+
```
### Server vitals card anatomy
Two-column key/value grid inside a single card. Keys are `text-xs text-muted-foreground`, values are `text-sm font-mono`.
| Field | Source | Notes |
|-------|--------|-------|
| Status | Always "Running" (if the page loads, the server is up) | `[CheckCircle]` success icon |
| Uptime | `server.uptime` from `systemHealthCheck` | Formatted as `Xd Xh Xm` |
| Started | `server.startedAt` | ISO datetime, formatted to locale |
| PID | `process.pid` from `status` endpoint | Integer |
| Process count | `health.processCount` | Active agent processes |
| Version | Package version from build | `font-mono` |
| Database | File size of SQLite `.db` file | Formatted as `X.X MB` |
The projects summary in health check is a read-only compact list (no edit actions). For full project management, use the Projects sub-page.
### Health Check -- Error State
```
+=============================================================================+
| Settings |
| [*heart*] Health [key] Accounts [folder] Projects ... |
| ----------------------------------------------------------------------- |
| |
| [AlertCircle] |
| Failed to load health data |
| |
| [ Retry ] |
| |
+=============================================================================+
```
Uses shared `<ErrorState>` component with `onRetry`.
---
## Accounts -- Default State
```
+=============================================================================+
| Settings |
| [heart] Health [*key*] Accounts [folder] Projects ... |
| ----------------------------------------------------------------------- |
| [ Refresh ] [ Add ] |
| |
| +-----------------------------------------------------------------------+ |
| | [CheckCircle] alice@company.com | |
| | [claude] [Pro] 2 agents (1 active) Available | |
| | | |
| | Session (5h) [========--------] 62% resets in 2h 14m | |
| | Weekly (7d) [=====-----------] 38% resets in 4d 11h | |
| | [trash] | |
| +-----------------------------------------------------------------------+ |
| |
| +-----------------------------------------------------------------------+ |
| | [AlertTriangle] bob@company.com | |
| | [claude] [Max] 1 agent (0 active) Exhausted | |
| | until 2:45 PM | |
| | | |
| | Session (5h) [================] 98% resets in 0h 32m | |
| | Weekly (7d) [=============---] 88% resets in 1d 6h | |
| | [trash] | |
| +-----------------------------------------------------------------------+ |
| |
+=============================================================================+
```
### Account card anatomy
Reuses the existing `<AccountCard>` component with two additions:
1. A `[trash]` delete button (bottom-right of card) with Shift+click bypass pattern
2. Exhaustion status uses `status-warning-*` tokens when exhausted
### Add Account dialog
`[ Add ]` opens a dialog:
```
+----------------------------------------------+
| Add Account [x] |
| |
| Provider [claude_____________v] |
| Email [_____________________] |
| |
| [ Cancel ] [ Add Account ]|
+----------------------------------------------+
```
- Provider dropdown populated from `listProviderNames` tRPC query
- Email is a text input, required
- On success: toast "Account added", invalidate `listAccounts`
### Accounts -- Empty State
```
+=============================================================================+
| Settings |
| [heart] Health [*key*] Accounts [folder] Projects ... |
| ----------------------------------------------------------------------- |
| |
| +-----------------------------------------------------------------------+ |
| | | |
| | [KeyRound] | |
| | No accounts registered | |
| | Use "cw account add" or click below. | |
| | | |
| | [ Add Account ] | |
| | | |
| +-----------------------------------------------------------------------+ |
| |
+=============================================================================+
```
Uses shared `<EmptyState>` with `KeyRound` icon.
---
## Projects -- Default State
```
+=============================================================================+
| Settings |
| [heart] Health [key] Accounts [*folder*] Projects ... |
| ----------------------------------------------------------------------- |
| [ Register Project ] |
| |
| +-----------------------------------------------------------------------+ |
| | backend [pencil] | |
| | github.com/org/backend-api [external-link] | |
| | | |
| | Default branch: main [pencil] | |
| | Initiatives: Auth Overhaul, Payments [trash] | |
| +-----------------------------------------------------------------------+ |
| |
| +-----------------------------------------------------------------------+ |
| | frontend [pencil] | |
| | github.com/org/frontend-app [external-link] | |
| | | |
| | Default branch: develop [pencil] | |
| | Initiatives: Auth Overhaul [trash] | |
| +-----------------------------------------------------------------------+ |
| |
+=============================================================================+
```
### Project card anatomy
```
+------------------------------------------------------------------------+
| <project-name> [pencil] |
| <project-url> [external-link] |
| |
| Default branch: <branch> [pencil] |
| Initiatives: <name>, <name> | [0 if none] [trash] |
+------------------------------------------------------------------------+
```
- Project name: `text-sm font-semibold`. The `[pencil]` next to it toggles inline name editing.
- Project URL: clickable `<a>` link, opens in new tab. `[external-link]` (ExternalLink icon, 12px) after URL. `text-xs text-muted-foreground hover:text-foreground underline-offset-2 hover:underline`.
- Default branch `[pencil]`: click to toggle inline branch editing (same as v1).
- Initiatives row: `text-xs text-muted-foreground`. Each initiative name is a link to `/initiatives/$id`. Shows "No initiatives" in dim text if none linked. Data from a new `getProjectInitiatives` query or joined from existing data.
- `[trash]` (Trash2 icon): click triggers `window.confirm()`; Shift+click bypasses. On successful delete, shows `toast.success("Project deleted")` before card animates out with `animate-out fade-out slide-out-to-left` (150ms).
### Inline name editing (click pencil next to name)
```
| [backend__________] [enter to save / esc to cancel] |
```
Same pattern as branch editing. Validates uniqueness client-side before save.
### Inline branch editing (click pencil next to branch)
```
| Default branch: [develop________] [enter to save / esc to cancel] |
```
---
## Projects -- Error State
```
+=============================================================================+
| Settings |
| [heart] Health [key] Accounts [*folder*] Projects ... |
| ----------------------------------------------------------------------- |
| |
| [AlertCircle] |
| Failed to load projects |
| |
| [ Retry ] |
| |
+=============================================================================+
```
- `[AlertCircle]` icon: `h-8 w-8 text-destructive`
- Error message: `text-sm text-destructive`
- `[ Retry ]` button: `variant="outline" size="sm"`, calls `projectsQuery.refetch()`
- `[ Register Project ]` button is hidden during error state
---
## Projects -- Delete In Progress
```
+------------------------------------------------------------------------+
| backend [pencil] |
| github.com/org/backend-api [external-link] |
| |
| Default branch: main [pencil] |
| Initiatives: Auth Overhaul [spinner] |
+------------------------------------------------------------------------+
```
- `[trash]` icon replaced by `[spinner]` (`Loader2` with `animate-spin`) during `deleteMutation.isPending`
- Button is `disabled` to prevent double-click
- Only the card being deleted shows the spinner; other cards remain interactive
- On success: `toast.success("Project deleted")` fires, then the card animates out (`animate-out fade-out slide-out-to-left`, 150ms duration)
---
## Projects -- Empty State
```
+=============================================================================+
| Settings |
| [heart] Health [key] Accounts [*folder*] Projects ... |
| ----------------------------------------------------------------------- |
| |
| +-----------------------------------------------------------------------+ |
| | | |
| | No projects registered | |
| | | |
| | [ Register Project ] | |
| | | |
| +-----------------------------------------------------------------------+ |
| |
+=============================================================================+
```
- `[ Register Project ]` button opens `RegisterProjectDialog`
- The top-right `[ Register Project ]` button is hidden when the empty state CTA is visible
---
## Projects -- Loading State
```
+=============================================================================+
| Settings |
| [heart] Health [key] Accounts [*folder*] Projects ... |
| ----------------------------------------------------------------------- |
| [ Register Project ] |
| |
| +-----------------------------------------------------------------------+ |
| | ░░░░░░░░░░░░░░ | |
| | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ | |
| | | |
| | ░░░░░░░░░░░░░░░░░░░░░ ░░ ░░ | |
| +-----------------------------------------------------------------------+ |
| |
| +-----------------------------------------------------------------------+ |
| | ░░░░░░░░░░░░░░ | |
| | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ | |
| | | |
| | ░░░░░░░░░░░░░░░░░░░░░ ░░ ░░ | |
| +-----------------------------------------------------------------------+ |
| |
+=============================================================================+
```
Skeleton cards mirror project card anatomy: name line, URL line, branch line with
pencil/trash placeholders. Shimmer animation sweeps left-to-right on a 1.5s loop.
---
## Workspace -- Default State
```
+=============================================================================+
| Settings |
| [heart] Health [key] Accounts [folder] Projects |
| [*sliders*] Workspace [alert-triangle] Danger Zone |
| ----------------------------------------------------------------------- |
| |
| GENERAL |
| +-----------------------------------------------------------------------+ |
| | Workspace root /Users/dev/my-project | |
| | Config file .cwrc (version 1) | |
| +-----------------------------------------------------------------------+ |
| |
| EXECUTION DEFAULTS |
| +-----------------------------------------------------------------------+ |
| | Default mode [REVIEW v] | |
| | New initiatives start in this execution mode. | |
| | | |
| | Merge approval [x] Require approval for merge tasks | |
| | Agents must get human sign-off before merging. | |
| +-----------------------------------------------------------------------+ |
| |
+=============================================================================+
```
### Workspace settings fields
| Field | Type | Source | Notes |
|-------|------|--------|-------|
| Workspace root | Read-only | `workspaceRoot` from server context | Display only, not editable |
| Config file | Read-only | Parsed `.cwrc` | Shows filename + version |
| Default mode | Select dropdown | `.cwrc` (future) | `review` or `yolo` |
| Merge approval | Checkbox | `.cwrc` (future) | Default for new initiatives |
These fields require extending the `.cwrc` config schema (currently `{ version: 1 }` only). Until the backend supports these, the section renders as read-only with a "Coming soon" badge on the editable fields.
---
## Danger Zone
```
+=============================================================================+
| Settings |
| [heart] Health [key] Accounts [folder] Projects |
| [sliders] Workspace [*alert-triangle*] Danger Zone |
| ----------------------------------------------------------------------- |
| |
| [AlertTriangle] These actions are irreversible. |
| |
| +-----------------------------------------------------------------------+ |
| | Clear all agent data | |
| | Removes all agent records, log chunks, and output history. | |
| | Projects, initiatives, and tasks are preserved. | |
| | [ Clear Agents ]| |
| +-----------------------------------------------------------------------+ |
| |
| +-----------------------------------------------------------------------+ |
| | Reset workspace | |
| | Deletes ALL data: initiatives, tasks, agents, accounts, projects. | |
| | The .cwrc config file and git repos are preserved on disk. | |
| | [ Reset Workspace ] | |
| +-----------------------------------------------------------------------+ |
| |
+=============================================================================+
```
### Danger Zone card anatomy
```
+------------------------------------------------------------------------+
| <action-title> text-sm font-semibold |
| <description> text-xs text-muted-fg |
| <preserved-note> text-xs text-muted-fg |
| [ Destructive Button ] |
+------------------------------------------------------------------------+
```
- Cards use `border-destructive/30` border tint
- Buttons use `variant="destructive"` styling
- Each button triggers a `window.confirm()` with explicit confirmation text: "Type RESET to confirm"
- Shift+click bypasses (consistent with app-wide pattern)
- Top banner: `[AlertTriangle]` icon with `text-destructive`, `text-sm font-medium`
---
## Source
- `packages/web/src/routes/settings.tsx`
- `packages/web/src/routes/settings/health.tsx`
- `packages/web/src/routes/settings/accounts.tsx` (proposed)
- `packages/web/src/routes/settings/projects.tsx`
- `packages/web/src/routes/settings/workspace.tsx` (proposed)
- `packages/web/src/routes/settings/danger.tsx` (proposed)
- `packages/web/src/components/RegisterProjectDialog.tsx`
- `packages/web/src/components/AccountCard.tsx`
- `packages/web/src/components/AddAccountDialog.tsx` (proposed)
---
## Design Review Notes
### What was improved in this revision
1. **Sub-page expansion (2 to 5 pages).** The original spec only had Health Check and Projects, which was embarrassingly thin for a workspace managing 10+ agents, multiple API accounts, and multiple git repos. Added: Accounts (dedicated), Workspace settings, Danger Zone. Each maps to real backend capabilities that already exist (`accountProcedures`, `.cwrc` config, `systemHealthCheck`).
2. **Health Check redesigned as a vitals dashboard.** The original wireframe said "Health Check: Unchanged" and showed nothing. The implementation (`health.tsx`) already renders server status, accounts, and projects -- but the wireframe never documented any of it. Now specced: server uptime, PID, process count, DB size, version, and a compact project clone status list. Accounts moved out to their own dedicated sub-page (they deserve more than a read-only summary).
3. **Accounts promoted to first-class sub-page.** The codebase already has `AccountCard` with full usage bars, exhaustion tracking, and agent counts. The health check page was cramming all this into a secondary section. Now accounts get their own page with add/remove actions (the tRPC procedures `addAccount` / `removeAccount` already exist), making it actually useful instead of display-only.
4. **Project cards enriched.** Three additions: (a) inline name editing alongside inline branch editing -- if you can edit the branch, you should be able to edit the name; (b) project URL is now a clickable external link (it was just dead text before -- why show a URL you cannot click?); (c) initiative cross-reference row showing which initiatives use this project (answers "can I safely delete this?").
5. **Delete flow improved.** Added explicit toast confirmation ("Project deleted") before card animates out. The spinner-only approach was correct for preventing double-click, but the user gets zero feedback that the delete succeeded -- the card just vanishes. A brief toast bridges that gap.
6. **Sub-page navigation given visual identity.** Plain text tabs for 5+ items is a mess. Added Lucide icons per sub-page with the same active/inactive styling from app-layout nav. Danger Zone gets destructive-red treatment to warn before you even click.
7. **Workspace settings page.** Currently `.cwrc` is `{ version: 1 }` with zero user-facing config. This wireframe establishes the UI surface for workspace-level defaults (execution mode, merge approval) so when the config schema grows, the frontend is ready. Read-only fields (workspace root, config version) provide orientation.
8. **Danger Zone.** Every serious tool needs one. Two graduated destructive actions: clear agent data (preserves structure) and full workspace reset (nuclear option). Confirmation requires typing "RESET" to prevent accidents. The Shift+click bypass pattern still applies for power users.
### What was NOT added (and why)
- **Keyboard shortcuts remapping page**: Skipped. The app has maybe 5 keyboard shortcuts total (tab switching 1-4, Cmd+K). A remapping UI is premature -- there is not enough shortcut surface to justify a settings page. Revisit when shortcuts exceed 15+.
- **Import/export settings**: Skipped. The `.cwrc` file is already a JSON file at the workspace root that can be committed to git. There is nothing else to export -- accounts are per-machine (OAuth tokens), projects are per-workspace. A dedicated import/export UI would be solving a problem that does not exist yet.
- **Notification preferences**: Skipped. The app has no notification system. Adding a preferences page for a feature that does not exist is pure wireframe theater.
- **Provider configuration page**: Skipped. Provider presets are code-level config (`src/agent/providers/presets.ts`) with 7 built-in providers. There is no user-facing need to edit provider CLI args or session ID extraction patterns. If custom providers are needed later, that is a CLI config concern, not a settings UI concern.
Reference in New Issue View Git Blame Copy Permalink