BillTracker/docs/ROADMAP_UI_AUDIT.md

# 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

1. **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.
2. **Use shadcn Tabs** for the two sections (Roadmap / Activity Log) instead of stacking two cards.
3. **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 | MEDIUM+LOW+NICE) |
| `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)