Skip to content

UI consolidation — research-backed best practices (ARGUS-120)

Input for the UI cleanup epic ARGUS-120, specifically 193 (nav consolidation), 125/126 (design-system foundation), and 123 (mobile/PWA). Complements the framework-choice doc 2026-06-26-ui-framework-review.md (Tailwind standalone + a component layer); this doc is about what to build, not with which tool.

Provenance / confidence (read first)

Produced via the deep-research harness (Scope → Search → Fetch → Verify → Synthesize). The search + extraction succeeded (15 sources, 25 claims), but the adversarial verification pass could not run — Anthropic's API rate-limited (a server-side 429, "not your usage limit") the ~75 concurrent verifier calls, so the harness marked every claim "unverified." Two re-runs hit the same limit (the harness's heavy fan-out + shared API key bursts past the per-minute ceiling).

So: these are sourced best-practice, not independently double-checked. They are mainstream, mutually consistent UX consensus from credible sources (Linear's own redesign writeup, IxDF, LogRocket, setproduct, pencilandpaper, GoodData, Imperavi), and are sanity-checked against domain knowledge — but the confidence layer is missing. Treat the recommendations as strong defaults, not gospel.

1. Information architecture / navigation → ARGUS-193

Findings (sourced): - Cap top-level nav at ~5 sections (≤5 primary for data-heavy apps [AlterSquare]; 5–7 tabs before overwhelm [LogRocket]; top-bar suits ≤6 flat sections [IGC]). The 15 → 5 plan is squarely in range. - Primary nav = sections; sub-navigation = in-page segmented control. Tabs are a secondary pattern, not primary [LogRocket]; tabs fit 2–6 peer views shown one at a time, dropdown beyond that [setproduct]. → top-bar picks the section, an in-page segment switches the detail. - Group by user task / workflow, not by technical module or data-type [IGC]. This is the heuristic to apply to our heterogeneous pages. - Overview → drill-down; don't mix dissimilar data on one surface [GoodData]. Each section is its own coherent view. - Dashboard IA checklist: Structure, Navigation, Hierarchy, Grouping, Labeling, Filtering [GoodData].

Unresolved tension (decide explicitly): sources disagree on top-bar vs sidebar at ~5 sections. Some favor a sidebar for data-dense tools ("holds more, easier to scan, common in dashboards" [IxDF]; "sidebar = primary nav" [LogRocket]); Linear uses an inverted-L (top bar + sidebar) [Linear]; others say a top-bar is correct at ≤6 flat sections [IGC]. Recommendation: keep the existing top-bar for 5 sections (lowest-risk, already built, fine at this count) + in-page segments for detail. Revisit a left sidebar only if sections grow past ~7 or sub-nav deepens.

Proposed consolidation (from 15):

Section Folds in (today's pages) Sub-nav
Tasks tasks board board / backlog toggle (exists)
Memory notes, episodes, injections, feed, review, projects segmented sub-tabs
Activity runs, agent-runs, research/artifacts segmented sub-tabs
Skills skills, lint segmented sub-tabs
Config telegram, jobs, parked segmented sub-tabs

Caveat per the "group by task not data-type" heuristic: "Activity" and "Config" are data-type buckets — pressure-test whether they map to real workflows. (E.g. is "research artifacts" an Activity, or does it belong with Memory as knowledge output?)

2. Visual design system → ARGUS-125/126

  • Few-variable theming in a perceptual color space. Linear reduced their dark system to ~3 inputs (base, accent, contrast) over LCH, deriving all surface elevations from it [Linear]. Validates the "remap legacy.css onto peacock CSS variables" strategy — build on a small semantic token set (OKLCH), not per-page colors.
  • Restrained accent. Peacock/teal sparingly as chrome, not saturating everything; raise text/icon contrast in dark mode [Linear].
  • Status ≠ color alone. Pair every status with a glyph + label; avoid the "rainbow salad" [pencilandpaper]. (Our "done = blue check, never green" already aligns.)
  • Typeface: Inter (or a tabular-figures UI font). Purpose-built for UI; the default at GitHub/Figma/Linear/Vercel/Notion; ships tabular figures by default so numerals column-align with no OpenType fiddling — ideal for the run-duration / count tables [madegooddesigns].
  • Type scale: small modular ratio for dense UIs + add extra small sizes; don't use a marketing-sized scale [Imperavi].
  • Spacing: 8-point grid baseline [UXPlanet].
  • Tables: left-align text, right-align numbers, never center; offer density modes (~40 / 48 / 56px rows); progressive disclosure — show less by default [pencilandpaper].

3. Mobile / PWA → ARGUS-123

  • 4–5 bottom-tab ceiling, scroll don't wrap to a second row, 48×48px touch targets, bottom bar for thumb reach [setproduct, IxDF]. Consolidating to 5 sections lets the mobile bottom bar mirror desktop 1:1.
  • Tables → cards / bottom-sheets on small screens, never horizontal scroll; replace hover with explicit buttons [AlterSquare]. (We already ship md:hidden card variants — keep that pattern.)

4. Product-model fit

Evidence leans Linear for the shell + visual system (few-variable LCH theming, restrained accent, top-bar + content + side-panel chrome, calm density) and Grafana-style discipline for the data views (row-density modes, tabular figures, status systems). → Linear-style chrome, Grafana-style rigor inside the data-heavy pages.

Net recommendation

  • 193: keep the top-bar; 5 task-grouped sections + in-page segmented sub-tabs; mobile bottom bar mirrors the 5. Re-examine the Activity/Config groupings against "group by task."
  • 125/126: small OKLCH semantic-token set; peacock as a restrained accent; Inter with tabular figures; small type scale + extra small sizes; 8pt spacing; status = glyph + label.
  • 123: 48px targets; cards over horizontal-scroll tables; bottom sheets for actions.

What verification would add (deferred)

The adversarial pass would have stress-tested the "magic numbers" (5 vs 7 sections, 40/48/56px rows) and the top-bar-vs-sidebar claim. Re-run when the API isn't rate-limited (lower the harness fan-out / VOTES_PER_CLAIM, or run off-peak). The recommendations above don't hinge on any single disputed number.

Sources

  • Linear — How we redesigned the Linear UI (primary): https://linear.app/now/how-we-redesigned-the-linear-ui
  • Interaction Design Foundation — Navigation: https://ixdf.org/literature/topics/navigation
  • LogRocket — Tabs UX best practices: https://blog.logrocket.com/ux-design/tabs-ux-best-practices/
  • setproduct — Tabs UI design: https://www.setproduct.com/blog/tabs-ui-design
  • pencilandpaper — Data dashboards: https://www.pencilandpaper.io/articles/ux-pattern-analysis-data-dashboards
  • pencilandpaper — Enterprise data tables: https://www.pencilandpaper.io/articles/ux-pattern-analysis-enterprise-data-tables
  • GoodData — Six principles of dashboard IA: https://medium.com/gooddata-developers/six-principles-of-dashboards-information-architecture-5487d84c20c4
  • AlterSquare — Designing for data-heavy workflows: https://altersquare.io/designing-ui-applications-heavy-data-workflows/
  • Imperavi — UI Typography, modular scale: https://imperavi.com/books/ui-typography/principles/modular-scale
  • madegooddesigns — Inter font: https://madegooddesigns.com/inter-font/
  • UXPlanet — 8-point grid: https://uxplanet.org/everything-you-should-know-about-8-point-grid-system-in-ux-design-b69cb945b18d
  • Intelligent Graphic & Code — Information architecture: https://www.intelligentgraphicandcode.com/design/information-architecture