Cockpit UX Principles
Here, "richer" means stronger grouping, clearer actions, better links, and more useful details on request. It does not mean longer default text.
Design Bar
- Show host status first: workspaces, approvals, blockers, dirty components, and active threads.
- Make blocked work actionable: each blocking card needs a clear next step and, when possible, a provider link or resume action.
- Keep text short in the default view. Use compact labels, counts, status chips, and recognizable provider icons.
- Put deeper evidence behind click, drawer, popover, or diagnostics mode.
- Do not show raw ISO dates, raw ids, stack-like strings, or JSON-shaped text in the primary cockpit.
Source Notes
| Source | Useful pattern | DevNexus implication |
|---|---|---|
| Shneiderman, The Eyes Have It | Overview first, zoom/filter, details on demand. | Host cockpit first, workspace drill-down second, raw evidence only on demand. |
| NN/g usability heuristics | System status, familiar language, recognition over recall, minimalist design. | Use words like approval, issue, PR, or thread instead of internal labels. |
| NN/g progressive disclosure | Show the most important options first; defer rare detail. | Cards should answer "what needs me?" before they expose diagnostics. |
| OpenAI Agents SDK HITL | Agent runs can pause for approval, store state, and resume. | Model approval as an interrupt with approve, reject, resume, and inspect actions. |
| Git Graph for VS Code | Dense branch graph, compact refs, click-to-open commit detail and file changes. | Work history should be compact and clickable; labels should clarify topology. |
| GitHub Projects | Multiple views over issues and PRs, with filters, fields, and automation. | Provider records should stay linked in place, such as #42: title with a provider icon. |
| GitHub issue and PR dashboards | Cross-repository views for assigned, mentioned, stale, and review-needed work. | A host cockpit should summarize all registered workspaces, not only switch between them. |
| Linear triage | A dedicated inbox for work from integrations or other teams. | Use a host action queue for approvals, review, rescue, archive, and forget decisions. |
| Linear display options | Views can group, order, switch layouts, and persist personal defaults. | Let users change grouping without creating several permanent dashboards. |
| Sentry issue status | Issue status drives triage, archive, resolve, and regression flow. | Thread cleanup should use explicit states: continue, archive, forget, rescue, merged, or blocked. |
| Sentry issue details | High-level issue actions stay in the header; heavy evidence lives below. | Keep summary and actions at top, with evidence and diagnostics lower down. |
| Backstage catalog | A host portal organizes components and plugins around catalog entities. | Components and plugins belong in the host cockpit, with workspace pages as drill-downs. |
| Grafana dashboard practices | Dashboards should answer a question, reduce cognitive load, and use drill-down links. | Each cockpit region needs one job: "what needs me?", "what changed?", or "where do I go?" |
| Grafana dashboard links | Links preserve context and can open specific dashboards or external systems. | Provider buttons should carry context and signal external navigation with an icon. |
| Argo CD overview | Health, sync, drift, and manual sync are exposed as compact operational state. | Components need simple health language: clean, dirty, blocked, stale, unknown. |
| Ray Dashboard | Overview panes show cluster status, recent jobs, events, and links to logs. | Separate host overview, recent threads, work map, and diagnostics. |
Product Principles
- The host cockpit is the control room.
- The first question is "what needs a human now?"
- Every blocked item needs a primary action, not just an explanation.
- Details open in place and preserve context.
- Provider links show the provider, short id, title, and external-link affordance.
- Work history should show shape and movement, not every field.
- Threads are first-class work artifacts.
- Plugins are part of the cockpit.
- Diagnostics are a mode, not the default cockpit.
Anti-Patterns
- Long explanations in cards.
- Raw timestamps such as
2026-05-20T19:36:20.769Z. - Raw ids without a human label.
- Lane labels that overlap or only make sense after selecting a row.
- Repeating a lane name inside every row label.
- Hiding the only useful action in a separate card far below the selected item.
- Treating advisory leases as the main source of truth for active work.