12 KiB

Raw Blame History

Roadmap Page — UI Audit & Redesign Proposal

Audited by: Ripley
Date: 2026-05-11
Component: client/components/AdminDashboard.jsx
Route: /admin/roadmap (rendered via AboutPage admin prop)
Framework: Vite + React + Tailwind CSS + shadcn/ui + Radix

Current State

The Roadmap page is an admin-only dashboard embedded inside AboutPage.jsx. It parses FUTURE.md and DEVELOPMENT_LOG.md via the /api/about-admin endpoint and renders two sections: a Roadmap card and a Development Activity Log card.

Problems

1. It's Not a Real Page — It's an Appendix to About

The roadmap is rendered inside AboutPage.jsx with an admin prop. The /admin/roadmap route literally renders <AboutPage admin />. This means:

The standard About page content (version cards, "Produced with AI" blurb, Sign In button) renders below the admin dashboard. An admin sees both the dashboard and the public about page stacked vertically.
The "Back" button links to /login — wrong for an admin navigating from the sidebar.
No dedicated page identity. It doesn't feel like a destination, it feels like a data dump tacked onto another page.

2. Two Giant Scrollboxes Trapped in Cards

Both Roadmap and Activity Log are max-h-[500px] scroll containers nested inside Card components. This creates:

Scroll-in-scroll: The page itself scrolls, and then each card has its own internal scroll. Users fight nested scroll areas.
500px is arbitrary and too short — on a 1080p screen with browser chrome, you see maybe 5-6 roadmap items before needing to scroll inside the card. With 10+ items now, most are hidden.
No visual indicator that content is scrollable — no fade-out gradient, no scroll shadow, nothing signals "there's more below."

3. Collapsible Everything = Nothing Visible at a Glance

Every roadmap item is a SimpleCollapsible (custom, not shadcn). CRITICAL and HIGH start expanded, but MEDIUM/LOW/NICE-TO-HAVE are collapsed. This means:

6 out of 10 items are invisible by default — you see 4 items, then 6 collapsed headers you have to click one by one.
The collapsible headers show a priority badge + title, but no description, no effort estimate, no status beyond "PENDING" — you have to click each one to learn anything.
No way to expand all / collapse all.
SimpleCollapsible is a custom component when shadcn has Collapsible (Radix-based, accessible, animated).

4. No Priority Grouping or Visual Hierarchy

All roadmap items render as a flat list inside a single scroll container. The priority emoji/badge is the only differentiator:

No section headers (CRITICAL / HIGH / MEDIUM / LOW) — items from different priorities blend together.
No count indicators ("2 Critical, 3 High, 4 Medium...").
No way to filter by priority or toggle visibility of entire tiers.
The PRIORITY_COLORS object defines border-l-4 left borders but the visual weight difference between orange and yellow on a dark theme is subtle.

5. Description Content Is Raw Markdown Dump

The parseFutureMarkdown function concatenates description, rationale, and implementation notes into a single description string with whitespace-pre-wrap. This means:

Markdown formatting (**Description:**, **Rationale:**, bullet points) renders as literal text, not styled content.
No visual separation between Description, Rationale, and Implementation Notes.
Long implementation notes (the business logic item has code blocks) just dump as plain text.
The markdown headers (**Description:**, etc.) show as bold text but with no structure — looks like a raw file view.

6. Activity Log Is Broken / Useless

The parseDevLogMarkdown function splits on --- horizontal rules and tries to parse the development log. Problems:

The actual DEVELOPMENT_LOG.md format doesn't consistently use --- separators between entries — it uses ### headers. The parser misses most entries.
devLogEntries often comes back nearly empty or with badly parsed data.
Each entry is a DevLogEntry component that's also collapsible (collapsed by default), so you're clicking to expand... inside a scrollbox... inside a card. Three layers of hiding.
The dev log is 54KB of data being shipped to the frontend on every page load. Most admins never look at it.

7. No Interactivity or Actionability

This is a read-only data wall. There's no:

Way to reorder priorities
Way to mark an item as "in progress" or "started"
Link to create a dispatch for an agent
Progress indicator (how many items done vs pending)
Filter or search
Sorting (by priority, by date added, by effort)

8. Version Badge Is Orphaned

A lone Badge with the version number floats at the top of the component with no label, no context, no styling weight. It looks like it fell out of another component.

9. No Responsive Consideration

The component renders the same way at every breakpoint. On mobile:

The 500px scroll containers are worse (less visible content).
Collapsible headers with badges + long titles overflow or wrap poorly.
No card reflow for small screens.

10. Accessibility Issues

SimpleCollapsible uses a div with onClick — not a button, no aria-expanded, no keyboard activation.
The scroll containers have no role or aria-label.
No skip links within the dashboard sections.
The priority emojis (🔴🟠🟡🔵💭) have no text alternatives for screen readers.

Redesign Proposal

Core Concept: Kanban-Style Priority Lanes

Replace the single flat scrollbox with a horizontal lane layout — one column per priority tier. Each lane shows its items as compact cards. This gives admins an at-a-glance view of the entire roadmap without scrolling or clicking.

Architecture Changes

Make it a standalone page — RoadmapPage.jsx, not AboutPage admin. The /admin/roadmap route should render its own component with its own layout, header, and identity.
Use shadcn Tabs for the two sections (Roadmap / Activity Log) instead of stacking two cards.
Separate the About page — admins who navigate to /admin/roadmap shouldn't see the public about page below it.

Roadmap Tab Layout

┌─────────────────────────────────────────────────────┐
│  🗺️ Roadmap                        v0.24.4         │
│  ┌─────────┬─────────┬─────────┬─────────┬─────────┐ │
│  │CRITICAL │ HIGH    │ MEDIUM  │ LOW     │ NICE    │ │
│  │ (1)     │ (3)     │ (4)     │ (3)     │ (1)     │ │
│  ├─────────┼─────────┼─────────┼─────────┼─────────┤ │
│  │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ │
│  │ │Item │ │ │Item │ │ │Item │ │ │Item │ │ │Item │ │ │
│  │ │card │ │ │card │ │ │card │ │ │card │ │ │card │ │ │
│  │ └─────┘ │ └─────┘ │ └─────┘ │ └─────┘ │ └─────┘ │ │
│  │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │         │ │
│  │ │     │ │ │card │ │ │card │ │ │card │ │         │ │
│  │ └─────┘ │ └─────┘ │ └─────┘ │ └─────┘ │         │ │
│  │         │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │         │ │
│  │         │ │card │ │ │card │ │ │card │ │         │ │
│  │         │ └─────┘ │ └─────┘ │ └─────┘ │         │ │
│  └─────────┴─────────┴─────────┴─────────┴─────────┘ │
└─────────────────────────────────────────────────────┘

On mobile (below lg breakpoint): lanes stack vertically with each lane as a collapsible section (using shadcn Collapsible or Accordion).

Item Card Design (compact, scannable)

┌─────────────────────────┐
│ 🔴 CRITICAL             │  ← Priority badge
│ No Confirmation Before  │  ← Title (bold, 2-3 lines max)
│ Destructive Actions     │
│                         │
│ Added: 2026-05-11       │  ← Meta line (date, agent)
│ Est: 3-4h              │  ← Effort estimate
│                         │
│ [Expand ▸]              │  ← Click to see full details
└─────────────────────────┘

Expanded card shows Description, Rationale, Implementation Notes as properly styled sections (not raw markdown dump).

Activity Log Tab

Replace the broken parseDevLogMarkdown with a simpler timeline format — just show version, date, agents involved, files modified. No full content dump.
Consider lazy-loading: only fetch developmentLog when the Activity Log tab is selected (it's 54KB of data nobody needs on page load).
Timeline format (vertical):

v0.24.4 — 2026-05-11
  Scarlett ✅ 12m | Neo ✅ 3m | Bishop ✅ 7m
  5 files modified
  [▸ Expand details]

v0.23.2 — 2026-05-10
  Neo ✅ | Bishop ✅
  3 files modified

Component Inventory (what to use)

Need	Use
Page container	Standalone `RoadmapPage.jsx`
Priority lanes	CSS Grid (`grid-cols-5` on `lg`, `grid-cols-1` on mobile)
Lane sections	`Card` with colored top border from `PRIORITY_COLORS`
Item cards	`Card` with `CardHeader`/`CardContent`
Item expand/collapse	shadcn `Collapsible` (Radix, accessible)
Tab switching	shadcn `Tabs` / `TabsList` / `TabsTrigger`
Priority badges	Keep current `Badge` + emoji approach, add `aria-label`
Scroll	Page-level scroll only, no nested scroll containers
Expand All / Collapse All	`Button` at top of Roadmap tab
Item count per lane	`Badge` variant="outline" in lane header

Files to Modify

File	Change
`client/components/AdminDashboard.jsx`	Delete (replaced by RoadmapPage)
`client/pages/AboutPage.jsx`	Remove `admin` prop, remove AdminDashboard import — AboutPage goes back to being a public-only page
`client/pages/RoadmapPage.jsx`	New — standalone roadmap page
`client/App.jsx`	Update `/admin/roadmap` route to render `<RoadmapPage />` instead of `<AboutPage admin />`; possibly add `/admin/about` route if admins need the about page
`client/api.js`	No changes needed (same endpoint)

Data Parsing Improvements

Parse FUTURE.md into structured sections — separate Description, Rationale, Implementation Notes into distinct fields on the item object instead of concatenating into one description blob.
Extract effort estimate from Implementation Notes (Estimated effort: 3-4 hours → effort: "3-4h").
Lazy-load dev log — only call /api/about-admin with developmentLog when the Activity Log tab is active, or split the API into two endpoints.

Responsive Breakpoints

Breakpoint	Layout
`< sm` (mobile)	Single column, lanes stack vertically as collapsible sections
`sm–lg` (tablet)	2 columns (CRITICAL+HIGH
`lg+` (desktop)	5 columns, one per priority tier

Accessibility Fixes

Replace SimpleCollapsible div+onClick with shadcn Collapsible (button trigger, aria-expanded, keyboard support)
Add aria-label to priority badges (e.g., aria-label="Critical priority")
Add role="region" and aria-label to lane sections
Ensure all interactive elements are keyboard-focusable
Add aria-live="polite" to expand/collapse regions

Priority for Implementation

This is a MEDIUM priority redesign. The current page works for data display but fails at being a useful admin tool. The kanban-style layout and proper parsing would make it genuinely useful for planning.

Estimated effort: 8-12 hours (Scarlett for UI, Neo for API split if lazy-loading)

12 KiB Raw Blame History Unescape Escape