# Roadmap: Xtablo v3.0 Design System & Visual Polish

**Created:** 2026-05-16
**Project mode:** Brownfield milestone on existing Go+HTMX backend
**Milestone:** v3.0 — Design System & Visual Polish

5 phases, sequential. Phase numbering continues from v2.0, so v3.0 starts at Phase 13.

---

## Previous Milestones

- [x] **v2.0 Collaboration, Planning, and Social Sign-in** — Phases 8-12, shipped 2026-05-16. Archive: [`milestones/v2.0-ROADMAP.md`](milestones/v2.0-ROADMAP.md)

---

## Phase Summary

| # | Phase | Goal | Requirements |
|---|-------|------|--------------|
| 13 | 5/5 | Complete    | 2026-05-16 |
| 14 | 1/2 | In Progress|  |
| 15 | Dashboard & Tablos | Restyle sidebar and tablo list to match JS app | DASH-01..03 |
| 16 | Tablo Detail | Restyle tasks, etapes, and files views | DETAIL-01..04 |
| 17 | Chat & Planning | Restyle discussion and planning pages | CHAT-UI-01, PLAN-UI-01 |

---

## Phase Details

### Phase 13: Design System Foundation
**Goal:** Replace the minimal `backend/internal/web/ui` with a full design system ported from `go-backend/internal/web/ui` — tokens, components, and Tailwind integration — so every subsequent phase has a stable component library to consume.
**Mode:** mvp
**Status:** Pending
**Requirements:** DS-01, DS-02, DS-03, DS-04, DS-05, DS-06, DS-07, DS-08, DS-09
**Plans:** 5/5 plans complete
**Success Criteria:**
1. `backend/internal/web/ui/base.css` defines all CSS custom properties (color, spacing, typography, shadows, gradients) matching the go-backend token vocabulary
2. All component types are implemented as templ components: button, input, textarea, select, card, badge, modal, empty-state, table, icon-button
3. `backend/tailwind.input.css` imports all component CSS files and the app shell CSS
4. A component catalog page (`/ui-catalog`, dev-only) renders all components for visual verification
5. All existing templates compile and unit tests pass with no regressions

Plans:
**Wave 1**
- [x] 13-01-PLAN.md — Token vocabulary + enum/helper foundation (base.css, auth.css extraction, variants.go, helpers.go)

**Wave 2** *(blocked on Wave 1 completion)*
- [x] 13-02-PLAN.md — Migrate existing components to go-backend API (button multi-class, badge pill, card typed API, template hardcodes)

**Wave 3** *(blocked on Wave 2 completion)*
- [x] 13-03-PLAN.md — Port form-input components: input, textarea, select, form-field (CSS + templ + tests)

**Wave 4** *(blocked on Wave 3 completion)*
- [x] 13-04-PLAN.md — Port surface components: modal, empty-state, table, icon-button, space + tailwind.input.css manifest

**Wave 5** *(blocked on Wave 4 completion)*
- [x] 13-05-PLAN.md — Catalog route (build-tag gated) + visual sign-off checkpoint

**User-in-loop:** Review the catalog page before proceeding to per-view application phases. Confirm token choices (brand color, radius, shadow levels) match what you want the product to look like.

### Phase 14: Auth Pages
**Goal:** Restyle login and signup pages to match the JS app's auth-card layout using the design system from Phase 13.
**Mode:** mvp
**Status:** Pending
**Requirements:** AUTH-UI-01, AUTH-UI-02, AUTH-UI-03
**Plans:** 1/2 plans executed
**Success Criteria:**
1. Login page has gradient background with animated background layer, centered auth card with brand logo, and status banner using design tokens
2. Signup page matches the same visual treatment as login
3. Google sign-in button uses the Material Design button style from the go-backend design
4. All existing auth handler tests pass unchanged
5. Browser walkthrough of login and signup matches the go-backend app.css auth-card design

Plans:
**Wave 1**
- [x] 14-01-PLAN.md — Auth foundation: logo assets + auth.css replacement + auth_components.templ + auth_layout.templ

**Wave 2** *(blocked on Wave 1 completion)*
- [ ] 14-02-PLAN.md — Page migration: update auth_login.templ and auth_signup.templ to use AuthLayout + FormField inputs + nav links + browser verify checkpoint

**User-in-loop:** Browser walkthrough checkpoint in Plan 02 — approve visual result before considering the phase complete.

### Phase 15: Dashboard & Tablos
**Goal:** Restyle the layout shell (sidebar + main) and tablo list/dashboard to match the JS app's sidebar + project-card layout.
**Mode:** mvp
**Status:** Pending
**Requirements:** DASH-01, DASH-02, DASH-03
**Success Criteria:**
1. Sidebar has brand section, nav items with icons, tablo list section, and user/account footer using sidebar-nav-shell classes
2. Tablo list uses project-card layout with color avatars, creation date, and action controls
3. Dashboard empty state uses the empty-state component
4. All existing tablo CRUD handler tests pass unchanged
5. Browser walkthrough of tablos list matches the go-backend project-card / sidebar design

**User-in-loop:** Approve sidebar shape (nav items, tablo list section) and tablo card layout before implementation.

### Phase 16: Tablo Detail
**Goal:** Restyle the tablo detail view — header, task kanban, etapes, and files — using design system components.
**Mode:** mvp
**Status:** Pending
**Requirements:** DETAIL-01, DETAIL-02, DETAIL-03, DETAIL-04
**Success Criteria:**
1. Tablo detail header uses project-card-top layout with title, avatar, and action controls
2. Task kanban uses tasks-section design: section header with add button, task rows with checkbox and meta
3. Etapes section uses the same card/section visual pattern as tasks
4. Files section uses the table component with consistent row actions
5. All existing task, etape, and file handler tests pass unchanged

**User-in-loop:** Approve kanban layout shape (whether columns stay horizontal or fold to list) and etape grouping UI before implementation.

### Phase 17: Chat & Planning
**Goal:** Restyle the discussion view and planning page using design system components to make them visually consistent with the rest of the app.
**Mode:** mvp
**Status:** Pending
**Requirements:** CHAT-UI-01, PLAN-UI-01
**Success Criteria:**
1. Discussion view uses card/surface design; own messages vs. others are visually differentiated
2. Planning page uses overview-section layout with chronological event list
3. All existing chat and planning handler tests pass unchanged
4. Browser walkthrough confirms both views look consistent with the Phase 15–16 restyled surfaces

**User-in-loop:** Approve chat bubble/row style and planning event row design before implementation.

---

## Coverage

**21 requirements mapped across 5 phases**

| Phase | Requirements | Count |
|-------|-------------|-------|
| 13 | DS-01, DS-02, DS-03, DS-04, DS-05, DS-06, DS-07, DS-08, DS-09 | 9 |
| 14 | AUTH-UI-01, AUTH-UI-02, AUTH-UI-03 | 3 |
| 15 | DASH-01, DASH-02, DASH-03 | 3 |
| 16 | DETAIL-01, DETAIL-02, DETAIL-03, DETAIL-04 | 4 |
| 17 | CHAT-UI-01, PLAN-UI-01 | 2 |
| **Total** | | **21 / 21 ✓** |
