227 lines
12 KiB
Markdown
227 lines
12 KiB
Markdown
# 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) |