Paperclip's UI is a professional-grade control plane, not a toy dashboard. It should feel like the kind of tool you live in all day — fast, keyboard-driven, information-dense without being cluttered, dark-themed by default. Every pixel should earn its place.
Design principles:
- **Dense but scannable.** Show maximum information without requiring clicks to reveal it. Use whitespace to separate, not to pad.
- **Keyboard-first.** Global shortcuts for search (Cmd+K), new issue (C), navigation. Power users should rarely touch the mouse.
- **Contextual, not modal.** Inline editing over dialog boxes. Dropdowns over page navigations. The user's mental context should never be broken unnecessarily.
- **Dark theme default.** Neutral grays, not pure black. Accent colors used sparingly for status and priority. Text is the primary visual element.
### Color System
- **Background:** `hsl(220, 13%, 10%)` (dark charcoal, not pure black)
- **Font:** System font stack (Inter if loaded, else `-apple-system, BlinkMacSystemFont, 'Segoe UI'`)
- **Body:** 13px / 1.5 line-height
- **Labels/metadata:** 11px / uppercase tracking
- **Headings:** 14-18px / semi-bold, never all-caps
### Icons
Use `lucide-react` throughout. Every sidebar item, every status indicator, every action button should have an icon. Icons are 16px in nav, 14px inline.
- **Properties panel:** Right side, 320px. Shown on detail views (issue detail, project detail, agent detail). Hidden on list views and dashboard. Resizable.
The properties panel slides in when you click into a detail view and slides out when you go back to a list. It is NOT a sidebar — it's contextual to the selected entity.
---
## 3. Sidebar
The sidebar is the primary navigation. It is grouped into logical sections with collapsible headers.
### 3.1 Company Header
Top of sidebar. Always visible.
```
┌─────────────────────────┐
│ [icon] Acme Corp ▼ │ ← Company switcher dropdown
├─────────────────────────┤
│ [🔍] [✏️] │ ← Search + New Issue
└─────────────────────────┘
```
**Company switcher** is a dropdown button that occupies the full width of the sidebar header. It shows:
- Company icon (first letter avatar with company color, or uploaded icon)
- Company name (truncated with ellipsis if long)
- Chevron-down icon
Clicking opens a dropdown with:
- List of all companies (with status dot: green=active, yellow=paused, gray=archived)
- Search field at top of dropdown (for users with many companies)
- **Inbox** — items requiring the board operator's attention. Badge count on the right. Includes: pending approvals, budget alerts, failed heartbeats. The number is the total unread/unresolved count.
- **Dashboard** — company health overview: agent statuses, task velocity, cost burn, pending approvals count.
- **Org Chart** — interactive tree visualization of the agent reporting hierarchy.
- **Agents** — flat list of all agents with status, role, last heartbeat, spend.
- **Costs** — cost dashboard with breakdowns by agent, project, model, time.
- **Activity** — audit log of all system events.
Note: Approvals do not have a top-level sidebar entry. They are surfaced through the **Inbox** (primary interaction point), **Dashboard** (pending count metric), and **inline on entity pages** (e.g., an agent detail page shows the approval that authorized its hire). The `/approvals` route still exists and is reachable via "See all approvals" links in Inbox and Dashboard, but it is not in the sidebar navigation.
### 3.5 Section Behavior
- Each section header is clickable to collapse/expand its children.
- Collapsed state persists in localStorage.
- Active nav item is highlighted with a left-border accent and background tint.
- Hovering a nav item shows a subtle background highlight.
- Badge counts are right-aligned, rendered as small pills (e.g., `3` in a rounded rect).
- Icons are 16px, left-aligned, with 8px gap to label text.
### 3.6 Sidebar Icons
Each nav item has a distinctive icon (lucide-react):
| Item | Icon |
|------|------|
| Inbox | `Inbox` |
| My Issues | `CircleUser` |
| Issues | `CircleDot` |
| Projects | `Hexagon` |
| Goals | `Target` |
| Views | `LayoutList` |
| Dashboard | `LayoutDashboard` |
| Org Chart | `GitBranch` |
| Agents | `Bot` |
| Costs | `DollarSign` |
| Activity | `History` |
---
## 4. Breadcrumb Bar
The breadcrumb bar sits above the main content and properties panel. It serves as both navigation and context indicator.
- **Status tabs:** `All Issues`, `Active` (todo + in_progress + in_review + blocked), `Backlog`. Each tab shows a status icon and count. Active tab is filled, others outlined.
- **Filter button:** Opens a filter bar below the toolbar.
- **Display dropdown:** Toggle between grouping modes (by status, by priority, by assignee, by project, none) and layout modes (list, board/kanban).
**Grouping:**
- Issues are grouped by status by default (matching the reference screenshots).
- Each group header shows: collapse chevron, status icon, status name, count, and a `+` button to create a new issue in that status.
- Groups are collapsible. Collapsed groups show just the header with count.
**Issue rows:**
Each row contains, left to right:
1.**Checkbox** — for bulk selection. Hidden by default, appears on hover (left of priority).
2.**Priority indicator** — icon representing critical/high/medium/low (see Color System above). Always visible.
3.**Issue key** — e.g., `CLIP-5`. Monospace, muted color. The prefix is derived from the project (or company if no project).
4.**Status circle** — clickable to open status change dropdown (same as reference screenshot). The circle's fill/color reflects current status.
5.**Title** — primary text, truncated with ellipsis if too long.
6.**Assignee** — avatar (agent icon) + agent name, right-aligned. If unassigned, shows a dashed circle placeholder.
7.**Date** — creation date or target date, muted text, far right.
**Row interactions:**
- Click row → navigate to issue detail view.
- Click status circle → opens inline status dropdown (Backlog, Todo, In Progress, In Review, Done, Cancelled) with keyboard numbers as shortcuts (1-6).
- Click checkbox → selects for bulk actions. When any checkbox is selected, a bulk action bar appears at the bottom of the list.
- Issue title, large (18px, semi-bold), editable on click (inline editing).
- Subtitle: issue key `CLIP-42` in muted text.
- Below the title: inline properties bar showing key properties as clickable chips (same pattern as reference screenshots): `[○ In Progress] [!!! High] [👤 CTO] [📅 Target date] [📁 Auth] [···]`. Each chip is clickable to change that property inline.
**Description:**
- Markdown-rendered description.
- Click to edit — opens a markdown editor in-place.
- Support for headings, lists, code blocks, links, images.
**Subtasks (if any):**
- Listed below description as a collapsible section.
- Each subtask is a mini issue row (status circle + title + assignee).
-`+ Add subtask` button at the bottom.
**Comments:**
- Chronological list of comments.
- Each comment shows: author avatar/icon, author name, timestamp, body (markdown rendered).
- Comment input at the bottom — a text area with markdown support and a "Comment" button.
- Comments from agents show a bot icon; comments from the board show a user icon.
#### Right Pane (Properties Panel)
**Header:** "Properties" label with a `+` button to add a custom field.
**Property list:** Each property is a row with label on the left and editable value on the right.
| Property | Control |
|----------|---------|
| Status | Dropdown with status options + colored dot |
| Priority | Dropdown with priority options + icon |
| Assignee | Agent picker dropdown with search |
| Project | Project picker dropdown |
| Goal | Goal picker dropdown |
| Labels | Multi-select tag input |
| Lead | Agent picker |
| Members | Multi-select agent picker |
| Start date | Date picker |
| Target date | Date picker |
| Created by | Read-only text |
| Created | Read-only timestamp |
| Billing code | Text input |
Below properties, a divider, then:
**Activity section:**
- "Activity" header with "See all" link.
- Compact timeline of recent events: status changes, assignment changes, comments, etc.
- Each entry: icon + description + relative timestamp.
### 5.4 New Issue Modal
Triggered by the sidebar pencil icon, keyboard shortcut `C`, or the `+` buttons in the issue list.
- "Create more" toggle — when on, creating an issue clears the form and stays open for rapid entry.
- "Create issue" primary button.
**Behavior:**
-`Cmd+Enter` submits the form.
- If opened from within a project context, the project is pre-filled.
- If opened from a specific status group's `+` button, that status is pre-filled.
- The slug/key is auto-generated from the project prefix + incrementing number (shown in breadcrumb).
### 5.5 Issue Board View (Kanban)
Accessible via Display dropdown → Board layout.
Columns represent statuses: Backlog | Todo | In Progress | In Review | Done
Each card shows:
- Issue key (muted)
- Title (primary text)
- Priority icon (bottom-left)
- Assignee avatar (bottom-right)
Cards are draggable between columns. Dragging a card to a new column changes its status (with transition validation — invalid transitions show an error toast).
Each column header has a `+` button to create a new issue in that status.
**Heartbeats tab:** table of heartbeat runs — time, source (manual/scheduler), status, duration, error (if any). Invoke button at top.
**Issues tab:** issues assigned to this agent.
**Costs tab:** cost breakdown for this agent — by model, by time period, with budget progress bar.
**Right pane properties:** Status, Role, Title, Reports To, Adapter Type, Context Mode, Budget (monthly), Spent (monthly), Last Heartbeat.
**Quick actions** in breadcrumb bar: [Pause] [Resume] [Invoke Heartbeat] [···]
---
## 11. Approvals (Contextual, Not Standalone)
Approvals are governance gates — decisions the board must make (hire an agent, approve a CEO strategy). They are NOT work items. Their data model stays separate from issues (different status machine, side-effect triggers, unstructured payload). But they don't need their own top-level nav entry.
### 11.1 Where Approvals Surface
**1. Inbox (primary).** Pending approvals are the highest-priority inbox items. The board operator sees them front and center with inline approve/reject actions (see Section 14).
**2. Dashboard metric card.** The "Pending Approvals" card shows the count and links to the full approvals list.
**3. Inline on entity pages.** When an entity was created via an approval, the detail page shows a contextual banner:
- Agent detail page: `"Hired via approval — requested by CEO on Feb 15"` with a link to the approval record.
- An agent in `pending` status (not yet created) could show: `"Pending approval — requested by CEO"` with approve/reject actions inline.
**4. Activity log.** Approval events (created, approved, rejected) appear in the activity timeline like any other event.
### 11.2 Approvals List Page (`/approvals`)
This page still exists — it's the "See all" destination from Inbox and Dashboard. But it's not in the sidebar.
Status tabs filter by approval status. Each row: status dot, type, title/summary (from payload), requester, relative time.
### 11.3 Approval Detail View
Three-pane layout. Middle pane renders the approval payload nicely based on type:
**`hire_agent` type:** Shows proposed agent name, role, title, reports-to, capabilities, adapter config, budget. Essentially a preview of the agent that will be created.
Each entry: actor icon (bot for agent, user for board, gear for system), actor name, action description with entity links, relative timestamp.
Filterable by: actor type (agent/user/system), entity type (issue/agent/project/etc), action type, time range.
Infinite scroll with "Load more" fallback.
---
## 14. Inbox
The inbox is the board operator's primary action center. It aggregates everything that needs human attention, with approvals as the highest-priority category.
Items are grouped by category, with the most actionable items first:
**Approvals pending** (top priority). Each approval item shows:
- Shield icon + approval type + title
- Requester + relative timestamp
- Key payload summary (1 line — agent name/role for hires, plan title for strategies)
- Inline **[Approve]** and **[Reject]** buttons for simple approvals (hire_agent). Clicking Approve/Reject shows a brief confirmation with an optional decision note field.
- **[View details →]** link for complex approvals (approve_ceo_strategy) that need full review before deciding.
- "See all approvals →" link in the category header navigates to `/approvals`.
**Alerts.** Agent errors (failed heartbeats, error status) and budget alerts (agents or company approaching 80% or 100% limits). Each links to the relevant agent or cost page.
**Stale work.** Tasks in `in_progress` or `todo` with no activity (no comments, no status changes) beyond a configurable threshold (default: 24h). Each shows issue key, title, and time since last activity. Clicking navigates to the issue.
### 14.3 Inbox Behavior
- Unread items have a filled blue dot indicator on the left.
- Clicking an item marks it as read.
- Approvals disappear from the inbox once approved/rejected (they move to the resolved state).
- Alerts disappear when the underlying condition is resolved (agent resumed, budget increased).
- The sidebar badge count reflects total unresolved inbox items.
- Inbox is computed from live data (pending approvals query + alert conditions), not a separate notification table. This keeps it simple for V1.
---
## 15. Search (Cmd+K Modal)
Global search accessible via `Cmd+K` or the sidebar search icon.
